@thomas.f/prnext 0.1.16-alpha → 0.1.18-alpha

package/runtime/dev-client.mjs

@@ -1,51 +1,124 @@
 import Refresh from 'react-refresh/runtime';
+import { createDevIndicator } from './dev-indicator.mjs';
+import { createConsoleCapture, isDevicePreview } from './dev-console.mjs';
+import { createDevToolsClient } from './dev-tools-client.mjs';
+import { createDevErrorOverlay } from './dev-error-overlay.mjs';
+import { collectDevIssues, formatDevIssuesForAI } from './dev-error-report.mjs';
 
 const state = globalThis.__PRNEXT_DEV__ ||= {
   applications: new Map(), modules: new Map(), buildId: null, manifest: null,
   pending: null, applying: false, unsafe: false, queued: null, source: null,
 };
+// Install before application bootstrap so initial renders/effects are captured.
+if (!state.consoleCapture && !state.consoleDisabled) state.consoleCapture = createConsoleCapture();
 if (!state.injected) { Refresh.injectIntoGlobalHook(globalThis); state.injected = true; }
 export const register = (type, id) => Refresh.register(type, id);
 export const signature = () => Refresh.createSignatureFunctionForTransform();
 export function registerModule(id, hash, boundary) {
   const previous = state.modules.get(id);
+  if (state.applying && (!previous || previous.hash !== hash)) state.refreshSourceChanged = true;
   if (previous && previous.hash !== hash && (!previous.boundary || !boundary)) state.unsafe = true;
   state.modules.set(id, { hash, boundary });
 }
 
-function clearError() { document.getElementById('__prnext_dev_error__')?.remove(); state.overlayError = undefined; }
+function clearError({ dismiss = false } = {}) {
+  state.errorOverlay?.dispose();state.errorOverlay=undefined;
+  document.getElementById('__prnext_dev_error__')?.remove(); state.overlayError = undefined;
+  clearTimeout(state.errorCopyTimer);state.errorCopyTimer=undefined;
+  state.errorEntry=undefined;state.errorReport=undefined;state.errorSource=undefined;
+  state.overlaySelectedId=undefined;state.overlayKind=undefined;state.overlayIssues=undefined;state.errorSources=undefined;
+  if (!dismiss) state.issue = undefined;
+  state.indicator?.update();
+}
+function dismissError() {
+  if(state.overlayError&&typeof state.overlayError==='object')(state.dismissedErrors ||= new WeakSet()).add(state.overlayError);
+  const key=errorKey(state.overlayError);
+  if(key){const entries=state.dismissedDigests ||= new Set();if(entries.size>=32)entries.delete(entries.values().next().value);entries.add(key);}
+  if(state.overlayKind==='typescript')state.dismissedTypeDiagnostic=state.lastTypeDiagnostic;
+  clearError({dismiss:true});
+  let focused=document.activeElement;
+  while(focused?.shadowRoot?.activeElement)focused=focused.shadowRoot.activeElement;
+  if(!focused||focused===document.body||focused===document.documentElement||focused.closest?.('[inert]'))document.getElementById('__prnext_dev_tools__')?.shadowRoot?.querySelector('.trigger')?.focus({preventScroll:true});
+}
 function errorKey(error) {
   return typeof error?.digest === 'string' ? `${error.digest.slice(0, 256)}:${String(error.message || '').slice(0, 512)}` : null;
 }
