@thomas.f/prnext 0.1.15-alpha → 0.1.17-alpha

package/runtime/dev-preview-touch.mjs

@@ -0,0 +1,122 @@
+// Mouse panning for same-origin mobile previews. Real touch/pen events retain
+// their native behavior; inputs and application-owned drag surfaces stay native.
+export function createPreviewTouch(document) {
+  const view = document.defaultView, root = document.documentElement;
+  if (!view?.PointerEvent || !root) return { cancel() {}, dispose() {} };
+  const controller = new view.AbortController(), capture = { capture: true, signal: controller.signal };
+  const reduced = view.matchMedia('(prefers-reduced-motion: reduce)');
+  let gesture, momentum = 0, blockedClick, sendingCancel = false;
+
+  function stopMomentum() { if (momentum) { try { view.cancelAnimationFrame(momentum); } catch {} } momentum = 0; }
+  function release(state) {
+    try { if (root.hasPointerCapture(state.pointer)) root.releasePointerCapture(state.pointer); } catch {}
+  }
+  function cancel() {
+    stopMomentum(); const state = gesture; gesture = undefined; blockedClick = undefined;
+    if (state) release(state);
+  }
+  function scrollPlan(event) {
+    const elements = event.composedPath().filter(node => node?.nodeType === 1);
+    if (elements.some(node => node.matches('input,textarea,select,option,video,audio,canvas,[role="slider"],[role="spinbutton"],[draggable="true"]') || node.isContentEditable)) return;
+    const chain = []; let x = true, y = true;
+    for (const node of elements) {
+      const style = view.getComputedStyle(node), action = style.touchAction;
+      if (action === 'none') return;
+      if (/pan-/.test(action)) {
+        x &&= /pan-(x|left|right)/.test(action); y &&= /pan-(y|up|down)/.test(action);
+      }
+      const viewport = node === document.scrollingElement;
+      // With visible root overflow, body overflow controls the viewport.
+      const overflowX = viewport && style.overflowX === 'visible' ? view.getComputedStyle(document.body || node).overflowX : style.overflowX;
+      const overflowY = viewport && style.overflowY === 'visible' ? view.getComputedStyle(document.body || node).overflowY : style.overflowY;
+      const canX = (viewport ? !/hidden|clip/.test(overflowX) : /auto|scroll|overlay/.test(overflowX)) && node.scrollWidth > node.clientWidth + 1;
+      const canY = (viewport ? !/hidden|clip/.test(overflowY) : /auto|scroll|overlay/.test(overflowY)) && node.scrollHeight > node.clientHeight + 1;
+      if (canX || canY) chain.push({ node, x: canX, y: canY, overscrollX: style.overscrollBehaviorX, overscrollY: style.overscrollBehaviorY });
+    }
+    if (chain.length && (x || y)) return { chain, x, y };
+  }
+  function pan(state, distance) {
+    let remaining = distance, consumed = 0;
+    const horizontal = state.axis === 'x', property = horizontal ? 'scrollLeft' : 'scrollTop';
+    for (const entry of state.chain) {
+      if (!entry[state.axis]) continue;
+      const before = entry.node[property];
+      entry.node.scrollBy({ [horizontal ? 'left' : 'top']: remaining, behavior: 'instant' });
+      const moved = entry.node[property] - before; consumed += moved; remaining -= moved;
+      if (Math.abs(remaining) < .5 || /contain|none/.test(entry[horizontal ? 'overscrollX' : 'overscrollY'])) break;
+    }
+    return consumed;
+  }
+  function coast(state) {
+    if (reduced.matches || Math.abs(state.velocity) < .08 || view.performance.now() - state.time > 80) return;
+    const started = view.performance.now(); let previous = started, velocity = state.velocity;
+    const tick = now => {
+      momentum = 0;
+      const elapsed = Math.min(32, now - previous); previous = now;
+      if (now - started > 700 || Math.abs(velocity) < .02) return;
+      const moved = pan(state, velocity * elapsed);
+      velocity *= Math.exp(-elapsed / 160);
+      if (Math.abs(moved) > .1) momentum = view.requestAnimationFrame(tick);
+    };
+    momentum = view.requestAnimationFrame(tick);
+  }
+  function begin(event) {
+    if (event.pointerType !== 'mouse') { cancel(); return; }
+    if (event.pointerType !== 'mouse' || !event.isPrimary || event.button !== 0 || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey || event.defaultPrevented) return;
+    cancel(); const plan = scrollPlan(event); if (!plan) return;
+    gesture = { ...plan, pointer: event.pointerId, target: event.target, startX: event.clientX, startY: event.clientY,
+      lastX: event.clientX, lastY: event.clientY, time: view.performance.now(), velocity: 0, axis: undefined };
+  }
+  function move(event) {
+    const state = gesture; if (!state || event.pointerId !== state.pointer) return;
+    const now = view.performance.now();
+    if (!state.axis) {
+      const dx = event.clientX - state.startX, dy = event.clientY - state.startY;
+      if (Math.hypot(dx, dy) < 6) return;
+      const axis = Math.abs(dx) > Math.abs(dy) ? 'x' : 'y';
+      if (!state[axis] || !state.chain.some(entry => entry[axis])) { gesture = undefined; return; }
+      state.axis = axis;
+      // Like native panning, release the control that received pointerdown so
+      // pressed controls and custom pointer capture do not remain stuck.
+      sendingCancel = true;
+      try { state.target.dispatchEvent(new view.PointerEvent('pointercancel', { bubbles: true, composed: true, pointerId: state.pointer, pointerType: 'mouse', isPrimary: true })); }
+      finally { sendingCancel = false; }
+      if (gesture !== state) return;
+      try { root.setPointerCapture(state.pointer); } catch {}
+    }
+    event.preventDefault(); event.stopImmediatePropagation();
+    const delta = state.axis === 'x' ? state.lastX - event.clientX : state.lastY - event.clientY;
+    const moved = pan(state, delta), elapsed = Math.max(8, now - state.time);
+    const speed = Math.max(-3, Math.min(3, moved / elapsed));
+    state.velocity = speed * .7 + state.velocity * .3;
+    state.lastX = event.clientX; state.lastY = event.clientY; state.time = now;
+  }
+  function end(event) {
+    const state = gesture; if (!state || event.pointerId !== state.pointer) return;
+    gesture = undefined;
+    if (state.axis) {
+      event.preventDefault(); event.stopImmediatePropagation();
+      blockedClick = { pointer: state.pointer, time: view.performance.now() }; coast(state);
+    }
+    release(state);
+  }
+  function preventActivation(event) {
+    if (!blockedClick || event.detail === 0 || view.performance.now() - blockedClick.time > 500) return;
+    if (event.pointerId !== undefined && event.pointerId !== blockedClick.pointer) return;
+    event.preventDefault(); event.stopImmediatePropagation();
+    if (event.type === 'click') blockedClick = undefined;
+  }
+  document.addEventListener('pointerdown', begin, capture);
+  document.addEventListener('pointermove', move, { ...capture, passive: false });
+  document.addEventListener('pointerup', end, capture);
+  document.addEventListener('pointercancel', event => { if (!sendingCancel && event.pointerId === gesture?.pointer) cancel(); }, capture);
+  document.addEventListener('lostpointercapture', event => { if (event.target === root && event.pointerId === gesture?.pointer) cancel(); }, capture);
+  document.addEventListener('click', preventActivation, capture);
+  document.addEventListener('mouseup', preventActivation, capture);
+  for (const name of ['selectstart', 'dragstart']) document.addEventListener(name, event => { if (gesture) event.preventDefault(); }, capture);
+  document.addEventListener('wheel', cancel, { ...capture, passive: true });
+  document.addEventListener('keydown', cancel, capture);
+  for (const name of ['blur', 'pagehide', 'resize']) view.addEventListener(name, cancel, { signal: controller.signal });
+  reduced.addEventListener('change', cancel, { signal: controller.signal });
+  return { cancel, dispose() { cancel(); controller.abort(); } };
+}

