@reckona/mreact-router 0.0.195 → 0.0.197

package/dist/client.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import { builtinModules } from "node:module";
-import { dirname, extname, join, relative, sep } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { analyzeBoundaryGraph, collectClientRouteModuleAnalysis, formatDiagnostic, } from "@reckona/mreact-compiler";
 import { collectClientRouteModuleAnalysisFromContext, createCompilerModuleContext, hasUnguardedBrowserGlobalReference, readTopLevelBooleanExport, readTopLevelBooleanExportFromContext, stripTypeScriptWithOxc, transformCompilerModuleContext, } from "@reckona/mreact-compiler/internal";
 import { assetPath } from "./assets.js";
@@ -54,6 +54,16 @@ export async function isClientRouteModule(options) {
 export async function inferClientRouteModule(options) {
     const cache = options.cache ?? createClientRouteInferenceCache();
     const sourceTransform = clientRouteSourceTransformForVitePlugins(options.vitePlugins);
+    const componentCollector = options.collectComponents
+        ? {
+            clientReachable: new Set(),
+            components: new Map(),
+            localExportNamesByFile: new Map(),
+            pendingExportValidations: [],
+            reachable: new Set(),
+            staticExportEdges: [],
+        }
+        : undefined;
     const code = await transformClientRouteSource({
         code: options.code,
         filename: options.filename,
@@ -63,9 +73,11 @@ export async function inferClientRouteModule(options) {
         const routeInference = await inferClientRouteModuleSource({
             cache,
             code,
+            componentCollector,
             filename: options.filename,
             ...(sourceTransform === undefined ? { moduleContext: options.moduleContext } : {}),
             root: true,
+            routeEntry: true,
             seen: new Set(),
             sourceTransform,
         });
@@ -78,21 +90,38 @@ export async function inferClientRouteModule(options) {
             }))
             : routeInference;
         if (options.appDir === undefined) {
-            return withClientRouteDiagnosticPath(mergedRouteInference, options.routePath);
+            const exportDiagnostics = finalizeClientRouteComponentExportValidations(componentCollector);
+            return withClientRouteDiagnosticPath({
+                ...mergedRouteInference,
+                ...(componentCollector === undefined
+                    ? {}
+                    : {
+                        components: normalizedClientRouteComponents(componentCollector, options.filename),
+                    }),
+                diagnostics: [...mergedRouteInference.diagnostics, ...exportDiagnostics],
+            }, options.routePath);
         }
         const shellInferences = await inferClientRouteShellModules({
             appDir: options.appDir,
             cache,
+            componentCollector,
             filename: options.filename,
             sourceTransform,
         });
+        const exportDiagnostics = finalizeClientRouteComponentExportValidations(componentCollector);
         return withClientRouteDiagnosticPath({
             client: mergedRouteInference.client || shellInferences.some((inference) => inference.client),
             clientBoundaryImports: mergedRouteInference.clientBoundaryImports,
             clientBoundaryFallbackImports: mergedRouteInference.clientBoundaryFallbackImports,
+            ...(componentCollector === undefined
+                ? {}
+                : {
+                    components: normalizedClientRouteComponents(componentCollector, options.filename),
+                }),
             diagnostics: [
                 ...mergedRouteInference.diagnostics,
                 ...shellInferences.flatMap((inference) => inference.diagnostics),
+                ...exportDiagnostics,
             ],
         }, options.routePath);
     }
@@ -161,6 +190,7 @@ export async function collectClientRouteReferences(options) {
         filename: options.filename,
         moduleContext: routeModuleContext,
         root: true,
+        routeEntry: true,
         seen: new Set(),
         sourceTransform,
     });
@@ -184,6 +214,7 @@ export async function collectClientRouteReferences(options) {
                 filename: sourceOptions.filename,
                 moduleContext,
                 root: true,
+                routeEntry: false,
                 seen: new Set(),
                 sourceTransform,
             }));
@@ -227,6 +258,7 @@ export async function collectClientRouteReferences(options) {
                     filename: shell,
                     moduleContext,
                     root: true,
+                    routeEntry: false,
                     seen: new Set(),
                     sourceTransform,
                 }),