-function showError(error) {
+function reportRecoverableError(error, info) {
+  const message=String(error?.message||error).slice(0,48*1024);
+  const key=message.replace(/^(?:Uncaught\s+)?Error:\s*/,'').split(/\n\s+at\s+/)[0].replace(/\r\n/g,'\n').trim();
+  if(state.recoverableKey===key)return;
+  // Keep one current diagnostic; the console retains the complete history.
+  // Never replace a blocking issue or open an overlay during successful recovery.
+  state.recoverableKey=key;
+  state.recoverableIssue={name:String(error?.name||'Error'),message,stack:String(error?.stack||message+(info?.componentStack||'')).slice(0,48*1024)};
+  if(state.errorOverlay)syncErrorOverlay();
+  state.indicator?.update();
+}
+function showError(error, { retain = true } = {}) {
+  if(error===null||error===undefined)error=new Error(String(error));
   const key = errorKey(error);
   if (error && typeof error === 'object' && (state.dismissedErrors?.has(error) || (key && state.dismissedDigests?.has(key)))) return;
-  state.overlayError = error;
-  let host = document.getElementById('__prnext_dev_error__');
-  if (!host) {
-    host = document.createElement('div'); host.id = '__prnext_dev_error__';
-    Object.assign(host.style, { position: 'fixed', inset: '0', zIndex: '2147483647' });
-    const shadow = host.attachShadow({ mode: 'open' });
-    const style = document.createElement('style');
-    style.textContent = ':host{color-scheme:dark}section{box-sizing:border-box;overflow:auto;height:100%;padding:32px;background:#17191fee;color:#f4f5f7;font:14px/1.6 ui-monospace,monospace}h1{font:600 22px system-ui;color:#ff7474}pre{white-space:pre-wrap;overflow-wrap:anywhere}button{position:fixed;right:24px;top:24px;padding:8px 14px;border:1px solid #697080;border-radius:6px;background:#292e39;color:white;cursor:pointer}';
-    const section = document.createElement('section'); section.setAttribute('role', 'alertdialog'); section.setAttribute('aria-label', 'PRNext development error');
-    const heading = document.createElement('h1'); heading.textContent = 'PRNext — development error';
-    const close = document.createElement('button'); close.textContent = 'Dismiss'; close.onclick = () => {
-      // React may report the same failed model again while its boundary retries.
-      // Closing that diagnostic must not block the recovered application.
-      if (state.overlayError && typeof state.overlayError === 'object') (state.dismissedErrors ||= new WeakSet()).add(state.overlayError);
-      const key = errorKey(state.overlayError);
-      if (key) {
-        const entries = state.dismissedDigests ||= new Set();
-        if (entries.size >= 32) entries.delete(entries.values().next().value);
-        entries.add(key);
-      }
-      clearError();
-    };
-    const details = document.createElement('pre'); details.id = 'details';
-    section.append(heading, close, details); shadow.append(style, section); document.documentElement.append(host);
+  if(retain){state.issue=error;if(error!==state.lastTypeDiagnostic)state.issueKind=state.devBuildState==='error'?'build':'runtime';}
+  state.indicator?.update();
+  syncErrorOverlay({preferredError:error,open:true});
+}
+function hasCriticalIssue(){return state.issue!==undefined&&state.issue!==state.lastTypeDiagnostic;}
+function syncErrorOverlay({preferredError,selectedId,open=false}={}) {
+  if(!open&&!state.errorOverlay)return;
+  const {issues,omitted}=collectDevIssues({critical:hasCriticalIssue()?state.issue:undefined,criticalKind:state.issueKind||'runtime',typeErrors:state.typeErrors,recoverable:state.recoverableIssue});
+  if(!issues.length){clearError();return;}
+  const selected=issues.find(issue=>issue.id===selectedId)
+    ||issues.find(issue=>issue.error===preferredError)
+    ||(preferredError===state.lastTypeDiagnostic&&preferredError!==undefined?issues.find(issue=>issue.kind==='typescript'&&issue.id===state.overlaySelectedId)||issues.find(issue=>issue.kind==='typescript'):undefined)
+    ||issues.find(issue=>issue.id===state.overlaySelectedId)||issues[0];
+  const changed=!state.errorOverlay?.host.isConnected||!state.errorEntry||state.errorEntry.id!==selected.id||state.errorEntry.error!==selected.error||state.errorReport.message!==selected.report.message||state.errorReport.stack!==selected.report.stack||state.overlayKind!==selected.kind;
+  state.overlayIssues={issues,omitted};state.overlaySelectedId=selected.id;state.overlayKind=selected.kind;state.overlayError=selected.error;
+  const sources=state.errorSources ||= new Map();for(const [id,cached]of sources)if(!issues.some(issue=>issue.id===id&&issue.error===cached.error&&issue.report.message===cached.report?.message&&issue.report.stack===cached.report?.stack))sources.delete(id);
+  if(!state.errorOverlay?.host.isConnected){
+    state.errorOverlay?.dispose();
+    state.errorOverlay=createDevErrorOverlay({onDismiss:dismissError,onSendToAI(){
+      const detail={kind:'error',error:state.errorReport,source:state.errorSource};
+      dismissError();
+      globalThis.dispatchEvent(new CustomEvent('prnext:devtools:ai',{detail}));
+    },onSelectIssue(id){syncErrorOverlay({selectedId:id});},onCopyForAI(){void copyErrorsForAI();}});
   }
-  host.shadowRoot.getElementById('details').textContent = String(error?.stack || error?.message || error).slice(0, 48 * 1024);
+  const overlay=state.errorOverlay;
+  if(changed){state.errorEntry=selected;state.errorReport=selected.report;state.errorSource=undefined;}
+  overlay.render(state.errorReport,{recoverable:selected.recoverable,kind:selected.kind,issues,selectedId:selected.id,omitted});
+  if(!changed)return;
+  const entry=state.errorEntry,cached=sources.get(selected.id);
+  if(cached){state.errorSource=cached.source;overlay.setSource(cached.source);overlay.setSourceStatus(cached.source.mapped?'':'Original source location.');return;}
+  overlay.setSourceStatus(state.tools?'Locating original source…':'');
+  if(state.tools)void state.tools.call('dev_source',{stack:state.errorReport.stack,error:state.errorReport}).then(source=>{
+    if(state.errorEntry!==entry||state.errorOverlay!==overlay||!overlay.host.isConnected)return;
+    sources.set(selected.id,{error:selected.error,report:entry.report,source});
+    state.errorSource=source;overlay.setSource(source);
+    overlay.setSourceStatus(source.mapped?'':'Original source location.');
+  }).catch(()=>{if(state.errorEntry===entry&&state.errorOverlay===overlay&&overlay.host.isConnected)overlay.setSourceStatus('Original source unavailable. Full details remain below.');});
+}
+async function copyErrorsForAI(){
+  const overlay=state.errorOverlay,current=state.overlayIssues;if(!overlay||!current)return;
+  try{
+    const sourceById=new Map([...(state.errorSources||[])].map(([id,cached])=>[id,cached.source]));
+    const prompt=formatDevIssuesForAI(current.issues,{route:location.pathname,sourceById,omitted:current.omitted});
+    if(!navigator.clipboard?.writeText)throw Error('Clipboard unavailable');
+    await navigator.clipboard.writeText(prompt);
+    if(state.errorOverlay===overlay){overlay.setCopyStatus('copied');clearTimeout(state.errorCopyTimer);state.errorCopyTimer=setTimeout(()=>{if(state.errorOverlay===overlay)overlay.setCopyStatus('idle');},1800);}
+  }catch{if(state.errorOverlay===overlay)overlay.setCopyStatus('error');}
+}
+
+function reload(reason) {
+  try{sessionStorage.setItem('__prnext_reload_reason__',reason);}catch{}
+  void state.tools?.browser('reload',{reason});
+  globalThis.dispatchEvent(new CustomEvent('prnext:reload',{detail:{reason}}));
+  location.reload();
+}
+function showReloadReason(){
+  let reason;try{reason=sessionStorage.getItem('__prnext_reload_reason__');sessionStorage.removeItem('__prnext_reload_reason__');}catch{}
+  if(!reason)return;
+  const note=document.createElement('div');note.id='__prnext_reload_reason__';note.setAttribute('role','status');note.textContent=reason;
+  Object.assign(note.style,{position:'fixed',bottom:'76px',left:'18px',maxWidth:'min(360px,calc(100vw - 36px))',padding:'10px 14px',border:'1px solid #292929',borderRadius:'10px',background:'#080808',color:'#ddd',font:'12px/1.5 system-ui',zIndex:'2147483646'});
+  document.documentElement.append(note);setTimeout(()=>note.remove(),6500);
 }
 
 async function updateStyles(urls) {
@@ -62,12 +135,54 @@ async function updateStyles(urls) {
   for (const link of old) if (!wanted.has(link.href)) link.remove();
 }
 
-async function applyUpdate(message) {
-  if (state.applying) { state.queued = message; return; }
-  if (!message.clientManifest) { location.reload(); return; }
+function typeDiagnostics(errors) {
+  state.typeErrors=errors;
+  if(!errors.length){
+    if(state.lastTypeDiagnostic!==undefined&&state.issue===state.lastTypeDiagnostic){
+      state.issue=undefined;
+    }
+    state.lastTypeDiagnostic=undefined;state.dismissedTypeDiagnostic=undefined;if(state.errorOverlay)syncErrorOverlay();state.indicator?.update();return;
+  }
+  const text=errors.join('\n');
+  const previous=state.lastTypeDiagnostic;
+  const critical=state.issue!==undefined&&state.issue!==previous;
+  state.lastTypeDiagnostic=text;
+  if(!critical)state.issue=text;
+  if(!critical&&state.dismissedTypeDiagnostic!==text&&(!state.overlayError||state.overlayKind==='typescript'))showError(text);
+  else if(state.errorOverlay)syncErrorOverlay();
+  state.indicator?.update();
+}
+async function applyUpdate(message, {navigation=false}={}) {
+  if(message.session&&state.session&&message.session!==state.session){reload('Development server restarted. Page reloaded.');return;}
+  if(message.sequence&&message.sequence<=(state.sequence||0))return;
+  if (state.applying) {
+    if(!state.queued||(message.sequence||0)>=(state.queued.sequence||0))state.queued={...message,navigation};
+    const pending=state.applied;await pending;
+    if((message.sequence||0)>(state.sequence||0)&&state.applying)await state.applied;
+    return;
+  }
+  if (!message.clientManifest) { reload('Refresh metadata changed. Page reloaded.'); return; }
   const changed = message.changed || [];
-  if (changed.some(file => /(?:^|\/)(?:(?:next|prnext)\.config\.|package(?:-lock)?\.json|\.env|pages\/_document\.)/.test(file))) { location.reload(); return; }
-  state.applying = true; state.unsafe = false; state.pending = null;
+  if (changed.some(file => /(?:^|\/)(?:(?:next|prnext)\.config\.|package(?:-lock)?\.json|\.env|pages\/_document\.)/.test(file))) { reload('Project configuration changed. Page reloaded.'); return; }
+  // An initial dynamic import/bootstrap failure has no mounted application to
+  // update. Retry once on a newer successfully compiled build, not repeatedly
+  // on reconnects or readiness messages for the same failed generation.
+  if(state.bootstrapFailed&&message.buildId!==state.bootstrapFailed.buildId){
+    state.bootstrapFailed=undefined;
+    reload('Application startup failed. Page reloaded after a successful rebuild.');return;
+  }
+  const refreshStarted=performance.now();
+  const localPath=location.pathname.slice((state.basePath||'').length)||'/';
+  const affected=message.affectedRoutes;
+  if(state.confirmed&&affected&&!affected.some(pattern=>pattern.includes('[')||pattern===localPath||pattern+'/'===localPath)){
+    state.buildId=message.buildId;state.sequence=message.sequence;state.lastRefresh={buildId:message.buildId,durationMs:0,changed,skipped:true};
+    document.documentElement.dataset.prnextDevBuild=message.buildId;
+    if(hasCriticalIssue()&&state.issueKind==='build'){clearError();if(state.typeErrors)typeDiagnostics(state.typeErrors);}
+    state.indicator?.update();
+    globalThis.dispatchEvent(new CustomEvent('prnext:refresh',{detail:state.lastRefresh}));return;
+  }
+  state.applying = true; state.confirmed=false; state.unsafe = false; state.refreshSourceChanged = false; state.pending = null; state.indicator?.update();
+  let applied;state.applied=new Promise(resolve=>{applied=resolve;});
   state.dismissedErrors = new WeakSet();
   state.dismissedDigests = new Set();
   try {
@@ -79,51 +194,135 @@ async function applyUpdate(message) {
     const application = await state.applications.get(kind);
     const route = kind === 'pages' ? manifest.pages.find(route => route.pattern === application.router.snapshot().pathname) : null;
     const entry = kind === 'pages' ? route?.client : manifest.app?.client;
-    if (!entry) { location.reload(); return; }
-    await import(/* webpackIgnore: true */ entry);
+    if (!entry) { reload('The current route changed. Page reloaded.'); return; }
+    if(!message.cssOnly)await import(/* webpackIgnore: true */ entry);
     const pending = state.pending;
     if (pending) await application.devPrepare?.(pending.options);
-    if (state.unsafe) { location.reload(); return; }
-    await updateStyles(kind === 'pages' ? route.css : manifest.app.css);
-    clearError();
-    Refresh.performReactRefresh();
-    if (pending) await application.devCommit?.(pending.options);
+    if (state.unsafe) { reload('An edited module exports values outside React components. Page reloaded.'); return; }
+    if (kind === 'app' && application.devPrepareStyles) await application.devPrepareStyles(manifest.app.routes);
+    else await updateStyles(kind === 'pages' ? route.css : application.devStyles?.(manifest.app.routes) || manifest.app.css);
+    if (kind === 'app') application.devStylesApplied?.(manifest.app.routes, { commit: !!message.cssOnly || !pending });
+    // An unrelated type-only edit may publish a new generation without changing
+    // any browser module. Keep its existing runtime/hydration issues and current
+    // selection until application code changes, rather than racing diagnostics.
+    if(state.refreshSourceChanged||navigation){
+      state.recoverableIssue=undefined;state.recoverableKey=undefined;
+      clearError();
+    }else if(hasCriticalIssue()&&(state.issueKind==='build'||errorKey(state.issue))){
+      clearError();
+    }
+    if(!message.cssOnly)Refresh.performReactRefresh();
+    if (pending) await (navigation ? application.devSync?.(pending.options) : application.devCommit?.(pending.options));
     state.buildId = message.buildId;
+    if(message.sequence)state.sequence=message.sequence;
     state.manifest = manifest;
     document.documentElement.dataset.prnextDevBuild = message.buildId;
-    globalThis.dispatchEvent(new CustomEvent('prnext:refresh', { detail: { buildId: message.buildId } }));
+    state.lastRefresh={buildId:message.buildId,durationMs:Math.round(performance.now()-refreshStarted),changed};
+    await painted();state.confirmed=true;
+    globalThis.dispatchEvent(new CustomEvent('prnext:refresh', { detail: state.lastRefresh }));
+    globalThis.dispatchEvent(new CustomEvent('prnext:devtools:ready'));
+    if(state.typeErrors)typeDiagnostics(state.typeErrors);
   } catch (error) { showError(error); }
   finally {
-    state.applying = false; state.pending = null;
-    if (state.queued) { const queued = state.queued; state.queued = null; if (queued.buildId !== state.buildId) void applyUpdate(queued); }
+    state.applying = false; state.pending = null; state.indicator?.update();
+    applied();
+    if (state.queued) { const queued = state.queued; state.queued = null; if (queued.buildId !== state.buildId) void applyUpdate(queued,{navigation:queued.navigation}); }
   }
 }
 
 function connect(options) {
+  state.basePath=options.basePath||'';
   if (state.source) return;
   state.buildId = options.dev.buildId;
-  const source = new EventSource(`${options.basePath || ''}/_prnext/dev`);
+  state.sequence=options.dev.sequence||0;state.session=options.dev.session;
+  state.clientId ||= crypto.randomUUID();
+  state.onDemand=options.dev.onDemand===true;
+  state.devConnection = 'connecting'; state.devBuildState = 'ready';
+  if (options.dev.indicator === false) { state.consoleCapture?.dispose(); state.consoleCapture = null; state.consoleDisabled = true; }
+  const snapshot=()=>({connection:state.devConnection,building:state.devBuildState==='building'||state.applying,confirmed:state.confirmed===true,router:state.currentKind,buildId:state.buildId,sequence:state.sequence,typeErrors:state.typeErrors?.length||0,issues:(state.typeErrors?.length||0)+(hasCriticalIssue()?1:0)+(state.recoverableIssue?1:0),criticalIssues:hasCriticalIssue()?1:0,lastRefresh:state.lastRefresh});
+  state.tools ||= createDevToolsClient({capture:state.consoleCapture,snapshot,config:options.dev.tools||options.devTools});
+  showReloadReason();
+  if (options.dev.indicator !== false && !isDevicePreview() && !state.indicator) state.indicator = createDevIndicator({
+    tools:state.tools,
+    position: options.dev.indicator?.position,
+    capture: state.consoleCapture,
+    snapshot: () => ({
+      connection: state.devConnection, building: state.devBuildState === 'building' || state.applying,
+      router: state.currentKind, buildId: state.buildId, sequence: state.sequence,
+      typeErrors: state.typeErrors?.length || 0,
+      issues: (state.typeErrors?.length || 0) + (hasCriticalIssue() ? 1 : 0) + (state.recoverableIssue ? 1 : 0),
+      criticalIssues: hasCriticalIssue() ? 1 : 0,
+    }),
+    showIssues() {
+      const critical=hasCriticalIssue();
+      const error = critical?state.issue:state.recoverableIssue||state.issue||state.lastTypeDiagnostic;
+      if (error===undefined||error===null) return;
+      if (typeof error === 'object') state.dismissedErrors?.delete(error);
+      const key = errorKey(error); if (key) state.dismissedDigests?.delete(key);
+      state.dismissedTypeDiagnostic = undefined; showError(error,{retain:error!==state.recoverableIssue});
+      state.errorOverlay?.focusDismiss();
+    },
+  });
+  if (isDevicePreview()) { try { parent.postMessage({type:'prnext:preview-ready'}, location.origin); } catch {} }
+  state.ensureRoute=async raw=>{
+    if(!state.onDemand)return;
+    const url=new URL(raw,location.href);if(url.origin!==location.origin)return;
+    state.ensuring=(state.ensuring||0)+1;
+    try{
+    const response=await fetch(`${options.basePath||''}/_prnext/ensure?client=${state.clientId}&path=${encodeURIComponent(url.pathname+url.search)}`,{cache:'no-store',credentials:'same-origin'});
+    if(!response.ok)throw Error(await response.text());
+    const update=await response.json();
+    if(update.buildId!==state.buildId)await applyUpdate(update,{navigation:true});
+    }finally{state.ensuring--;}
+  };
+  const source = new EventSource(`${options.basePath || ''}/_prnext/dev?client=${state.clientId}&path=${encodeURIComponent(location.pathname+location.search)}`);
   state.source = source;
+  source.onopen = () => { state.devConnection = 'connected'; state.indicator?.update(); };
+  source.onerror = () => { state.devConnection = 'reconnecting'; state.indicator?.update(); };
   source.onmessage = event => {
     let message; try { message = JSON.parse(event.data); } catch { return; }
+    if(message.session&&state.session&&message.session!==state.session){reload('Development server restarted. Page reloaded.');return;}
+    state.devBuildState = message.state; state.indicator?.update();
+    if(Array.isArray(message.typeErrors))typeDiagnostics(message.typeErrors);
     if (message.state === 'error') { showError(message.error || 'Build failed'); return; }
     if (message.state !== 'ready') return;
     if (message.buildId === state.buildId) return;
-    void applyUpdate(message);
+    // A cold navigation may receive SSE readiness before its ensure response.
+    // Updating modules is safe; refreshing the old route would cancel the click.
+    // A retained branch can become cold after ensure() has returned. Its
+    // worker-triggered compilation is still part of the pending navigation;
+    // committing a refresh here would abort it and restore the previous URL.
+    void applyUpdate(message,{navigation:state.ensuring>0||message.reason?.code==='route-opened'});
   };
   globalThis.addEventListener('error', event => { if (event.error) showError(event.error); });
   globalThis.addEventListener('unhandledrejection', event => showError(event.reason));
-  globalThis.addEventListener('pagehide', () => source.close(), { once: true });
+  globalThis.addEventListener('pagehide', () => {source.close();state.tools?.dispose();state.stopHydrationDiagnostics?.();}, { once: true });
 }
 
 state.reportError = showError;
+state.reportRecoverableError = reportRecoverableError;
+if(state.consoleCapture&&!state.stopHydrationDiagnostics){
+  let serial=0;
+  // Attribute-only hydration mismatches are reported by React through console,
+  // without invoking onRecoverableError. Match its diagnostic, not arbitrary logs.
+  state.stopHydrationDiagnostics=state.consoleCapture.subscribe(()=>{
+    for(const entry of state.consoleCapture?.snapshot().entries||[]){
+      if(entry.id<=serial)continue;serial=entry.id;
+      if((entry.level==='error'||entry.level==='warn')&&entry.text.includes('https://react.dev/link/hydration-mismatch')&&/Hydration failed|A tree hydrated/i.test(entry.text))reportRecoverableError(entry.text);
+    }
+  });
+}
+function painted(){return new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve)));}
 state.bootstrap = (kind, options, start) => {
   state.currentKind = kind;
   if (!state.applications.has(kind)) {
+    state.confirmed=false;
     const application = Promise.resolve().then(start);
     state.applications.set(kind, application);
     connect(options);
-    application.catch(showError);
+    application.then(async current=>{await current.devReady;await painted();if(!state.applying){state.confirmed=true;globalThis.dispatchEvent(new CustomEvent('prnext:devtools:ready'));}},error=>{
+      state.bootstrapFailed={kind,buildId:options.dev.buildId};state.confirmed=false;showError(error);
+    }).catch(showError);
   } else if (state.applying) state.pending = { kind, options };
   return state.applications.get(kind);
 };

package/runtime/dev-compiler-broker.mjs

@@ -0,0 +1,42 @@
+import http from 'node:http';
+import {randomBytes,timingSafeEqual} from 'node:crypto';
+import {readFile,realpath} from 'node:fs/promises';
+import path from 'node:path';
+
+// Private control plane. Request headers and bodies never cross this endpoint.
+export async function createDevCompilerBroker({compile,maxPending=64}) {
+  const token=randomBytes(32).toString('base64url');let pending=0;
+  const server=http.createServer(async(req,res)=>{
+    const supplied=Buffer.from(req.headers.authorization||''),expected=Buffer.from('Bearer '+token);
+    if(req.method!=='POST'||req.url!=='/compile'||supplied.length!==expected.length||!timingSafeEqual(supplied,expected)){res.writeHead(403).end();return;}
+    if(pending>=maxPending){res.writeHead(503).end();return;}
+    pending++;
+    try{
+      const chunks=[];let bytes=0;
+      for await(const chunk of req){bytes+=chunk.length;if(bytes>65536)throw Error('Compiler request too large');chunks.push(chunk);}
+      // Decode once: an HTTP chunk boundary may split a UTF-8 route name.
+      const input=JSON.parse(Buffer.concat(chunks,bytes).toString('utf8'));if(typeof input.pattern!=='string'||!input.pattern.startsWith('/')||input.pattern.length>4096)throw Error('Invalid route pattern');
+      if(input.sources!==undefined&&(!Array.isArray(input.sources)||input.sources.length>32||!input.sources.every(p=>typeof p==='string'&&p.startsWith('/')&&p.length<=4096)))throw Error('Invalid retained route patterns');
+      const directory=await compile(input.pattern,input.sources||[]);
+      res.writeHead(200,{'content-type':'application/json','cache-control':'no-store'}).end(JSON.stringify({directory}));
+    }catch(error){res.writeHead(500,{'content-type':'application/json'}).end(JSON.stringify({error:String(error.message).slice(0,2048)}));}
+    finally{pending--;}
+  });
+  server.requestTimeout=125000;server.headersTimeout=5000;
+  await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(0,'127.0.0.1',resolve);});
+  return {descriptor:JSON.stringify({port:server.address().port,token}),close:()=>new Promise(resolve=>{server.close(resolve);server.closeIdleConnections();})};
+}
+
+export function deferredCompiler(descriptor,{root,home}) {
+  const value=JSON.parse(descriptor);
+  if(!Number.isInteger(value.port)||value.port<1||value.port>65535||!/^[\w-]{43}$/.test(value.token))throw Error('Invalid private compiler endpoint');
+  return async(pattern,signal,sources=[])=>{
+    const response=await fetch(`http://127.0.0.1:${value.port}/compile`,{method:'POST',headers:{authorization:'Bearer '+value.token,'content-type':'application/json'},body:JSON.stringify({pattern,sources}),signal:AbortSignal.any([...(signal?[signal]:[]),AbortSignal.timeout(120000)])});
+    const result=await response.json();if(!response.ok)throw Error(result.error||'Deferred route compilation failed');
+    const directory=await realpath(path.resolve(root,result.directory)),parent=await realpath(home),relative=path.relative(parent,directory);
+    if(!relative||relative.startsWith('..')||path.isAbsolute(relative))throw Error('Compiler generation escaped its development session');
+    const manifest=JSON.parse(await readFile(path.join(directory,'manifest.json'),'utf8'));
+    if(!manifest.dev||manifest.devSession!==path.basename(parent))throw Error('Invalid development generation');
+    return {distDir:directory,manifest};
+  };
+}