package/runtime/dev-runtime-pool.mjs

@@ -0,0 +1,45 @@
+import {spawn} from 'node:child_process';
+import {randomBytes} from 'node:crypto';
+import {writeFile,rm} from 'node:fs/promises';
+import {fileURLToPath} from 'node:url';
+import path from 'node:path';
+import {EventEmitter} from 'node:events';
+
+export function createDevRuntimePool({binary,root,home,environment={},onChild=()=>{}}){
+  let spare,disposed=false;const children=new Set();
+  function create(){
+    if(disposed)throw Error('Development runtime is closed');
+    const token=randomBytes(32).toString('base64url');
+    const child=spawn(binary,['dev-spare',root,'--node',process.execPath,'--script',fileURLToPath(new URL('./dev-runtime-spare.mjs',import.meta.url))],{cwd:root,windowsHide:true,stdio:['pipe','pipe','pipe'],env:{...process.env,...environment,NODE_ENV:'development',PRNEXT_DEV_SPARE_TOKEN:token}});
+    children.add(child);onChild(child);
+    const messages=new EventEmitter();let buffer='';child.stdout.setEncoding('utf8');child.stdout.on('data',chunk=>{buffer+=chunk;if(buffer.length>65536){child.kill();return;}for(let end;(end=buffer.indexOf('\n'))>=0;){const line=buffer.slice(0,end);buffer=buffer.slice(end+1);try{const message=JSON.parse(line);if(message.type)messages.emit(message.type,message);}catch{}}});
+    child.once('exit',()=>{children.delete(child);if(spare?.child===child)spare=undefined;});
+    child.stdin.on('error',()=>{});
+    const wait=type=>new Promise((resolve,reject)=>{
+      const timeout=setTimeout(()=>fail(Error('Development runtime warmup timed out')),15000);
+      const clean=()=>{clearTimeout(timeout);messages.off(type,message);child.off('exit',exit);child.off('error',fail);};
+      const fail=error=>{clean();reject(error);};const exit=()=>fail(Error('Development runtime exited'));
+      const message=value=>{clean();resolve(value);};
+      messages.on(type,message);child.once('exit',exit);child.once('error',fail);
+    });
+    const ready=wait('warm');ready.catch(()=>{if(spare?.child===child)spare=undefined;void stop(child);});
+    return {child,token,ready,wait};
+  }
+  async function stop(child){
+    if(!child?.pid||child.exitCode!==null||child.signalCode)return;
+    await new Promise(resolve=>{const timer=setTimeout(()=>child.kill('SIGKILL'),30000);child.once('exit',()=>{clearTimeout(timer);resolve();});child.stdin.end();if(child.connected)child.disconnect();});
+  }
+  return {
+    warm(){if(!spare)spare=create();return spare.ready;},
+    async take(directory){
+      const selected=spare||create();spare=undefined;
+      try{
+        const {port,guardPort}=await selected.ready,dist=path.join(root,directory),armed=selected.wait('armed');selected.child.stdin.write(JSON.stringify({type:'arm',dist})+'\n');await armed;
+        const descriptor=path.join(home,'transport-'+path.basename(directory)+'.json');
+        await writeFile(descriptor,JSON.stringify({project:root,dist,port,guardPort,token:selected.token}),{mode:0o600,flag:'wx'});
+        spare=create();return {child:selected.child,descriptor,pid:selected.child.pid,close:async()=>{await stop(selected.child);await rm(descriptor,{force:true});}};
+      }catch(error){await stop(selected.child);throw error;}
+    },
+    async close(){disposed=true;await Promise.all([...children].map(stop));},
+  };
+}

