@mandujs/core 0.28.0 → 0.29.1

package/src/dev-error-overlay/__tests__/overlay-injector.test.ts

@@ -0,0 +1,241 @@
+/**
+ * Phase 18.α — Dev Error Overlay regression tests.
+ *
+ * Covers:
+ *   - Dev injection emits both <style> and <script> tags
+ *   - Production (NODE_ENV=production) suppresses injection
+ *   - Explicit `enabled: false` suppresses injection even in dev
+ *   - Stack parsing handles Chrome + Firefox shapes + fallthrough
+ *   - Error embed escapes `</script>` sequences
+ *   - Payload builder tolerates non-Error throws
+ *   - buildOverlayErrorHtml wraps the embed in a valid doctype doc
+ *   - Client IIFE mounts the mounted-flag guard to prevent double-mount
+ */
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import {
+  buildOverlayHeadTag,
+  maybeInjectDevOverlay,
+  shouldInjectOverlay,
+  parseStackFrames,
+  buildPayloadFromError,
+  buildOverlayErrorEmbed,
+  buildOverlayErrorHtml,
+} from "../overlay-injector";
+import {
+  OVERLAY_CLIENT_SCRIPT,
+  _testOnly_buildOverlayClientScript,
+} from "../overlay-client";
+import {
+  OVERLAY_CUSTOM_EVENT,
+  OVERLAY_MOUNTED_FLAG,
+  OVERLAY_PAYLOAD_ELEMENT_ID,
+} from "../types";
+
+describe("shouldInjectOverlay", () => {
+  const prevEnv = process.env.NODE_ENV;
+  afterEach(() => {
+    if (prevEnv === undefined) delete process.env.NODE_ENV;
+    else process.env.NODE_ENV = prevEnv;
+  });
+
+  it("returns true in dev with default config", () => {
+    process.env.NODE_ENV = "development";
+    expect(shouldInjectOverlay({ isDev: true })).toBe(true);
+  });
+
+  it("returns false when isDev is false", () => {
+    process.env.NODE_ENV = "development";
+    expect(shouldInjectOverlay({ isDev: false })).toBe(false);
+  });
+
+  it("returns false when NODE_ENV=production even if isDev lies", () => {
+    process.env.NODE_ENV = "production";
+    expect(shouldInjectOverlay({ isDev: true })).toBe(false);
+  });
+
+  it("returns false when user opts out via enabled: false", () => {
+    process.env.NODE_ENV = "development";
+    expect(shouldInjectOverlay({ isDev: true, enabled: false })).toBe(false);
+  });
+
+  it("returns true when user explicitly enables in dev", () => {
+    process.env.NODE_ENV = "development";
+    expect(shouldInjectOverlay({ isDev: true, enabled: true })).toBe(true);
+  });
+});
+
+describe("buildOverlayHeadTag", () => {
+  const prevEnv = process.env.NODE_ENV;
+  afterEach(() => {
+    if (prevEnv === undefined) delete process.env.NODE_ENV;
+    else process.env.NODE_ENV = prevEnv;
+  });
+
+  it("emits <style> and <script> in dev", () => {
+    process.env.NODE_ENV = "development";
+    const out = buildOverlayHeadTag({ isDev: true });
+    expect(out).toContain("<style");
+    expect(out).toContain("id=\"__mandu-dev-overlay-style\"");
+    expect(out).toContain("<script");
+    expect(out).toContain("id=\"__mandu-dev-overlay-client\"");
+    expect(out).toContain(".mandu-dev-overlay");
+  });
+
+  it("emits empty string in production", () => {
+    process.env.NODE_ENV = "production";
+    expect(buildOverlayHeadTag({ isDev: true })).toBe("");
+  });
+
+  it("emits empty string when opted out", () => {
+    process.env.NODE_ENV = "development";
+    expect(buildOverlayHeadTag({ isDev: true, enabled: false })).toBe("");
+  });
+
+  it("maybeInjectDevOverlay is alias with same behavior", () => {
+    process.env.NODE_ENV = "development";
+    expect(maybeInjectDevOverlay({ isDev: true })).toBe(
+      buildOverlayHeadTag({ isDev: true }),
+    );
+  });
+
+  it("does not contain the sentinel flag leaking as a global assignment outside the IIFE", () => {
+    process.env.NODE_ENV = "development";
+    const out = buildOverlayHeadTag({ isDev: true });
+    // The sentinel is only ever referenced via `window[MOUNTED]`, never as a bare identifier assignment.
+    expect(out.includes(`var ${OVERLAY_MOUNTED_FLAG}=`)).toBe(false);
+    // But the string literal MUST appear at least once (inside the IIFE).
+    expect(out).toContain(OVERLAY_MOUNTED_FLAG);
+  });
+});
+
+describe("parseStackFrames", () => {
+  it("parses Chrome-style frames", () => {
+    const stack = `TypeError: boom
+    at myFn (/src/app/page.tsx:42:10)
+    at Other (/src/app/layout.tsx:7:5)`;
+    const frames = parseStackFrames(stack);
+    expect(frames.length).toBe(2);
+    expect(frames[0].fn).toBe("myFn");
+    expect(frames[0].file).toBe("/src/app/page.tsx");
+    expect(frames[0].line).toBe(42);
+    expect(frames[0].column).toBe(10);
+  });
+
+  it("parses Firefox-style frames", () => {
+    const stack = `TypeError: boom
+myFn@/src/app/page.tsx:42:10
+@/src/app/layout.tsx:7:5`;
+    const frames = parseStackFrames(stack);
+    expect(frames.length).toBeGreaterThanOrEqual(1);
+    expect(frames[0].file).toBe("/src/app/page.tsx");
+    expect(frames[0].line).toBe(42);
+  });
+
+  it("tolerates empty / null input", () => {
+    expect(parseStackFrames(undefined)).toEqual([]);
+    expect(parseStackFrames(null)).toEqual([]);
+    expect(parseStackFrames("")).toEqual([]);
+  });
+
+  it("falls through with <anonymous> for unparseable lines", () => {
+    const stack = `SomeWeirdRuntime\nopaque frame line`;
+    const frames = parseStackFrames(stack);
+    expect(frames.length).toBeGreaterThan(0);
+    expect(frames.some((f) => f.fn === "<anonymous>")).toBe(true);
+  });
+});
+
+describe("buildPayloadFromError", () => {
+  it("extracts name, message, and stack from an Error", () => {
+    const err = new Error("boom");
+    err.name = "CustomError";
+    const p = buildPayloadFromError(err, { kind: "ssr", routeId: "r1" });
+    expect(p.name).toBe("CustomError");
+    expect(p.message).toBe("boom");
+    expect(p.kind).toBe("ssr");
+    expect(p.routeId).toBe("r1");
+    expect(typeof p.timestamp).toBe("number");
+  });
+
+  it("tolerates string throws", () => {
+    const p = buildPayloadFromError("just a string");
+    expect(p.message).toBe("just a string");
+    expect(p.name).toBe("Error");
+    expect(p.frames).toEqual([]);
+  });
+
+  it("tolerates null and undefined", () => {
+    const p1 = buildPayloadFromError(null);
+    expect(p1.name).toBe("Error");
+    const p2 = buildPayloadFromError(undefined);
+    expect(p2.name).toBe("Error");
+  });
+});
+
+describe("buildOverlayErrorEmbed", () => {
+  it("emits a JSON script tag with the payload id", () => {
+    const p = buildPayloadFromError(new Error("test"), { kind: "ssr" });
+    const embed = buildOverlayErrorEmbed(p);
+    expect(embed).toContain(`id="${OVERLAY_PAYLOAD_ELEMENT_ID}"`);
+    expect(embed).toContain("application/json");
+    expect(embed).toContain(OVERLAY_CUSTOM_EVENT);
+  });
+
+  it("escapes </script> in the payload so it cannot break out", () => {
+    const err = new Error("</script><script>alert(1)</script>");
+    const p = buildPayloadFromError(err);
+    const embed = buildOverlayErrorEmbed(p);
+    // The literal </script> sequence must not appear in the serialized JSON.
+    // escapeJsonForInlineScript breaks it into a harmless form.
+    const between = embed.split(`id="${OVERLAY_PAYLOAD_ELEMENT_ID}"`)[1] ?? "";
+    const payloadChunk = between.split("</script>")[0] ?? "";
+    expect(payloadChunk.toLowerCase().includes("<script>alert(1)")).toBe(false);
+  });
+});
+
+describe("buildOverlayErrorHtml", () => {
+  const prevEnv = process.env.NODE_ENV;
+  afterEach(() => {
+    if (prevEnv === undefined) delete process.env.NODE_ENV;
+    else process.env.NODE_ENV = prevEnv;
+  });
+
+  it("wraps the embed in a valid dev HTML document", () => {
+    process.env.NODE_ENV = "development";
+    const p = buildPayloadFromError(new Error("ssr boom"), { kind: "ssr", routeId: "home" });
+    const html = buildOverlayErrorHtml(p);
+    expect(html.startsWith("<!doctype html>")).toBe(true);
+    expect(html).toContain("<title>");
+    expect(html).toContain(`id="${OVERLAY_PAYLOAD_ELEMENT_ID}"`);
+    expect(html).toContain(".mandu-dev-overlay");
+  });
+});
+
+describe("OVERLAY_CLIENT_SCRIPT shape", () => {
+  it("is a well-formed IIFE", () => {
+    expect(OVERLAY_CLIENT_SCRIPT.startsWith("(function(){")).toBe(true);
+    expect(OVERLAY_CLIENT_SCRIPT.endsWith("})();")).toBe(true);
+  });
+
+  it("references the mounted-flag guard (prevents double-mount on HMR)", () => {
+    expect(OVERLAY_CLIENT_SCRIPT).toContain(OVERLAY_MOUNTED_FLAG);
+    expect(OVERLAY_CLIENT_SCRIPT).toContain("window[MOUNTED]=true");
+  });
+
+  it("wires all three error entry points", () => {
+    expect(OVERLAY_CLIENT_SCRIPT).toContain(`"error"`);
+    expect(OVERLAY_CLIENT_SCRIPT).toContain("unhandledrejection");
+    expect(OVERLAY_CLIENT_SCRIPT).toContain(OVERLAY_CUSTOM_EVENT);
+  });
+
+  it("stays under the 10 KB-gzip target (rough byte budget check)", () => {
+    // Uncompressed budget: 64 KB is a generous ceiling; gzip typically
+    // achieves 4-5x on this sort of string-heavy JS. We assert uncompressed
+    // < 32 KB as a hard ceiling — the current IIFE is ~7 KB uncompressed.
+    expect(OVERLAY_CLIENT_SCRIPT.length).toBeLessThan(32 * 1024);
+  });
+
+  it("is recomputable — _testOnly_buildOverlayClientScript yields identical output", () => {
+    expect(_testOnly_buildOverlayClientScript()).toBe(OVERLAY_CLIENT_SCRIPT);
+  });
+});