package/runtime/dev-console-copy.mjs

@@ -0,0 +1,19 @@
+export function consolePrompt(entries, {kind='logs',version,route='/',source='Page',dropped=0}={}) {
+  const groups = new Map();
+  const hasServer=entries.some(entry=>entry.source==='server');
+  for (const entry of entries) {
+    const key = (entry.source||'browser')+'\0'+entry.level + '\0' + entry.text;
+    const group = groups.get(key);
+    if (group) group.count++;
+    else groups.set(key,{entry,count:1});
+  }
+  const instruction = kind === 'errors' ? 'Fix all errors below.' : kind === 'message' ? `Investigate the ${hasServer?'server':'client'} message below and fix its root cause if it indicates a problem.` : `Review the ${hasServer?'development':'client'} logs below and fix the errors they reveal.`;
+  // The report deliberately omits URL query/fragment and browser/session data.
+  let path='/';try{path=new URL(route,'http://prnext.local').pathname;}catch{}
+  const header = [instruction,'','Context:',`- Framework: PRNext ${version || ''}`.trimEnd(),`- Route: ${path}`,`- Source: ${source} ${hasServer?'development console (browser and server)':'client console'}`,`- Captured messages: ${entries.length} (${groups.size} unique)`];
+  if(dropped)header.push('- Earlier messages were removed from the bounded console buffer.');
+  header.push('','Diagnostic messages:');
+  for (const {entry,count} of groups.values()) header.push('',`--- ${entry.level.toUpperCase()}${hasServer?' · '+(entry.source||'browser'):''}${count>1?` · ${count} occurrences`:''} ---`,entry.text);
+  header.push('','Find the root cause, make the smallest safe code changes, preserve intended behavior, and run the relevant checks.');
+  return header.join('\n');
+}