package/runtime/dev-runtime-spare.mjs

@@ -0,0 +1,57 @@
+// One prewarmed process becomes exactly one immutable development generation.
+// It is owned by the CLI, never shared across builds or production projects.
+import net from 'node:net';
+import {timingSafeEqual} from 'node:crypto';
+import {realpath,readFile} from 'node:fs/promises';
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {createRequire} from 'node:module';
+const root=await realpath(process.cwd()),token=process.env.PRNEXT_DEV_SPARE_TOKEN;
+delete process.env.PRNEXT_DEV_SPARE_TOKEN;
+if(!token)throw Error('Private development parent required');
+const announce=value=>process.stdout.write(JSON.stringify(value)+'\n');
+const spareHeartbeat=setInterval(()=>process.stdout.write('alive\n'),1000);spareHeartbeat.unref();
+// Warm framework dependencies only; no application module or data function runs.
+const require=createRequire(path.join(root,'package.json'));
+try{require('react');require('react-dom/server.node');}catch{/* Actual bootstrap reports missing peers. */}
+let armed,starting,ready;
+const controls=new Map();
+globalThis.__PRNEXT_DEV_WORKER_PULSE__=line=>{for(const[socket,watch]of controls)if(watch&&!socket.destroyed)socket.write(line);};
+const broker=net.createServer(socket=>{
+  socket.setNoDelay(true);socket.setTimeout(10000,()=>socket.destroy());let source='';
+  socket.on('data',chunk=>{
+    source+=chunk;if(Buffer.byteLength(source)>8192){socket.destroy();return;}
+    if(!source.includes('\n'))return;socket.removeAllListeners('data');
+    void(async()=>{
+      const input=JSON.parse(source.trim()),supplied=Buffer.from(input.token||''),expected=Buffer.from(token);
+      if(supplied.length!==expected.length||!timingSafeEqual(supplied,expected)||!armed||input.project!==root||input.dist!==armed.dist)throw Error('Invalid generation capability');
+      if(!starting)starting=(async()=>{
+        const manifest=JSON.parse(await readFile(path.join(armed.dist,'manifest.json'),'utf8'));
+        if(manifest.dev!==true)throw Error('Development build required');
+        for(const key of ['PRNEXT_CACHE_URL','PRNEXT_CACHE_TOKEN'])delete process.env[key];
+        if(input.cache){process.env.PRNEXT_CACHE_URL=input.cache.url;process.env.PRNEXT_CACHE_TOKEN=input.cache.token;}
+        process.env.PRNEXT_WORKER_SOCKET=String(Math.max(1,Math.min(512,input.lanes||1)));
+        process.env.PRNEXT_WORKER_TOKEN=token;process.env.PRNEXT_WORKER_ACTIVITY='1';
+        clearInterval(spareHeartbeat);
+        process.argv=[process.execPath,path.join(armed.dist,'runtime/worker.mjs'),root,armed.dist];
+        const announced=new Promise(resolve=>{globalThis.__PRNEXT_DEV_WORKER_READY__=resolve;});
+        await import(pathToFileURL(process.argv[1]).href);ready=await announced;
+        return ready;
+      })().catch(()=>process.exit(1));
+      const info=await starting;if(!socket.destroyed){
+        socket.setTimeout(0);controls.set(socket,input.watch===true);socket.write(JSON.stringify(info)+'\n');
+        let command='';socket.on('data',chunk=>{command+=chunk;if(command.length>16){socket.destroy();return;}if(command==='retire\n')process.stdin.emit('end');});
+      }
+    })().catch(()=>socket.destroy());
+  });
+  socket.on('error',()=>{});
+  socket.on('close',()=>{const owned=controls.delete(socket);if(owned&&!controls.size&&ready)process.stdin.emit('end');});
+});
+broker.maxConnections=16;
+broker.listen(0,'127.0.0.1',()=>{broker.unref();announce({type:'warm',port:broker.address().port});});
+let control='';const arm=chunk=>{control+=chunk;if(control.length>8192)process.exit(1);if(!control.includes('\n'))return;process.stdin.off('data',arm);
+  let message;try{message=JSON.parse(control.trim());}catch{process.exit(1);}if(message?.type!=='arm'||armed)process.exit(1);
+  void realpath(message.dist).then(dist=>{if(!dist.startsWith(root+path.sep))throw Error('Generation outside project');armed={dist};announce({type:'armed'});}).catch(()=>process.exit(1));
+};process.stdin.on('data',arm);
+// Parent lifetime is guarded even while this is still an unused spare.
+process.stdin.resume();process.stdin.once('end',()=>{broker.close();if(!starting)process.exit();});

package/runtime/dev-tools-client.mjs