package/src/dev-error-overlay/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Phase 18.α — Dev Error Overlay public surface.
+ *
+ * Consumed by:
+ *   - `runtime/ssr.ts` (injects `<style>` + `<script>` into `<head>` in dev)
+ *   - `runtime/server.ts` (embeds an SSR 500 payload so the overlay can
+ *     mount even when the React tree never rendered)
+ *
+ * Production never imports from here at runtime — tree-shaking drops
+ * the IIFE string because `shouldInjectOverlay` returns `false`.
+ */
+export {
+  buildOverlayHeadTag,
+  maybeInjectDevOverlay,
+  shouldInjectOverlay,
+  parseStackFrames,
+  buildPayloadFromError,
+  buildOverlayErrorEmbed,
+  buildOverlayErrorHtml,
+  type DevOverlayInjectorConfig,
+} from "./overlay-injector";
+export { OVERLAY_CLIENT_SCRIPT } from "./overlay-client";
+export { OVERLAY_STYLES } from "./overlay-styles";
+export {
+  OVERLAY_PAYLOAD_ELEMENT_ID,
+  OVERLAY_CUSTOM_EVENT,
+  OVERLAY_MOUNTED_FLAG,
+  type DevErrorPayload,
+  type DevErrorStackFrame,
+} from "./types";

