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

package/runtime/dev-notification.mjs

@@ -0,0 +1,81 @@
+// Leave space for the inherited control envelope below its 64 KiB limit.
+export const MAX_DEV_NOTIFICATION_BYTES=60*1024;
+const size=value=>Buffer.byteLength(JSON.stringify(value));
+
+// Measure the JSON representation too: control characters and lone surrogates
+// expand when escaped, independently of their UTF-8 source length.
+function boundedString(value,limit){
+  if(size(value)<=limit)return value;
+  const suffix='…';
+  const prefix=end=>{
+    if(end>0&&end<value.length&&/[\uD800-\uDBFF]/.test(value[end-1])&&/[\uDC00-\uDFFF]/.test(value[end]))end--;
+    return value.slice(0,end);
+  };
+  let low=0,high=value.length;
+  while(low<high){const middle=Math.ceil((low+high)/2);if(size(prefix(middle)+suffix)<=limit)low=middle;else high=middle-1;}
+  return prefix(low)+suffix;
+}
+function boundedList(value,{count,itemBytes,totalBytes}){
+  const result=[];let bytes=2;
+  for(const entry of value.slice(0,count)){
+    if(typeof entry!=='string')continue;
+    const comma=result.length?1:0,remaining=totalBytes-bytes-comma;
+    if(remaining<5)break;
+    const text=boundedString(entry,Math.min(itemBytes,remaining));
+    result.push(text);bytes+=size(text)+comma;
+  }
+  return result;
+}
+const serialized=value=>{try{return JSON.stringify(value);}catch{return undefined;}};
+
+/** Keep the wire event and state file identical, bounded, and conservative. */
+export function prepareDevNotification(value){
+  let notification={...value};const truncated=new Set();
+  for(const [key,limits]of Object.entries({changed:{count:32,itemBytes:512,totalBytes:16*1024},typeErrors:{count:32,itemBytes:4096,totalBytes:8*1024}})){
+    if(notification[key]===undefined)continue;
+    const original=notification[key],next=Array.isArray(original)?boundedList(original,limits):[];
+    if(serialized(original)!==JSON.stringify(next))truncated.add(key);
+    notification[key]=next;
+  }
+  if(notification.error!==undefined){
+    const next=typeof notification.error==='string'?boundedString(notification.error,8*1024):'Development compilation failed.';
+    if(next!==notification.error)truncated.add('error');notification.error=next;
+  }
+  if(truncated.has('changed')&&Object.hasOwn(notification,'affectedRoutes')){delete notification.affectedRoutes;truncated.add('affectedRoutes');}
+  const stamp=()=>{
+    if(truncated.size){notification.notificationTruncated=true;notification.truncatedFields=[...truncated];}
+  };
+  const trimSelection=()=>{
+    for(const key of ['routes','compiler','transforms','affectedRoutes'])if(Object.hasOwn(notification,key)){delete notification[key];truncated.add(key);}
+  };
+  const fits=text=>typeof text==='string'&&Buffer.byteLength(text)<=MAX_DEV_NOTIFICATION_BYTES;
+  stamp();let text=serialized(notification);
+  if(fits(text))return {notification,text};
+
+  // Removing affectedRoutes asks every active page to refresh. Never send a
+  // shortened selection, which could silently leave an affected page stale.
+  trimSelection();stamp();text=serialized(notification);
+  if(fits(text))return {notification,text};
+
+  // Unexpected metadata or large identities must not defeat the final bound.
+  // Preserve complete usable IDs/URLs; an omitted client manifest causes the
+  // browser's existing conservative reload path instead of fetching a bad URL.
+  const previous=notification;notification={};truncated.add('metadata');
+  for(const [key,limit]of Object.entries({state:128,buildId:512,session:512,clientManifest:8192,pagesManifest:8192})){
+    if(typeof previous[key]==='string'&&size(previous[key])<=limit)notification[key]=previous[key];
+    else if(previous[key]!==undefined)truncated.add(key);
+  }
+  for(const key of ['sequence','listenerPid'])if(Number.isSafeInteger(previous[key])&&previous[key]>=0)notification[key]=previous[key];
+  for(const key of ['safeMode','cssOnly'])if(typeof previous[key]==='boolean')notification[key]=previous[key];
+  for(const key of ['changed','typeErrors','error'])if(previous[key]!==undefined)notification[key]=previous[key];
+  if(previous.reason&&typeof previous.reason==='object'){
+    notification.reason={};
+    for(const [key,limit]of Object.entries({code:256,summary:2048}))if(typeof previous.reason[key]==='string')notification.reason[key]=boundedString(previous.reason[key],limit);
+    if(serialized(previous.reason)!==JSON.stringify(notification.reason))truncated.add('reason');
+  }
+  stamp();text=JSON.stringify(notification);
+  // The allowlisted fields have a combined byte budget below 60 KiB. Keep this
+  // assertion next to serialization so future additions cannot break the RPC.
+  if(!fits(text))throw Error('Development notification exceeds its byte budget');
+  return {notification,text};
+}