@@ -0,0 +1,155 @@
+import { safeRequestPath, normalizeEntries } from './dev-tools-model.mjs';
+
+// The development-only sidecar is bound to loopback and authenticated with an
+// ephemeral session capability. Diagnostics stay local by default; the explicit
+// Host AI relay shares tool responses only when the connected assistant asks.
+export function createDevToolsClient({ capture, snapshot = () => ({}), config, target = globalThis } = {}) {
+  const nativeFetch = target.fetch?.bind(target), subscribers = new Set();
+  const clientId = target.crypto?.randomUUID?.() || 'browser-' + Math.random().toString(36).slice(2);
+  const valid = config?.version === 1 && typeof config.token === 'string' && /^http:\/\/(?:127\.0\.0\.1|localhost|\[::1\]):\d+$/.test(config.endpoint || '');
+  let disposed = false, data = {}, connection = valid ? 'connecting' : 'unavailable', polling = 0, pollTimer, pollingRequest;
+  let requests = [], serial = 0, logSerial = 0, reportTimer, lastSummary, lastContext, lastError;
+  let browserInFlight = 0; const browserQueue = [];
+  const pending = new Map(), originals = [], localEvents = new AbortController();
+  const base = () => target.location?.href || 'http://localhost/';
+  const state = () => ({ ...data, connection, available: valid, clientId, localRequests: requests.slice(), context: lastContext, error: lastError || data.error });
+  function notify() { for (const subscriber of subscribers) { try { subscriber(state()); } catch {} } }
+  async function request(path, body, timeout = 8000) {
+    if (!valid || disposed || !nativeFetch) throw Error('The local development tools are unavailable. Restart PRNext dev.');
+    const controller = new AbortController(); const timer = target.setTimeout(() => controller.abort(), timeout); pending.set(controller,timer);
+    try {
+      const response = await nativeFetch(config.endpoint + path, { method: 'POST', mode: 'cors', cache: 'no-store', credentials: 'omit',
+        headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + config.token }, body: JSON.stringify(body), signal: controller.signal });
+      const result = await response.json(); if (!response.ok) {const error=Error(result?.error?.message || result?.error || 'Local tools request failed (' + response.status + ').');error.status=response.status;error.code=result?.code;throw error;}
+      connection = 'connected'; lastError = undefined; return result;
+    } catch (error) { if (!disposed) { connection = error.status&&![401,403].includes(error.status)?'connected':'disconnected'; lastError = error.name === 'AbortError' ? 'Local tools request timed out.' : error.message; } throw error; }
+    finally { target.clearTimeout(timer); pending.delete(controller); }
+  }
+  async function call(name, args = {}) {
+    try { return await request('/v1/tools/' + encodeURIComponent(name), args, name === 'dev_verify' ? 35000 : 10000); }
+    finally { notify(); }
+  }
+  async function refresh() {
+    if (!valid || disposed) return state();
+    if (pollingRequest) return pollingRequest;
+    pollingRequest = call('dev_snapshot').then(result => { data = result; notify(); return state(); }).catch(() => state()).finally(() => { pollingRequest = undefined; });
+    return pollingRequest;
+  }
+  function browser(kind, extras = {}) {
+    if (!valid || disposed) return Promise.resolve();
+    const info = snapshot();
+    const body = { session: config.session, clientId, buildId: info.buildId ?? null, sequence: info.sequence || 0,
+      path: target.location?.pathname || '/', issues: info.issues || 0, typeErrors: info.typeErrors || 0, building: Boolean(info.building),
+      confirmed: info.confirmed === true, hydrated: info.confirmed === true, kind, ...extras };
+    return new Promise(resolve => {
+      if (browserQueue.length >= 100) browserQueue.shift().resolve();
+      browserQueue.push({ body, resolve }); pumpBrowser();
+    });
+  }
+  function pumpBrowser() {
+    while (!disposed && browserInFlight < 2 && browserQueue.length) {
+      const job = browserQueue.shift(); browserInFlight++;
+      void request('/v1/browser', job.body).catch(() => {}).finally(() => { browserInFlight--;job.resolve();pumpBrowser(); });
+    }
+  }
+  function report() {
+    if (disposed) return;
+    const entries = capture?.snapshot().entries || [];
+    const brief = text => text.length > 8000 ? text.slice(0, 7900) + '\n[Truncated for the local AI bridge; full message remains in the browser console.]' : text;
+    const unsent = entries.filter(entry => entry.id > logSerial);
+    const fresh = unsent.slice(-20).map(entry => ({ ...entry, text: brief(entry.text) }));
+    if (fresh.length) logSerial = fresh.at(-1).id;
+    const info = snapshot(), summary = [info.buildId, info.sequence, info.issues, info.typeErrors, info.building, info.confirmed].join(':');
+    const errors = entries.filter(entry => entry.level === 'error').slice(-10).map(entry => ({ id: entry.id, text: brief(entry.text), time: entry.time }));
+    void browser(summary !== lastSummary && !info.building && info.confirmed === true ? 'applied' : info.issues || errors.length ? 'errors' : 'heartbeat', {
+      logs: fresh, droppedLogs: Math.max(0, unsent.length - 20) + (capture?.snapshot().dropped || 0), errors, issues: info.issues || 0, typeErrors: info.typeErrors || 0, building: Boolean(info.building),
+      visibility: target.document?.visibilityState || 'visible', hydrated: info.confirmed === true, confirmed: info.confirmed === true,
+    }); lastSummary = summary;
+  }
+  function scheduleReport() { if (!reportTimer && valid) reportTimer = target.setTimeout(() => { reportTimer = undefined; report(); }, 300); }
+  function recordRequest(entry) {
+    if (disposed) return;
+    const record = { ...entry, id: ++serial, source: 'browser' };
+    requests.push(record); if (requests.length > 300) requests.shift();
+    void browser('request', { request: record }); notify();
+  }
+  function ignored(url) {
+    return valid && url.origin === config.endpoint || /\/_prnext\/(?:dev|ensure|assets)\b/.test(url.pathname);
+  }
+  if (nativeFetch) {
+    const original = target.fetch;
+    const replacement = function (...args) {
+      let url, method = 'GET';
+      try { url = new URL(typeof args[0] === 'string' || args[0] instanceof URL ? String(args[0]) : args[0].url, base()); method = String(args[1]?.method || args[0]?.method || 'GET').toUpperCase(); } catch {}
+      const started = target.performance?.now?.() ?? Date.now(), time = Date.now();
+      return Reflect.apply(original, target, args).then(response => {
+        if (url && !ignored(url)) recordRequest({ method, path: safeRequestPath(url.href, base()), status: response.status, time,
+          duration: Math.max(0, (target.performance?.now?.() ?? Date.now()) - started), kind: 'fetch', failed: !response.ok });
+        return response;
+      }, error => {
+        if (url && !ignored(url)) recordRequest({ method, path: safeRequestPath(url.href, base()), status: null, time,
+          duration: Math.max(0, (target.performance?.now?.() ?? Date.now()) - started), kind: 'fetch', failed: true, error: error.name === 'AbortError' ? 'Aborted' : 'Network error' });
+        throw error;
+      });
+    };
+    try { target.fetch = replacement; originals.push(() => { if (target.fetch === replacement) target.fetch = original; }); } catch {}
+  }
+  const xhr = target.XMLHttpRequest?.prototype;
+  if (xhr) {
+    const open = xhr.open, send = xhr.send, records = new WeakMap();
+    const wrappedOpen = function (method, raw, ...args) { const result = Reflect.apply(open, this, [method, raw, ...args]); records.delete(this);try { const url = new URL(raw, base()); if (!ignored(url)) records.set(this, { method: String(method).toUpperCase(), path: safeRequestPath(url.href, base()), kind: 'xhr' }); } catch {} return result; };
+    const wrappedSend = function (...args) {
+      const entry = records.get(this); if (entry) { const start = target.performance?.now?.() ?? Date.now(), time = Date.now();
+        this.addEventListener('loadend', () => { recordRequest({ ...entry, time, status: this.status || null, failed: this.status === 0 || this.status >= 400,
+          duration: Math.max(0, (target.performance?.now?.() ?? Date.now()) - start) }); }, { once: true }); }
+      return Reflect.apply(send, this, args);
+    };
+    try { xhr.open = wrappedOpen; xhr.send = wrappedSend; originals.push(() => { if (xhr.open === wrappedOpen) xhr.open = open; if (xhr.send === wrappedSend) xhr.send = send; }); } catch {}
+  }
+  const unsubscribe = capture?.subscribe(() => { scheduleReport(); notify(); });
+  target.addEventListener?.('prnext:refresh', scheduleReport, { signal: localEvents.signal });
+  target.addEventListener?.('prnext:devtools:ready', scheduleReport, { signal: localEvents.signal });
+  target.addEventListener?.('popstate', scheduleReport, { signal: localEvents.signal });
+  target.addEventListener?.('prnext:devtools:ai', event => {
+    const detail = event.detail || {};
+    lastContext = detail.kind === 'error' ? { ...detail, text: detail.error?.message || String(detail.error || ''),
+      source: detail.source?.file ? `${detail.source.file}:${detail.source.line}:${detail.source.column}` : detail.source,
+      mappedSource: detail.source?.file ? detail.source : undefined,
+    } : detail;
+    notify(); target.dispatchEvent(new CustomEvent('prnext:devtools:context', { detail: lastContext }));
+  }, { signal: localEvents.signal });
+  const heartbeat = valid ? target.setInterval(report, 5000) : undefined;
+  if (valid) scheduleReport();
+  function watch() {
+    polling++; void refresh();
+    if (!pollTimer) pollTimer = target.setInterval(() => void refresh(), 1500);
+    let watching=true;
+    return () => { if(!watching)return;watching=false;if (--polling <= 0) { polling = 0; target.clearInterval(pollTimer); pollTimer = undefined; } };
+  }
+  function captureFor(store = capture) {
+    let clearedAt = 0;
+    return {
+      snapshot() { const captured = store?.snapshot() || { entries: [], dropped: 0 }; return { entries: normalizeEntries({ ...data, serverLogs: (data.serverLogs || []).filter(entry => (entry.time || entry.timestamp || 0) > clearedAt) }, captured.entries), dropped: captured.dropped }; },
+      subscribe(callback) { subscribers.add(callback); const stop = watch(), stopCapture = store !== capture ? store?.subscribe(callback) : undefined; return () => { subscribers.delete(callback); stop(); stopCapture?.(); }; },
+      clear() { store?.clear(); clearedAt = Date.now(); notify(); },
+    };
+  }
+  const unified = captureFor();
+  return {
+    call, refresh, snapshot: state, subscribe(callback) { subscribers.add(callback); return () => subscribers.delete(callback); }, watch,
+    consoleCapture: unified, captureFor, localCapture: capture, browser, report, endpoint: config?.endpoint,
+    setContext(context) { lastContext = context; notify(); },
+    async sendContext(context, prompt) {
+      const submitted=lastContext;
+      const latest=await refresh();
+      if(latest.connection!=='connected'||latest.ai?.connected!==true)throw Error('Connect your assistant before sending a request.');
+      let result;
+      try{result=await call('dev_ai_context', { kind: context.kind || 'selection', context, prompt });}
+      catch(error){if(error.code==='assistant_required'){data={...data,ai:{...data.ai,connected:false}};notify();}throw error;}
+      if(result.queued!==true||result.connected!==true){if(result.connected!==true){data={...data,ai:{...data.ai,connected:false}};notify();}throw Error('Your assistant is no longer connected. Reconnect and try again.');}
+      if(lastContext===submitted)lastContext = { ...context, sent: true }; notify(); return result;
+    },
+    dispose() { disposed = true; unsubscribe?.(); localEvents.abort(); target.clearInterval(heartbeat); target.clearInterval(pollTimer); target.clearTimeout(reportTimer);
+      for (const job of browserQueue.splice(0)) job.resolve();for (const [controller,timer] of pending) { controller.abort();target.clearTimeout(timer); } pending.clear();for (const restore of originals.reverse()) restore(); subscribers.clear(); requests = []; },
+  };
+}

