@rangojs/router 0.0.0-experimental.136 → 0.0.0-experimental.138

package/dist/vite/expose-internal-ids.js

@@ -1,886 +0,0 @@
-import { parseAst } from "vite";
-import MagicString from "magic-string";
-import path from "node:path";
-import { createHash } from "node:crypto";
-import { normalizePath, hashId, detectImports, findMatchingParen, countArgs, findStatementEnd, buildExportMap, } from "./expose-id-utils.ts";
-import { transformInlineHandlers, } from "./ast-handler-extract.ts";
-// ---------------------------------------------------------------------------
-// Virtual module for loader manifest
-// ---------------------------------------------------------------------------
-const VIRTUAL_LOADER_MANIFEST = "virtual:rsc-router/loader-manifest";
-const RESOLVED_VIRTUAL_LOADER_MANIFEST = "\0" + VIRTUAL_LOADER_MANIFEST;
-// ---------------------------------------------------------------------------
-// Virtual module prefix for extracted inline handlers
-// ---------------------------------------------------------------------------
-const VIRTUAL_HANDLER_PREFIX = "virtual:handler-extract:";
-const PRERENDER_CONFIG = {
-    fnName: "Prerender",
-    brand: "prerenderHandler",
-};
-const STATIC_CONFIG = {
-    fnName: "Static",
-    brand: "staticHandler",
-};
-const STRICT_CREATE_CONFIGS = [
-    { fnName: "createLoader" },
-    { fnName: "createHandle" },
-    { fnName: "createLocationState" },
-];
-function escapeRegExp(input) {
-    return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-/**
- * Check whether every non-type export in `code` is accounted for by the given
- * bindings. Returns false if any export exists that is not one of the known
- * create* call locals/exports, allowing callers to bail out for mixed-export
- * files.
- */
-function isExportOnlyFile(code, bindings) {
-    if (bindings.length === 0)
-        return false;
-    const knownLocals = new Set();
-    const knownExports = new Set();
-    for (const b of bindings) {
-        knownLocals.add(b.localName);
-        for (const e of b.exportNames)
-            knownExports.add(e);
-    }
-    // Bail on star re-exports (unknown exports)
-    if (/export\s*\*/.test(code))
-        return false;
-    // Check `export const/let/var/function/class/default X` declarations
-    const declExportPattern = /export\s+(const|let|var|function|class|default)\s+(\w+)/g;
-    let match;
-    while ((match = declExportPattern.exec(code)) !== null) {
-        if (!knownExports.has(match[2]))
-            return false;
-    }
-    // Check `export { X }` and `export { X as Y }` specifiers: the local name
-    // must reference a known create* binding.
-    const specExportPattern = /export\s*\{([^}]+)\}/g;
-    while ((match = specExportPattern.exec(code)) !== null) {
-        const specifiers = match[1]
-            .split(",")
-            .map((s) => s.trim())
-            .filter(Boolean);
-        for (const spec of specifiers) {
-            const m = spec.match(/^([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?$/);
-            if (!m)
-                continue;
-            const local = m[1];
-            if (!knownLocals.has(local))
-                return false;
-        }
-    }
-    return true;
-}
-// NOTE: This regex may over-count when the fn name appears inside strings or
-// comments, but it's only used for the warning heuristic (totalCalls >
-// supportedBindings) and the inline-extraction pre-check, so over-counting
-// triggers a harmless extra AST parse rather than affecting correctness.
-function countCreateCallsForNames(code, fnNames) {
-    const pattern = new RegExp(`\\b(?:${fnNames.map(escapeRegExp).join("|")})\\s*(?:<[^>]*>\\s*)?\\(`, "g");
-    return (code.match(pattern) || []).length;
-}
-function getImportedFnNames(code, importedName) {
-    const importPattern = /import\s*\{([^}]*)\}\s*from\s*["']@rangojs\/router(?:\/[^"']*)?["']/g;
-    const localNames = new Set();
-    let match;
-    while ((match = importPattern.exec(code)) !== null) {
-        const specList = match[1]
-            .split(",")
-            .map((s) => s.trim())
-            .filter(Boolean);
-        for (const spec of specList) {
-            const m = spec.match(/^([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?$/);
-            if (!m)
-                continue;
-            const imported = m[1];
-            const local = m[2] || imported;
-            if (imported === importedName) {
-                localNames.add(local);
-            }
-        }
-    }
-    const names = Array.from(localNames);
-    return names.length > 0 ? names : [importedName];
-}
-function getCalledIdentifierFromCall(callExpr) {
-    const callee = callExpr?.callee;
-    if (callee?.type === "Identifier")
-        return callee.name;
-    if (callee?.type === "TSInstantiationExpression" &&
-        callee.expression?.type === "Identifier") {
-        return callee.expression.name;
-    }
-    return null;
-}
-function collectCreateExportBindingsFallback(code, fnNames) {
-    const alternation = fnNames.map(escapeRegExp).join("|");
-    const exportConstPattern = new RegExp(`export\\s+const\\s+(\\w+)\\s*=\\s*(?:${alternation})\\s*(?:<[^>]*>)?\\s*\\(`, "g");
-    const localDeclPattern = new RegExp(`\\bconst\\s+(\\w+)\\s*=\\s*((?:${alternation})\\s*(?:<[^>]*>)?\\s*\\()`, "g");
-    const exportSpecPattern = /export\s*\{([^}]+)\}/g;
-    const exportMap = new Map();
-    const pushExport = (local, exported) => {
-        const list = exportMap.get(local);
-        if (list) {
-            if (!list.includes(exported))
-                list.push(exported);
-            return;
-        }
-        exportMap.set(local, [exported]);
-    };
-    let match;
-    while ((match = exportConstPattern.exec(code)) !== null) {
-        pushExport(match[1], match[1]);
-    }
-    while ((match = exportSpecPattern.exec(code)) !== null) {
-        const specifiers = match[1]
-            .split(",")
-            .map((s) => s.trim())
-            .filter(Boolean);
-        for (const specifier of specifiers) {
-            const specMatch = specifier.match(/^([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?$/);
-            if (!specMatch)
-                continue;
-            const local = specMatch[1];
-            const exported = specMatch[2] || local;
-            pushExport(local, exported);
-        }
-    }
-    const bindings = [];
-    while ((match = localDeclPattern.exec(code)) !== null) {
-        const localName = match[1];
-        const exportNames = exportMap.get(localName) ?? [];
-        if (exportNames.length === 0)
-            continue;
-        const openParenPos = match.index + match[0].length - 1;
-        const closeParenPos = findMatchingParen(code, openParenPos + 1) - 1;
-        if (closeParenPos <= openParenPos)
-            continue;
-        bindings.push({
-            localName,
-            exportNames,
-            callExprStart: match.index + match[0].length - match[2].length,
-            callOpenParenPos: openParenPos,
-            callCloseParenPos: closeParenPos,
-            argCount: countArgs(code, openParenPos + 1, closeParenPos),
-            statementEnd: findStatementEnd(code, closeParenPos + 1),
-        });
-    }
-    return bindings;
-}
-function collectCreateExportBindings(code, fnNames, program) {
-    if (!program) {
-        try {
-            program = parseAst(code, { jsx: true });
-        }
-        catch {
-            return collectCreateExportBindingsFallback(code, fnNames);
-        }
-    }
-    const exportMap = buildExportMap(program);
-    const fnNameSet = new Set(fnNames);
-    const bindings = [];
-    const collectFromVarDecl = (varDecl, statementEnd) => {
-        if (varDecl?.type !== "VariableDeclaration" || varDecl.kind !== "const") {
-            return;
-        }
-        for (const decl of varDecl.declarations ?? []) {
-            const calledIdentifier = getCalledIdentifierFromCall(decl?.init);
-            if (decl?.id?.type !== "Identifier" ||
-                decl?.init?.type !== "CallExpression" ||
-                !calledIdentifier ||
-                !fnNameSet.has(calledIdentifier)) {
-                continue;
-            }
-            const localName = decl.id.name;
-            const exportNames = exportMap.get(localName) ?? [];
-            if (exportNames.length === 0)
-                continue;
-            const callStart = decl.init.start;
-            const callEnd = decl.init.end;
-            const calleeEnd = decl.init.callee.end;
-            let openParenPos = -1;
-            for (let i = calleeEnd; i < callEnd; i++) {
-                if (code[i] === "(") {
-                    openParenPos = i;
-                    break;
-                }
-            }
-            if (openParenPos === -1)
-                continue;
-            const closeParenPos = findMatchingParen(code, openParenPos + 1) - 1;
-            if (closeParenPos <= openParenPos)
-                continue;
-            bindings.push({
-                localName,
-                exportNames,
-                callExprStart: decl.init.start,
-                callOpenParenPos: openParenPos,
-                callCloseParenPos: closeParenPos,
-                argCount: decl.init.arguments?.length ?? 0,
-                statementEnd,
-            });
-        }
-    };
-    for (const node of program.body ?? []) {
-        if (node?.type === "VariableDeclaration") {
-            collectFromVarDecl(node, node.end);
-            continue;
-        }
-        if (node?.type === "ExportNamedDeclaration" &&
-            node.declaration?.type === "VariableDeclaration") {
-            collectFromVarDecl(node.declaration, node.end);
-        }
-    }
-    return bindings;
-}
-function buildUnsupportedShapeWarning(filePath, fnName) {
-    return [
-        `[rsc-router] Unsupported ${fnName} shape in "${filePath}".`,
-        `Supported shapes are:`,
-        `  - export const X = ${fnName}(...)`,
-        `  - const X = ${fnName}(...); export { X }`,
-        `  - const X = ${fnName}(...); export { X as Y }`,
-        `Potentially unsupported forms include:`,
-        `  - export let/var X = ${fnName}(...)`,
-        `  - inline ${fnName}(...) calls`,
-    ].join("\n");
-}
-// ---------------------------------------------------------------------------
-// Loader helpers
-// ---------------------------------------------------------------------------
-function hasCreateLoaderImport(code) {
-    return /import\s*\{[^}]*\bcreateLoader\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/server)?["']/.test(code);
-}
-/**
- * Generate lightweight client stubs for loader files.
- *
- * When a loader file is imported from a client component (e.g., for useLoader()),
- * the client only needs { __brand: "loader", $$id: "..." } objects.
- * This function replaces the entire file contents with just those stub exports,
- * preventing server-only data (constants, DB queries, etc.) from leaking into
- * the client bundle.
- *
- * Only applies when ALL named exports are createLoader() calls (plus type exports
- * which are erased at compile time). Files with mixed exports are left untouched.
- */
-function generateClientLoaderStubs(bindings, code, filePath, isBuild) {
-    if (!isExportOnlyFile(code, bindings))
-        return null;
-    const exportNames = bindings.flatMap((b) => b.exportNames);
-    const stubs = exportNames.map((name) => {
-        const loaderId = isBuild
-            ? hashId(filePath, name)
-            : `${filePath}#${name}`;
-        return `export const ${name} = { __brand: "loader", $$id: "${loaderId}" };`;
-    });
-    return { code: stubs.join("\n") + "\n" };
-}
-function transformLoaders(bindings, s, filePath, isBuild) {
-    let hasChanges = false;
-    for (const binding of bindings) {
-        const exportName = binding.exportNames[0];
-        const loaderId = isBuild
-            ? hashId(filePath, exportName)
-            : `${filePath}#${exportName}`;
-        // Inject $$id as hidden third parameter.
-        // createLoader(fn) -> createLoader(fn, undefined, "id")
-        // createLoader(fn, true) -> createLoader(fn, true, "id")
-        const paramInjection = binding.argCount === 1
-            ? `, undefined, "${loaderId}"`
-            : `, "${loaderId}"`;
-        s.appendLeft(binding.callCloseParenPos, paramInjection);
-        const propInjection = `\n${binding.localName}.$$id = "${loaderId}";`;
-        s.appendRight(binding.statementEnd, propInjection);
-        hasChanges = true;
-    }
-    return hasChanges;
-}
-// ---------------------------------------------------------------------------
-// Handle helpers
-// ---------------------------------------------------------------------------
-function analyzeCreateHandleArgs(code, startPos, endPos) {
-    const content = code.slice(startPos, endPos).trim();
-    return { hasArgs: content.length > 0 };
-}
-function transformHandles(bindings, s, code, filePath, isBuild) {
-    let hasChanges = false;
-    for (const binding of bindings) {
-        const exportName = binding.exportNames[0];
-        const args = analyzeCreateHandleArgs(code, binding.callOpenParenPos + 1, binding.callCloseParenPos);
-        const handleId = isBuild
-            ? hashId(filePath, exportName)
-            : `${filePath}#${exportName}`;
-        let paramInjection;
-        if (!args.hasArgs) {
-            paramInjection = `undefined, "${handleId}"`;
-        }
-        else {
-            paramInjection = `, "${handleId}"`;
-        }
-        s.appendLeft(binding.callCloseParenPos, paramInjection);
-        const propInjection = `\n${binding.localName}.$$id = "${handleId}";`;
-        s.appendRight(binding.statementEnd, propInjection);
-        hasChanges = true;
-    }
-    return hasChanges;
-}
-// ---------------------------------------------------------------------------
-// LocationState helpers
-// ---------------------------------------------------------------------------
-function transformLocationState(bindings, s, filePath, isBuild) {
-    let hasChanges = false;
-    for (const binding of bindings) {
-        if (binding.argCount > 0)
-            continue; // Already has a key, skip
-        const exportName = binding.exportNames[0];
-        const stateKey = isBuild
-            ? hashId(filePath, exportName)
-            : `${filePath}#${exportName}`;
-        s.appendLeft(binding.callCloseParenPos, `"${stateKey}"`);
-        const propInjection = `\n${binding.localName}.__rsc_ls_key = "__rsc_ls_${stateKey}";`;
-        s.appendRight(binding.statementEnd, propInjection);
-        hasChanges = true;
-    }
-    return hasChanges;
-}
-// ---------------------------------------------------------------------------
-// Parameterized handler helpers (prerender + static)
-// ---------------------------------------------------------------------------
-/**
- * Replace the entire file with lightweight stubs when ALL non-type exports are
- * handler calls of the given type. Returns null for files with mixed exports.
- */
-function generateWholeFileStubs(cfg, bindings, code, filePath, isBuild) {
-    if (!isExportOnlyFile(code, bindings))
-        return null;
-    const exportNames = bindings.flatMap((b) => b.exportNames);
-    const stubs = exportNames.map((name) => {
-        const handlerId = isBuild
-            ? hashId(filePath, name)
-            : `${filePath}#${name}`;
-        return `export const ${name} = { __brand: "${cfg.brand}", $$id: "${handlerId}" };`;
-    });
-    return { code: stubs.join("\n") + "\n", map: null };
-}
-/**
- * Replace handler call expressions with lightweight stub objects in non-RSC
- * environments. Other exports, imports, and module-level code remain untouched.
- */
-function generateExprStubs(cfg, bindings, code, filePath, sourceId, isBuild) {
-    if (bindings.length === 0)
-        return null;
-    const s = new MagicString(code);
-    let hasChanges = false;
-    for (const binding of bindings) {
-        const exportName = binding.exportNames[0];
-        const handlerId = isBuild
-            ? hashId(filePath, exportName)
-            : `${filePath}#${exportName}`;
-        s.overwrite(binding.callExprStart, binding.callCloseParenPos + 1, `{ __brand: "${cfg.brand}", $$id: "${handlerId}" }`);
-        hasChanges = true;
-    }
-    if (!hasChanges)
-        return null;
-    return {
-        code: s.toString(),
-        map: s.generateMap({
-            source: sourceId,
-            includeContent: true,
-            hires: "boundary",
-        }),
-    };
-}
-/**
- * Inject $$id into export const handler calls in RSC environments.
- */
-function transformHandlerIds(cfg, bindings, s, filePath, isBuild) {
-    let hasChanges = false;
-    for (const binding of bindings) {
-        const exportName = binding.exportNames[0];
-        const handlerId = isBuild
-            ? hashId(filePath, exportName)
-            : `${filePath}#${exportName}`;
-        // Injection strategy matches the runtime overload signatures:
-        //   0 args                              -> inject undefined, "id"
-        //   1 arg  (handler)                    -> inject , undefined, "id"
-        //   2+ args                             -> inject , "id"
-        let paramInjection;
-        if (binding.argCount === 0) {
-            paramInjection = `undefined, "${handlerId}"`;
-        }
-        else if (binding.argCount === 1) {
-            paramInjection = `, undefined, "${handlerId}"`;
-        }
-        else {
-            paramInjection = `, "${handlerId}"`;
-        }
-        s.appendLeft(binding.callCloseParenPos, paramInjection);
-        const propInjection = `\n${binding.localName}.$$id = "${handlerId}";`;
-        s.appendRight(binding.statementEnd, propInjection);
-        hasChanges = true;
-    }
-    return hasChanges;
-}
-// ---------------------------------------------------------------------------
-// Router helpers
-// ---------------------------------------------------------------------------
-function transformRouter(code, filePath, routerFnNames) {
-    const pat = new RegExp(`\\b(?:${routerFnNames.map(escapeRegExp).join("|")})\\s*(?:<[^>]*>)?\\s*\\(`, "g");
-    let match;
-    const s = new MagicString(code);
-    let changed = false;
-    // Compute the import path for the generated route names file.
-    // filePath is relative to project root (e.g., "src/router.tsx")
-    const basename = path.basename(filePath).replace(/\.(tsx?|jsx?)$/, "");
-    const routeNamesImport = `./${basename}.named-routes.gen.js`;
-    const routeNamesVar = `__rsc_rn`;
-    while ((match = pat.exec(code)) !== null) {
-        const callStart = match.index;
-        const parenPos = match.index + match[0].length - 1;
-        const afterParen = code.slice(parenPos + 1).trimStart();
-        // Skip if $$id is already present
-        if (afterParen.includes("$$id"))
-            continue;
-        // Compute line number for this call
-        const lineNumber = code.slice(0, callStart).split("\n").length;
-        const hash = createHash("sha256")
-            .update(`${filePath}:${lineNumber}`)
-            .digest("hex")
-            .slice(0, 8);
-        changed = true;
-        const injected = ` $$id: "${hash}", $$routeNames: ${routeNamesVar},`;
-        if (afterParen.startsWith("{")) {
-            const bracePos = code.indexOf("{", parenPos + 1);
-            s.appendRight(bracePos + 1, injected);
-        }
-        else if (afterParen.startsWith(")")) {
-            s.appendRight(parenPos + 1, `{${injected} }`);
-        }
-    }
-    if (!changed)
-        return null;
-    // Prepend the static import as the first line. MagicString tracks the
-    // offset so all downstream source maps remain correct.
-    s.prepend(`import { NamedRoutes as ${routeNamesVar} } from "${routeNamesImport}";\n`);
-    return {
-        code: s.toString(),
-        map: s.generateMap({ hires: true }),
-    };
-}
-// ---------------------------------------------------------------------------
-// Router ID plugin (separate: must run at normal priority, NOT "post")
-// ---------------------------------------------------------------------------
-/**
- * Inject stable $$id into createRouter() calls at compile time.
- * This must be a separate plugin without enforce:"post" because running
- * at "post" priority changes Vite's dep optimization timing and can cause
- * ERR_OUTDATED_OPTIMIZED_DEP / React dual-instance issues.
- */
-export function exposeRouterId() {
-    let projectRoot = "";
-    return {
-        name: "@rangojs/router:expose-router-id",
-        configResolved(config) {
-            projectRoot = config.root;
-        },
-        transform(code, id) {
-            if (!code.includes("createRouter"))
-                return null;
-            if (!/import\s*\{[^}]*\bcreateRouter\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/server)?["']/.test(code)) {
-                return null;
-            }
-            if (id.includes("node_modules"))
-                return null;
-            const filePath = normalizePath(path.relative(projectRoot, id));
-            const routerFnNames = getImportedFnNames(code, "createRouter");
-            return transformRouter(code, filePath, routerFnNames);
-        },
-    };
-}
-// ---------------------------------------------------------------------------
-// Consolidated plugin
-// ---------------------------------------------------------------------------
-export function exposeInternalIds(options) {
-    let config;
-    let isBuild = false;
-    let projectRoot = "";
-    // Loader registry: hashedId -> { filePath, exportName }
-    const loaderRegistry = new Map();
-    // Prerender handler module tracking (consumed via plugin API)
-    const prerenderHandlerModules = new Map();
-    // Static handler module tracking (consumed via plugin API)
-    const staticHandlerModules = new Map();
-    // Virtual module registry for inline handler extraction (both types)
-    const virtualHandlers = new Map();
-    // De-duplicate unsupported shape warnings across repeated transforms.
-    const unsupportedShapeWarnings = new Set();
-    return {
-        name: "@rangojs/router:expose-internal-ids",
-        enforce: "post",
-        api: {
-            prerenderHandlerModules,
-            staticHandlerModules,
-        },
-        configResolved(resolved) {
-            config = resolved;
-            isBuild = options?.forceBuild || config.command === "build";
-            projectRoot = config.root;
-        },
-        // --------------- Virtual module support ---------------
-        resolveId(id, importer) {
-            if (id === VIRTUAL_LOADER_MANIFEST) {
-                return RESOLVED_VIRTUAL_LOADER_MANIFEST;
-            }
-            if (id.startsWith(VIRTUAL_HANDLER_PREFIX)) {
-                return "\0" + id;
-            }
-            // Resolve imports FROM virtual modules against the original file
-            if (importer?.startsWith("\0" + VIRTUAL_HANDLER_PREFIX)) {
-                const entry = virtualHandlers.get(importer);
-                if (entry) {
-                    return this.resolve(id, entry.originalModuleId, { skipSelf: true });
-                }
-            }
-        },
-        load(id) {
-            // Virtual handler modules (both prerender and static)
-            if (id.startsWith("\0" + VIRTUAL_HANDLER_PREFIX)) {
-                const entry = virtualHandlers.get(id);
-                if (!entry)
-                    return null;
-                return [
-                    ...entry.imports,
-                    `export const ${entry.exportName} = ${entry.handlerCode};`,
-                ].join("\n") + "\n";
-            }
-            if (id !== RESOLVED_VIRTUAL_LOADER_MANIFEST)
-                return;
-            if (!isBuild) {
-                return `import { setLoaderImports } from "@rangojs/router/server";
-
-// Dev mode: empty map, loaders are resolved dynamically via path parsing
-setLoaderImports({});
-`;
-            }
-            // Build mode: generate lazy import map
-            const lazyImports = [];
-            for (const [hashedId, { filePath, exportName }] of loaderRegistry) {
-                lazyImports.push(`  "${hashedId}": () => import("/${filePath}").then(m => m.${exportName})`);
-            }
-            if (lazyImports.length === 0) {
-                return `import { setLoaderImports } from "@rangojs/router/server";
-
-// No fetchable loaders discovered during build
-setLoaderImports({});
-`;
-            }
-            return `import { setLoaderImports } from "@rangojs/router/server";
-
-// Lazy import map - loaders are loaded on-demand when first requested
-setLoaderImports({
-${lazyImports.join(",\n")}
-});
-`;
-        },
-        // --------------- Loader pre-scan (build mode) ---------------
-        async buildStart() {
-            if (!isBuild)
-                return;
-            const fs = await import("node:fs/promises");
-            async function scanDir(dir) {
-                const results = [];
-                try {
-                    const entries = await fs.readdir(dir, { withFileTypes: true });
-                    for (const entry of entries) {
-                        const fullPath = path.join(dir, entry.name);
-                        if (entry.isDirectory()) {
-                            if (entry.name !== "node_modules") {
-                                results.push(...(await scanDir(fullPath)));
-                            }
-                        }
-                        else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) {
-                            results.push(fullPath);
-                        }
-                    }
-                }
-                catch {
-                    // Directory doesn't exist or not readable
-                }
-                return results;
-            }
-            try {
-                const srcDir = path.join(projectRoot, "src");
-                const files = await scanDir(srcDir);
-                for (const filePath of files) {
-                    const content = await fs.readFile(filePath, "utf-8");
-                    if (!content.includes("createLoader"))
-                        continue;
-                    if (!hasCreateLoaderImport(content))
-                        continue;
-                    const fnNames = getImportedFnNames(content, "createLoader");
-                    const relativePath = normalizePath(path.relative(projectRoot, filePath));
-                    const bindings = collectCreateExportBindings(content, fnNames);
-                    for (const binding of bindings) {
-                        const exportName = binding.exportNames[0];
-                        const hashedId = hashId(relativePath, exportName);
-                        loaderRegistry.set(hashedId, {
-                            filePath: relativePath,
-                            exportName,
-                        });
-                    }
-                }
-            }
-            catch (error) {
-                console.warn("[exposeInternalIds] Loader pre-scan failed:", error);
-            }
-        },
-        // --------------- Unified transform ---------------
-        transform(code, id) {
-            if (id.includes("/node_modules/"))
-                return;
-            const filePath = normalizePath(path.relative(projectRoot, id));
-            const isRscEnv = this.environment?.name === "rsc";
-            // Warn if named-routes.gen is imported in a client component.
-            // NamedRoutes is server-only data and would bloat the client bundle.
-            if (id.includes(".named-routes.gen.") && !isRscEnv && this.environment?.name === "client") {
-                this.warn(`\n` +
-                    `!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n` +
-                    `!!                                                              !!\n` +
-                    `!!  WARNING: NamedRoutes imported in a CLIENT component!        !!\n` +
-                    `!!                                                              !!\n` +
-                    `!!  File: ${filePath.padEnd(53)}!!\n` +
-                    `!!                                                              !!\n` +
-                    `!!  NamedRoutes contains your entire route structure — every    !!\n` +
-                    `!!  route name and URL pattern in your application. Shipping    !!\n` +
-                    `!!  this to the browser exposes your full routing topology to   !!\n` +
-                    `!!  the client, which is a security concern (internal/admin     !!\n` +
-                    `!!  routes, API endpoints, hidden paths become visible).        !!\n` +
-                    `!!                                                              !!\n` +
-                    `!!  It also bloats the client bundle — this map contains all    !!\n` +
-                    `!!  named routes in your application.                           !!\n` +
-                    `!!                                                              !!\n` +
-                    `!!  Fix: remove the import or move it to a server component.    !!\n` +
-                    `!!                                                              !!\n` +
-                    `!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n`);
-            }
-            // Fast exit: if the file doesn't import from @rangojs/router at all,
-            // skip all create* analysis and transforms.
-            if (!code.includes("@rangojs/router"))
-                return;
-            // Detect all relevant imports in one pass
-            const has = detectImports(code);
-            // Quick bail-out: also check for raw create* identifiers.
-            // This is safe even with aliases (e.g., `import { createLoader as cl }`)
-            // because the import statement itself always contains the canonical name
-            // "createLoader", so code.includes("createLoader") will still match.
-            const hasLoaderCode = has.loader && code.includes("createLoader");
-            const hasHandleCode = has.handle && code.includes("createHandle");
-            const hasLocationStateCode = has.locationState && code.includes("createLocationState");
-            const hasPrerenderHandlerCode = has.prerenderHandler && code.includes("Prerender");
-            const hasStaticHandlerCode = has.staticHandler && code.includes("Static");
-            if (!hasLoaderCode &&
-                !hasHandleCode &&
-                !hasLocationStateCode &&
-                !hasPrerenderHandlerCode &&
-                !hasStaticHandlerCode) {
-                return;
-            }
-            // Per-invocation caches to avoid redundant AST parsing.
-            // getImportedFnNames is cached by canonical name (imports never change).
-            // collectCreateExportBindings is cached by fnNames key; the cache is
-            // cleared when `code` changes (e.g., after inline handler extraction).
-            const _fnNamesCache = new Map();
-            const _bindingsCache = new Map();
-            let _cachedAst;
-            let _astParseFailed = false;
-            let _astCodeRef = code;
-            const getFnNames = (canonicalName) => {
-                let result = _fnNamesCache.get(canonicalName);
-                if (!result) {
-                    result = getImportedFnNames(code, canonicalName);
-                    _fnNamesCache.set(canonicalName, result);
-                }
-                return result;
-            };
-            // Lazy AST parse: parsed once and shared across all
-            // collectCreateExportBindings calls for the same code string.
-            const lazyAst = () => {
-                if (code !== _astCodeRef) {
-                    _cachedAst = undefined;
-                    _astParseFailed = false;
-                    _astCodeRef = code;
-                }
-                if (_cachedAst !== undefined || _astParseFailed)
-                    return _cachedAst;
-                try {
-                    _cachedAst = parseAst(code, { jsx: true });
-                }
-                catch {
-                    _astParseFailed = true;
-                }
-                return _cachedAst;
-            };
-            const getBindings = (currentCode, fnNames) => {
-                const key = fnNames.join("\0");
-                let result = _bindingsCache.get(key);
-                if (!result) {
-                    result = collectCreateExportBindings(currentCode, fnNames, lazyAst());
-                    _bindingsCache.set(key, result);
-                }
-                return result;
-            };
-            // Warn on create* declaration shapes that are currently unsupported by
-            // non-AST transforms (loader/handle/locationState only).
-            for (const cfg of STRICT_CREATE_CONFIGS) {
-                const hasCode = cfg.fnName === "createLoader"
-                    ? hasLoaderCode
-                    : cfg.fnName === "createHandle"
-                        ? hasHandleCode
-                        : hasLocationStateCode;
-                if (!hasCode)
-                    continue;
-                const fnNames = getFnNames(cfg.fnName);
-                const totalCalls = countCreateCallsForNames(code, fnNames);
-                const supportedBindings = getBindings(code, fnNames).length;
-                if (totalCalls <= supportedBindings)
-                    continue;
-                const warnKey = `${id}::${cfg.fnName}`;
-                if (unsupportedShapeWarnings.has(warnKey))
-                    continue;
-                unsupportedShapeWarnings.add(warnKey);
-                this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName));
-            }
-            // --- Loader: track for manifest (RSC env only) ---
-            if (hasLoaderCode && isRscEnv) {
-                const fnNames = getFnNames("createLoader");
-                const bindings = getBindings(code, fnNames);
-                for (const binding of bindings) {
-                    const exportName = binding.exportNames[0];
-                    const hashedId = hashId(filePath, exportName);
-                    loaderRegistry.set(hashedId, {
-                        filePath,
-                        exportName,
-                    });
-                }
-            }
-            // --- Loader: client stubs for non-RSC environments ---
-            if (hasLoaderCode && !isRscEnv) {
-                const fnNames = getFnNames("createLoader");
-                const bindings = getBindings(code, fnNames);
-                const stubResult = generateClientLoaderStubs(bindings, code, filePath, isBuild);
-                if (stubResult)
-                    return stubResult;
-            }
-            // --- PrerenderHandler: non-RSC stub replacement ---
-            if (hasPrerenderHandlerCode && !isRscEnv) {
-                const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-                const bindings = getBindings(code, fnNames);
-                const wholeFile = generateWholeFileStubs(PRERENDER_CONFIG, bindings, code, filePath, isBuild);
-                if (wholeFile)
-                    return wholeFile;
-                const exprStubs = generateExprStubs(PRERENDER_CONFIG, bindings, code, filePath, id, isBuild);
-                if (exprStubs)
-                    return exprStubs;
-            }
-            // --- PrerenderHandler: RSC build module tracking ---
-            if (hasPrerenderHandlerCode && isRscEnv && isBuild) {
-                const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-                const exportNames = getBindings(code, fnNames)
-                    .map((b) => b.exportNames[0]);
-                if (exportNames.length > 0) {
-                    prerenderHandlerModules.set(id, exportNames);
-                }
-            }
-            // --- Inline handler extraction to virtual modules ---
-            // Runs before stubs/tracking so inline calls become imports, then
-            // the existing regex fast path handles both the original file's
-            // export const patterns and the virtual modules independently.
-            //
-            // Cheap pre-check: count total fnName( occurrences vs export const
-            // patterns. If they match, every call is a named export and the
-            // regex fast path handles them -- skip the AST parse entirely.
-            //
-            // Each iteration creates a fresh MagicString so that AST positions
-            // from findHandlerCalls always match the string they were parsed from.
-            let changed = false;
-            const handlerConfigs = [
-                hasStaticHandlerCode && STATIC_CONFIG,
-                hasPrerenderHandlerCode && PRERENDER_CONFIG,
-            ].filter((c) => !!c).map((cfg) => {
-                const fnNames = getFnNames(cfg.fnName);
-                return { cfg, fnNames };
-            });
-            for (const { cfg, fnNames } of handlerConfigs) {
-                const totalCalls = countCreateCallsForNames(code, fnNames);
-                const supportedBindings = getBindings(code, fnNames).length;
-                if (totalCalls > supportedBindings) {
-                    const iterS = new MagicString(code);
-                    const result = transformInlineHandlers(cfg.fnName, VIRTUAL_HANDLER_PREFIX, iterS, code, filePath, virtualHandlers, id, parseAst);
-                    if (result) {
-                        changed = true;
-                        code = iterS.toString();
-                        _bindingsCache.clear();
-                    }
-                }
-            }
-            // --- StaticHandler: non-RSC stub replacement ---
-            if (hasStaticHandlerCode && !isRscEnv) {
-                const fnNames = getFnNames(STATIC_CONFIG.fnName);
-                const bindings = getBindings(code, fnNames);
-                const wholeFile = generateWholeFileStubs(STATIC_CONFIG, bindings, code, filePath, isBuild);
-                if (wholeFile)
-                    return wholeFile;
-                const exprStubs = generateExprStubs(STATIC_CONFIG, bindings, code, filePath, id, isBuild);
-                if (exprStubs)
-                    return exprStubs;
-            }
-            // --- StaticHandler: RSC build module tracking ---
-            if (hasStaticHandlerCode && isRscEnv && isBuild) {
-                const fnNames = getFnNames(STATIC_CONFIG.fnName);
-                const exportNames = getBindings(code, fnNames)
-                    .map((b) => b.exportNames[0]);
-                if (exportNames.length > 0) {
-                    staticHandlerModules.set(id, exportNames);
-                }
-            }
-            // --- Unified MagicString transforms ---
-            // Single pipeline for all downstream transforms (loaders, handles,
-            // locationState, handler IDs). Uses the post-extraction code so
-            // positions are always consistent.
-            const s = new MagicString(code);
-            if (hasLoaderCode) {
-                const fnNames = getFnNames("createLoader");
-                changed = transformLoaders(getBindings(code, fnNames), s, filePath, isBuild) || changed;
-            }
-            if (hasHandleCode) {
-                const fnNames = getFnNames("createHandle");
-                changed = transformHandles(getBindings(code, fnNames), s, code, filePath, isBuild) || changed;
-            }
-            if (hasLocationStateCode) {
-                const fnNames = getFnNames("createLocationState");
-                changed =
-                    transformLocationState(getBindings(code, fnNames), s, filePath, isBuild) || changed;
-            }
-            if (hasPrerenderHandlerCode && isRscEnv) {
-                const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-                changed =
-                    transformHandlerIds(PRERENDER_CONFIG, getBindings(code, fnNames), s, filePath, isBuild) || changed;
-            }
-            if (hasStaticHandlerCode && isRscEnv) {
-                const fnNames = getFnNames(STATIC_CONFIG.fnName);
-                changed =
-                    transformHandlerIds(STATIC_CONFIG, getBindings(code, fnNames), s, filePath, isBuild) || changed;
-            }
-            if (!changed)
-                return;
-            return {
-                code: s.toString(),
-                map: s.generateMap({ source: id, includeContent: true }),
-            };
-        },
-    };
-}
-//# sourceMappingURL=expose-internal-ids.js.map