@@ -343,8 +375,10 @@ async function inferClientRouteShellModules(options) {
         return await inferClientRouteModuleSource({
             cache: options.cache,
             code,
+            componentCollector: options.componentCollector,
             filename: shell,
             root: true,
+            routeEntry: false,
             seen: new Set(),
             sourceTransform: options.sourceTransform,
         });
@@ -366,6 +400,256 @@ export function isClientRouteSource(code) {
     const analysis = collectClientRouteModuleAnalysis({ code });
     return (analysis.hasUseClientDirective || (!analysis.hasUseServerDirective && analysis.clientRuntime));
 }
+function collectClientRouteComponentsForModule(collector, options) {
+    if (collector === undefined) {
+        return;
+    }
+    if (options.root) {
+        markClientRouteComponentReachable(collector, options.filename, ["default"]);
+    }
+    const localExportNames = collector.localExportNamesByFile.get(options.filename) ?? new Set();
+    for (const info of options.analysis.topLevelExportRenderInfo) {
+        localExportNames.add(info.name);
+    }
+    collector.localExportNamesByFile.set(options.filename, localExportNames);
+    const serverOnly = options.analysis.hasUseServerDirective || hasServerOnlyImports(options.analysis);
+    const explicitClient = isExplicitClientRouteSource(options.analysis, options.filename);
+    for (const info of options.analysis.topLevelExportRenderInfo) {
+        const component = {
+            classification: serverOnly
+                ? "server-only"
+                : explicitClient || info.clientRuntime
+                    ? options.routeEntry && info.name === "default"
+                        ? "client-route"
+                        : "client-boundary"
+                    : "server-render",
+            exportName: info.name,
+            file: options.filename,
+            origin: clientRouteComponentOrigin({
+                analysis: options.analysis,
+                filename: options.filename,
+                info,
+                serverOnly,
+            }),
+        };
+        collector.components.set(clientRouteComponentKey(component.file, component.exportName), component);
+    }
+    for (const info of options.analysis.topLevelExportRenderInfo) {
+        if (!isClientRouteComponentReachable(collector, options.filename, info.name)) {
+            continue;
+        }
+        const renderedNames = new Set([
+            ...(options.analysis.reachableExportRenderedComponentNames[info.name] ?? []),
+            ...(options.analysis.reachableExportRenderedComponentRoots[info.name] ?? []),
+        ]);
+        for (const rendered of options.analysis.topLevelExportRenderInfo) {
+            if (rendered.name !== "default" &&
+                (renderedNames.has(rendered.name) || renderedNames.has(rendered.localName ?? rendered.name))) {
+                markClientRouteComponentReachable(collector, options.filename, [rendered.name], {
+                    clientExecution: clientRouteComponentRunsOnClient(collector, options.filename, info.name),
+                });
+            }
+        }
+    }
+}
+function clientRouteComponentOrigin(options) {
+    if (options.analysis.hasUseServerDirective) {
+        return "use-server-directive";
+    }
+    if (options.serverOnly) {
+        return "server-only-import";
+    }
+    if (options.analysis.hasUseClientDirective) {
+        return "use-client-directive";
+    }
+    if (/\.compat(?:\.mreact)?\.[cm]?[jt]sx?$/.test(options.filename)) {
+        return "compat-filename";
+    }
+    if (/\.client(?:\.mreact)?\.[cm]?[jt]sx?$/.test(options.filename)) {
+        return "client-filename";
+    }
+    return options.info.clientRuntime ? "inferred-client-runtime" : "server-render";
+}
+function normalizedClientRouteComponents(collector, routeFile) {
+    return Array.from(collector.components.values())
+        .filter((component) => collector.reachable.has(clientRouteComponentKey(component.file, component.exportName)) ||
+        collector.reachable.has(clientRouteComponentKey(component.file, "*")))
+        .map((component) => component.classification === "server-render" &&
+        (collector.clientReachable.has(clientRouteComponentKey(component.file, component.exportName)) ||
+            collector.clientReachable.has(clientRouteComponentKey(component.file, "*")))
+        ? { ...component, classification: "shared" }
+        : component)
+        .sort((left, right) => {
+        const leftRoute = left.file === routeFile && left.exportName === "default";
+        const rightRoute = right.file === routeFile && right.exportName === "default";
+        if (leftRoute !== rightRoute) {
+            return leftRoute ? -1 : 1;
+        }
+        return left.file === right.file
+            ? left.exportName === right.exportName
+                ? left.classification.localeCompare(right.classification)
+                : left.exportName.localeCompare(right.exportName)
+            : left.file.localeCompare(right.file);
+    });
+}
+function clientRouteComponentKey(file, exportName) {
+    return `${file}\0${exportName}`;
+}
+function markClientRouteComponentReachable(collector, file, exportNames, options = {}) {
+    if (collector === undefined) {
+        return;
+    }
+    if (exportNames === undefined) {
+        collector.reachable.add(clientRouteComponentKey(file, "*"));
+        if (options.clientExecution === true) {
+            collector.clientReachable.add(clientRouteComponentKey(file, "*"));
+        }
+        return;
+    }
+    for (const exportName of exportNames) {
+        const key = clientRouteComponentKey(file, exportName);
+        collector.reachable.add(key);
+        if (options.clientExecution === true) {
+            collector.clientReachable.add(key);
+        }
+    }
+}
+function clientRouteComponentRunsOnClient(collector, file, exportName) {
+    if (collector === undefined) {
+        return false;
+    }
+    const key = clientRouteComponentKey(file, exportName);
+    const component = collector.components.get(key);
+    return (component?.classification === "client-boundary" ||
+        component?.classification === "client-route" ||
+        component?.classification === "shared" ||
+        collector.clientReachable.has(key) ||
+        collector.clientReachable.has(clientRouteComponentKey(file, "*")));
+}
+function isClientRouteComponentReachable(collector, file, exportName) {
+    return (collector === undefined ||
+        collector.reachable.has(clientRouteComponentKey(file, exportName)) ||
+        collector.reachable.has(clientRouteComponentKey(file, "*")));
+}
+function propagateClientRouteComponentStaticExport(collector, file, resolved, reference) {
+    if (collector === undefined) {
+        return;
+    }
+    const wildcardReachable = collector.reachable.has(clientRouteComponentKey(file, "*"));
+    const wildcardClientExecution = clientRouteComponentRunsOnClient(collector, file, "*");
+    if (reference.exportAll) {
+        if (wildcardReachable) {
+            markClientRouteComponentReachable(collector, resolved, undefined, {
+                clientExecution: wildcardClientExecution,
+            });
+        }
+        for (const key of collector.reachable) {
+            const [reachableFile, exportName] = key.split("\0");
+            if (reachableFile === file && exportName !== undefined && exportName !== "*") {
+                markClientRouteComponentReachable(collector, resolved, [exportName], {
+                    clientExecution: clientRouteComponentRunsOnClient(collector, file, exportName),
+                });
+            }
+        }
+        return;
+    }
+    for (const specifier of reference.specifiers) {
+        if (wildcardReachable ||
+            collector.reachable.has(clientRouteComponentKey(file, specifier.exportedName))) {
+            markClientRouteComponentReachable(collector, resolved, [specifier.localName], {
+                clientExecution: wildcardClientExecution ||
+                    clientRouteComponentRunsOnClient(collector, file, specifier.exportedName),
+            });
+        }
+    }
+    if (reference.specifiers.length === 0) {
+        for (const exportName of reference.exportedNames) {
+            if (wildcardReachable || collector.reachable.has(clientRouteComponentKey(file, exportName))) {
+                markClientRouteComponentReachable(collector, resolved, [exportName], {
+                    clientExecution: wildcardClientExecution ||
+                        clientRouteComponentRunsOnClient(collector, file, exportName),
+                });
+            }
+        }
+    }
+}
+function collectUnknownClientRouteComponents(collector, options) {
+    if (collector === undefined) {
+        return;
+    }
+    for (const exportName of options.exportNames ?? ["*"]) {
+        const component = {
+            classification: "unknown",
+            exportName,
+            file: options.file,
+            origin: "unresolved-reference",
+        };
+        collector.components.set(clientRouteComponentKey(component.file, component.exportName), component);
+        markClientRouteComponentReachable(collector, component.file, [component.exportName]);
+    }
+}
+function collectClientRoutePendingExportValidation(collector, options) {
+    if (collector === undefined || options.exportNames.length === 0) {
+        return;
+    }
+    collector.pendingExportValidations.push(options);
+}
+function collectClientRouteStaticExportEdge(collector, options) {
+    collector?.staticExportEdges.push(options);
+}
+function finalizeClientRouteComponentExportValidations(collector) {
+    if (collector === undefined) {
+        return [];
+    }
+    const exportNamesByFile = new Map();
+    for (const [file, names] of collector.localExportNamesByFile) {
+        exportNamesByFile.set(file, new Set(names));
+    }
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const edge of collector.staticExportEdges) {
+            const exportedNames = exportNamesByFile.get(edge.file) ?? new Set();
+            const sourceNames = exportNamesByFile.get(edge.resolved) ?? new Set();
+            const namesToAdd = edge.reference.exportAll
+                ? new Set([...sourceNames].filter((exportName) => exportName !== "default"))
+                : new Set(edge.reference.specifiers
+                    .filter((specifier) => sourceNames.has(specifier.localName))
+                    .map((specifier) => specifier.exportedName));
+            for (const exportName of namesToAdd) {
+                if (!exportedNames.has(exportName)) {
+                    exportedNames.add(exportName);
+                    changed = true;
+                }
+            }
+            exportNamesByFile.set(edge.file, exportedNames);
+        }
+    }
+    const diagnostics = [];
+    const seen = new Set();
+    for (const pending of collector.pendingExportValidations) {
+        const availableExportNames = exportNamesByFile.get(pending.file) ?? new Set();
+        const missingExportNames = pending.exportNames.filter((exportName) => !availableExportNames.has(exportName));
+        if (missingExportNames.length === 0) {
+            continue;
+        }
+        const key = `${pending.importer}\0${pending.source}\0${missingExportNames.join("\0")}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        collectUnknownClientRouteComponents(collector, {
+            exportNames: missingExportNames,
+            file: pending.file,
+        });
+        diagnostics.push(unresolvedClientRouteReferenceDiagnostic({
+            exportNames: missingExportNames,
+            filename: pending.importer,
+            source: pending.source,
+        }));
+    }
+    return diagnostics;
+}
 function isExplicitClientRouteSource(analysis, filename) {
     return analysis.hasUseClientDirective || isClientBoundaryFilename(filename);
 }
@@ -384,22 +668,35 @@ function hasServerOnlyImports(analysis) {
 async function inferClientRouteModuleSource(options) {
     const analysis = await clientRouteModuleAnalysisForSource(options);
     const usesNavigationLinkLocal = detectLinkComponentUsage(analysis);
-    if (isServerOnlyClientRouteSource(analysis)) {
-        return emptyClientRouteModuleInferenceResult({
+    collectClientRouteComponentsForModule(options.componentCollector, {
+        analysis,
+        filename: options.filename,
+        root: options.root,
+        routeEntry: options.routeEntry,
+    });
+    const forcedInference = isServerOnlyClientRouteSource(analysis)
+        ? emptyClientRouteModuleInferenceResult({
+            availableExportNames: analysis.topLevelExportRenderInfo.map((info) => info.name),
             navigationLinkExportNames: detectLinkComponentExportNames(analysis),
             serverOnly: true,
             serverOnlyClientRuntime: analysis.clientRuntime,
             usesNavigationLink: usesNavigationLinkLocal,
-        });
-    }
-    if (isExplicitClientRouteSource(analysis, options.filename)) {
-        return emptyClientRouteModuleInferenceResult({
-            client: true,
-            clientBoundaryModule: true,
-        });
+        })
+        : isExplicitClientRouteSource(analysis, options.filename)
+            ? emptyClientRouteModuleInferenceResult({
+                availableExportNames: analysis.topLevelExportRenderInfo.map((info) => info.name),
+                client: true,
+                clientBoundaryModule: true,
+            })
+            : undefined;
+    if (forcedInference !== undefined && options.componentCollector === undefined) {
+        return forcedInference;
     }
     if (options.seen.has(options.filename)) {
-        return emptyClientRouteModuleInferenceResult();
+        return (forcedInference ??
+            emptyClientRouteModuleInferenceResult({
+                availableExportNames: analysis.topLevelExportRenderInfo.map((info) => info.name),
+            }));
     }
     options.seen.add(options.filename);
     try {
@@ -409,6 +706,7 @@ async function inferClientRouteModuleSource(options) {
         const nestedClientExportNames = new Set();
         const clientReferenceSourceFiles = [];
         const diagnostics = [];
+        const availableExportNames = new Set(analysis.topLevelExportRenderInfo.map((info) => info.name));
         let boundaryGraphFallbackRequired = false;
         let clientProxy = false;
         let nestedClient = false;
@@ -422,8 +720,11 @@ async function inferClientRouteModuleSource(options) {
             }
         }
         if (hasServerOnlyImports(analysis) &&
-            (implicitModuleClient || clientBoundaryExportNames.size > 0)) {
+            (implicitModuleClient || clientBoundaryExportNames.size > 0) &&
+            options.componentCollector === undefined) {
             return emptyClientRouteModuleInferenceResult({
+                availableExportNames: Array.from(availableExportNames),
+                navigationLinkExportNames: detectLinkComponentExportNames(analysis),
                 serverOnly: true,
                 serverOnlyClientRuntime: true,
             });
@@ -450,15 +751,46 @@ async function inferClientRouteModuleSource(options) {
             if (reference.sideEffect && isStyleModuleSpecifier(reference.source)) {
                 continue;
             }
+            const renderingExportNames = rendered ? renderedLocalExportNames(reference, exportInfo) : [];
+            const renderedImportedNames = rendered
+                ? renderedImportedExportNames(reference, renderedComponentRoots)
+                : [];
+            const renderedFromReachableExport = rendered &&
+                renderingExportNames.some((exportName) => isClientRouteComponentReachable(options.componentCollector, options.filename, exportName));
             const resolved = await resolveAppLocalModule({
                 allowExplicitNonSource: options.sourceTransform !== undefined,
                 cache: options.cache,
                 importer: options.filename,
                 specifier: reference.source,
+                tolerateUnresolved: options.componentCollector !== undefined,
             });
             if (resolved === undefined) {
+                if (options.componentCollector !== undefined &&
+                    renderedFromReachableExport &&
+                    reference.source.startsWith(".")) {
+                    collectUnknownClientRouteComponents(options.componentCollector, {
+                        exportNames: renderedImportedNames,
+                        file: resolve(dirname(options.filename), reference.source),
+                    });
+                    diagnostics.push(unresolvedClientRouteReferenceDiagnostic({
+                        filename: options.filename,
+                        source: reference.source,
+                    }));
+                }
                 continue;
             }
+            if (renderedFromReachableExport) {
+                const clientExecution = renderingExportNames.some((exportName) => clientRouteComponentRunsOnClient(options.componentCollector, options.filename, exportName));
+                markClientRouteComponentReachable(options.componentCollector, resolved, renderedImportedNames, { clientExecution });
+                if (renderedImportedNames !== undefined) {
+                    collectClientRoutePendingExportValidation(options.componentCollector, {
+                        exportNames: renderedImportedNames,
+                        file: resolved,
+                        importer: options.filename,
+                        source: reference.source,
+                    });
+                }
+            }
             const source = await readClientRouteSource({
                 cache: options.cache,
                 filename: resolved,
@@ -467,6 +799,7 @@ async function inferClientRouteModuleSource(options) {
             const imported = await inferClientRouteModuleSource({
                 cache: options.cache,
                 code: source,
+                componentCollector: options.componentCollector,
                 filename: resolved,
                 moduleContext: await compilerModuleContextForSource({
                     cache: options.cache,
@@ -474,6 +807,7 @@ async function inferClientRouteModuleSource(options) {
                     filename: resolved,
                 }),
                 root: false,
+                routeEntry: false,
                 seen: options.seen,
                 sourceTransform: options.sourceTransform,
             });
@@ -505,8 +839,8 @@ async function inferClientRouteModuleSource(options) {
                 continue;
             }
             if (rendered) {
-                const importedExportNames = renderedImportedExportNames(reference, renderedComponentRoots);
-                const renderedExportNames = renderedLocalExportNames(reference, exportInfo);
+                const importedExportNames = renderedImportedNames;
+                const renderedExportNames = renderingExportNames;
                 const importedBoundary = imported.clientBoundaryModule ||
                     matchesInferredExportNames(importedExportNames, imported.clientBoundaryExportNames);
                 const importedNested = matchesInferredExportNames(importedExportNames, imported.nestedClientExportNames);
@@ -553,10 +887,23 @@ async function inferClientRouteModuleSource(options) {
                     cache: options.cache,
                     importer: options.filename,
                     specifier: reference.source,
+                    tolerateUnresolved: options.componentCollector !== undefined,
                 });
                 if (resolved === undefined) {
+                    if (options.componentCollector !== undefined) {
+                        diagnostics.push(unresolvedClientRouteReferenceDiagnostic({
+                            filename: options.filename,
+                            source: reference.source,
+                        }));
+                    }
                     continue;
                 }
+                propagateClientRouteComponentStaticExport(options.componentCollector, options.filename, resolved, reference);
+                collectClientRouteStaticExportEdge(options.componentCollector, {
+                    file: options.filename,
+                    reference,
+                    resolved,
+                });
                 const source = await readClientRouteSource({
                     cache: options.cache,
                     filename: resolved,
@@ -565,6 +912,7 @@ async function inferClientRouteModuleSource(options) {
                 const exported = await inferClientRouteModuleSource({
                     cache: options.cache,
                     code: source,
+                    componentCollector: options.componentCollector,
                     filename: resolved,
                     moduleContext: await compilerModuleContextForSource({
                         cache: options.cache,
@@ -572,10 +920,24 @@ async function inferClientRouteModuleSource(options) {
                         filename: resolved,
                     }),
                     root: false,
+                    routeEntry: false,
                     seen: options.seen,
                     sourceTransform: options.sourceTransform,
                 });
                 diagnostics.push(...exported.diagnostics);
+                if (reference.exportAll) {
+                    for (const exportName of exported.availableExportNames) {
+                        availableExportNames.add(exportName);
+                    }
+                }
+                else {
+                    for (const specifier of reference.specifiers) {
+                        availableExportNames.add(specifier.exportedName);
+                    }
+                    for (const exportName of reference.exportedNames) {
+                        availableExportNames.add(exportName);
+                    }
+                }
                 // A re-export renders nothing itself, so it does not set the module's
                 // own `usesNavigationLink`; it only forwards per-export `Link` usage so
                 // an importer that renders this name can decide precisely. Map the
@@ -620,7 +982,8 @@ async function inferClientRouteModuleSource(options) {
                 }
             }
         }
-        return {
+        const inferred = {
+            availableExportNames: Array.from(availableExportNames),
             boundaryGraphFallbackCandidate: analysis.staticExports.length > 0 || boundaryGraphFallbackRequired,
             boundaryGraphFallbackRequired,
             client: clientBoundaryImports.length > 0 ||
@@ -640,6 +1003,15 @@ async function inferClientRouteModuleSource(options) {
             serverOnlyClientRuntime: false,
             usesNavigationLink,
         };
+        return forcedInference === undefined
+            ? inferred
+            : {
+                ...forcedInference,
+                availableExportNames: inferred.availableExportNames,
+                diagnostics,
+                navigationLinkExportNames: inferred.navigationLinkExportNames,
+                usesNavigationLink: inferred.usesNavigationLink,
+            };
     }
     finally {
         options.seen.delete(options.filename);
@@ -647,6 +1019,7 @@ async function inferClientRouteModuleSource(options) {
 }
 function emptyClientRouteModuleInferenceResult(overrides = {}) {
     return {
+        availableExportNames: [],
         boundaryGraphFallbackCandidate: false,
         boundaryGraphFallbackRequired: false,
         client: false,
@@ -883,7 +1256,7 @@ function matchingBraceEnd(source, openBraceIndex) {
             }
             continue;
         }
-        if (char === "\"" || char === "'" || char === "`") {
+        if (char === '"' || char === "'" || char === "`") {
             quote = char;
             continue;
         }
@@ -940,8 +1313,7 @@ function addDestructuredCallbackNames(names, destructured) {
         const property = destructuredBindingName(rawProperty);
         const alias = destructuredBindingName(rawAlias);
         const name = alias ?? property;
-        if (name !== undefined &&
-            (isCallbackPropName(property) || isCallbackPropName(name))) {
+        if (name !== undefined && (isCallbackPropName(property) || isCallbackPropName(name))) {
             names.add(name);
         }
     }
@@ -1001,6 +1373,20 @@ function serverOnlyClientImportReferenceDiagnostic(options) {
         source: options.reference.source,
     };
 }
+function unresolvedClientRouteReferenceDiagnostic(options) {
+    const exportSuffix = options.exportNames === undefined || options.exportNames.length === 0
+        ? ""
+        : ` (${options.exportNames.map((name) => JSON.stringify(name)).join(", ")})`;
+    return {
+        code: "MR_CLIENT_BOUNDARY_INFERENCE_UNRESOLVED_REFERENCE",
+        filename: options.filename,
+        level: "warn",
+        localNames: [...(options.exportNames ?? [])],
+        message: `${options.filename}: rendered component reference ${JSON.stringify(options.source)}${exportSuffix} ` +
+            "could not be resolved to an exported component.",
+        source: options.source,
+    };
+}
 function functionCallInteractiveImportDiagnostic(options) {
     const localNames = options.reference.localNames.filter(startsUppercase);
     const component = localNames[0] ?? options.reference.localNames[0] ?? options.reference.source;
@@ -1066,7 +1452,7 @@ async function resolveAppLocalModule(options) {
     if (!options.specifier.startsWith(".")) {
         return undefined;
     }
-    const cacheKey = `${options.importer}\0${options.specifier}\0${options.allowExplicitNonSource === true ? "explicit" : "source"}`;
+    const cacheKey = `${options.importer}\0${options.specifier}\0${options.allowExplicitNonSource === true ? "explicit" : "source"}\0${options.tolerateUnresolved === true ? "tolerant" : "strict"}`;
     const cached = options.cache.resolvedByImport.get(cacheKey);
     if (cached !== undefined) {
         return cached;
@@ -1075,6 +1461,7 @@ async function resolveAppLocalModule(options) {
         allowExplicitNonSource: options.allowExplicitNonSource === true,
         importer: options.importer,
         specifier: options.specifier,
+        tolerateUnresolved: options.tolerateUnresolved === true,
     });
     options.cache.resolvedByImport.set(cacheKey, resolved);
     return resolved;
@@ -1094,6 +1481,9 @@ async function resolveAppLocalModuleUncached(options) {
             return candidate;
         }
     }
+    if (options.tolerateUnresolved) {
+        return undefined;
+    }
     throw new Error(`${importer}: could not resolve app-local import ${JSON.stringify(specifier)}.`);
 }
 async function isFile(path) {
@@ -1318,6 +1708,12 @@ export async function buildNavigationRuntimeBundle(options = {}) {
 export async function buildClientRouteOutput(options) {
     const entry = await buildClientRouteEntrySource(options);
     const dropConsoleFunctions = options.dropConsoleFunctions ?? resolveClientConsolePureFunctions(options.dropClientConsole);
+    const sourceRegionModulePaths = options.debugLabels === true ? undefined : new Set([options.filename]);
+    const runtimePlugin = workspaceRuntimePlugin({
+        debugLabels: options.debugLabels === true,
+        routeFiles: [options.filename],
+        sourceRegionModulePaths,
+    });
     const bundled = await bundleRouterModule({
         code: entry.code,
         cacheDir: options.cacheDir,
@@ -1329,7 +1725,8 @@ export async function buildClientRouteOutput(options) {
         minify: options.minify === true,
         platform: "browser",
         preserveExports: true,
-        plugins: [workspaceRuntimePlugin({ routeFiles: [options.filename] })],
+        sourceRegionModulePaths,
+        plugins: [runtimePlugin],
         sourceMap: options.sourceMap,
         vitePlugins: options.vitePlugins,
     });
@@ -1350,6 +1747,15 @@ export async function buildClientRouteBatchOutput(options) {
             vitePlugins: options.vitePlugins ?? route.vitePlugins,
         }),
     })));