package/runtime/dev-tools-mcp.mjs

@@ -0,0 +1,126 @@
+import {devToolResult} from './dev-tools-result.mjs';
+import {open,realpath,lstat} from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {StringDecoder} from 'node:string_decoder';
+import {randomUUID} from 'node:crypto';
+import path from 'node:path';
+import {devToolDefinitions} from './dev-tools-server.mjs';
+
+/** Read only this project's private capability, never a URL supplied by a tool. */
+export async function readDevToolsConnection(directory){
+  const root=await realpath(directory),container=path.join(root,'.prnext-dev'),filename=path.join(container,'tools.json');
+  const parent=await lstat(container).catch(error=>{if(error.code==='ENOENT')throw Error('Start prnext dev in this project before connecting its MCP.');throw error;});
+  if(!parent.isDirectory()||parent.isSymbolicLink()||await realpath(container)!==container)throw Error('Invalid development connection directory');
+  const info=await lstat(filename).catch(error=>{if(error.code==='ENOENT')throw Error('Start prnext dev in this project before connecting its MCP.');throw error;});
+  if(!info.isFile()||info.isSymbolicLink()||info.size>4096)throw Error('Invalid development connection file');
+  if(process.platform!=='win32'&&(info.mode&0o077))throw Error('Development connection file must be private (0600)');
+  const handle=await open(filename,constants.O_RDONLY|(constants.O_NOFOLLOW||0));let value;try{const stat=await handle.stat();if(!stat.isFile()||stat.size>4096||stat.ino!==info.ino)throw Error('Development connection file changed');value=JSON.parse(await handle.readFile('utf8'));}finally{await handle.close();}
+  let endpoint;try{endpoint=new URL(value.endpoint);}catch{throw Error('Invalid development endpoint');}
+  if(value.version!==1||value.root!==root||endpoint.protocol!=='http:'||endpoint.hostname!=='127.0.0.1'||!endpoint.port||endpoint.username||endpoint.password||endpoint.pathname!=='/'||endpoint.search||endpoint.hash||!Number.isInteger(value.pid)||value.pid<=0||!/^[\w-]{40,100}$/.test(value.token||''))throw Error('Invalid development connection file');
+  try{process.kill(value.pid,0);}catch{throw Error('Development session is no longer running. Restart prnext dev.');}
+  return value;
+}
+export async function callLocalDevTool(directory,name,args={}, {client='PRNext stdio MCP',fetcher=fetch,assistantId,leaseId}={}){
+  if(!devToolDefinitions.some(tool=>tool.name===name))throw Error('Unknown development tool');
+  const connection=await readDevToolsConnection(directory);
+  const response=await fetcher(connection.endpoint+'/v1/tools/'+name,{method:'POST',headers:{Authorization:'Bearer '+connection.token,'Content-Type':'application/json','X-PRNext-Client':client.slice(0,100),...(assistantId?{'X-PRNext-Assistant':assistantId,'X-PRNext-Lease':leaseId}:{})},body:JSON.stringify(args),signal:AbortSignal.timeout(name==='dev_verify'?35000:30000)});
+  const result=await response.json();if(!response.ok)throw Object.assign(Error(result.error||'Local development tool failed'),{code:result.code});
+  if(result.session!==connection.session)throw Error('Development session changed; retry the tool');return result;
+}
+/** Initialized stdio sessions stay connected while their input pipe is alive. */
+export function createDevAssistantLease(directory,{fetcher=fetch,heartbeatMs=10000}={}){
+  const instanceId=randomUUID();let client='PRNext MCP client',started=false,closed=false,timer,pending,lease,closing,lastBeat=0;
+  async function post(connection,body,timeout=3000){
+    const response=await fetcher(connection.endpoint+'/v1/assistant',{method:'POST',headers:{Authorization:'Bearer '+connection.token,'Content-Type':'application/json'},body:JSON.stringify(body),signal:AbortSignal.timeout(timeout)});
+    const result=await response.json();if(!response.ok)throw Object.assign(Error(result.error||'Assistant initialization failed'),{code:result.code});
+    if(result.session!==connection.session)throw Error('Development session changed; retry initialization');return result;
+  }
+  function maintain(force=false){
+    if(closed)return Promise.resolve(false);if(pending)return pending;
+    pending=(async()=>{
+      const connection=await readDevToolsConnection(directory);
+      if(lease&&lease.connection.session!==connection.session)lease=undefined;
+      if(lease&&!force&&Date.now()-lastBeat<heartbeatMs)return true;
+      if(lease){
+        try{await post(connection,{event:'heartbeat',instanceId,leaseId:lease.id});lastBeat=Date.now();return true;}
+        catch(error){if(error.code!=='assistant_lease_expired')throw error;lease=undefined;}
+      }
+      const result=await post(connection,{event:'register',instanceId,client});
+      if(typeof result.leaseId!=='string'||!/^[\w-]{20,100}$/.test(result.leaseId))throw Error('Invalid assistant initialization reply');
+      lease={id:result.leaseId,connection};lastBeat=Date.now();return true;
+    })().catch(()=>false).finally(()=>{pending=undefined;});return pending;
+  }
+  return {
+    async start(info){
+      if(started||closed)return maintain();started=true;
+      if(typeof info?.name==='string'&&info.name.trim())client=info.name.replace(/[\u0000-\u001f\u007f]/g,' ').slice(0,100);
+      const ready=await maintain();if(!closed){timer=setInterval(()=>void maintain(true),heartbeatMs);timer.unref?.();}return ready;
+    },
+    async call(name,args){
+      if(closed)throw Error('MCP session closed');if(!started)throw Error('Initialize the MCP session first');
+      if(!await maintain()||!lease)throw Error('The development assistant connection is unavailable. Start prnext dev in this project.');
+      const invoke=()=>callLocalDevTool(directory,name,args,{fetcher,client:'PRNext stdio MCP',assistantId:instanceId,leaseId:lease.id});
+      try{return await invoke();}catch(error){
+        // Expired leases are rejected before a tool executes, so only this error
+        // can safely reinitialize and retry without duplicating a mutation.
+        if(error.code!=='assistant_lease_expired'||closed)throw error;lease=undefined;
+        if(!await maintain(true)||!lease)throw error;return invoke();
+      }
+    },
+    close(){
+      if(closing)return closing;closed=true;clearInterval(timer);
+      closing=(async()=>{await pending;if(lease)try{await post(lease.connection,{event:'unregister',instanceId,leaseId:lease.id},1000);}catch{}lease=undefined;})();return closing;
+    },
+  };
+}
+export function devMcpReply(message,invoke){
+  if(!message||message.jsonrpc!=='2.0'||typeof message.method!=='string')throw Error('Invalid JSON-RPC request');
+  if(Object.hasOwn(message,'id')&&message.id!==null&&!['string','number'].includes(typeof message.id))throw Error('Invalid JSON-RPC id');
+  if(!Object.hasOwn(message,'id'))return;
+  const reply=result=>({jsonrpc:'2.0',id:message.id,result});
+  if(message.method==='initialize')return reply({protocolVersion:['2025-11-25','2025-06-18','2025-03-26','2024-11-05'].includes(message.params?.protocolVersion)?message.params.protocolVersion:'2025-06-18',capabilities:{tools:{listChanged:false}},serverInfo:{name:'PRNext local development',version:'1.0.0'},instructions:'Local project development only. After edits, call dev_verify with the previous snapshot sequence. A compiled generation alone is not browser verification. No shell or arbitrary file access is exposed.'});
+  if(message.method==='ping')return reply({});
+  if(message.method==='tools/list')return reply({tools:devToolDefinitions});
+  if(message.method==='tools/call')return Promise.resolve().then(()=>invoke(message.params?.name,message.params?.arguments||{})).then(result=>reply(devToolResult(result)),error=>reply({content:[{type:'text',text:String(error.message).slice(0,2000)}],isError:true}));
+  return {jsonrpc:'2.0',id:message.id,error:{code:-32601,message:'Method not found'}};
+}
+/** MCP stdio is newline-delimited JSON. Stdout contains protocol messages only. */
+export async function runDevMcp(directory,{input=process.stdin,output=process.stdout,invoke,assistant=createDevAssistantLease(directory)}={}){
+  const pending=new Set(),decoder=new StringDecoder('utf8');let buffer='',discard=false,initializeSeen=false,initialized=false,clientInfo,initializing,stopping=false;
+  const write=value=>{if(value)output.write(JSON.stringify(value)+'\n');};
+  async function dispatch(message){
+    if(message?.method==='initialize'){
+      const result=devMcpReply(message,invoke);if(result?.result){initializeSeen=true;clientInfo=message.params?.clientInfo;}return result;
+    }
+    if(message?.jsonrpc==='2.0'&&message.method==='notifications/initialized'&&!Object.hasOwn(message,'id')){
+      if(initializeSeen&&!initialized){initialized=true;initializing=Promise.resolve(assistant.start(clientInfo));await initializing;}return;
+    }
+    if(message?.method==='tools/list'||message?.method==='tools/call'){
+      if(!initialized)return {jsonrpc:'2.0',id:message.id??null,error:{code:-32002,message:'Initialize the MCP session first.'}};
+      await initializing;
+    }
+    return devMcpReply(message,invoke||((name,args)=>assistant.call(name,args)));
+  }
+  function line(value){
+    if(!value.trim())return;
+    let message;try{message=JSON.parse(value);}catch{write({jsonrpc:'2.0',id:null,error:{code:-32700,message:'Parse error'}});return;}
+    if(pending.size>=16){write({jsonrpc:'2.0',id:message.id??null,error:{code:-32000,message:'Too many pending local tools'}});return;}
+    // Enter initialization synchronously before accepting the next line or EOF.
+    // The actual tools remain concurrent, with the initialization promise as a barrier.
+    const task=dispatch(message).then(write,error=>write({jsonrpc:'2.0',id:message?.id??null,error:{code:-32600,message:String(error.message).slice(0,1000)}})).finally(()=>pending.delete(task));pending.add(task);
+  }
+  const shutdown=()=>{stopping=true;void assistant.close();input.destroy();};
+  if(input===process.stdin){process.once('SIGINT',shutdown);process.once('SIGTERM',shutdown);}
+  try{
+  for await(const chunk of input){
+    const next=typeof chunk==='string'?chunk:decoder.write(chunk);
+    for(const part of next.split(/(?<=\n)/)){
+      const ends=part.endsWith('\n');
+      if(!discard){buffer+=part;if(Buffer.byteLength(buffer)>256*1024){write({jsonrpc:'2.0',id:null,error:{code:-32600,message:'Request too large'}});discard=true;buffer='';}}
+      if(ends){if(!discard)line(buffer);buffer='';discard=false;}
+    }
+  }
+  if(buffer&&!discard)line(buffer+decoder.end());
+  }catch(error){if(!stopping)throw error;}
+  finally{await assistant.close();await Promise.allSettled(pending);if(input===process.stdin){process.off('SIGINT',shutdown);process.off('SIGTERM',shutdown);}}
+}