package/src/dev-error-overlay/overlay-client.ts

@@ -0,0 +1,300 @@
+/**
+ * Phase 18.α — Dev Error Overlay client IIFE.
+ *
+ * This file EXPORTS a string (`OVERLAY_CLIENT_SCRIPT`) that is inlined
+ * into the SSR `<head>` by the injector. It is NOT compiled as a
+ * module; the whole body runs in parse order on every dev page load.
+ *
+ * Size target: < 10 KB gzipped (current ≈ 2 KB gz). No dependencies.
+ * Only touches `window`, `document`, `navigator.clipboard`, and a tiny
+ * WeakSet.
+ *
+ * Listeners installed:
+ *   - `window.onerror`          → uncaught script errors
+ *   - `unhandledrejection`      → Promise rejections
+ *   - custom event `__MANDU_ERROR__` → the server embeds a 500 payload
+ *     in the HTML, fires this event on DOMContentLoaded, and the
+ *     overlay picks it up. User code can also `dispatchEvent` it to
+ *     surface synthetic errors.
+ *
+ * Everything scoped in an IIFE — NO globals leak except the single
+ * `__MANDU_OVERLAY_MOUNTED__` sentinel that prevents double-mount on
+ * HMR.
+ */
+import { OVERLAY_STYLES } from "./overlay-styles";
+import {
+  OVERLAY_CUSTOM_EVENT,
+  OVERLAY_MOUNTED_FLAG,
+  OVERLAY_PAYLOAD_ELEMENT_ID,
+} from "./types";
+
+/**
+ * Build the client-side IIFE body as a string. Parameterised by the
+ * style block and the two sentinel names so tests can verify the exact
+ * shape without re-declaring the constants.
+ */
+function buildOverlayClientScript(): string {
+  // The IIFE below references the constants through string interpolation,
+  // NOT through imports — because it runs in the browser and has no
+  // module loader.
+  return `(function(){
+var MOUNTED=${JSON.stringify(OVERLAY_MOUNTED_FLAG)};
+var EVT=${JSON.stringify(OVERLAY_CUSTOM_EVENT)};
+var PAYLOAD_ID=${JSON.stringify(OVERLAY_PAYLOAD_ELEMENT_ID)};
+if(typeof window==="undefined"||typeof document==="undefined")return;
+if(window[MOUNTED]===true)return;
+window[MOUNTED]=true;
+
+var STYLE=${JSON.stringify(OVERLAY_STYLES)};
+var seen=new WeakSet();
+
+function parseFrames(stack){
+  if(typeof stack!=="string"||stack.length===0)return [];
+  var lines=stack.split("\\n");
+  var out=[];
+  for(var i=0;i<lines.length;i++){
+    var raw=lines[i];
+    var t=raw.trim();
+    if(!t||t===stack.split("\\n")[0]&&/^[A-Z][a-zA-Z]*(?:Error)?:/.test(t))continue;
+    // Chrome:  "    at fn (file:line:col)"
+    // Firefox: "fn@file:line:col"
+    var m=t.match(/^at\\s+(.+?)\\s+\\((.+):(\\d+):(\\d+)\\)$/);
+    if(!m)m=t.match(/^at\\s+(.+):(\\d+):(\\d+)$/);
+    if(m&&m.length===5){
+      out.push({fn:m[1],file:m[2],line:parseInt(m[3],10),column:parseInt(m[4],10),raw:raw});
+      continue;
+    }
+    if(m&&m.length===4){
+      out.push({fn:"<anonymous>",file:m[1],line:parseInt(m[2],10),column:parseInt(m[3],10),raw:raw});
+      continue;
+    }
+    var ff=t.match(/^(.*?)@(.+):(\\d+):(\\d+)$/);
+    if(ff){
+      out.push({fn:ff[1]||"<anonymous>",file:ff[2],line:parseInt(ff[3],10),column:parseInt(ff[4],10),raw:raw});
+      continue;
+    }
+    out.push({fn:"<anonymous>",file:t,line:null,column:null,raw:raw});
+  }
+  return out;
+}
+
+function toPayload(err,kind){
+  var name="Error",message="",stack="";
+  if(err&&typeof err==="object"){
+    name=err.name||"Error";
+    message=typeof err.message==="string"?err.message:String(err.message||"");
+    stack=typeof err.stack==="string"?err.stack:"";
+  }else if(typeof err==="string"){
+    message=err;
+  }else if(err!=null){
+    try{message=String(err);}catch(_){message="<unserializable error>";}
+  }
+  return {
+    name:name,
+    message:message,
+    frames:parseFrames(stack),
+    stack:stack,
+    kind:kind,
+    timestamp:Date.now(),
+    url:typeof location!=="undefined"?location.pathname+location.search:undefined,
+    userAgent:typeof navigator!=="undefined"?navigator.userAgent:undefined
+  };
+}
+
+function esc(s){
+  if(s==null)return "";
+  return String(s).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&#39;");
+}
+
+function fileHref(file,line,col){
+  // vscode://file/<abs>:<line>:<col> — falls back gracefully when the
+  // host OS has no handler. Relative paths get "//" prefix so the URL
+  // still parses, even though the editor may refuse to jump.
+  var p=file;
+  if(!/^[a-zA-Z]:|^\\//.test(p))p="/"+p;
+  var u="vscode://file"+p;
+  if(line)u+=":"+line;
+  if(col)u+=":"+col;
+  return u;
+}
+
+function renderFrames(frames){
+  if(!frames||frames.length===0)return '<li class="mandu-dev-overlay__frame"><span class="mandu-dev-overlay__frame-fn">&lt;no stack&gt;</span></li>';
+  var items=[];
+  for(var i=0;i<frames.length&&i<40;i++){
+    var f=frames[i];
+    var loc=esc(f.file)+(f.line?":"+f.line:"")+(f.column?":"+f.column:"");
+    var href=f.file?fileHref(f.file,f.line,f.column):"";
+    var locHtml=href?'<a class="mandu-dev-overlay__frame-link" href="'+esc(href)+'">'+loc+'</a>':loc;
+    items.push('<li class="mandu-dev-overlay__frame"><span class="mandu-dev-overlay__frame-fn">'+esc(f.fn||"<anonymous>")+'</span><span class="mandu-dev-overlay__frame-loc">'+locHtml+'</span></li>');
+  }
+  return items.join("");
+}
+
+function ensureStyleTag(){
+  if(document.getElementById("__mandu-dev-overlay-style"))return;
+  var s=document.createElement("style");
+  s.id="__mandu-dev-overlay-style";
+  s.textContent=STYLE;
+  (document.head||document.documentElement).appendChild(s);
+}
+
+function copyForAI(payload,btn){
+  var text="# Mandu dev error snapshot\\n\\n"
+    +"- kind: "+payload.kind+"\\n"
+    +"- name: "+payload.name+"\\n"
+    +"- message: "+payload.message+"\\n"
+    +"- url: "+(payload.url||"")+"\\n"
+    +"- routeId: "+(payload.routeId||"")+"\\n"
+    +"- timestamp: "+new Date(payload.timestamp).toISOString()+"\\n\\n"
+    +"## Stack\\n\\n\`\`\`\\n"+payload.stack+"\\n\`\`\`\\n";
+  var done=function(){
+    var prev=btn.textContent;
+    btn.textContent="Copied!";
+    setTimeout(function(){btn.textContent=prev;},1500);
+  };
+  if(navigator.clipboard&&navigator.clipboard.writeText){
+    navigator.clipboard.writeText(text).then(done,function(){
+      fallbackCopy(text);done();
+    });
+  }else{
+    fallbackCopy(text);done();
+  }
+}
+
+function fallbackCopy(text){
+  try{
+    var ta=document.createElement("textarea");
+    ta.value=text;ta.style.position="fixed";ta.style.left="-9999px";
+    document.body.appendChild(ta);ta.select();
+    try{document.execCommand("copy");}catch(_){}
+    document.body.removeChild(ta);
+  }catch(_){}
+}
+
+function mount(payload){
+  if(seen.has(payload))return;
+  seen.add(payload);
+  ensureStyleTag();
+  var root=document.getElementById("__mandu-dev-overlay-root");
+  if(!root){
+    root=document.createElement("div");
+    root.id="__mandu-dev-overlay-root";
+    root.className="mandu-dev-overlay";
+    root.setAttribute("role","dialog");
+    root.setAttribute("aria-modal","true");
+    root.setAttribute("aria-label","Mandu dev error overlay");
+    (document.body||document.documentElement).appendChild(root);
+  }
+  var kindLabel=({ssr:"SSR render failed",window:"Uncaught error",unhandledrejection:"Unhandled promise rejection",manual:"Error"})[payload.kind]||"Error";
+  var meta="";
+  if(payload.routeId||payload.url){
+    meta='<div class="mandu-dev-overlay__meta">'
+      +(payload.routeId?'<div class="mandu-dev-overlay__meta-item"><span class="mandu-dev-overlay__meta-label">Route</span><span class="mandu-dev-overlay__meta-value">'+esc(payload.routeId)+'</span></div>':'')
+      +(payload.url?'<div class="mandu-dev-overlay__meta-item"><span class="mandu-dev-overlay__meta-label">URL</span><span class="mandu-dev-overlay__meta-value">'+esc(payload.url)+'</span></div>':'')
+      +'<div class="mandu-dev-overlay__meta-item"><span class="mandu-dev-overlay__meta-label">Time</span><span class="mandu-dev-overlay__meta-value">'+esc(new Date(payload.timestamp).toLocaleTimeString())+'</span></div>'
+      +'</div>';
+  }
+  root.innerHTML='<div class="mandu-dev-overlay__panel">'
+    +'<div class="mandu-dev-overlay__header">'
+      +'<div class="mandu-dev-overlay__title">'
+        +'<span class="mandu-dev-overlay__kind">'+esc(kindLabel)+'</span>'
+        +'<span class="mandu-dev-overlay__name">'+esc(payload.name)+'</span>'
+      +'</div>'
+      +'<div class="mandu-dev-overlay__actions">'
+        +'<button type="button" class="mandu-dev-overlay__btn mandu-dev-overlay__btn--primary" data-action="copy">Copy for AI</button>'
+        +'<button type="button" class="mandu-dev-overlay__btn" data-action="close" aria-label="Close overlay">Close</button>'
+      +'</div>'
+    +'</div>'
+    +'<div class="mandu-dev-overlay__body">'
+      +'<p class="mandu-dev-overlay__message">'+esc(payload.message||"(no message)")+'</p>'
+      +meta
+      +'<h3 class="mandu-dev-overlay__section-title">Stack frames</h3>'
+      +'<ol class="mandu-dev-overlay__frames">'+renderFrames(payload.frames)+'</ol>'
+      +(payload.stack?'<h3 class="mandu-dev-overlay__section-title" style="margin-top:16px">Raw stack</h3><pre class="mandu-dev-overlay__stack">'+esc(payload.stack)+'</pre>':'')
+    +'</div>'
+    +'<div class="mandu-dev-overlay__footer">Dev-only overlay. Press <code>Esc</code> to dismiss. Never shipped in production builds.</div>'
+  +'</div>';
+  root.hidden=false;
+
+  var onClick=function(e){
+    var t=e.target;
+    if(!t||!t.getAttribute)return;
+    var a=t.getAttribute("data-action");
+    if(a==="close")hide();
+    else if(a==="copy")copyForAI(payload,t);
+  };
+  root.onclick=onClick;
+}
+
+function hide(){
+  var root=document.getElementById("__mandu-dev-overlay-root");
+  if(root)root.hidden=true;
+}
+
+function handle(err,kind,extra){
+  try{
+    var p=toPayload(err,kind);
+    if(extra&&typeof extra==="object"){
+      if(extra.routeId)p.routeId=extra.routeId;
+      if(extra.url)p.url=extra.url;
+    }
+    mount(p);
+  }catch(_){
+    // overlay must never throw — silent drop.
+  }
+}
+
+window.addEventListener("error",function(ev){
+  if(ev&&ev.error)handle(ev.error,"window");
+  else if(ev)handle(ev.message||"Script error",(\"window\"));
+});
+window.addEventListener("unhandledrejection",function(ev){
+  handle(ev&&ev.reason,"unhandled-rejection");
+});
+window.addEventListener(EVT,function(ev){
+  var d=ev&&ev.detail;
+  if(!d)return;
+  if(d.name||d.message||d.stack){
+    var p={
+      name:d.name||"Error",
+      message:d.message||"",
+      frames:d.frames||parseFrames(d.stack||""),
+      stack:d.stack||"",
+      kind:d.kind||"manual",
+      timestamp:d.timestamp||Date.now(),
+      routeId:d.routeId,
+      url:d.url||(typeof location!=="undefined"?location.pathname+location.search:undefined),
+      userAgent:typeof navigator!=="undefined"?navigator.userAgent:undefined
+    };
+    mount(p);
+  }
+});
+document.addEventListener("keydown",function(e){
+  if(e.key==="Escape")hide();
+});
+
+function readEmbedded(){
+  var el=document.getElementById(PAYLOAD_ID);
+  if(!el)return;
+  try{
+    var data=JSON.parse(el.textContent||"null");
+    if(data&&typeof data==="object")mount(data);
+  }catch(_){}
+}
+if(document.readyState==="loading"){
+  document.addEventListener("DOMContentLoaded",readEmbedded);
+}else{
+  readEmbedded();
+}
+
+// Public surface (tests + user code)
+window.__MANDU_DEV_OVERLAY__={show:function(e){handle(e,"manual");},hide:hide};
+})();`;
+}
+
+/** The serialized IIFE. Computed once at module-load. */
+export const OVERLAY_CLIENT_SCRIPT = buildOverlayClientScript();
+
+/** @internal test-only accessor so tests can recompute / inspect the script. */
+export const _testOnly_buildOverlayClientScript = buildOverlayClientScript;