+    const debugLabels = options.routes.some((route) => route.debugLabels === true);
+    const sourceRegionModulePaths = debugLabels
+        ? undefined
+        : new Set(entries.map((entry) => entry.filename));
+    const runtimePlugin = workspaceRuntimePlugin({
+        debugLabels,
+        routeFiles: entries.map((entry) => entry.filename),
+        sourceRegionModulePaths,
+    });
     const bundled = await bundleRouterModules({
         base: options.assetBaseUrl ?? "/_mreact/client/",
         cacheDir: options.cacheDir,
@@ -1363,7 +1769,8 @@ export async function buildClientRouteBatchOutput(options) {
         })),
         minify: options.minify === true,
         platform: "browser",
-        plugins: [workspaceRuntimePlugin({ routeFiles: entries.map((entry) => entry.filename) })],
+        sourceRegionModulePaths,
+        plugins: [runtimePlugin],
         root: options.projectRoot,
         sourceMap: options.sourceMap,
         dropConsoleFunctions: options.dropConsoleFunctions,
@@ -1392,13 +1799,20 @@ export async function buildClientRouteEntrySource(options) {
         filename: options.filename,
     });
     const routeSourceAnalysis = collectClientRouteModuleAnalysisFromContext(moduleContext);
+    const compilerFilename = options.debugLabels === true ? basename(options.filename) : options.filename;
+    const compilerModuleContext = compilerFilename === options.filename
+        ? moduleContext
+        : createCompilerModuleContext({
+            code: options.code,
+            filename: compilerFilename,
+        });
     const compiled = transformCompilerModuleContext({
         code: options.code,
         clientBoundaryImports: options.clientBoundaryImports ?? [],
-        filename: options.filename,
-        moduleContext,
+        filename: compilerFilename,
+        moduleContext: compilerModuleContext,
         target: "client",
-        dev: options.minify !== true,
+        dev: options.debugLabels === true,
     });
     if (compiled.diagnostics.length > 0) {
         throw new Error(compiled.diagnostics
@@ -1416,7 +1830,8 @@ export async function buildClientRouteEntrySource(options) {
     const routeId = routeIdForPath(options.routePath);
     const routeUsesCells = detectRouteCellStateHint(compiled.code);
     const routeUsesReactiveEffect = detectRouteReactiveEffectHint(compiled.code);
-    const routeUsesCleanupScope = routeUsesCells || routeUsesReactiveEffect;
+    const routeUsesDomRefs = compiled.metadata.imports.some((entry) => entry.source === "@reckona/mreact-reactive-dom" && entry.specifiers.includes("bindDomRef"));
+    const routeUsesCleanupScope = routeUsesCells || routeUsesReactiveEffect || routeUsesDomRefs;
     const routeExplicitlyRequiresHydration = isExplicitClientRouteSource(routeSourceAnalysis, options.filename);
     const routeHasEventBindings = (compiled.metadata.eventHydrationManifest?.events.length ?? 0) > 0;
     const routeCapturesEventBindings = compiled.code.includes("__mreactEventBindings");
@@ -1427,6 +1842,7 @@ export async function buildClientRouteEntrySource(options) {
     const routeRequiresFullHydration = routeExplicitlyRequiresHydration ||
         routeUsesCells ||
         routeUsesReactiveEffect ||
+        routeUsesDomRefs ||
         routeHasEventBindings;
     const routeUsesOnlyClientReferenceBoundaries = !routeRequiresFullHydration &&
         clientReferenceManifest.length > 0 &&
@@ -1447,7 +1863,7 @@ export async function buildClientRouteEntrySource(options) {
         ? `import { bindCapturedEvent as __mreactBindCapturedEvent } from "@reckona/mreact-reactive-dom/internal";\n`
         : "";
     const routeReactiveDomMetadataImport = !routeUsesOnlyClientReferenceBoundaries
-        ? `${routeCapturedEventImport}import { withEventBindingMetadata as __mreactWithEventBindingMetadata, withPropBindingMetadata as __mreactWithPropBindingMetadata } from "@reckona/mreact-reactive-dom";\n`
+        ? `${routeCapturedEventImport}import { ${routeUsesDomRefs ? "getDomRefBindings as __mreactGetDomRefBindings, " : ""}withEventBindingMetadata as __mreactWithEventBindingMetadata, withPropBindingMetadata as __mreactWithPropBindingMetadata } from "@reckona/mreact-reactive-dom";\n`
         : "";
     const navigationStateDeclaration = inlineClientNavigation
         ? `const __mreactNavigationState = __mreactGlobal.__mreactNavigationState ??= {
@@ -1723,9 +2139,10 @@ __mreactGlobal.__mreactRouteCell = (nativeCell, initial) => {
       __mreactActiveCellIndex = 0;
     }
     return () => {
-      for (const __mreactDispose of Array.from(__mreactRouteEffectDisposers)) {
-        __mreactDispose();
-      }
+      __mreactRunLifecycleTasks(
+        Array.from(__mreactRouteEffectDisposers),
+        (__mreactDispose) => __mreactDispose(),
+      );
       __mreactRouteEffectDisposers.clear();
     };
   });
@@ -1736,13 +2153,33 @@ __mreactGlobal.__mreactRouteCell = (nativeCell, initial) => {
         ? `  __mreactDisposeRoute(__mreactRouteId);
   const __mreactRouteEffectDisposers = new Set();
   __mreactRouteDisposers.set(__mreactRouteId, () => {
-    for (const __mreactDispose of Array.from(__mreactRouteEffectDisposers)) {
-      __mreactDispose();
-    }
+    __mreactRunLifecycleTasks(
+      Array.from(__mreactRouteEffectDisposers),
+      (__mreactDispose) => __mreactDispose(),
+    );
     __mreactRouteEffectDisposers.clear();
   });
 `
         : "";
+    const routeLifecycleFunctions = `
+function __mreactRunLifecycleTasks(values, run) {
+  let firstError;
+
+  for (const value of values) {
+    try {
+      run(value);
+    } catch (error) {
+      firstError ??= error;
+    }
+  }
+
+  if (firstError !== undefined) {
+    queueMicrotask(() => {
+      throw firstError;
+    });
+  }
+}
+`;
     const routeCellDropFunction = routeUsesCells
         ? `
 function __mreactDropMismatchedRouteState(previousState, nextState) {
@@ -1768,12 +2205,18 @@ function __mreactDisposeRoute(routeId) {
 }
 `
         : "";
-    const routeCleanupNavigationDispose = routeUsesCleanupScope
-        ? `  if (currentRouteId !== nextRouteId) {
-    __mreactDisposeRoute(currentRouteId);
+    const routeCleanupNavigationDispose = `  if (currentRouteId !== nextRouteId) {
+    const __mreactRegisteredRouteDisposers = __mreactGlobal.__mreactRouteDisposers;
+    const __mreactRegisteredRouteDispose = __mreactRegisteredRouteDisposers?.get(currentRouteId);
+    if (__mreactRegisteredRouteDispose !== undefined) {
+      __mreactRegisteredRouteDisposers.delete(currentRouteId);
+      __mreactRunLifecycleTasks(
+        [__mreactRegisteredRouteDispose],
+        (__mreactDispose) => __mreactDispose(),
+      );
+    }
   }
-`
-        : "";
+`;
     const routeNodeResolver = routeUsesCells
         ? `
 function __mreactResolveRouteNode(value) {
@@ -1812,9 +2255,7 @@ function __mreactResolveRouteNode(value) {
   const previousDisposers = current.__mreactEventDisposers;
 
   if (Array.isArray(previousDisposers)) {
-    for (const dispose of previousDisposers) {
-      dispose();
-    }
+    __mreactRunLifecycleTasks(previousDisposers, (dispose) => dispose());
   }
 
   const rawBindings = next.__mreactEventBindings;
@@ -1843,14 +2284,26 @@ function __mreactResolveRouteNode(value) {
   const previousDisposers = current.__mreactEventDisposers;
 
   if (Array.isArray(previousDisposers)) {
-    for (const dispose of previousDisposers) {
-      dispose();
-    }
+    __mreactRunLifecycleTasks(previousDisposers, (dispose) => dispose());
   }
 
   current.__mreactEventDisposers = [];
   current.__mreactHasEvents = false;
 }
+`;
+    const routeDomRefBindingSyncFunction = routeUsesDomRefs
+        ? `function __mreactSyncDomRefBindings(current, next) {
+  __mreactRunLifecycleTasks(
+    Array.from(__mreactGetDomRefBindings(current)),
+    (binding) => binding.dispose(),
+  );
+  __mreactRunLifecycleTasks(
+    Array.from(__mreactGetDomRefBindings(next)),
+    (binding) => binding.retarget(current),
+  );
+}
+`
+        : `function __mreactSyncDomRefBindings() {}
 `;
     const boundaryOnlyHydrationBlock = routeRequiresFullHydration
         ? ""
@@ -1909,6 +2362,7 @@ ${routeCellHydrationIndent}__mreactMarker.setAttribute(__mreactRouteHydratedAttr
 ${routeCellHydrationIndent}__mreactMarkRouteHydrated();
 ${routeCellHydrationEnd}}
 ${routeCellDropFunction}
+${routeLifecycleFunctions}
 ${routeCleanupFunction}
 
 function __mreactMarkRouteHydrated() {
@@ -2495,13 +2949,14 @@ function __mreactApplyNavigationHtml(html, url) {
   const currentRouteId = currentMarker.getAttribute("${routeHydrationContract.routeMarkerAttribute}");
   const nextRouteId = nextMarker.getAttribute("${routeHydrationContract.routeMarkerAttribute}");
 
+${routeCleanupNavigationDispose}
   __mreactMarkRouteHydrating();
   __mreactSyncHeadMetadata(template.content, html);
   if (!__mreactApplyNavigationShellHtml(currentMarker, nextMarker)) {
     __mreactUnmountCompatBoundaries(currentMarker);
     __mreactResumeNode(currentMarker, nextMarker);
   }
-${routeCleanupNavigationDispose}  __mreactSyncRouteDataScripts(template.content, currentRouteId, nextRouteId);
+  __mreactSyncRouteDataScripts(template.content, currentRouteId, nextRouteId);
 
   const script = template.content.querySelector('script[type="module"][src]')?.getAttribute("src");
   if (script !== null && script !== undefined) {
@@ -3658,6 +4113,7 @@ function __mreactResumeNode(current, next) {
   }
 
   __mreactSyncEventBindings(current, next);
+  __mreactSyncDomRefBindings(current, next);
   __mreactSyncAttributes(current, next);
   __mreactSyncPropBindings(current, next);
   __mreactResumeChildren(current, next);
@@ -3680,6 +4136,7 @@ function __mreactShouldReplaceNode(current, next) {
 }
 
 ${routeEventBindingSyncFunction}
+${routeDomRefBindingSyncFunction}
 
 function __mreactSyncAttributes(current, next) {
   for (const attribute of Array.from(current.attributes)) {
@@ -3699,9 +4156,7 @@ function __mreactSyncPropBindings(current, next) {
   const previousBindings = current.__mreactPropBindings;
 
   if (Array.isArray(previousBindings)) {
-    for (const binding of previousBindings) {
-      binding.dispose?.();
-    }
+    __mreactRunLifecycleTasks(previousBindings, (binding) => binding.dispose?.());
   }
 
   const bindings = next.__mreactPropBindings;
@@ -3717,9 +4172,7 @@ function __mreactSyncPropBindings(current, next) {
   next.__mreactPropBindings = [];
   next.__mreactHasReactiveProps = false;
 
-  for (const binding of bindings) {
-    binding.retarget?.(current);
-  }
+  __mreactRunLifecycleTasks(bindings, (binding) => binding.retarget?.(current));
 }
 
 function __mreactResumeChildren(current, next) {
@@ -3885,22 +4338,33 @@ export function invalidateReactiveDevtoolsCache() {}
 export function prepareReactiveEffectRunDevtoolsEvent() { return undefined; }`,
                 loader: "ts",
             }));
+            if (options.sourceRegionModulePaths !== undefined) {
+                buildApi.onLoad({ filter: /.*/ }, (args) => {
+                    if (isAbsolute(args.path) &&
+                        isRouteClientDependencySourcePath(args.path, routeFiles) &&
+                        !runtimePackageDirs.some((runtimePackageDir) => args.path.startsWith(`${runtimePackageDir}${sep}`))) {
+                        options.sourceRegionModulePaths?.add(args.path);
+                    }
+                    return undefined;
+                });
+            }
             buildApi.onLoad({ filter: /\.(?:mreact\.)?[cm]?[jt]sx$/ }, async (args) => {
                 if (!isRouteClientDependencySourcePath(args.path, routeFiles)) {
                     return undefined;
                 }
                 const source = await readFile(args.path, "utf8");
+                const compilerFilename = options.debugLabels ? basename(args.path) : args.path;
                 const moduleContext = createCompilerModuleContext({
                     code: source,
-                    filename: args.path,
+                    filename: compilerFilename,
                 });
                 if (!hasJsxSyntax(moduleContext.program)) {
                     return undefined;
                 }
                 const output = transformCompilerModuleContext({
                     code: source,
-                    dev: true,
-                    filename: args.path,
+                    dev: options.debugLabels,
+                    filename: compilerFilename,
                     mode: isCompatSourcePath(args.path) ? "compat" : "reactive",
                     moduleContext,
                     target: "client",