package/runtime/dev-tools-metrics.mjs

@@ -0,0 +1,31 @@
+import {readdir,lstat,open} from 'node:fs/promises';
+import {constants} from 'node:fs';
+import path from 'node:path';
+
+// Lazy tails of the existing bounded inspector format. The directory is created
+// inside this development session, never accepted from an HTTP/tool argument.
+export function createDevMetricsCollector(directory,{since=Date.now()}={}){
+  const seen=new Set();let running,last=0;
+  return async function collect(record){
+    if(running)return running;if(Date.now()-last<700)return;
+    running=(async()=>{
+      const container=await lstat(directory).catch(()=>null);if(!container?.isDirectory()||container.isSymbolicLink())return;
+      const names=(await readdir(directory)).filter(name=>/^(?:worker-\d+-\d+|native-\d+)\.jsonl(?:\.1)?$/.test(name));
+      const files=(await Promise.all(names.slice(-64).map(async name=>({name,info:await lstat(path.join(directory,name)).catch(()=>null)})))).filter(file=>file.info?.isFile()&&!file.info.isSymbolicLink()).sort((a,b)=>b.info.mtimeMs-a.info.mtimeMs).slice(0,4);
+      for(const file of files){
+        let handle;try{
+          handle=await open(path.join(directory,file.name),constants.O_RDONLY|(constants.O_NOFOLLOW||0));const stat=await handle.stat();if(!stat.isFile()||stat.ino!==file.info.ino)continue;
+          const bytes=Buffer.alloc(Math.min(stat.size,65536)),start=Math.max(0,stat.size-bytes.length);await handle.read(bytes,0,bytes.length,start);
+          const lines=bytes.toString('utf8').split('\n');if(start)lines.shift();
+          for(const line of lines){if(line.length>4096||!line)continue;
+            let event;try{event=JSON.parse(line);}catch{continue;}
+            if(!Number.isFinite(event.time)||event.time<since||!['http','fetch'].includes(event.type))continue;
+            const id=file.name+':'+line;if(seen.has(id))continue;seen.add(id);
+            record({time:event.time,path:event.type==='fetch'?event.destination:event.route,route:event.route,method:event.method||'GET',status:event.status,duration:event.durationMs,kind:event.type,source:'server',failed:!!event.error||event.status>=400});
+          }
+        }catch{/* Inspection must not break development. */}finally{await handle?.close().catch(()=>{});}
+      }
+      if(seen.size>2000){const keep=[...seen].slice(-1000);seen.clear();for(const id of keep)seen.add(id);}
+    })().catch(()=>{}).finally(()=>{last=Date.now();running=undefined;});return running;
+  };
+}

