@reckona/mreact-router 0.0.81 → 0.0.83

package/src/client-route-inference.ts

@@ -0,0 +1,18 @@
+export {
+  collectClientRouteReferences,
+  compilerModuleContextForSource,
+  createClientRouteInferenceCache,
+  detectClientNavigationHint,
+  detectNavigationRuntimeHint,
+  formatClientRouteInferenceDiagnostic,
+  inferClientRouteModule,
+  isClientRouteModule,
+  isClientRouteSource,
+  routeToClientManifestEntry,
+  type ClientReferenceImport,
+  type ClientRouteInferenceCache,
+  type ClientRouteInferenceDiagnostic,
+  type ClientRouteInferenceResult,
+  type ClientRouteManifestEntry,
+  type ClientRouteReferenceResult,
+} from "./client.js";

package/src/client.ts

@@ -3,15 +3,17 @@ import { readFile, stat } from "node:fs/promises";
 import { builtinModules } from "node:module";
 import { dirname, extname, join, relative, sep } from "node:path";
 import {
+  analyzeBoundaryGraph,
   collectClientRouteModuleAnalysis,
   formatDiagnostic,
   type ComponentMetadata,
+  type BoundaryGraphResult,
   type ClientRouteModuleAnalysis,
   type ClientRouteStaticImportReference,
-  type ClientReferenceMetadata,
   type StaticImportReference,
   type TopLevelExportRenderInfo,
 } from "@reckona/mreact-compiler";