package/runtime/dev-console.mjs

@@ -0,0 +1,106 @@
+// Browser-only diagnostics. Records stay in this window, never sent to PRNext.
+// Bound both retained entries and formatting work; do not invoke object getters.
+const LIMIT = 500, TEXT_LIMIT = 128_000, TEXT_BUDGET = 2 * 1024 * 1024;
+const clip = text => text.length > TEXT_LIMIT ? text.slice(0,TEXT_LIMIT) + '\n[Message truncated at 128000 characters]' : text;
+const nativeStackGetter = Object.getOwnPropertyDescriptor(new Error(), 'stack')?.get;
+export function formatConsoleValue(value, depth = 0, seen = new WeakSet()) {
+  try {
+    if (typeof value === 'string') return clip(value);
+    if (typeof value === 'function') return '[Function]';
+    if (value === null || typeof value !== 'object') return clip(String(value));
+    if (seen.has(value)) return '[Circular]';
+    seen.add(value);
+    if (value instanceof Error) {
+      // Custom error properties can also be getters. Do not evaluate them.
+      const stack = Object.getOwnPropertyDescriptor(value, 'stack'), message = Object.getOwnPropertyDescriptor(value, 'message');
+      // V8 exposes its lazy stack as a shared native getter. Permit that getter,
+      // but never a custom accessor installed on a logged error object.
+      const nativeStack = nativeStackGetter && stack?.get === nativeStackGetter ? Reflect.apply(nativeStackGetter, value, []) : undefined;
+      const text = typeof nativeStack === 'string' ? nativeStack : stack && 'value' in stack && typeof stack.value === 'string' ? stack.value : message && 'value' in message && typeof message.value === 'string' ? message.value : '[Error]';
+      return clip(text);
+    }
+    if (depth >= 3) return Array.isArray(value) ? '[Array]' : '[Object]';
+    const keys = Object.keys(value), parts = [];
+    let remaining = TEXT_LIMIT;
+    for (const key of keys.slice(0, 20)) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      const text = descriptor && 'value' in descriptor ? formatConsoleValue(descriptor.value, depth + 1, seen) : '[Getter]';
+      const part = (Array.isArray(value) ? '' : key.slice(0, 100) + ': ') + text;
+      parts.push(part.slice(0, remaining)); remaining -= part.length;
+      if (remaining <= 0) break;
+    }
+    if (keys.length > parts.length) parts.push('…');
+    return clip(Array.isArray(value) ? '[' + parts.join(', ') + ']' : '{' + parts.join(', ') + '}');
+  } catch { return '[Unavailable]'; }
+}
+
+function formatArguments(args) {
+  const values = args.slice(0, 20);
+  if (typeof values[0] !== 'string') return clip(values.map(value => formatConsoleValue(value)).join(' '));
+  let index = 1;
+  const message = clip(values[0]).replace(/%[%sdifoOc]/g, token => {
+    if (token === '%%') return '%';
+    if (index >= values.length) return token;
+    const value = values[index++];
+    if (token === '%c') return '';
+    // Never coerce user objects through custom toString/valueOf methods.
+    if (/^%[dif]$/.test(token) && (typeof value === 'string' || typeof value === 'number')) return String(token === '%f' ? parseFloat(value) : parseInt(value, 10));
+    return formatConsoleValue(value);
+  });
+  return clip([message, ...values.slice(index).map(value => formatConsoleValue(value))].join(' '));
+}
+
+export function createConsoleCapture(target = globalThis) {
+  const entries = [], subscribers = new Set(), replacements = [];
+  let serial = 0, busy = false, scheduled = false, disposed = false, dropped = 0, retainedChars = 0;
+  function notify() {
+    if (scheduled || disposed) return;
+    scheduled = true;
+    queueMicrotask(() => {
+      scheduled = false;
+      if (!disposed) for (const subscriber of subscribers) { try { subscriber(); } catch {} }
+    });
+  }
+  function record(level, args) {
+    if (busy || disposed) return;
+    busy = true;
+    try {
+      const text=formatArguments(args);entries.push({id:++serial,time:Date.now(),level,text});retainedChars+=text.length;
+      while(entries.length>LIMIT||retainedChars>TEXT_BUDGET){retainedChars-=entries.shift().text.length;dropped++;}
+      notify();
+    } catch {} finally { busy = false; }
+  }
+  function clear() { entries.length = 0; dropped = 0;retainedChars=0;notify(); }
+  for (const method of ['log', 'info', 'warn', 'error', 'debug', 'table', 'trace', 'assert', 'clear']) {
+    const original = target.console?.[method];
+    if (typeof original !== 'function') continue;
+    const replacement = function (...args) {
+      // Keep the native console, return value and exception behavior intact.
+      try { return Reflect.apply(original, target.console, args); }
+      finally {
+        if (method === 'clear') clear();
+        else if (method === 'assert') { if (!args[0]) record('error', ['Assertion failed:', ...args.slice(1)]); }
+        else record(method === 'table' || method === 'trace' ? 'log' : method, args);
+      }
+    };
+    try { target.console[method] = replacement; replacements.push({method, original, replacement}); } catch {}
+  }
+  const onError = event => { if (event.error || event.message) record('error', [event.error || event.message]); };
+  const onRejection = event => record('error', ['Unhandled rejection:', event.reason]);
+  target.addEventListener('error', onError);
+  target.addEventListener('unhandledrejection', onRejection);
+  return {
+    snapshot: () => ({ entries: entries.slice(), dropped }), clear,
+    subscribe(callback) { subscribers.add(callback); return () => subscribers.delete(callback); },
+    dispose() {
+      disposed = true; subscribers.clear(); entries.length = 0;
+      for (const {method, original, replacement} of replacements) if (target.console[method] === replacement) target.console[method] = original;
+      target.removeEventListener('error', onError); target.removeEventListener('unhandledrejection', onRejection);
+    },
+  };
+}
+
+export function isDevicePreview() {
+  try { return globalThis.frameElement?.getAttribute('data-prnext-preview') === 'true'; }
+  catch { return false; }
+}