package/runtime/dev-tools-model.mjs

@@ -0,0 +1,42 @@
+// Small pure helpers shared by the development panels and the local bridge.
+export function safeRequestPath(raw, base = 'http://localhost') {
+  try { const url = new URL(raw, base); return url.origin === new URL(base).origin ? url.pathname : url.origin + url.pathname; }
+  catch { return '[Unavailable URL]'; }
+}
+
+export function routeParameters(pattern) {
+  return [...String(pattern).matchAll(/\[\[\.\.\.([^\]]+)\]\]|\[\.\.\.([^\]]+)\]|\[([^\]]+)\]/g)]
+    .map(match => ({ name: match[1] || match[2] || match[3], optional: Boolean(match[1]), catchAll: Boolean(match[1] || match[2]) }));
+}
+
+export function materializeRoute(pattern, values = {}) {
+  let missing;
+  const path = String(pattern).replace(/\[\[\.\.\.([^\]]+)\]\]|\[\.\.\.([^\]]+)\]|\[([^\]]+)\]/g, (_match, optional, all, one) => {
+    const name = optional || all || one, value = String(values[name] ?? '').trim();
+    if (!value) { if (!optional) missing ||= name; return ''; }
+    return optional || all ? value.split('/').filter(Boolean).map(encodeURIComponent).join('/') : encodeURIComponent(value);
+  }).replace(/\/{2,}/g, '/');
+  if (missing) throw Error('Enter ' + missing + '.');
+  return path || '/';
+}
+
+export function durationLabel(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? (value < 1000 ? Math.round(value) + ' ms' : (value / 1000).toFixed(2) + ' s') : 'Not measured';
+}
+
+export function normalizeEntries(data = {}, browser = []) {
+  const server = Array.isArray(data.serverLogs) ? data.serverLogs : [];
+  return [...browser.map(entry => ({ ...entry, id: 'browser:' + entry.id, source: 'browser' })),
+    ...server.map((entry, index) => ({ ...entry, id: 'server:' + (entry.id ?? index), time: entry.time || entry.timestamp || 0,
+      level: entry.level || 'log', text: String(entry.text ?? entry.message ?? ''), source: 'server' }))]
+    .sort((a, b) => a.time - b.time).slice(-750);
+}
+
+export function formatMcpConfig(server, client = 'codex') {
+  if (client !== 'codex') return JSON.stringify({ mcpServers: { 'prnext-dev': client==='cursor'?{type:'stdio',...server}:server } }, null, 2);
+  const lines = ['[mcp_servers.prnext-dev]', 'command = ' + JSON.stringify(server.command),
+    'args = [' + (server.args || []).map(argument => JSON.stringify(argument)).join(', ') + ']'];
+  if (server.env && Object.keys(server.env).length) lines.push('', '[mcp_servers.prnext-dev.env]',
+    ...Object.entries(server.env).map(([key, value]) => JSON.stringify(key) + ' = ' + JSON.stringify(String(value))));
+  return lines.join('\n');
+}