@mandujs/core 0.46.1 → 0.47.0

package/package.json

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

package/src/client/router.ts

@@ -341,26 +341,47 @@ export async function navigate(
       if (scroll) window.scrollTo(0, 0);
     };
 
-    // View Transitions API — 브라우저 지원 시 URL + DOM 전환을 동기화
+    // View Transitions API — 브라우저 지원 시 URL + DOM 전환을 동기화.
+    //
+    // Issue #253 (regression fix on top of #252): when the transition
+    // aborts (rapid navigation, popstate races, the user clicks a
+    // second link before the first transition finishes), the browser
+    // SKIPS the callback we passed in — meaning `applyUpdate` never
+    // runs and the click is silently lost. The user sees "first click
+    // does nothing, second click works".
+    //
+    // Track whether `applyUpdate` actually ran. If any of the three
+    // ViewTransition promises (`updateCallbackDone`, `ready`,
+    // `finished`) reject before it does, run `applyUpdate` directly.
+    // The `applied` flag prevents double-apply when the transition
+    // completes normally (the callback runs and the promises resolve).
+    let applied = false;
+    const safeApply = () => {
+      if (applied) return;
+      applied = true;
+      applyUpdate();
+    };
     if (!replace && "startViewTransition" in document) {
-      // `startViewTransition` is part of the View Transitions API which
-      // is not yet in every lib.dom.d.ts. Narrow the cast to the only
-      // method we call rather than widening to `any`.
-      const transition = (document as Document & {
-        startViewTransition: (callback: () => void) => {
-          finished?: Promise<unknown>;
-          ready?: Promise<unknown>;
-          updateCallbackDone?: Promise<unknown>;
-        };
-      }).startViewTransition(applyUpdate);
-      // ViewTransition.finished/ready reject with InvalidStateError when a
-      // newer transition aborts this one (rapid navigation, popstate, etc.).
-      // Swallow those — they are expected and not actionable for the app.
-      transition?.finished?.catch(() => {});
-      transition?.ready?.catch(() => {});
-      transition?.updateCallbackDone?.catch(() => {});
+      try {
+        const transition = (document as Document & {
+          startViewTransition: (callback: () => void) => {
+            finished?: Promise<unknown>;
+            ready?: Promise<unknown>;
+            updateCallbackDone?: Promise<unknown>;
+          };
+        }).startViewTransition(safeApply);
+        // Each of these rejects with InvalidStateError when the
+        // transition aborts before our callback gets to run. Tying
+        // `safeApply` to all three is belt-and-braces — whichever
+        // rejects first wakes up the navigation we owe the user.
+        transition?.updateCallbackDone?.catch(() => safeApply());
+        transition?.ready?.catch(() => safeApply());
+        transition?.finished?.catch(() => safeApply());
+      } catch {
+        safeApply();
+      }
     } else {
-      applyUpdate();
+      safeApply();
     }
   } catch (error) {
     // abort된 네비게이션은 조용히 무시 (새 네비게이션이 대체함)

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;}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{var vt=document.startViewTransition(run);if(vt){if(vt.finished&&typeof vt.finished.catch==="function")vt.finished.catch(function(){});if(vt.ready&&typeof vt.ready.catch==="function")vt.ready.catch(function(){});if(vt.updateCallbackDone&&typeof vt.updateCallbackDone.catch==="function")vt.updateCallbackDone.catch(function(){});}}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"){var ranSwap=false;var safeRun=function(){if(ranSwap)return;ranSwap=true;run();};try{var vt=document.startViewTransition(safeRun);if(vt){if(vt.updateCallbackDone&&typeof vt.updateCallbackDone.catch==="function")vt.updateCallbackDone.catch(safeRun);if(vt.ready&&typeof vt.ready.catch==="function")vt.ready.catch(safeRun);if(vt.finished&&typeof vt.finished.catch==="function")vt.finished.catch(safeRun);}}catch(e){warn("startViewTransition threw, running swap directly",e&&e.message||e);safeRun();}}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/deploy/compile/vercel.ts

