@mandujs/core 0.39.1 → 0.39.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.39.1",
+  "version": "0.39.3",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/client/spa-nav-helper.ts

@@ -97,7 +97,7 @@
  * flow is documented in this file's JSDoc; anyone editing this string
  * MUST update the exclusion-matrix test and the body-swap test to match.
  */
-export const SPA_NAV_HELPER_BODY = `(function(){if(typeof document==="undefined"||typeof window==="undefined")return;var L=window.location;var H=window.history;var TAG="[mandu-spa-nav]";function warn(m,d){try{console.warn(TAG+" "+m,d==null?"":d);}catch(_){}}function info(m,d){try{console.debug(TAG+" "+m,d==null?"":d);}catch(_){}}function hardNav(u,why){warn("falling back to full navigation: "+why,u);try{L.href=u;}catch(_){}}function esc(h){try{if(typeof CSS!=="undefined"&&CSS&&typeof CSS.escape==="function")return CSS.escape(h);}catch(_){}return String(h).replace(/([^a-zA-Z0-9_-])/g,"\\\\$1");}function extractHash(u){var i=u.indexOf("#");return i>=0?u.slice(i+1):"";}function scrollToHash(hash,url){if(!hash){try{window.scrollTo(0,0);}catch(_){}return;}var el=null;try{el=document.getElementById?document.getElementById(hash):null;}catch(_){}if(!el){try{el=document.querySelector?document.querySelector('[name="'+esc(hash)+'"]'):null;}catch(_){}}if(el&&typeof el.scrollIntoView==="function"){try{el.scrollIntoView({behavior:"instant",block:"start"});}catch(e1){try{el.scrollIntoView();}catch(_){}}try{if(L.hash!=="#"+hash)L.hash="#"+hash;}catch(_){}info("scrolled to #"+hash,url==null?"":url);}else{info("hash target #"+hash+" not found, scrolling to top",url==null?"":url);try{window.scrollTo(0,0);}catch(_){}}}function okAnchor(a){if(!a||!a.getAttribute)return null;if(a.hasAttribute("data-no-spa"))return null;if(a.hasAttribute("download"))return null;var t=a.getAttribute("target");if(t&&t!=="_self")return null;var h=a.getAttribute("href");if(!h)return null;var u;try{u=new URL(h,L.href);}catch(_){return null;}if(u.origin!==L.origin)return null;if(u.protocol!=="http:"&&u.protocol!=="https:")return null;if(u.pathname===L.pathname&&u.search===L.search&&!u.hash)return null;return u;}function pickContainer(doc){var main=doc.querySelector("main");if(main)return{src:main,dst:document.querySelector("main"),kind:"main"};var root=doc.getElementById&&doc.getElementById("root");if(root){var dstR=document.getElementById?document.getElementById("root"):null;if(dstR)return{src:root,dst:dstR,kind:"#root"};}if(doc.body)return{src:doc.body,dst:document.body,kind:"body"};return null;}function mergeHead(doc){try{var newTitle=doc.querySelector("title");if(newTitle)document.title=newTitle.textContent||document.title;var nh=doc.head,ch=document.head;if(!nh||!ch)return;var keep={};var metas=ch.querySelectorAll("meta[name=viewport],meta[charset]");for(var i=0;i<metas.length;i++)keep[metas[i].outerHTML]=true;var sel="meta,link[rel=icon],link[rel=shortcut icon],link[rel=canonical]";var oldMetas=ch.querySelectorAll(sel);for(var j=0;j<oldMetas.length;j++){if(!keep[oldMetas[j].outerHTML])oldMetas[j].parentNode.removeChild(oldMetas[j]);}var newMetas=nh.querySelectorAll(sel);for(var k=0;k<newMetas.length;k++){if(!keep[newMetas[k].outerHTML])ch.appendChild(newMetas[k].cloneNode(true));}}catch(e){warn("head merge failed",e&&e.message||e);}}function runScripts(container){try{var scripts=container.querySelectorAll("script");for(var i=0;i<scripts.length;i++){var old=scripts[i];var s=document.createElement("script");for(var j=0;j<old.attributes.length;j++){var a=old.attributes[j];try{s.setAttribute(a.name,a.value);}catch(_){}}if(!old.src)s.text=old.textContent||"";old.parentNode&&old.parentNode.removeChild(old);(document.head||document.body||document.documentElement).appendChild(s);}}catch(e){warn("script re-exec failed",e&&e.message||e);}}function doSwap(doc,url,startedAt){var perr=doc.querySelector&&doc.querySelector("parsererror");if(perr){hardNav(url,"DOMParser returned parsererror");return false;}var pick=pickContainer(doc);if(!pick||!pick.dst){hardNav(url,"no swap container matched (main/#root/body)");return false;}info("swap target container: "+pick.kind);try{pick.dst.innerHTML=pick.src.innerHTML;}catch(e){hardNav(url,"innerHTML assignment threw: "+(e&&e.message||e));return false;}mergeHead(doc);runScripts(pick.dst);scrollToHash(extractHash(url),url);var dur=0;try{dur=Math.round((performance&&performance.now?performance.now():Date.now())-startedAt);}catch(_){}info("swapped to "+url+" in "+dur+"ms (container="+pick.kind+")");try{window.dispatchEvent(new CustomEvent("__MANDU_SPA_NAV__",{detail:{url:url,durationMs:dur,container:pick.kind}}));}catch(_){}try{window.dispatchEvent(new CustomEvent("mandu:spa-navigate",{detail:{url:url}}));}catch(_){}return true;}function nav(url,push){var startedAt=0;try{startedAt=performance&&performance.now?performance.now():Date.now();}catch(_){startedAt=Date.now();}fetch(url,{credentials:"same-origin",headers:{"Accept":"text/html"}}).then(function(r){if(!r.ok){hardNav(url,"fetch responded "+r.status);return null;}var ct=r.headers.get("content-type");if(!ct||ct.indexOf("text/html")<0){hardNav(url,"non-HTML response ("+(ct||"no content-type")+")");return null;}return r.text();}).then(function(html){if(html==null)return;if(typeof DOMParser==="undefined"){hardNav(url,"DOMParser unavailable");return;}var doc;try{doc=new DOMParser().parseFromString(html,"text/html");}catch(e){hardNav(url,"DOMParser threw: "+(e&&e.message||e));return;}if(push){try{H.pushState({mandu:1},"",url);}catch(e){hardNav(url,"pushState threw: "+(e&&e.message||e));return;}}var run=function(){doSwap(doc,url,startedAt);};if(typeof document.startViewTransition==="function"){try{document.startViewTransition(run);}catch(e){warn("startViewTransition threw, running swap directly",e&&e.message||e);run();}}else{run();}}).catch(function(e){hardNav(url,"fetch rejected: "+(e&&e.message||e));});}function samePageHashNav(u,push){var url=u.pathname+u.search+u.hash;if(push){try{H.pushState({mandu:1},"",url);}catch(e){warn("pushState threw on same-page hash nav",e&&e.message||e);}}info("same-page hash nav "+url);scrollToHash(u.hash?u.hash.slice(1):"",url);try{window.dispatchEvent(new CustomEvent("__MANDU_SPA_NAV__",{detail:{url:url,durationMs:0,container:"hash"}}));}catch(_){}}document.addEventListener("click",function(e){if(e.defaultPrevented)return;if(e.button!==0||e.metaKey||e.altKey||e.ctrlKey||e.shiftKey)return;if(window.__MANDU_ROUTER_STATE__)return;var tgt=e.target;var a=tgt&&typeof tgt.closest==="function"?tgt.closest("a"):null;if(!a)return;var url=okAnchor(a);if(!url)return;e.preventDefault();if(url.pathname===L.pathname&&url.search===L.search&&url.hash){samePageHashNav(url,true);return;}nav(url.pathname+url.search+url.hash,true);},false);window.addEventListener("popstate",function(){if(window.__MANDU_ROUTER_STATE__)return;nav(L.pathname+L.search+L.hash,false);});window.__MANDU_SPA_HELPER__=1;})();`;
+export const SPA_NAV_HELPER_BODY = `(function(){if(typeof document==="undefined"||typeof window==="undefined")return;var L=window.location;var H=window.history;var TAG="[mandu-spa-nav]";function warn(m,d){try{console.warn(TAG+" "+m,d==null?"":d);}catch(_){}}function info(m,d){try{console.debug(TAG+" "+m,d==null?"":d);}catch(_){}}function hardNav(u,why){warn("falling back to full navigation: "+why,u);try{L.href=u;}catch(_){}}function esc(h){try{if(typeof CSS!=="undefined"&&CSS&&typeof CSS.escape==="function")return CSS.escape(h);}catch(_){}return String(h).replace(/([^a-zA-Z0-9_-])/g,"\\\\$1");}function extractHash(u){var i=u.indexOf("#");return i>=0?u.slice(i+1):"";}function scrollToHash(hash,url){if(!hash){try{window.scrollTo(0,0);}catch(_){}return;}var el=null;try{el=document.getElementById?document.getElementById(hash):null;}catch(_){}if(!el){try{el=document.querySelector?document.querySelector('[name="'+esc(hash)+'"]'):null;}catch(_){}}if(el&&typeof el.scrollIntoView==="function"){try{el.scrollIntoView({behavior:"instant",block:"start"});}catch(e1){try{el.scrollIntoView();}catch(_){}}try{if(L.hash!=="#"+hash)L.hash="#"+hash;}catch(_){}info("scrolled to #"+hash,url==null?"":url);}else{info("hash target #"+hash+" not found, scrolling to top",url==null?"":url);try{window.scrollTo(0,0);}catch(_){}}}function okAnchor(a){if(!a||!a.getAttribute)return null;if(a.hasAttribute("data-no-spa"))return null;if(a.hasAttribute("download"))return null;var t=a.getAttribute("target");if(t&&t!=="_self")return null;var h=a.getAttribute("href");if(!h)return null;var u;try{u=new URL(h,L.href);}catch(_){return null;}if(u.origin!==L.origin)return null;if(u.protocol!=="http:"&&u.protocol!=="https:")return null;if(u.pathname===L.pathname&&u.search===L.search&&!u.hash)return null;return u;}function pickContainer(doc){var main=doc.querySelector("main");if(main)return{src:main,dst:document.querySelector("main"),kind:"main"};var root=doc.getElementById&&doc.getElementById("root");if(root){var dstR=document.getElementById?document.getElementById("root"):null;if(dstR)return{src:root,dst:dstR,kind:"#root"};}if(doc.body)return{src:doc.body,dst:document.body,kind:"body"};return null;}function mergeHead(doc){try{var newTitle=doc.querySelector("title");if(newTitle)document.title=newTitle.textContent||document.title;var nh=doc.head,ch=document.head;if(!nh||!ch)return;var keep={};var metas=ch.querySelectorAll("meta[name=viewport],meta[charset]");for(var i=0;i<metas.length;i++)keep[metas[i].outerHTML]=true;var sel="meta,link[rel=icon],link[rel=shortcut icon],link[rel=canonical]";var oldMetas=ch.querySelectorAll(sel);for(var j=0;j<oldMetas.length;j++){if(!keep[oldMetas[j].outerHTML])oldMetas[j].parentNode.removeChild(oldMetas[j]);}var newMetas=nh.querySelectorAll(sel);for(var k=0;k<newMetas.length;k++){if(!keep[newMetas[k].outerHTML])ch.appendChild(newMetas[k].cloneNode(true));}}catch(e){warn("head merge failed",e&&e.message||e);}}function runScripts(container){try{var scripts=container.querySelectorAll("script");for(var i=0;i<scripts.length;i++){var old=scripts[i];var s=document.createElement("script");for(var j=0;j<old.attributes.length;j++){var a=old.attributes[j];try{s.setAttribute(a.name,a.value);}catch(_){}}if(!old.src)s.text=old.textContent||"";old.parentNode&&old.parentNode.removeChild(old);(document.head||document.body||document.documentElement).appendChild(s);}}catch(e){warn("script re-exec failed",e&&e.message||e);}}function doSwap(doc,url,startedAt){var perr=doc.querySelector&&doc.querySelector("parsererror");if(perr){hardNav(url,"DOMParser returned parsererror");return false;}try{var cRoot=document.getElementById?document.getElementById("root"):null;var nRoot=doc.getElementById?doc.getElementById("root"):null;var ck=cRoot&&cRoot.getAttribute?cRoot.getAttribute("data-mandu-layout"):"";var nk=nRoot&&nRoot.getAttribute?nRoot.getAttribute("data-mandu-layout"):"";if(ck&&nk&&ck!==nk){hardNav(url,"cross-layout transition ("+ck+" -> "+nk+")");return false;}}catch(_){}var pick=pickContainer(doc);if(!pick||!pick.dst){hardNav(url,"no swap container matched (main/#root/body)");return false;}info("swap target container: "+pick.kind);try{pick.dst.innerHTML=pick.src.innerHTML;}catch(e){hardNav(url,"innerHTML assignment threw: "+(e&&e.message||e));return false;}mergeHead(doc);runScripts(pick.dst);scrollToHash(extractHash(url),url);var dur=0;try{dur=Math.round((performance&&performance.now?performance.now():Date.now())-startedAt);}catch(_){}info("swapped to "+url+" in "+dur+"ms (container="+pick.kind+")");try{window.dispatchEvent(new CustomEvent("__MANDU_SPA_NAV__",{detail:{url:url,durationMs:dur,container:pick.kind}}));}catch(_){}try{window.dispatchEvent(new CustomEvent("mandu:spa-navigate",{detail:{url:url}}));}catch(_){}return true;}function nav(url,push){var startedAt=0;try{startedAt=performance&&performance.now?performance.now():Date.now();}catch(_){startedAt=Date.now();}fetch(url,{credentials:"same-origin",headers:{"Accept":"text/html"}}).then(function(r){if(!r.ok){hardNav(url,"fetch responded "+r.status);return null;}var ct=r.headers.get("content-type");if(!ct||ct.indexOf("text/html")<0){hardNav(url,"non-HTML response ("+(ct||"no content-type")+")");return null;}return r.text();}).then(function(html){if(html==null)return;if(typeof DOMParser==="undefined"){hardNav(url,"DOMParser unavailable");return;}var doc;try{doc=new DOMParser().parseFromString(html,"text/html");}catch(e){hardNav(url,"DOMParser threw: "+(e&&e.message||e));return;}if(push){try{H.pushState({mandu:1},"",url);}catch(e){hardNav(url,"pushState threw: "+(e&&e.message||e));return;}}var run=function(){doSwap(doc,url,startedAt);};if(typeof document.startViewTransition==="function"){try{document.startViewTransition(run);}catch(e){warn("startViewTransition threw, running swap directly",e&&e.message||e);run();}}else{run();}}).catch(function(e){hardNav(url,"fetch rejected: "+(e&&e.message||e));});}function samePageHashNav(u,push){var url=u.pathname+u.search+u.hash;if(push){try{H.pushState({mandu:1},"",url);}catch(e){warn("pushState threw on same-page hash nav",e&&e.message||e);}}info("same-page hash nav "+url);scrollToHash(u.hash?u.hash.slice(1):"",url);try{window.dispatchEvent(new CustomEvent("__MANDU_SPA_NAV__",{detail:{url:url,durationMs:0,container:"hash"}}));}catch(_){}}document.addEventListener("click",function(e){if(e.defaultPrevented)return;if(e.button!==0||e.metaKey||e.altKey||e.ctrlKey||e.shiftKey)return;if(window.__MANDU_ROUTER_STATE__)return;var tgt=e.target;var a=tgt&&typeof tgt.closest==="function"?tgt.closest("a"):null;if(!a)return;var url=okAnchor(a);if(!url)return;e.preventDefault();if(url.pathname===L.pathname&&url.search===L.search&&url.hash){samePageHashNav(url,true);return;}nav(url.pathname+url.search+url.hash,true);},false);window.addEventListener("popstate",function(){if(window.__MANDU_ROUTER_STATE__)return;nav(L.pathname+L.search+L.hash,false);});window.__MANDU_SPA_HELPER__=1;})();`;
 
 /** Ready-to-inject `<script>` tag for SSR `<head>` injection. */
 export const SPA_NAV_HELPER_SCRIPT = `<script>${SPA_NAV_HELPER_BODY}</script>`;