package/runtime/dev-dependency-graph.mjs

@@ -0,0 +1,40 @@
+// Keep inherited-stdio RPC frames below the native listener's 64 KiB limit.
+const FRAME_BYTES=48*1024,MAX_FILES=100000,MAX_RECORDS=50000,MAX_EDGES=1000000,MAX_BYTES=16*1024*1024;
+function batches(values){
+  const result=[];let batch=[],bytes=2;
+  for(const value of values){const size=Buffer.byteLength(JSON.stringify(value))+1;if(size>FRAME_BYTES)throw Error('Development graph entry exceeds the control frame budget');if(bytes+size>FRAME_BYTES){result.push(batch);batch=[];bytes=2;}batch.push(value);bytes+=size;}
+  if(batch.length)result.push(batch);return result;
+}
+export function compactDependencyGraph(manifest){
+  if(manifest.devDependencyStatus?.complete===false)throw Error(manifest.devDependencyStatus.reason||'Incomplete development graph');
+  const files=[],ids=new Map(),records=[];let edges=0,bytes=0;
+  const intern=file=>{if(typeof file!=='string'||!file||Buffer.byteLength(file)>8192)throw Error('Invalid development dependency');if(!ids.has(file)){bytes+=Buffer.byteLength(file);ids.set(file,files.length);files.push(file);}return ids.get(file);};
+  for(const record of [...manifest.devDependencies||[],...manifest.devModules||[]]){
+    const entries=[...new Set(record.files)].map(intern);edges+=entries.length;bytes+=Buffer.byteLength(record.route)+entries.length*4;
+    // Split a single very broad route too; the native builder merges its parts.
+    for(let offset=0;offset<Math.max(entries.length,1);offset+=4000)records.push({route:record.route,module:!!record.module,files:entries.slice(offset,offset+4000)});
+    if(files.length>MAX_FILES||records.length>MAX_RECORDS||edges>MAX_EDGES||bytes>MAX_BYTES)throw Error('Development graph exceeds its bounded file, edge or memory budget');
+  }
+  return {files,records,edges};
+}
+export async function publishDependencyGraph(gateway,manifest){
+  const graph=compactDependencyGraph(manifest),transaction=String(manifest.buildId);
+  await gateway.request('graph-begin',{transaction,files:graph.files.length,records:graph.records.length,edges:graph.edges});
+  try{
+    for(const files of batches(graph.files))await gateway.request('graph-files',{transaction,files});
+    for(const records of batches(graph.records))await gateway.request('graph-records',{transaction,records});
+    return await gateway.request('graph-commit',{transaction});
+  }catch(error){await gateway.request('graph-abort',{transaction}).catch(()=>{});throw error;}
+}
+export async function affectedDependencies(gateway,files){
+  const routes=new Set(),modules=new Set(),unknown=new Set();let complete=true;
+  for(const batch of batches(files).flatMap(batch=>{const chunks=[];for(let i=0;i<batch.length;i+=512)chunks.push(batch.slice(i,i+512));return chunks;})){
+    const result=await gateway.request('affected',{files:batch,transitive:true});
+    complete&&=result.complete!==false;
+    for(const value of result.routes||[])routes.add(value);for(const value of result.modules||[])modules.add(value);for(const value of result.unknown||[])unknown.add(value);
+  }
+  // HMR compiler messages and frontend notifications also have finite budgets.
+  if(Buffer.byteLength(JSON.stringify([...routes]))>32*1024||Buffer.byteLength(JSON.stringify([...modules]))>256*1024)complete=false;
+  return {routes:complete?[...routes]:[],modules:complete?[...modules]:[],unknown:[...unknown],complete};
+}
+export const canSkipUnopenedRoutes=(result,files,dormant,indexValid)=>indexValid&&result.complete!==false&&files.length>0&&result.unknown.length===files.length&&result.unknown.every(file=>dormant.has(file));