package/runtime/dev-popout.mjs

@@ -0,0 +1,34 @@
+// Created synchronously from a user click; never opens a background popup.
+export function createToolWindow({ owner, title, width, height, onClose, reservedWindow }) {
+  let popup=reservedWindow;
+  try { if(popup===undefined)popup = owner.open('about:blank', '_blank', `popup=yes,width=${width},height=${height},resizable=yes,scrollbars=yes`); }
+  catch { return null; }
+  if (!popup) return null;
+  let finished = false, timer;
+  function cleanup() {
+    if (finished) return;
+    finished = true; owner.clearInterval(timer);
+    owner.removeEventListener('pagehide', close);
+    onClose?.();
+  }
+  function close() { try { if (!popup.closed) popup.close(); } finally { cleanup(); } }
+  try {
+    // The UI uses the retained window reference; it needs no reverse opener.
+    popup.opener = null;
+    const document = popup.document;
+    document.title = title; document.documentElement.lang = 'en';
+    const viewport=document.createElement('meta');viewport.name='viewport';viewport.content='width=device-width, initial-scale=1';document.head.append(viewport);
+    document.body.style.cssText = 'margin:0;background:#080808;color-scheme:dark';
+    const host = document.createElement('prnext-dev-window'), shadow = host.attachShadow({mode:'open'});
+    const style = document.createElement('style');
+    style.textContent = `:host{display:block;color-scheme:dark}*,*::before,*::after{box-sizing:border-box}[hidden]{display:none!important}svg{width:16px;height:16px;flex:none}.sr-only{position:absolute;width:1px;height:1px;padding:0;overflow:hidden;clip-path:inset(50%);white-space:nowrap}`;
+    shadow.append(style); document.body.replaceChildren(host);
+    popup.addEventListener('pagehide', cleanup, {once:true});
+    owner.addEventListener('pagehide', close, {once:true});
+    timer = owner.setInterval(() => { if (popup.closed) cleanup(); }, 500);
+    return { window:popup, shadow, close, focus() { try { popup.focus(); } catch {} } };
+  } catch { close(); return null; }
+}
+
+export const popoutIcon = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 3h7v7m0-7L11 13"/><path d="M10 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-5"/></svg>';
+export const dockIcon = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M10 14H3V7m0 7L13 4"/><path d="M3 18v1a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2h-1"/></svg>';

package/runtime/dev-position.mjs