package/src/runtime/server.ts

@@ -1173,6 +1173,72 @@ export function setCreateApp(fn: CreateAppFn): void {
   defaultRegistry.setCreateApp(fn);
 }
 
+/**
+ * Issue #232 follow-up — eager page-component registration.
+ *
+ * After a dev-mode HMR reload, `registerPageHandler` / `registerPageLoader`
+ * install lazy thunks. The actual component import and
+ * `registerRouteComponent` call is deferred until the first request for
+ * that route. On a brand-new browser reload triggered by HMR the request
+ * normally populates the registry in time, but any code path that renders
+ * without going through `loadPageData` first (or a thrown error that
+ * short-circuits it) leaves `routeComponents` empty, and the default
+ * appCreator renders the "404 - Route Not Found" fallback even though the
+ * route is valid.
+ *
+ * `prewarmPageRoutes()` walks every registered `pageHandler` / `pageLoader`
+ * once and drives it through the same code path the first request would
+ * take, so `routeComponents` is fully populated before the server starts
+ * serving. The cost is a one-time module import per page route — trivial
+ * in dev. Production `mandu start` is unaffected because it already runs
+ * requests through the same lazy path without HMR races.
+ */
+export async function prewarmPageRoutes(
+  registry: ServerRegistry = defaultRegistry,
+): Promise<{ prewarmed: string[]; failed: Array<{ routeId: string; error: string }> }> {
+  const prewarmed: string[] = [];
+  const failed: Array<{ routeId: string; error: string }> = [];
+
+  // pageHandlers path (routes with .slot.ts / filling)
+  for (const routeId of registry.pageHandlers.keys()) {
+    try {
+      await ensurePageRouteMetadata(routeId, registry);
+      prewarmed.push(routeId);
+    } catch (err) {
+      failed.push({
+        routeId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  // pageLoaders path (plain page components, no slot)
+  for (const routeId of registry.pageLoaders.keys()) {
+    if (registry.routeComponents.has(routeId)) continue; // already warm
+    try {
+      const loader = registry.pageLoaders.get(routeId);
+      if (!loader) continue;
+      const module = await loader();
+      const exported: unknown = module.default;
+      const exportedObj = exported as Record<string, unknown> | null;
+      const component = typeof exported === "function"
+        ? (exported as RouteComponent)
+        : (exportedObj?.component as RouteComponent | undefined);
+      if (typeof component === "function") {
+        registry.registerRouteComponent(routeId, component);
+        prewarmed.push(routeId);
+      }
+    } catch (err) {
+      failed.push({
+        routeId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  return { prewarmed, failed };
+}
+
 /**
  * Layout 로더 등록 (전역)
  */
@@ -2782,6 +2848,9 @@ async function renderPageSSR(
         hmrPort: settings.hmrPort,
         routeId: route.id,
         routePattern: route.pattern,
+        // Issue #233 — emit data-mandu-layout so SPA nav can detect
+        // cross-layout transitions and hard-nav instead of half-swapping.
+        layoutChain: route.layoutChain,
         hydration: route.hydration,
         bundleManifest: settings.bundleManifest,
         criticalData: loaderData as Record<string, unknown> | undefined,
@@ -2830,6 +2899,9 @@ async function renderPageSSR(
       prefetch: settings.prefetch,
       spa: settings.spa,
       devtools: settings.devtools,
+      // Issue #233 — SPA nav uses this to detect cross-layout transitions
+      // and fall back to a hard navigation.
+      layoutChain: route.layoutChain,
     });
     return ok(cookies ? cookies.applyToResponse(ssrResponse) : ssrResponse);
   } catch (error) {

package/src/runtime/ssr.ts

@@ -53,6 +53,16 @@ export interface SSROptions {
   bundleManifest?: BundleManifest;
   /** 라우트 ID (island 식별용) */
   routeId?: string;
+  /**
+   * Issue #233 — layout chain applied to this render, ordered outer → inner.
+   * Serialized into `data-mandu-layout` on `<div id="root">` so the SPA
+   * navigation helper can detect cross-layout transitions and fall back
+   * to a hard navigation instead of a soft `<main>` swap (which would
+   * leave stale layout chrome like a sidebar from the source layout).
+   * When omitted or empty the attribute is dropped — same-layout nav
+   * remains cheap and visually crossfaded.
+   */
+  layoutChain?: string[];
   /** 추가 head 태그 */
   headTags?: string;
   /** 추가 body 끝 태그 */
@@ -623,8 +633,25 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     spa,
     devtools,
     devErrorOverlay,
+    layoutChain,
   } = options;
 
+  // Issue #233 — derive a stable short key for the layout chain so the
+  // SPA nav helper can detect cross-layout transitions. Deterministic
+  // per server, stable across the same route/layout combo. Missing /
+  // empty chain → omit the attribute entirely (attribute absence acts
+  // like a wildcard match).
+  let layoutKey = "";
+  if (layoutChain && layoutChain.length > 0) {
+    let hash = 0;
+    const joined = layoutChain.join("|");
+    for (let i = 0; i < joined.length; i++) {
+      hash = ((hash << 5) - hash + joined.charCodeAt(i)) | 0;
+    }
+    layoutKey = (hash >>> 0).toString(16).padStart(8, "0");
+  }
+  const rootAttrs = layoutKey ? ` data-mandu-layout="${layoutKey}"` : "";
+
   // CSS 링크 태그 생성
   // - cssPath가 string이면 해당 경로 사용
   // - cssPath가 false 또는 undefined이면 링크 미삽입 (404 방지)
@@ -804,7 +831,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   ${devErrorOverlayTag}
 </head>
 <body>
-  <div id="root">${bodyContent}</div>
+  <div id="root"${rootAttrs}>${bodyContent}</div>
   ${dataScript}
   ${routeScript}
   ${hydrationScripts}

package/src/runtime/streaming-ssr.ts

@@ -99,6 +99,12 @@ export interface StreamingSSROptions {
   routeId?: string;
   /** 라우트 패턴 */
   routePattern?: string;
+  /**
+   * Issue #233 — layout chain (outer → inner). Emitted as
+   * `data-mandu-layout="<hash>"` on `<div id="root">` so the SPA
+   * navigation helper can detect cross-layout transitions.
+   */
+  layoutChain?: string[];
   /** Critical 데이터 (Shell과 함께 즉시 전송) - JSON-serializable object만 허용 */
   criticalData?: Record<string, unknown>;
   // Note: deferredData는 renderWithDeferredData의 deferredPromises로 대체됨
@@ -543,8 +549,24 @@ function generateHTMLShell(options: StreamingSSROptions): string {
     transitions = true,
     prefetch = true,
     spa = true,
+    layoutChain,
   } = options;
 
+  // Issue #233 — layout-key for SPA cross-layout detection. Mirror of the
+  // block in `ssr.ts::renderToHTML`; see that call-site for the full
+  // rationale. Streaming path must stamp the same attribute so the SPA
+  // helper's layout-mismatch heuristic is consistent across modes.
+  let layoutKey = "";
+  if (layoutChain && layoutChain.length > 0) {
+    let hash = 0;
+    const joined = layoutChain.join("|");
+    for (let i = 0; i < joined.length; i++) {
+      hash = ((hash << 5) - hash + joined.charCodeAt(i)) | 0;
+    }
+    layoutKey = (hash >>> 0).toString(16).padStart(8, "0");
+  }
+  const rootAttrs = layoutKey ? ` data-mandu-layout="${layoutKey}"` : "";
+
   // CSS 링크 태그 생성
   // - cssPath가 string이면 해당 경로 사용
   // - cssPath가 false 또는 undefined이면 링크 미삽입 (404 방지)
@@ -652,7 +674,7 @@ function generateHTMLShell(options: StreamingSSROptions): string {
   ${fastRefreshPreamble}
 </head>
 <body>
-  <div id="root">${islandOpenTag}`;
+  <div id="root"${rootAttrs}>${islandOpenTag}`;
 }
 
 /**