@@ -0,0 +1,344 @@
+/**
+ * Vercel compiler — manifest + DeployIntent cache → `vercel.json`.
+ *
+ * Issue #250 — Phase 1 M3.
+ *
+ * The compiler is the new identity of the Vercel adapter. The old
+ * adapter was a config scaffolder that emitted the same hand-writable
+ * `vercel.json` regardless of project shape (Issue #250). With the
+ * intent cache in place, `compileVercelJson()` reads:
+ *
+ *   - the routes manifest (what routes exist and their kind)
+ *   - `.mandu/deploy.intent.json` (typed DeployIntent per route)
+ *
+ * and emits a `vercel.json` whose functions block, regions, headers,
+ * and rewrites are derived from the intents — no template variables,
+ * no copy-paste-and-edit. Adapters never invent defaults; missing
+ * intent for any route is a hard error so deploys can't drift
+ * silently into the wrong shape.
+ *
+ * # Runtime mapping
+ *
+ *   - `static` → no function entry. The route prerenders at build
+ *     time and ships from the CDN.
+ *   - `edge`   → `runtime: "edge"` on the function entry.
+ *   - `node`   → omit `runtime` so Vercel uses its built-in Node
+ *     runtime. (Note: current Mandu `startServer` is Bun-only, so
+ *     a `node` intent on Vercel is flagged as not-yet-supported in
+ *     `compileWarnings`. The compile still succeeds — the user can
+ *     opt out by changing the intent.)
+ *   - `bun`    → `runtime: "@vercel/bun@1.0.0"`. Issue #248 noted
+ *     that the package is unpublished today; the compiler emits
+ *     the field anyway and surfaces a warning. Once the runtime
+ *     ships, no compiler change is required.
+ *
+ * # Cache mapping
+ *
+ *   - `"no-store"` → `Cache-Control: no-store`
+ *   - `"public"`   → `Cache-Control: public`
+ *   - `{ maxAge, sMaxAge, swr }` → `public, max-age=...,
+ *     s-maxage=..., stale-while-revalidate=...` (only the keys
+ *     present are written).
+ *
+ * Per-route headers go in `vercel.json#headers` keyed off the route
+ * pattern (with `:param` segments mapped to `:param`).
+ *
+ * # Provider-specific overrides
+ *
+ * `intent.overrides.vercel` is shallow-merged onto the function entry,
+ * so things like `memory` / `maxDuration` / regions overrides work
+ * without growing the core schema.
+ *
+ * # Schema portability gates
+ *
+ * `runtime: "static"` on a dynamic page without `generateStaticParams`
+ * is rejected via `isStaticIntentValidFor`. Issue #250 RFC marks this
+ * as the canonical "schema portability" failure mode adapters must
+ * surface clearly — we list the offending routes in the error.
+ */
+
+import type { RouteSpec, RoutesManifest } from "../../spec/schema";
+import {
+  isStaticIntentValidFor,
+  type DeployIntent,
+  type DeployRuntime,
+} from "../intent";
+import type { DeployIntentCache } from "../cache";
+
+// ─── Vercel config shape ──────────────────────────────────────────────
+
+export interface VercelHeader {
+  source: string;
+  headers: Array<{ key: string; value: string }>;
+}
+
+export interface VercelFunctionConfig {
+  /** Vercel runtime spec; omit for built-in Node. */
+  runtime?: string;
+  /** Per-function regions (provider-specific identifiers). */
+  regions?: string[];
+  /** Function timeout in seconds (Vercel field name). */
+  maxDuration?: number;
+  /** Memory in MB. */
+  memory?: number;
+  /** Anything else from `intent.overrides.vercel`. */
+  [key: string]: unknown;
+}
+
+export interface VercelConfig {
+  $schema: string;
+  version: 2;
+  framework: null;
+  buildCommand: string;
+  installCommand: string;
+  outputDirectory: string;
+  functions?: Record<string, VercelFunctionConfig>;
+  headers?: VercelHeader[];
+  rewrites?: Array<{ source: string; destination: string }>;
+}
+
+// ─── Public surface ───────────────────────────────────────────────────
+
+export interface CompileVercelOptions {
+  /** Project name (Mandu-side bookkeeping; not emitted into vercel.json). */
+  projectName: string;
+  /** Build command. Defaults to `bun run mandu build --static` (static-only). */
+  buildCommand?: string;
+  /** Install command. */
+  installCommand?: string;
+  /** Output directory. Defaults to `dist`. */
+  outputDirectory?: string;
+}
+
+export interface VercelCompileResult {
+  config: VercelConfig;
+  /**
+   * Non-fatal warnings the CLI surfaces to the user. Examples: the
+   * `node` / `bun` intent was emitted but the corresponding Vercel
+   * runtime is not yet usable for Mandu (see #248).
+   */
+  warnings: string[];
+  /**
+   * Per-route summary the CLI prints in `mandu deploy --target=vercel`
+   * dry-run, so the operator can confirm the intent → vercel.json
+   * mapping at a glance before pushing.
+   */
+  perRoute: Array<{
+    routeId: string;
+    pattern: string;
+    runtime: DeployRuntime;
+    functionEntry: string | null;
+    cacheHeader: string | null;
+  }>;
+}
+
+export class VercelCompileError extends Error {
+  readonly code = "DEPLOY_VERCEL_COMPILE_FAILED";
+  readonly routes: ReadonlyArray<{ routeId: string; reason: string }>;
+
+  constructor(
+    routes: ReadonlyArray<{ routeId: string; reason: string }>,
+  ) {
+    super(
+      `Vercel compile failed:\n${routes.map((r) => `  - ${r.routeId}: ${r.reason}`).join("\n")}`,
+    );
+    this.routes = routes;
+    this.name = "VercelCompileError";
+  }
+}
+
+/**
+ * Compile a manifest + intent cache into a `vercel.json`.
+ *
+ * Throws `VercelCompileError` when one or more routes have intents
+ * the adapter cannot represent (missing entry, invalid `static`
+ * declaration, etc). Non-fatal issues are returned in `warnings`.
+ */
+export function compileVercelJson(
+  manifest: RoutesManifest,
+  cache: DeployIntentCache,
+  options: CompileVercelOptions,
+): VercelCompileResult {
+  validateProjectName(options.projectName);
+
+  const warnings: string[] = [];
+  const errors: Array<{ routeId: string; reason: string }> = [];
+  const functions: Record<string, VercelFunctionConfig> = {};
+  const headers: VercelHeader[] = [];
+  const perRoute: VercelCompileResult["perRoute"] = [];
+
+  // Long-cache directive for hashed bundles is the same in every
+  // Mandu deploy — ship it unconditionally.
+  headers.push({
+    source: "/.mandu/client/(.*)",
+    headers: [
+      { key: "Cache-Control", value: "public, max-age=31536000, immutable" },
+    ],
+  });
+
+  for (const route of manifest.routes) {
+    const entry = cache.intents[route.id];
+    if (!entry) {
+      errors.push({
+        routeId: route.id,
+        reason: "no DeployIntent in .mandu/deploy.intent.json — run `mandu deploy:plan` first",
+      });
+      continue;
+    }
+    const { intent } = entry;
+
+    // Schema portability gate: `runtime: "static"` on a route that
+    // can't actually be prerendered.
+    const isDynamic = isPatternDynamic(route.pattern);
+    const hasGenerateStaticParams =
+      route.kind === "page" &&
+      Array.isArray((route as { staticParams?: unknown[] }).staticParams) &&
+      ((route as { staticParams?: unknown[] }).staticParams?.length ?? 0) > 0;
+    const validation = isStaticIntentValidFor(intent, {
+      isDynamic,
+      hasGenerateStaticParams,
+      kind: route.kind,
+    });
+    if (!validation.ok) {
+      errors.push({ routeId: route.id, reason: validation.reason });
+      continue;
+    }
+
+    // Per-route header (built from the intent cache directive).
+    const cacheHeader = formatCacheControl(intent.cache);
+    if (cacheHeader && intent.runtime === "static") {
+      headers.push({
+        source: route.pattern,
+        headers: [{ key: "Cache-Control", value: cacheHeader }],
+      });
+    }
+
+    // Function entry (skipped for static).
+    let functionEntry: string | null = null;
+    if (intent.runtime !== "static") {
+      functionEntry = mapRouteToFunctionEntry(route);
+      const fn: VercelFunctionConfig = {};
+
+      if (intent.runtime === "edge") {
+        fn.runtime = "edge";
+      } else if (intent.runtime === "bun") {
+        fn.runtime = "@vercel/bun@1.0.0";
+        warnings.push(
+          `${route.id}: runtime: "bun" emits @vercel/bun@1.0.0 in vercel.json, but the package is not published yet (Issue #248). Deploy will fail until @vercel/bun ships or the intent changes.`,
+        );
+      } else {
+        // node — leave runtime unset so Vercel picks its built-in
+        // Node runtime, but warn that Mandu's startServer is Bun-only.
+        warnings.push(
+          `${route.id}: runtime: "node" — Vercel will run this on its built-in Node runtime, but Mandu's startServer uses Bun-only globals. Switch to runtime: "edge" / "bun", or self-host this route.`,
+        );
+      }
+
+      if (intent.regions && intent.regions.length > 0) fn.regions = intent.regions;
+      if (intent.timeout !== undefined) {
+        // Vercel `maxDuration` is in seconds; intent.timeout is in ms.
+        fn.maxDuration = Math.max(1, Math.ceil(intent.timeout / 1000));
+      }
+
+      // Provider-specific overrides — last write wins.
+      const overrides = (intent.overrides?.vercel ?? {}) as Record<string, unknown>;
+      for (const [k, v] of Object.entries(overrides)) {
+        fn[k] = v;
+      }
+
+      // `node` intent leaves `runtime` undefined intentionally — only
+      // strip the key when it never got set.
+      if (fn.runtime === undefined) delete fn.runtime;
+
+      functions[functionEntry] = fn;
+
+      if (cacheHeader) {
+        headers.push({
+          source: route.pattern,
+          headers: [{ key: "Cache-Control", value: cacheHeader }],
+        });
+      }
+    }
+
+    // Visibility on Vercel is owned by Project Settings (preview
+    // protection / IP allowlist). Surface a hint when the user
+    // declared `private` so they know to wire it up out of band.
+    if (intent.visibility === "private") {
+      warnings.push(
+        `${route.id}: visibility: "private" — Vercel routes default to public. Configure preview protection / IP allowlist in Project Settings.`,
+      );
+    }
+
+    perRoute.push({
+      routeId: route.id,
+      pattern: route.pattern,
+      runtime: intent.runtime,
+      functionEntry,
+      cacheHeader,
+    });
+  }
+
+  if (errors.length > 0) {
+    throw new VercelCompileError(errors);
+  }
+
+  const config: VercelConfig = {
+    $schema: "https://openapi.vercel.sh/vercel.json",
+    version: 2,
+    framework: null,
+    buildCommand: options.buildCommand ?? "bun run mandu build --static",
+    installCommand: options.installCommand ?? "bun install --frozen-lockfile",
+    outputDirectory: options.outputDirectory ?? "dist",
+    headers,
+  };
+  if (Object.keys(functions).length > 0) {
+    config.functions = functions;
+  }
+
+  return { config, warnings, perRoute };
+}
+
+/** Stable JSON output — trailing newline so editors don't fight us. */
+export function renderVercelJsonFromCompile(result: VercelCompileResult): string {
+  return `${JSON.stringify(result.config, null, 2)}\n`;
+}
+
+// ─── Internals ────────────────────────────────────────────────────────
+
+function validateProjectName(name: string): void {
+  if (!/^[a-z0-9][a-z0-9-_]{0,99}$/i.test(name)) {
+    throw new Error(`compileVercelJson: projectName "${name}" is invalid`);
+  }
+}
+
+/**
+ * Map a route's manifest entry to the vercel.json `functions[*]` key.
+ *
+ * Vercel keys functions by their on-disk path relative to the project
+ * root (e.g., `api/embed.ts`). Mandu's manifest stores `module` in the
+ * same shape, so we use that directly. For page routes the
+ * `componentModule` is the canonical SSR entry.
+ */
+function mapRouteToFunctionEntry(route: RouteSpec): string {
+  const entry =
+    (route as { componentModule?: string }).componentModule ?? route.module;
+  return entry.replace(/^\.?\//, "");
+}
+
+function formatCacheControl(cache: DeployIntent["cache"]): string | null {
+  if (cache === "no-store") return "no-store";
+  if (cache === "public") return "public";
+  const bits: string[] = ["public"];
+  if (cache.maxAge !== undefined) bits.push(`max-age=${cache.maxAge}`);
+  if (cache.sMaxAge !== undefined) bits.push(`s-maxage=${cache.sMaxAge}`);
+  if (cache.swr !== undefined) bits.push(`stale-while-revalidate=${cache.swr}`);
+  return bits.length > 1 ? bits.join(", ") : null;
+}
+
+function isPatternDynamic(pattern: string): boolean {
+  return (
+    /\[(\.\.\.)?[^\]]+\]/.test(pattern) ||
+    /\/:[^/]+/.test(pattern) ||
+    /\*/.test(pattern)
+  );
+}

package/src/deploy/index.ts

@@ -60,3 +60,14 @@ export {
   type PlanDiffEntryKind,
   type PlanResult,
 } from "./plan";
+
+export {
+  compileVercelJson,
+  renderVercelJsonFromCompile,
+  VercelCompileError,
+  type CompileVercelOptions,
+  type VercelCompileResult,
+  type VercelConfig,
+  type VercelFunctionConfig,
+  type VercelHeader,
+} from "./compile/vercel";