@@ -0,0 +1,107 @@
+// Pointer capture stays on the logo: dragging never installs page-wide styles.
+// A tab-local preference cannot override a newly configured default corner.
+const corners = ['top-left', 'top-right', 'bottom-left', 'bottom-right'];
+const preference = 'prnext:dev-corner:v1';
+
+export function createDevPosition({ host, trigger, position, onDrag, announce }) {
+  const view = host.ownerDocument.defaultView;
+  const controller = new AbortController(), events = { signal: controller.signal };
+  let current = corners.includes(position) ? position : 'bottom-left';
+  const configured = current;
+  try {
+    const saved = JSON.parse(view.sessionStorage.getItem(preference));
+    if (saved?.configured === configured && corners.includes(saved.corner)) current = saved.corner;
+  } catch { /* Storage can be disabled by the browser. */ }
+  host.dataset.position = current;
+  trigger.style.touchAction = 'none';
+  trigger.setAttribute('aria-description', 'Drag to a corner. Use Alt + arrow keys to move the logo.');
+  trigger.setAttribute('aria-keyshortcuts', 'Alt+ArrowUp Alt+ArrowDown Alt+ArrowLeft Alt+ArrowRight');
+  const hints = view.document.createElement('div'); hints.className = 'corner-hints'; hints.hidden = true; hints.setAttribute('aria-hidden', 'true');
+  for (const corner of corners) {
+    const node = view.document.createElement('span'); node.className = 'corner-hint'; node.dataset.corner = corner; hints.append(node);
+  }
+  host.shadowRoot.append(hints);
+  let drag, motion, suppressClick = false;
+  function viewport() {
+    const port = view.visualViewport;
+    return { x: port?.offsetLeft || 0, y: port?.offsetTop || 0, width: port?.width || view.innerWidth, height: port?.height || view.innerHeight };
+  }
+  function nearest(x, y) {
+    const port = viewport();
+    return `${y < port.y + port.height / 2 ? 'top' : 'bottom'}-${x < port.x + port.width / 2 ? 'left' : 'right'}`;
+  }
+  function highlight(corner) {
+    for (const node of hints.children) node.dataset.active = String(node.dataset.corner === corner);
+  }
+  function clearCoordinates() {
+    for (const name of ['top', 'right', 'bottom', 'left']) host.style.removeProperty(name);
+  }
+  function settle(corner, from, save = true) {
+    motion?.cancel(); motion = null;
+    current = corner; host.dataset.position = corner; clearCoordinates();
+    const target = host.getBoundingClientRect();
+    if (from && !view.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+      motion = host.animate([
+        { transform: `translate(${from.x - target.x}px,${from.y - target.y}px)` },
+        { transform: 'translate(0,0)' },
+      ], { duration: 420, easing: 'cubic-bezier(.16,1,.3,1)' });
+    }
+    if (save) {
+      try { view.sessionStorage.setItem(preference, JSON.stringify({ configured, corner })); } catch {}
+      announce(`Logo moved to ${corner.replace('-', ' ')}.`);
+    }
+  }
+  function finish(cancel = false) {
+    if (!drag) return;
+    const state = drag; drag = null;
+    if (state.moved) {
+      suppressClick = true;
+      const from = host.getBoundingClientRect();
+      hints.hidden = true; delete host.dataset.dragging;
+      settle(cancel ? state.corner : nearest(from.x + 22, from.y + 22), from, !cancel);
+    }
+    if (trigger.hasPointerCapture(state.pointer)) trigger.releasePointerCapture(state.pointer);
+  }
+  trigger.addEventListener('pointerdown', event => {
+    if (drag || event.button !== 0 || !event.isPrimary) return;
+    suppressClick = false;
+    const rect = host.getBoundingClientRect();
+    drag = { pointer: event.pointerId, x: event.clientX, y: event.clientY, rect, corner: current, moved: false };
+    trigger.setPointerCapture(event.pointerId);
+  }, events);
+  trigger.addEventListener('pointermove', event => {
+    if (!drag || event.pointerId !== drag.pointer) return;
+    const dx = event.clientX - drag.x, dy = event.clientY - drag.y;
+    if (!drag.moved && Math.hypot(dx, dy) < 6) return;
+    if (!drag.moved) {
+      drag.moved = true; motion?.cancel(); motion = null; onDrag();
+      host.dataset.dragging = 'true'; hints.hidden = false;
+    }
+    event.preventDefault();
+    const port = viewport();
+    const x = Math.max(port.x + 4, Math.min(port.x + port.width - 48, drag.rect.x + dx));
+    const y = Math.max(port.y + 4, Math.min(port.y + port.height - 48, drag.rect.y + dy));
+    host.style.left = x + 'px'; host.style.top = y + 'px'; host.style.right = 'auto'; host.style.bottom = 'auto';
+    highlight(nearest(x + 22, y + 22));
+  }, events);
+  trigger.addEventListener('pointerup', event => { if(event.pointerId === drag?.pointer) finish(); }, events);
+  trigger.addEventListener('pointercancel', event => { if(event.pointerId === drag?.pointer) finish(true); }, events);
+  trigger.addEventListener('lostpointercapture', event => { if(event.pointerId === drag?.pointer) finish(true); }, events);
+  trigger.addEventListener('dragstart', event => event.preventDefault(), events);
+  trigger.addEventListener('click', event => {
+    if (suppressClick && event.detail !== 0) { suppressClick = false; event.preventDefault(); event.stopImmediatePropagation(); }
+  }, { ...events, capture: true });
+  trigger.addEventListener('keydown', event => {
+    if (event.key === 'Escape' && drag?.moved) { event.preventDefault(); event.stopPropagation(); finish(true); }
+    if (!event.altKey || !['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'].includes(event.key)) return;
+    event.preventDefault(); event.stopPropagation();
+    const rect = host.getBoundingClientRect(); onDrag();
+    const [vertical, horizontal] = current.split('-');
+    settle(`${event.key === 'ArrowUp' ? 'top' : event.key === 'ArrowDown' ? 'bottom' : vertical}-${event.key === 'ArrowLeft' ? 'left' : event.key === 'ArrowRight' ? 'right' : horizontal}`, rect);
+  }, events);
+  function resize() { if (drag) finish(true); motion?.cancel(); motion = null; }
+  view.addEventListener('resize', resize, events);
+  view.addEventListener('blur', () => finish(true), events);
+  view.visualViewport?.addEventListener('resize', resize, events);
+  return { dispose() { controller.abort(); motion?.cancel(); hints.remove(); } };
+}

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 = []; },
+  };
+}