package/runtime/dev-element-picker-style.mjs

@@ -0,0 +1,27 @@
+// This chrome lives in its own shadow root and never changes application styles.
+export const elementPickerStyle = `
+  :host{all:initial;position:fixed;inset:0;overflow:hidden;pointer-events:none;z-index:2147483647;color-scheme:dark;color:#ededed;font:12px/1.4 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;text-align:left;direction:ltr}
+  *,*::before,*::after{box-sizing:border-box}[hidden]{display:none!important}svg{display:block;width:16px;height:16px;flex:none}
+  .target{position:fixed;left:0;top:0;outline:1px dashed #e8e5ee;outline-offset:0;box-shadow:0 0 0 1px #17141b80;background:transparent;pointer-events:none}
+  .corner{position:absolute;width:5px;height:5px;background:#f4f2f8;box-shadow:0 0 0 1px #17141b;pointer-events:none}
+  .corner[data-corner=tl]{left:-3px;top:-3px}.corner[data-corner=t]{left:calc(50% - 2.5px);top:-3px}.corner[data-corner=tr]{right:-3px;top:-3px}.corner[data-corner=r]{right:-3px;top:calc(50% - 2.5px)}
+  .corner[data-corner=bl]{left:-3px;bottom:-3px}.corner[data-corner=b]{left:calc(50% - 2.5px);bottom:-3px}.corner[data-corner=br]{right:-3px;bottom:-3px}.corner[data-corner=l]{left:-3px;top:calc(50% - 2.5px)}
+  .picker-tag{position:fixed;left:0;top:0;width:max-content;max-width:min(280px,calc(100vw - 16px));padding:4px 6px;border-radius:5px;background:#101014ed;pointer-events:none}
+  .picker-tag-top{display:flex;align-items:center;min-width:0}
+  .picker-dimensions{color:#b6b2bd;font:10px/1.4 ui-monospace,SFMono-Regular,Consolas,monospace;white-space:nowrap;font-variant-numeric:tabular-nums;flex:none}
+  .picker-source{display:flex;align-items:center;gap:6px;margin-top:4px;color:#f0edf5;font:500 11px/16px ui-monospace,SFMono-Regular,Consolas,monospace;white-space:nowrap;min-width:0}
+  .picker-source-name{min-width:0;overflow:hidden;text-overflow:ellipsis}.picker-source-line{flex:none;margin-left:-6px;color:#b6b2bd;font-variant-numeric:tabular-nums}
+  .picker-source-parent{flex:none;color:#a6a1ae;font:10px/16px ui-sans-serif,system-ui}
+  .picker-file-icon{display:grid;place-items:center;flex:none;width:15px;height:15px;border-radius:2px;color:#dad6e2;font:800 9px/1 ui-sans-serif,system-ui;letter-spacing:-.5px}.picker-file-icon svg{width:15px;height:15px}
+  .picker-file-icon[data-language=javascript]{background:#f7df1e;color:#17150b}.picker-file-icon[data-language=typescript]{background:#3178c6;color:#fff}.picker-file-icon[data-language=html]{background:#e34f26;color:#fff}.picker-file-icon[data-language=css]{background:#7956b5;color:#fff;font-size:12px}.picker-file-icon[data-language=json]{color:#f7df1e}.picker-file-icon[data-language=vue]{color:#60c59a}.picker-file-icon[data-language=svelte]{color:#ff7c55}.picker-file-icon[data-language=python]{color:#80b9ef}.picker-file-icon[data-language=rust]{color:#ebaa8e}
+  .hint{position:fixed;left:50%;bottom:max(16px,env(safe-area-inset-bottom));transform:translateX(-50%);display:flex;align-items:center;gap:10px;width:max-content;max-width:calc(100vw - 24px);padding:6px 6px 6px 14px;border:0;border-radius:22px;background:#080808;box-shadow:0 3px 8px #0006,0 12px 32px #0007;pointer-events:auto}
+  .picker-instruction{font-size:12px;font-weight:500;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+  .picker-enter{margin-left:4px}.hint kbd{display:inline-flex;align-items:center;justify-content:center;min-width:20px;height:20px;padding:0 4px;border:1px solid #343238;border-radius:5px;color:#939098;background:transparent;font:10px/1 ui-sans-serif,system-ui}
+  .picker-cancel{display:flex;align-items:center;justify-content:center;gap:9px;min-height:34px;padding:6px 10px;border:0;border-radius:15px;background:#191919;color:#ededed;font:500 11px/1.4 ui-sans-serif,system-ui;cursor:pointer;white-space:nowrap;flex:none;-webkit-tap-highlight-color:transparent}
+  .picker-cancel:hover{background:#252525}.picker-cancel:focus-visible{outline:1px solid #aaa;outline-offset:-3px;background:#252525}
+  .sr-only{position:absolute;width:1px;height:1px;padding:0;overflow:hidden;clip-path:inset(50%);white-space:nowrap}
+  @media(max-width:350px){.hint{gap:8px}.hint .picker-enter{display:none}.picker-tag{max-width:calc(100vw - 16px)}}
+  @media(pointer:coarse){.picker-cancel{min-width:64px;min-height:44px;padding-inline:12px}.picker-cancel kbd,.hint .picker-enter{display:none}.hint{border-radius:28px}.picker-cancel{border-radius:21px}}
+  @media(prefers-reduced-motion:no-preference){.picker-cancel{transition:background-color 120ms}.target,.picker-tag{animation:picker-mark-in 110ms ease-out}.target[data-motion=true]{transition:translate 110ms cubic-bezier(.22,.8,.2,1),width 110ms cubic-bezier(.22,.8,.2,1),height 110ms cubic-bezier(.22,.8,.2,1)}.picker-tag[data-motion=true]{transition:translate 110ms cubic-bezier(.22,.8,.2,1)}.hint{animation:picker-bar-in 180ms cubic-bezier(.16,1,.3,1)}@keyframes picker-mark-in{from{opacity:0}to{opacity:1}}@keyframes picker-bar-in{from{opacity:0;translate:0 6px}to{opacity:1;translate:0 0}}}
+  @media(forced-colors:active){.target{outline-color:Highlight;box-shadow:none;background:transparent}.corner{background:Highlight;box-shadow:0 0 0 1px Canvas}.picker-tag,.hint{background:Canvas;color:CanvasText;border:1px solid ButtonText;box-shadow:none}.picker-dimensions,.picker-source,.picker-source-line,.picker-source-parent{color:CanvasText}.picker-file-icon[data-language]{color:CanvasText;background:Canvas}.picker-cancel{background:ButtonFace;color:ButtonText;border:1px solid ButtonText}.picker-cancel:focus-visible{outline:2px solid Highlight;outline-offset:-3px}.hint kbd{color:ButtonText;border-color:ButtonText}}
+`;