+import type { ClientReferenceMetadata } from "@reckona/mreact-shared/compiler-contract";
 import {
   collectClientRouteModuleAnalysisFromContext,
   createCompilerModuleContext,
@@ -29,6 +31,11 @@ import {
 } from "./bundle-pipeline.js";
 import type { AppRoute } from "./routes.js";
 import { existingRouteShellCandidates } from "./route-shells.js";
+import {
+  routeDataScriptIds,
+  routeDataScriptSelector,
+  routeHydrationContract,
+} from "./route-hydration-contract.js";
 import { stripRouteClientSource } from "./route-source.js";
 import { hasJsxSyntax } from "./source-jsx.js";
 import { sourceModuleCandidates } from "./source-modules.js";
@@ -103,6 +110,8 @@ export interface ClientRouteInferenceResult {
 }
 
 interface ClientRouteModuleInferenceResult extends ClientRouteInferenceResult {
+  boundaryGraphFallbackCandidate: boolean;
+  boundaryGraphFallbackRequired: boolean;
   clientBoundaryExportNames: string[];
   clientBoundaryModule: boolean;
   nestedClientExportNames: string[];
@@ -211,9 +220,20 @@ export async function inferClientRouteModule(options: {
       seen: new Set(),
       sourceTransform,
     });
+    const mergedRouteInference = routeInference.boundaryGraphFallbackRequired
+      ? mergeClientRouteInference(
+          routeInference,
+          await inferClientRouteModuleBoundaryGraph({
+            cache,
+            code,
+            filename: options.filename,
+            sourceTransform,
+          }),
+        )
+      : routeInference;
 
     if (options.appDir === undefined) {
-      return routeInference;
+      return mergedRouteInference;
     }
 
     const shellInferences = await inferClientRouteShellModules({
@@ -224,10 +244,10 @@ export async function inferClientRouteModule(options: {
     });
 
     return {
-      client: routeInference.client || shellInferences.some((inference) => inference.client),
-      clientBoundaryImports: routeInference.clientBoundaryImports,
+      client: mergedRouteInference.client || shellInferences.some((inference) => inference.client),
+      clientBoundaryImports: mergedRouteInference.clientBoundaryImports,
       diagnostics: [
-        ...routeInference.diagnostics,
+        ...mergedRouteInference.diagnostics,
         ...shellInferences.flatMap((inference) => inference.diagnostics),
       ],
     };
@@ -239,6 +259,68 @@ export async function inferClientRouteModule(options: {
   }
 }
 
+async function inferClientRouteModuleBoundaryGraph(options: {
+  cache: ClientRouteInferenceCache;
+  code: string;
+  filename: string;
+  sourceTransform?: ClientRouteSourceTransform | undefined;
+}): Promise<ClientRouteInferenceResult> {
+  const graph = await analyzeBoundaryGraph({
+    entries: [{ file: options.filename, kind: "route-page" }],
+    readModule: async (file) => {
+      if (file === options.filename) {
+        return options.code;
+      }
+
+      return await readClientRouteSource({
+        cache: options.cache,
+        filename: file,
+        sourceTransform: options.sourceTransform,
+      });
+    },
+    resolveModule: async ({ importer, source }) =>
+      await resolveAppLocalModule({
+        allowExplicitNonSource: options.sourceTransform !== undefined,
+        cache: options.cache,
+        importer,
+        specifier: source,
+      }),
+  });
+
+  return clientRouteInferenceFromBoundaryGraph(graph, options.filename);
+}
+
+function clientRouteInferenceFromBoundaryGraph(
+  graph: BoundaryGraphResult,
+  filename: string,
+): ClientRouteInferenceResult {
+  const clientBoundaryImports = graph.clientBoundaries
+    .filter((boundary) => boundary.importerFile === filename)
+    .map((boundary) => boundary.source);
+  const clientRoute = graph.modules.some(
+    (module) => module.file === filename && module.classification === "client-route",
+  );
+
+  return {
+    client: clientRoute || clientBoundaryImports.length > 0,
+    clientBoundaryImports,
+    diagnostics: [],
+  };
+}
+
+function mergeClientRouteInference(
+  left: ClientRouteInferenceResult,
+  right: ClientRouteInferenceResult,
+): ClientRouteInferenceResult {
+  return {
+    client: left.client || right.client,
+    clientBoundaryImports: Array.from(
+      new Set([...left.clientBoundaryImports, ...right.clientBoundaryImports]),
+    ),
+    diagnostics: [...left.diagnostics, ...right.diagnostics],
+  };
+}
+
 export async function collectClientRouteReferences(options: {
   appDir?: string | undefined;
   cache?: ClientRouteInferenceCache | undefined;
@@ -534,6 +616,7 @@ async function inferClientRouteModuleSource(options: {
     const nestedClientExportNames = new Set<string>();
     const clientReferenceSourceFiles: string[] = [];
     const diagnostics: ClientRouteInferenceDiagnostic[] = [];
+    let boundaryGraphFallbackRequired = false;
     let clientProxy = false;
     let nestedClient = false;
     const exportInfo = analysis.topLevelExportRenderInfo;
@@ -605,6 +688,9 @@ async function inferClientRouteModuleSource(options: {
       diagnostics.push(...imported.diagnostics);
 
       if (!imported.client) {
+        if (rendered && imported.boundaryGraphFallbackCandidate) {
+          boundaryGraphFallbackRequired = true;
+        }
         if (imported.serverOnlyClientRuntime && rendered) {
           diagnostics.push(
             serverOnlyClientImportReferenceDiagnostic({
@@ -706,11 +792,16 @@ async function inferClientRouteModuleSource(options: {
         } else if (exported.client) {
           nestedClient = true;
           clientReferenceSourceFiles.push(resolved);
+        } else if (exported.boundaryGraphFallbackCandidate) {
+          boundaryGraphFallbackRequired = true;
         }
       }
     }
 
     return {
+      boundaryGraphFallbackCandidate:
+        analysis.staticExports.length > 0 || boundaryGraphFallbackRequired,
+      boundaryGraphFallbackRequired,
       client:
         clientBoundaryImports.length > 0 ||
         clientBoundaryExportNames.size > 0 ||
@@ -735,6 +826,8 @@ function emptyClientRouteModuleInferenceResult(
   overrides: Partial<ClientRouteModuleInferenceResult> = {},
 ): ClientRouteModuleInferenceResult {
   return {
+    boundaryGraphFallbackCandidate: false,
+    boundaryGraphFallbackRequired: false,
     client: false,
     clientBoundaryImports: [],
     clientBoundaryExportNames: [],
@@ -1287,7 +1380,7 @@ export function withHydrationMarkers(options: {
 export function withRouteMarkers(options: { html: string; routePath: string }): string {
   const routeId = routeIdForPath(options.routePath);
 
-  return `<div data-mreact-route-id="${escapeHtmlAttribute(routeId)}">${options.html}</div>`;
+  return `<div ${routeHydrationContract.routeMarkerAttribute}="${escapeHtmlAttribute(routeId)}">${options.html}</div>`;
 }
 
 export function hydrationMarkerParts(options: {
@@ -1299,6 +1392,9 @@ export function hydrationMarkerParts(options: {
 }): { prefix: string; suffix: string } {
   const routeId = routeIdForPath(options.routePath);
   const escapedRouteId = escapeHtmlAttribute(routeId);
+  const [propsScriptId, clientReferencesScriptId] = routeDataScriptIds(routeId).map((id) =>
+    escapeHtmlAttribute(id),
+  );
   const propsJson = escapeScriptJson(JSON.stringify(options.props));
   const script = options.script ?? clientScriptForPath(options.routePath);
   const scriptSrc = assetPath(script, options.assetBaseUrl ?? "/_mreact/client/");
@@ -1308,13 +1404,13 @@ export function hydrationMarkerParts(options: {
       : escapeScriptJson(JSON.stringify(options.clientReferenceManifest));
 
   return {
-    prefix: `<div data-mreact-route-id="${escapedRouteId}">`,
+    prefix: `<div ${routeHydrationContract.routeMarkerAttribute}="${escapedRouteId}">`,
     suffix: [
       "</div>",
-      `<script type="application/json" id="mreact-props-${escapedRouteId}">${propsJson}</script>`,
+      `<script type="application/json" id="${propsScriptId}">${propsJson}</script>`,
       clientReferencesJson === undefined
         ? undefined
-        : `<script type="application/json" id="mreact-client-references-${escapedRouteId}">${clientReferencesJson}</script>`,
+        : `<script type="application/json" id="${clientReferencesScriptId}">${clientReferencesJson}</script>`,
       `<script type="module" src="${escapeHtmlAttribute(scriptSrc)}"></script>`,
     ]
       .filter((part): part is string => part !== undefined)
@@ -1670,7 +1766,7 @@ function __mreactResolveRouteNode(value) {
   const boundaryOnlyHydrationBlock = routeRequiresFullHydration
     ? ""
     : `${routeCellHydrationIndent}if (!__mreactHasNonSerializableClientBoundaries(__mreactMarker) && __mreactHydrateClientBoundaries(document, __mreactClientReferences, __mreactClientReferenceComponents)) {
-${routeCellHydrationIndent}  __mreactMarker.setAttribute("data-mreact-hydrated", "true");
+${routeCellHydrationIndent}  __mreactMarker.setAttribute(${JSON.stringify(routeHydrationContract.hydratedAttribute)}, "true");
 ${routeCellHydrationIndent}  return;
 ${routeCellHydrationIndent}}
 `;
@@ -1681,8 +1777,12 @@ ${routeCellHydrationIndent}}
   const entry = `${routeCellEffectImport}${routeCleanupScopeImport}${emitCompatClientReferenceImportBlock(compatClientReferenceNames)}${clientReferenceImportBlock}${routeHydrationCode}
 
 const __mreactRouteId = ${JSON.stringify(routeId)};
-const __mreactRouteStateSignature = ${JSON.stringify(routeStateSignature)};
-const __mreactGlobal = globalThis;
+  const __mreactRouteStateSignature = ${JSON.stringify(routeStateSignature)};
+  const __mreactRouteMarkerAttribute = ${JSON.stringify(routeHydrationContract.routeMarkerAttribute)};
+  const __mreactRouteHydratedAttribute = ${JSON.stringify(routeHydrationContract.hydratedAttribute)};
+  const __mreactPropsScriptPrefix = ${JSON.stringify(routeHydrationContract.propsScriptPrefix)};
+  const __mreactClientReferencesScriptPrefix = ${JSON.stringify(routeHydrationContract.clientReferencesScriptPrefix)};
+  const __mreactGlobal = globalThis;
 ${navigationStateDeclaration}
 ${routeCellStateDeclaration}
 ${routeCleanupStateDeclaration}
@@ -1692,9 +1792,9 @@ ${routeNodeResolver}
 
 export function __mreactHydrateRoute() {
   __mreactApplyOutOfOrderFragments(document);
-  const __mreactMarker = document.querySelector(\`[data-mreact-route-id="\${__mreactRouteId}"]\`);
-  const __mreactPropsElement = document.getElementById(\`mreact-props-\${__mreactRouteId}\`);
-  const __mreactClientReferencesElement = document.getElementById(\`mreact-client-references-\${__mreactRouteId}\`);
+  const __mreactMarker = document.querySelector(\`[\${__mreactRouteMarkerAttribute}="\${__mreactRouteId}"]\`);
+  const __mreactPropsElement = document.getElementById(\`\${__mreactPropsScriptPrefix}\${__mreactRouteId}\`);
+  const __mreactClientReferencesElement = document.getElementById(\`\${__mreactClientReferencesScriptPrefix}\${__mreactRouteId}\`);
   const __mreactProps = __mreactPropsElement?.textContent === undefined
     ? {}
     : JSON.parse(__mreactPropsElement.textContent);
@@ -1711,7 +1811,7 @@ export function __mreactHydrateRoute() {
 ${routeCellHydrationStart}${routeCleanupHydrationStart}${boundaryOnlyHydrationBlock}${routeComponentGuard}${routeCellHydrationIndent}const __mreactNode = ${routeNodeExpression};
 ${routeCellHydrationIndent}__mreactResumeRoute(__mreactMarker, __mreactNode);
 ${routeCellHydrationIndent}__mreactHydrateClientBoundaries(document, __mreactClientReferences, __mreactClientReferenceComponents);
-${routeCellHydrationIndent}__mreactMarker.setAttribute("data-mreact-hydrated", "true");
+${routeCellHydrationIndent}__mreactMarker.setAttribute(__mreactRouteHydratedAttribute, "true");
 ${routeCellHydrationEnd}}
 ${routeCellDropFunction}
 ${routeCleanupFunction}
@@ -2098,15 +2198,15 @@ function __mreactApplyNavigationHtml(html, url) {
   const template = document.createElement("template");
   template.innerHTML = html.replace(/^\\s*<!doctype html>/i, "");
   __mreactApplyOutOfOrderFragments(template.content);
-  const nextMarker = template.content.querySelector("[data-mreact-route-id]");
-  const currentMarker = document.querySelector("[data-mreact-route-id]");
+  const nextMarker = template.content.querySelector("[${routeHydrationContract.routeMarkerAttribute}]");
+  const currentMarker = document.querySelector("[${routeHydrationContract.routeMarkerAttribute}]");
 
   if (nextMarker === null || currentMarker === null) {
     return false;
   }
 
-  const currentRouteId = currentMarker.getAttribute("data-mreact-route-id");
-  const nextRouteId = nextMarker.getAttribute("data-mreact-route-id");
+  const currentRouteId = currentMarker.getAttribute("${routeHydrationContract.routeMarkerAttribute}");
+  const nextRouteId = nextMarker.getAttribute("${routeHydrationContract.routeMarkerAttribute}");
 
   __mreactSyncHeadMetadata(template.content, html);
   __mreactResumeNode(currentMarker, nextMarker);
@@ -2114,7 +2214,7 @@ ${routeCleanupNavigationDispose}  __mreactSyncRouteDataScripts(template.content,
 
   const script = template.content.querySelector('script[type="module"][src]')?.getAttribute("src");
   if (script !== null && script !== undefined) {
-    void import(/* @vite-ignore */ script).then((module) => module.__mreactHydrateRoute?.());
+    void import(/* @vite-ignore */ script).then((module) => module.${routeHydrationContract.routeHydrateExport}?.());
   }
 
   __mreactApplyOutOfOrderFragments(document);
@@ -2207,15 +2307,15 @@ function __mreactRouteDataScriptIds(...routeIds) {
       continue;
     }
 
-    ids.add(\`mreact-props-\${routeId}\`);
-    ids.add(\`mreact-client-references-\${routeId}\`);
+    ids.add(\`${routeHydrationContract.propsScriptPrefix}\${routeId}\`);
+    ids.add(\`${routeHydrationContract.clientReferencesScriptPrefix}\${routeId}\`);
   }
 
   return ids;
 }
 
 function __mreactRouteDataScriptSelector() {
-  return 'script[type="application/json"][id^="mreact-props-"], script[type="application/json"][id^="mreact-client-references-"]';
+  return ${JSON.stringify(routeDataScriptSelector())};
 }
 
 function __mreactCurrentHistoryState(url) {

package/src/layout-composer.ts

@@ -0,0 +1,142 @@
+import { relative, sep } from "node:path";
+import { escapeHtmlAttribute } from "@reckona/mreact-shared/html-escape";
+
+export interface SlotRenderContext {
+  consumedSlots: Set<string>;
+  namedSlots: Readonly<Record<string, string>>;
+}
+
+export interface ShellFile {
+  file: string;
+  id: string;
+  kind: "layout" | "template";
+}
+
+export interface RenderedShellParts {
+  prefix: string;
+  suffix: string;
+}
+
+export function createSlotRenderContext(
+  namedSlots: Readonly<Record<string, string>> = {},
+): SlotRenderContext {
+  return {
+    consumedSlots: new Set(),
+    namedSlots,
+  };
+}
+
+export function splitLayoutSlot(
+  layoutHtml: string,
+  slotContext: SlotRenderContext = createSlotRenderContext(),
+): RenderedShellParts {
+  const html = replaceNamedLayoutSlots(layoutHtml, slotContext);
+  const match = findDefaultLayoutSlot(html);
+
+  if (match === null) {
+    return { prefix: html, suffix: "" };
+  }
+
+  return {
+    prefix: html.slice(0, match.index),
+    suffix: html.slice(match.index + match[0].length),
+  };
+}
+
+export function markShellBoundary(html: string, shell: ShellFile): string {
+  const attributeName =
+    shell.kind === "layout" ? "data-mreact-layout-boundary" : "data-mreact-template-boundary";
+
+  if (html.includes(`${attributeName}=`)) {
+    return html;
+  }
+
+  return html.replace(
+    /<([A-Za-z][^\s/>]*)([^>]*)>/,
+    `<$1$2 ${attributeName}="${escapeHtmlAttribute(shell.id)}">`,
+  );
+}
+
+export function shellBoundaryId(appDir: string, directory: string): string {
+  const relativeDirectory = relative(appDir, directory);
+
+  return relativeDirectory === ""
+    ? "root"
+    : relativeDirectory.replaceAll(sep, "/").replace(/[^A-Za-z0-9_$/-]/g, "_");
+}
+
+export function warnUnconsumedRouteSlots(options: {
+  appDir: string;
+  pageFile: string;
+  serverModuleCacheVersion: string | undefined;
+  slotContext: SlotRenderContext;
+}): void {
+  if (options.serverModuleCacheVersion !== undefined) {
+    return;
+  }
+
+  const slotNames = Object.keys(options.slotContext.namedSlots);
+  if (slotNames.length === 0) {
+    return;
+  }
+
+  const routeLabel = relative(options.appDir, options.pageFile).replaceAll(sep, "/");
+
+  for (const name of slotNames) {
+    if (name === "default") {
+      console.warn(
+        `[mreact] ${routeLabel}: slots.default does not target <Slot />; use the page body for default slot content.`,
+      );
+      continue;
+    }
+
+    if (!options.slotContext.consumedSlots.has(name)) {
+      console.warn(
+        `[mreact] ${routeLabel}: slots.{${name}} is not consumed by any ancestor layout or template.`,
+      );
+    }
+  }
+}
+
+function replaceNamedLayoutSlots(layoutHtml: string, slotContext: SlotRenderContext): string {
+  return layoutHtml.replace(SLOT_TAG_PATTERN, (source, openAttributes: string) => {
+    const name = readSlotName(openAttributes);
+
+    if (name === undefined || name === "default") {
+      return source;
+    }
+
+    if (Object.hasOwn(slotContext.namedSlots, name)) {
+      slotContext.consumedSlots.add(name);
+      return slotContext.namedSlots[name] ?? "";
+    }
+
+    return "";
+  });
+}
+
+const SLOT_TAG_PATTERN = /<slot\b([^>]*)>(?:<\/slot\s*>)?/g;
+
+function findDefaultLayoutSlot(html: string): RegExpExecArray | null {
+  SLOT_TAG_PATTERN.lastIndex = 0;
+
+  for (;;) {
+    const match = SLOT_TAG_PATTERN.exec(html);
+
+    if (match === null) {
+      return null;
+    }
+
+    const name = readSlotName(match[1] ?? "");
+
+    if (name === undefined || name === "default") {
+      return match;
+    }
+  }
+}
+
+function readSlotName(attributes: string): string | undefined {
+  const match = /\bname\s*=\s*(?:"([^"]*)"|'([^']*)')/.exec(attributes);
+
+  return match?.[1] ?? match?.[2];
+}