@runeditrun/rer 0.1.0 → 0.2.0

package/cli/hydration/probe.mjs

@@ -0,0 +1,164 @@
+// The in-page half of the hydration check. `probe` is serialized into an init
+// script, so it must stay self-contained (no imports, no closures over module
+// scope). It runs before the document parses, while the check holds every
+// application script in the network layer:
+//  - when parsing ends (readyState "interactive"), it surveys the page sections,
+//    makes the case's edit, snapshots every element in <body> and starts sampling;
+//  - it releases the held scripts (window.__rerRelease) once every one-shot
+//    animation has finished ("after") or at the midpoint of the edited section's
+//    intro window ("mid"), recording whether React had already hydrated;
+//  - every frame it samples one-shot animations, the opacity of animated elements
+//    and which page sections are present;
+//  - once React owns the page and the DOM and animations are quiet, it records
+//    which snapshot elements were replaced and sets settledAt.
+// Elements are matched across a rebuild by a structural key (tag:index path from
+// <body>) that ignores script, style, link, template and noscript elements and the
+// nodes the probe inserted.
+export function probe(config) {
+ const S = window.__rerProbe = { config, survey: null, edit: null, editBeforeHydration: null, sectionKeys: [], addressSections: [], addressLoose: false,
+  replaced: [], starts: {}, opacity: {}, missing: [], frames: 0, oneShot: [], releasedAt: null, releaseNote: null, fiberAtRelease: null, hydratedAt: null, settledAt: null, settled: null, rer: null, error: null };
+ const SECTION = new Set(['HEADER', 'NAV', 'SECTION', 'ARTICLE', 'ASIDE', 'FOOTER']), SKIP = new Set(['SCRIPT', 'STYLE', 'LINK', 'TEMPLATE', 'NOSCRIPT']);
+ const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+/, ADDRESS = '.__cf_email__,a[href*="/cdn-cgi/l/email-protection"]';
+ const inserted = new WeakSet(), tracked = new WeakMap(), watch = new Set();
+ const now = () => Math.round(performance.now() * 10) / 10;
+ const own = (el, prefix) => { for (const key of Object.keys(el)) if (key.startsWith(prefix)) return el[key]; return undefined; };
+ const fiber = el => own(el, '__reactFiber$') !== undefined;
+ const counted = el => !SKIP.has(el.tagName) && !inserted.has(el);
+ const kids = el => [...el.children].filter(counted);
+ const keyOf = el => {
+  const parts = [];
+  for (let e = el; e !== document.body; e = e.parentElement) { if (!e || !e.parentElement || !counted(e)) return null; parts.unshift(e.tagName.toLowerCase() + ':' + kids(e.parentElement).indexOf(e)); }
+  return parts.join('>');
+ };
+ const resolveKey = key => {
+  let el = document.body;
+  for (const part of key.split('>')) { const at = part.lastIndexOf(':'); el = kids(el)[+part.slice(at + 1)]; if (!el || el.tagName.toLowerCase() !== part.slice(0, at)) return null; }
+  return el;
+ };
+ const walk = (el, key, out) => { let i = 0; for (const child of el.children) { if (!counted(child)) continue; const k = (key ? key + '>' : '') + child.tagName.toLowerCase() + ':' + i++; out.push([child, k]); walk(child, k, out); } return out; };
+ const outermost = () => { const out = []; const visit = el => { for (const child of el.children) { if (!counted(child)) continue; if (SECTION.has(child.tagName)) out.push(child); else visit(child); } }; visit(document.body); return out; };
+ const label = el => el.tagName.toLowerCase() + (el.id ? '#' + el.id : el.classList.length ? '.' + el.classList[0] : '') + (el.getAttribute('aria-label') ? `[aria-label="${el.getAttribute('aria-label')}"]` : '');
+ const texts = root => {
+  const out = [], walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  for (let n = walker.nextNode(); n; n = walker.nextNode()) { const p = n.parentElement; if (p && !p.closest('script,style,template,noscript,textarea,svg') && n.nodeValue.trim()) out.push(n); }
+  return out;
+ };
+ // A text node with sibling nodes is a separate text fiber: splitting it always mismatches.
+ const mixed = n => n.nodeValue.trim().length >= 4 && n.parentNode.childNodes.length >= 2;
+ const lone = n => n.nodeValue.trim().length >= 2 && n.parentNode.childNodes.length === 1;
+ const split = n => { const rest = n.splitText(Math.max(1, Math.floor(n.nodeValue.length / 2))), span = document.createElement('span'); inserted.add(span); span.textContent = rest.nodeValue; rest.replaceWith(span); };
+ const anyFiber = () => fiber(document.body) || [...document.body.querySelectorAll('*')].some(fiber);
+ // An element React has not hydrated yet: no fiber, under a parent React owns that does not set its HTML.
+ const pending = () => [...document.body.querySelectorAll('*')].filter(el => counted(el) && !el.closest('svg') && !fiber(el) && el.parentElement && fiber(el.parentElement) && !own(el.parentElement, '__reactProps$')?.dangerouslySetInnerHTML).length;
+ const oneShot = () => document.getAnimations().filter(a => {
+  if (typeof CSSTransition !== 'undefined' && a instanceof CSSTransition) return false;
+  const timing = a.effect && a.effect.getComputedTiming();
+  return timing && Number.isFinite(timing.endTime) && timing.activeDuration >= 50;
+ });
+ const outside = n => !outermost().some(section => section.contains(n));
+ let snapshot = [], scope = null, editAt = null, lastMutation = 0;
+
+ function begin() {
+  const sections = outermost();
+  S.sectionKeys = sections.map(keyOf);
+  S.survey = {
+   sections: sections.map(section => { const all = texts(section); return { key: keyOf(section), label: label(section), split: all.some(mixed), lone: all.some(lone) }; }),
+   loose: texts(document.body).some(n => outside(n) && mixed(n)),
+   advisories: texts(document.body).filter(n => mixed(n) && EMAIL.test(n.nodeValue)).map(n => { const section = sections.find(s => s.contains(n)); return { section: section ? label(section) : 'outside every section', text: n.nodeValue.trim().slice(0, 80) }; }),
+  };
+  S.addressSections = sections.filter(s => s.querySelector(ADDRESS) || EMAIL.test(s.textContent)).map(keyOf);
+  S.addressLoose = texts(document.body).some(n => outside(n) && EMAIL.test(n.nodeValue)) || [...document.querySelectorAll(ADDRESS)].some(outside);
+  S.editBeforeHydration = !anyFiber();
+  if (config.kind === 'section' || config.kind === 'loose') {
+   const root = config.kind === 'section' ? sections[config.section] : document.body;
+   if (config.kind === 'section') scope = root;
+   const candidates = root ? texts(root).filter(n => config.kind === 'section' || outside(n)) : [];
+   const target = candidates.find(mixed) ?? (config.kind === 'section' ? candidates.find(lone) : undefined);
+   if (target) {
+    const mode = mixed(target) ? 'split' : 'text';
+    S.edit = { mode, parent: keyOf(target.parentElement), text: target.nodeValue.trim().slice(0, 60) };
+    if (mode === 'split') split(target); else target.nodeValue = 'Übersetzt: ' + target.nodeValue;
+   }
+  }
+  snapshot = walk(document.body, '', []);
+  editAt = now();
+  new MutationObserver(() => { lastMutation = now(); }).observe(document.body, { childList: true, subtree: true, characterData: true });
+  requestAnimationFrame(frame);
+ }
+
+ function release(note) {
+  // React owning any element already means a script the check could not hold (an
+  // inline module script) hydrated the page, so the release timing was not exercised.
+  S.releasedAt = now(); S.releaseNote = note ?? null; S.fiberAtRelease = anyFiber();
+  window.__rerRelease();
+ }
+
+ function tryRelease() {
+  if (S.releasedAt !== null || S.frames < 3) return;
+  const animations = oneShot();
+  if (config.release === 'mid') {
+   const mine = animations.filter(a => (scope ?? document.body).contains(a.effect.target));
+   if (!mine.length) return release('no intro to release into');
+   if (mine.some(a => a.startTime === null)) return;
+   const start = Math.min(...mine.map(a => a.startTime + a.effect.getTiming().delay)), end = Math.max(...mine.map(a => a.startTime + a.effect.getComputedTiming().endTime));
+   const at = document.timeline.currentTime;
+   if (at >= (start + end) / 2) release(`${Math.round(100 * (at - start) / (end - start))}% through the intro window (${Math.round(start)}-${Math.round(end)} ms)`);
+   return;
+  }
+  if (animations.some(a => a.playState !== 'finished') && now() - editAt < 15000) return;
+  release();
+ }
+
+ function sample() {
+  S.frames++;
+  for (const a of oneShot()) {
+   const el = a.effect.target;
+   if (!el || !el.isConnected) continue;
+   let record = tracked.get(el);
+   // A new element object at a key gets a new id, so a rebuilt element is a second entry.
+   if (!record) { const key = keyOf(el); if (key === null) continue; record = { key, id: S.oneShot.length + 1 }; tracked.set(el, record); watch.add(key); }
+   const name = a.animationName || a.id || 'animation', list = (S.starts[record.key + ' ' + name] ??= []);
+   if (!S.oneShot.includes(record.key + ' ' + name)) S.oneShot.push(record.key + ' ' + name);
+   if (a.startTime !== null && !list.some(item => item.id === record.id)) list.push({ id: record.id, start: Math.round((a.startTime + a.effect.getTiming().delay) * 10) / 10, seen: now() });
+  }
+  for (const key of watch) {
+   const el = resolveKey(key);
+   if (!el) continue;
+   const opacity = +getComputedStyle(el).opacity, record = (S.opacity[key] ??= { first: opacity, max: opacity, dip: null });
+   if (opacity > record.max) record.max = opacity;
+   else if (record.max > record.first && record.max - opacity > 0.15 && (!record.dip || record.max - opacity > record.dip.from - record.dip.to)) record.dip = { from: record.max, to: opacity, at: now() };
+  }
+  const present = new Set(outermost().map(keyOf)), lost = S.sectionKeys.filter(key => !present.has(key));
+  if (lost.length) S.missing.push({ at: now(), lost });
+ }
+
+ function frame() {
+  if (S.settledAt !== null) return;
+  try {
+   sample();
+   tryRelease();
+   const t = now();
+   if (S.releasedAt !== null) {
+    if (S.hydratedAt === null && fiber(document.body) && pending() === 0) S.hydratedAt = t;
+    const quiet = t - lastMutation > 300 && !oneShot().some(a => a.playState === 'running');
+    if (S.hydratedAt !== null && t - S.hydratedAt > 300 && quiet) return settle('hydrated');
+    if (S.hydratedAt === null && t - S.releasedAt > 8000 && !anyFiber()) return settle('not hydrated');
+    if (t - S.releasedAt > 20000) return settle('timeout');
+   }
+  } catch (error) { S.error = String(error && error.stack || error); return settle('error'); }
+  requestAnimationFrame(frame);
+ }
+
+ function settle(state) {
+  S.settled = state; S.settledAt = now();
+  S.replaced = snapshot.filter(([el]) => !el.isConnected).map(([, key]) => key);
+  S.rer = window.__rerHydration ? JSON.parse(JSON.stringify(window.__rerHydration)) : null;
+ }
+
+ let begun = false;
+ document.addEventListener('readystatechange', () => {
+  if (begun || document.readyState === 'loading') return;
+  begun = true;
+  try { begin(); } catch (error) { S.error = String(error && error.stack || error); settle('error'); }
+ });
+}

package/cli/hydration/scripts.mjs

@@ -0,0 +1,39 @@
+// Which scripts a page loads count as the application's, so a page that loads them
+// and never hydrates fails rather than being skipped as plain HTML. They are:
+// script requests to the page's own origin; module scripts and modulepreload links
+// in the served document, from any origin (a Vite base on a CDN host); and
+// cross-origin script requests sent in CORS mode, as every module fetch is, that
+// the document does not name as a classic <script src>. A third-party classic
+// script on a plain-HTML page is none of these.
+
+const attribute = (attrs, name) => { const match = new RegExp(`(?:^|\\s)${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'=<>\`]+))`, 'i').exec(attrs); return match ? (match[1] ?? match[2] ?? match[3]) : null; };
+const resolveUrl = (href, base) => { try { return new URL(href, base).href; } catch { return null; } };
+
+/** The module scripts (inline ones as "inline module script"), modulepreload links
+ * and classic script sources of a served document, as absolute URLs. */
+export function documentScripts(html, pageUrl) {
+ const tag = /<!--[\s\S]*?-->|<(script|link)\b([^>]*)>/gi, modules = [], classic = [];
+ for (let match; (match = tag.exec(html));) {
+  const name = match[1]?.toLowerCase(), attrs = match[2] ?? '';
+  if (name === 'link') {
+   const href = attribute(attrs, 'href');
+   if (href && (attribute(attrs, 'rel') ?? '').toLowerCase().split(/\s+/).includes('modulepreload')) modules.push(resolveUrl(href, pageUrl));
+  } else if (name === 'script') {
+   const src = attribute(attrs, 'src'), module = (attribute(attrs, 'type') ?? '').trim().toLowerCase() === 'module';
+   if (module) modules.push(src ? resolveUrl(src, pageUrl) : 'inline module script');
+   else if (src) classic.push(resolveUrl(src, pageUrl));
+   const close = html.toLowerCase().indexOf('</script', tag.lastIndex);
+   tag.lastIndex = close < 0 ? html.length : close;
+  }
+ }
+ return { modules: modules.filter(Boolean), classic: classic.filter(Boolean) };
+}
+
+/** The application scripts of one load of `path`, given the document it was served:
+ * same-origin paths as paths, other origins as full URLs. */
+export function applicationScripts(load, html, origin, path) {
+ const page = new URL(path, origin), show = url => { const parsed = new URL(url, page); return parsed.origin === page.origin ? parsed.pathname + parsed.search : parsed.href; };
+ const { modules, classic } = documentScripts(html ?? '', page.href), named = new Set(classic);
+ const found = [...load.scripts, ...modules.map(url => url === 'inline module script' ? url : show(url)), ...load.crossScripts.filter(url => !named.has(url)).map(show)];
+ return [...new Set(found)];
+}

package/cli/hydration/verdict.mjs

@@ -0,0 +1,85 @@
+// Turns probe records into failures. Every failure names the page, the case, the
+// section and its evidence.
+import { describeCase } from './cases.mjs';
+
+const LATE_MS = 34; // two frames
+const within = (key, scope) => key === scope || key.startsWith(scope + '>');
+const list = (keys, limit = 6) => keys.slice(0, limit).join(', ') + (keys.length > limit ? ` and ${keys.length - limit} more` : '');
+
+/** Replays in one load: a one-shot animation on a rebuilt element starting more
+ * than two frames after the original did, or an animated element whose opacity
+ * dropped by more than 0.15 after rising (unless it did so on the plain load). */
+export function replays(record, baseline) {
+ const found = [];
+ for (const [id, entries] of Object.entries(record.starts ?? {})) {
+  const [key, name] = id.split(' ');
+  for (const entry of entries.slice(1)) { const late = entry.start - entries[0].start; if (late > LATE_MS) { found.push(`${key} restarted its ${name} animation ${Math.round(late)} ms late`); break; } }
+ }
+ for (const [key, opacity] of Object.entries(record.opacity ?? {})) {
+  if (opacity.dip && !baseline?.opacity?.[key]?.dip) found.push(`${key} opacity fell from ${opacity.dip.from.toFixed(2)} to ${opacity.dip.to.toFixed(2)}`);
+ }
+ return found;
+}
+
+/** What one edit load did: replaced elements (less those the plain load replaces),
+ * those outside the region the case may rebuild, replays, and frames that lacked
+ * a page section present at the edit. */
+export function measure(item, record, { survey, baseline }) {
+ const base = baseline.record ?? {}, excluded = new Set(base.replaced ?? []);
+ const replaced = (record.replaced ?? []).filter(key => !excluded.has(key));
+ let allowed = () => true;
+ if (item.kind === 'section') { const scope = survey.sections[item.section].key; allowed = key => within(key, scope); }
+ else if (item.kind === 'loose') allowed = key => !survey.sections.some(section => within(key, section.key));
+ else if (item.kind === 'cloudflare') allowed = key => (record.addressSections ?? []).some(scope => within(key, scope)) || (record.addressLoose && !survey.sections.some(section => within(key, section.key)));
+ return { replaced, outside: replaced.filter(key => !allowed(key)), replays: replays(record, base), missing: record.missing ?? [] };
+}
+
+/** A page the check may skip: React never hydrated it, it loads no application
+ * script (scripts.mjs) and its plain load raised no page or console error. A page
+ * whose scripts load but never hydrate (a broken client entry, or client scripts
+ * on another origin that the check aborts) is a failure, not a skip. */
+export const plainHtml = (load, scripts) => load.record?.settled === 'not hydrated' && !scripts.length && !load.errors.length;
+
+/** The failure for a page whose plain load never hydrated and is not plain HTML. */
+export function judgeUnhydrated({ path, scripts, baseline: { record, errors } }) {
+ const state = record?.settled ?? 'no probe record';
+ const why = state === 'not hydrated' ? `React never hydrated the page${scripts.length ? ` although it loads application scripts (${list(scripts, 3)})` : ''}` : `the page did not settle (${state}${record?.error ? ': ' + record.error : ''})`;
+ return `${path} plain load: ${why}${errors.length ? `; ${list([...new Set(errors)], 3)}` : ''}`;
+}
+
+/** Failures for one page: its plain load, its case loads and its canaries. */
+export function judgePage(page) {
+ const failures = [], { path, baseline, loads, survey } = page, base = baseline.record;
+ const fail = (what, evidence) => failures.push(`${path} ${what}: ${evidence}`);
+ const noisy = (what, load) => { if (load.errors.length) fail(what, `recovery was not quiet (${list([...new Set(load.errors)], 3)})`); };
+ const unheld = (what, load) => { if (load.unheld?.length) fail(what, `not exercised: the check's script hold let ${list(load.unheld, 3)} reach the page before the probe released the scripts`); return load.unheld?.length > 0; };
+ unheld('plain load', baseline);
+ noisy('plain load', baseline);
+ if (base.rer?.count) fail('plain load', `window.__rerHydration.count is ${base.rer.count} with no edit (${list(base.rer.stacks ?? [], 2)})`);
+ let exercised = false;
+ for (const { item, load } of loads) {
+  const what = describeCase(item, survey), record = load.record;
+  if (!record || record.settled !== 'hydrated') { fail(what, record?.settled === 'error' ? `the probe failed: ${record.error}` : `the page did not settle after hydration within the time limit (${record?.settled ?? 'no record'})`); continue; }
+  if (unheld(what, load)) continue;
+  noisy(what, load);
+  if (item.kind === 'plain') {
+   if (item.reduced && record.oneShot.length) fail(what, `one-shot animations ran: ${list(record.oneShot)}`);
+   if (record.rer?.count) fail(what, `window.__rerHydration.count is ${record.rer.count} with no edit`);
+   continue;
+  }
+  if (!record.editBeforeHydration) { fail(what, 'not exercised: the edit landed after React had started hydrating'); continue; }
+  if (record.fiberAtRelease !== false) { fail(what, 'not exercised: React hydrated before the probe released the scripts (a script the check cannot hold, such as the client bundle inlined in an inline module script, hydrated the page)'); continue; }
+  if (item.kind !== 'cloudflare' && !record.edit) { fail(what, 'not exercised: the probe found no text to edit'); continue; }
+  const { replaced, outside, replays: replayed, missing } = measure(item, record, page);
+  if (outside.length) fail(what, `React replaced ${outside.length} element(s) outside ${item.kind === 'section' ? 'the edited section' : item.kind === 'loose' ? 'the loose content (a page section was rebuilt)' : 'the sections holding addresses'}: ${list(outside)}`);
+  if (replaced.length) {
+   if (item.kind !== 'cloudflare') exercised = true;
+   if (!(record.rer?.count >= 1)) fail(what, `React rebuilt ${replaced.length} element(s) but window.__rerHydration.count is ${record.rer?.count ?? 'absent'}; the client entry must pass onRecoverableError: createRecoverableErrorHandler()`);
+  }
+  for (const replay of replayed) fail(what, `an intro replayed: ${replay}`);
+  if (missing.length) fail(what, `${missing.length} frame(s) lacked a page section present at the edit (${list([...new Set(missing.flatMap(frame => frame.lost))])})`);
+ }
+ if (survey.sections.length && loads.some(({ item }) => item.kind === 'section' || item.kind === 'loose') && !exercised) fail('all edits', 'not exercised: no edit before hydration made React rebuild anything, so the check proved nothing on this page');
+ if (survey.sections.length && !loads.some(({ item }) => item.kind === 'section')) fail('all edits', 'not exercised: no page section has text to edit');
+ return failures;
+}

package/cli/inspect.mjs

@@ -1,19 +1,23 @@
 import { dependencyDoctor } from './dependency-doctor.mjs';
 import { inventory } from './export.mjs';
-import { readFile } from 'node:fs/promises';
+import { lstat, readFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
-import { resolve } from 'node:path';
+import { delimiter, dirname, resolve } from 'node:path';
 import { aliases, pins, requiredHooks, serverDefaults, verbs, releaseFlags } from './contract.mjs';
 import { runningVersion } from './version.mjs';
 import { contained, readPackage } from './project.mjs';
 import { shared } from './shared.mjs';
-import { missing } from './errors.mjs';
+import { missing, RerError } from './errors.mjs';
 import { projectNodePin } from './node-runtime-discovery.mjs';
 import { localSettingKeys, requiredLocalSettings } from './settings.mjs';
 import { localAiDiagnostics } from './ai-local.mjs';
 import { authCopyClauses } from './auth-copy.mjs';
 import { cacheWarnings } from './cache-doctor.mjs';
 import { deployedMain } from './deploy-config.mjs';
+import { commandArgv, commandLine, declaredPackage, exactVersion, lockedPackage, packageName, vendoredPaths } from './package-mode.mjs';
+import { vendoredCalls } from './package-calls.mjs';
+import { doorProtocol } from './door.mjs';
+import { savedOrigin } from './door-mode.mjs';
 
 // cliVersion: the rer version of the code answering (absent for a vendored copy
 // too old to record one). defaults: what a server start applies when the person
@@ -28,8 +32,10 @@ export async function describe(project) {
  const capabilities = project.adapter?.verbs ?? {};
  return { contractVersion: 1, ...versioned, profile: 'first-party', defaults, pins: { node: pkg.engines?.node, pnpm: pkg.packageManager?.replace(/^pnpm@/, '') },
   verbs: Object.fromEntries(Object.entries(capabilities).map(([verb, capability]) => [verb, { flags: (verbs[verb]?.flags ?? releaseFlags).filter(flag => capability.flags?.includes(flag)), effects: verbs[verb]?.effects ?? 'Existing Base release producer.' }])),
-  aliases: Object.fromEntries(Object.entries(aliases).filter(([alias, verb]) => pkg.scripts?.[alias] === `node scripts/rer.mjs${verb ? ' ' + verb : ''}`)),
-  local: { state: project.adapter?.state, settings: project.adapter?.settings ?? [], installerState: '.seed/installer', outbox: '/__dev/outbox', ...await localState(project), ...(project.adapter?.devIdentity ? { devIdentity: true, devKey: '.rer/local/dev-key.env' } : {}) },
+  aliases: Object.fromEntries(Object.entries(aliases).filter(([alias, verb]) => pkg.scripts?.[alias] === commandLine(verb, declaredPackage(pkg) !== undefined))),
+  local: { state: project.adapter?.state, settings: project.adapter?.settings ?? [], installerState: '.seed/installer', outbox: '/__dev/outbox', ...await localState(project), origin: await savedOrigin(project), ...(project.adapter?.devIdentity ? { devIdentity: true, devKey: '.rer/local/dev-key.env' } : {}) },
+  // This pin serves a checkout through the machine's front door (rer door).
+  door: { protocol: doorProtocol },
  };
 }
 
@@ -57,6 +63,9 @@ export async function check(project, explicitProfile) {
  for (const loop of project.descriptor.loops ?? []) add('SC-10.loop.' + loop.id, !loop.required || loop.enabled, `Enable the required ${loop.id} loop or correct its declaration.`);
  if (project.profile === 'first-party' || explicitProfile === 'first-party') {
   const adapter = project.adapter, pkg = await readPackage(project.root), marker = project.descriptor.seedContract;
+  // Package mode (an @runeditrun/rer pin) and vendored mode differ only in
+  // where rer comes from: the command targets and the source clauses below.
+  const packaged = declaredPackage(pkg) !== undefined;
   add('SC-09.profile', marker?.version === 1 && marker?.profile === 'first-party', 'Restore OPERATIONS v2 seedContract version 1, profile first-party and the adapter pointer.');
   add('SC-01.adapter', adapter?.version === 1, 'Export commandAdapter version 1 from scripts/installer/local.mjs.');
   for (const hook of requiredHooks) add('SC-01.hook.' + hook, adapter?.[hook] ?? adapter?.hooks?.[hook], `Missing ${hook} hook/inventory; adopt the shared command adapter with a real ${hook} target.`);
@@ -64,14 +73,18 @@ export async function check(project, explicitProfile) {
    const declaration = project.descriptor.commands[verb];
    add('SC-01.verb.' + verb, declaration && adapter?.verbs?.[verb], `Missing ${verb}; declare it in OPERATIONS and expose its shared implementation.`);
    for (const flag of definition.flags) add('SC-01.flag.' + verb + '.' + flag.slice(2), adapter?.verbs?.[verb]?.flags?.includes(flag), `Missing ${verb} ${flag}; restore the shared implementation supporting this flag.`);
-   add('SC-02.target.' + verb, declaration?.argv?.join('\0') === ['node', 'scripts/rer.mjs', verb].join('\0'), `Declare ${verb} argv as node scripts/rer.mjs ${verb}.`);
+   const argv = commandArgv(verb, packaged);
+   add('SC-02.target.' + verb, declaration?.argv?.join('\0') === argv.join('\0'), `Declare ${verb} argv as ${argv.join(' ')}.`);
   }
-  for (const [alias, verb] of Object.entries(aliases)) add('SC-02.alias.' + alias, pkg.scripts?.[alias] === `node scripts/rer.mjs${verb ? ' ' + verb : ''}`, `Set package script ${alias} to node scripts/rer.mjs${verb ? ' ' + verb : ''}.`);
+  for (const [alias, verb] of Object.entries(aliases)) add('SC-02.alias.' + alias, pkg.scripts?.[alias] === commandLine(verb, packaged), `Set package script ${alias} to ${commandLine(verb, packaged)}.`);
   add('SC-02.install-lifecycle', !pkg.scripts?.install, 'Remove the install lifecycle alias; use deps or frozen pnpm install.');
   let nodeFile; try { nodeFile = (await readFile(resolve(project.root, '.node-version'), 'utf8')).trim(); } catch {}
   add('SC-02.node-file', nodeFile === pins.node, `Set .node-version to ${pins.node}.`);
   add('SC-02.node-engine', pkg.engines?.node === pins.node, `Pin package.json engines.node to ${pins.node}.`);
   add('SC-02.pnpm', pkg.packageManager === `pnpm@${pins.pnpm}`, `Pin packageManager to pnpm@${pins.pnpm}.`);
+  if (packaged) for (const [id, ok, message] of await packageClauses(project.root, pkg)) add(id, ok, message);
+  // Vendored mode: the copy and its recorded inventory.
+  else {
   for (const path of ['scripts/rer.mjs', 'scripts/base-cli/inventory.json', 'scripts/base-onboarding/adapter.mjs']) {
    let exists = false; try { await contained(project.root, path); exists = true; } catch {}
    add('SC-01.portable.' + path, exists, `Restore portable source ${path} through the documented export tool.`);
@@ -94,6 +107,7 @@ export async function check(project, explicitProfile) {
     add('SC-01.inventory.' + path, exact, `Restore stale or missing portable CLI source ${path} with the source export tool.`);
    }
   } catch { add('SC-01.inventory', false, 'Restore the deterministic portable CLI source inventory.'); }
+  }
   add('SC-08.portability', typeof adapter?.portability?.export === 'function' && typeof adapter?.portability?.import === 'function', 'Adopt the reviewed mainline complete local portability API; archive support remains unavailable until then.');
   if (adapter?.devIdentity) for (const [id, ok, message] of await devIdentityClauses(project.root, adapter)) add(id, ok, message);
   for (const [id, ok, message] of await authCopyClauses(project.root)) add(id, ok, message);
@@ -102,12 +116,40 @@ export async function check(project, explicitProfile) {
  return { clauses, ok: clauses.every(clause => clause.ok) };
 }
 
+// Package mode: the exact pin, its lockfile entry, no vendored copy and no
+// command still calling one.
+async function packageClauses(root, pkg) {
+ const declared = declaredPackage(pkg), locked = await lockedPackage(root), clauses = [];
+ clauses.push(['SC-13.package.pin', pkg.devDependencies?.[packageName] === declared && exactVersion.test(declared), `Pin ${packageName} in devDependencies to an exact version (for example "0.2.0"), not ${JSON.stringify(declared)} or a runtime dependency.`]);
+ clauses.push(['SC-13.package.lockfile', locked?.locked && locked.specifier === declared && locked.version === declared, `Run pnpm install so pnpm-lock.yaml locks ${packageName} ${declared}${locked?.version ? ` (it locks ${locked.version})` : ''}.`]);
+ for (const path of vendoredPaths) {
+  let present = true; try { await lstat(resolve(root, path)); } catch { present = false; }
+  clauses.push(['SC-13.package.vendored.' + path, !present, `Remove ${path}: a checkout that pins ${packageName} runs the package, not a vendored copy (node scripts/export-cli.mjs --to-package converts one).`]);
+ }
+ // Delivery operations, the scripts they run and CI workflows call the package too.
+ const calls = await vendoredCalls(root);
+ clauses.push(['SC-13.package.calls', !calls.length, `Run pnpm exec rer VERB instead of the removed vendored copy (pnpm install --frozen-lockfile first where nothing has installed yet) in ${calls.length} place${calls.length === 1 ? '' : 's'}:\n${calls.slice(0, 20).join('\n')}${calls.length > 20 ? `\n...and ${calls.length - 20} more` : ''}`]);
+ return clauses;
+}
+
+// Without the pinned pnpm on PATH, rer provides it for this command only
+// (cli/pnpm-runtime.mjs); it never changes global tools.
 export async function tools(root, store, signal) {
  const node = await projectNodePin(root);
  if (node && process.versions.node !== node) throw missing(`Node ${node} is required. Run it with rer, with automatic project runtime selection enabled.`);
- const version = await probePnpm(root, store, signal);
- if (version !== pins.pnpm) throw missing(`pnpm ${pins.pnpm} is required. Install/select the documented pin; rer never changes global tools.`);
+ const found = await probePnpm(root, store, signal).catch(error => { if (signal?.aborted) throw error; return null; });
+ if (found === pins.pnpm) return;
+ const { cachedPnpm, downloadPnpm } = await import('./pnpm-runtime.mjs');
+ let directory = await cachedPnpm(pins.pnpm);
+ if (!directory) {
+  store.report?.(`Fetching pnpm ${pins.pnpm} for this project (PATH has ${found ? `pnpm ${found}` : 'no pnpm'}); rer keeps it in its own cache.`);
+  try { directory = await downloadPnpm(pins.pnpm, signal); }
+  catch (error) { if (signal?.aborted || error instanceof RerError) throw error; throw missing(`pnpm ${pins.pnpm} is required and could not be fetched (${error.message}). Check the connection, or install pnpm ${pins.pnpm} yourself.`); }
+ }
+ usePnpm(directory);
+ if (await probePnpm(root, store, signal) !== pins.pnpm) throw missing(`pnpm ${pins.pnpm} is required. The pnpm rer provides did not report it; install pnpm ${pins.pnpm} yourself.`);
 }
+const usePnpm = directory => { process.env.PATH = [dirname(process.execPath), directory, process.env.PATH].filter(Boolean).join(delimiter); };
 
 export async function doctor(project, store, signal) {
  const { inspectOperations } = await import('../operations/operations.mjs');
@@ -127,6 +169,11 @@ export async function doctor(project, store, signal) {
    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) values = parsed;
   } catch {}
   try { pnpm = await probePnpm(project.root, store, signal); } catch (error) { if (signal?.aborted) throw error; }
+  // A pnpm rer already provides counts; doctor never fetches one.
+  if (pnpm !== pins.pnpm) {
+   const directory = await (await import('./pnpm-runtime.mjs')).cachedPnpm(pins.pnpm).catch(() => undefined);
+   if (directory) { usePnpm(directory); try { pnpm = await probePnpm(project.root, store, signal); } catch (error) { if (signal?.aborted) throw error; } }
+  }
  }
  const aiIssues = await localAiDiagnostics(project,process.env);
  const dependencies=project.profile==='first-party'?await dependencyDoctor(project.root):[];

package/cli/lifecycle.mjs

@@ -1,5 +1,3 @@
-import { createHmac } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
 import { dependencyInputs } from './dependency-input.mjs';
 import { linkDependencies } from './dependencies.mjs';
 import { savedSetupAnswers } from './setup-answers.mjs';
@@ -13,9 +11,10 @@ import { missing, refuse, RerError, lifecycleError } from './errors.mjs';
 import { executeDeclared } from './independent.mjs';
 import { transfer } from './transfers.mjs';
 import { runtimeFrontDoor } from './runtime-front-door.mjs';
-import { localSettingKeys, requiredLocalSettings } from './settings.mjs';
+import { localCliSessionProof, localSettingKeys, requiredLocalSettings } from './settings.mjs';
 import { rememberSetupAnswers } from './setup-answers.mjs';
 import { ensureDevKey, readDevKey, refuseDevLayerOutput, openUrl, DEV_KEY_HEADER } from './dev-identity.mjs';
+import { announceDoorRoute, routeRunning, verifyDoorFor } from './door-mode.mjs';
 
 export async function runCommand(project, options, out) {
  if(project.profile==='first-party'&&['dev','preview'].includes(options.verb))return (await import('./managed-server.mjs')).managedServer(project,options,out);
@@ -42,11 +41,12 @@ export async function runCommand(project, options, out) {
     selected = await selectedOrigin(project, options, { setup: options.verb === 'setup' });
     if (options.verb === 'setup') {input = await setupInput(project, options, selected.vars, signal, { origin: selected.url });await dependencyInputs({project,input,origin:selected.url});}
     else if (requiredLocalSettings(project, selected.vars).length) throw missing('Private owner settings are missing. Run rer setup --owner-email EMAIL first.');
-    if (options.verb !== 'outbox') await availablePort(selected.host, selected.port, { root: project.root, saved: !selected.explicitPort && selected.savedOrigin !== undefined });
+    if (options.verb !== 'outbox' && !selected.door) await availablePort(selected.host, selected.port, { root: project.root, saved: !selected.explicitPort && selected.savedOrigin !== undefined });
     if (options.verb === 'setup') announcePort(out, options, selected);
    }
    const { localOperation } = await shared('local/operation.mjs');
-   if (options.verb !== 'outbox') try { operation = await localOperation(project.root, process.env.RER_LOCAL_OPERATION); } catch (error) { throw refuse(error.message); }
+   // The run site reads no local state: it builds beside a running rer dev.
+   if (options.verb !== 'outbox' && !options.site) try { operation = await localOperation(project.root, process.env.RER_LOCAL_OPERATION); } catch (error) { throw refuse(error.message); }
    const { recoverInterrupted } = await shared('local/recovery.mjs');
    if (operation) await recoverInterrupted(project.root, operation);
   }
@@ -67,6 +67,8 @@ export async function runCommand(project, options, out) {
   if (project.profile === 'independent') return await executeDeclared(project, options, store, signal);
   await tools(project.root, store, signal);
   const adapter = project.adapter;
+  // The run site: static pages built from edition identity, never the app build.
+  if (options.site) return await (await import('./site.mjs')).siteCommand(project, options, store, signal, out);
   if (options.verb === 'install') {
    await store.run('Installing frozen dependencies', 'pnpm', ['install', '--frozen-lockfile'], { cwd: project.root, signal, env: { ...process.env, CI: 'true' } }); return {};
   }
@@ -75,7 +77,10 @@ export async function runCommand(project, options, out) {
    if (!Array.isArray(target)) throw refuse('A complete internal verification target is missing.');
    await store.run('Verifying application', target[0], target[1], { cwd: project.root, signal, env: { ...process.env, RER_LOCAL_OPERATION: operation.token } });
    await store.step('Serving the production build as rer deploy hosts it');
-   return { hosted: await (await import('./hosted-output.mjs')).checkHostedOutput(project.root, { declaration: adapter.deployDeclaration ?? adapter.deploy?.declaration }) };
+   const declaration = adapter.deployDeclaration ?? adapter.deploy?.declaration;
+   const hosted = await (await import('./hosted-output.mjs')).checkHostedOutput(project.root, { declaration });
+   await store.step('Checking that page sections hydrate as separate units');
+   return { hosted, hydration: await (await import('./hydration/check.mjs')).checkHydration(project.root, { pages: adapter.publicPages, declaration, report: lines => lines.forEach(line => store.report(line)) }) };
   }
   if (['export', 'import'].includes(options.verb)) return await transfer(project, options, signal, { store, operationToken: operation.token });
   if (options.verb === 'deploy') {
@@ -89,7 +94,17 @@ export async function runCommand(project, options, out) {
   const devKey = adapter.devIdentity ? options.verb === 'setup' ? await ensureDevKey(project.root) : await readDevKey(project.root) : null;
   if (devKey) store.addSecrets?.([devKey]);
   let app;
-  if (options.verb === 'setup') proxy = await runtimeFrontDoor(selected);
+  if (options.verb === 'setup') { proxy = await runtimeFrontDoor({ ...selected, devKey: devKey ?? undefined, origin: selected.url }); if (selected.door) await announceDoorRoute(selected, proxy); }
+  // The outbox of a door-mode checkout is read from its running server's own
+  // proxy, never through the door: with no such server nothing is sent. A key
+  // is sent only once the door has proved it is this account's.
+  if (options.verb === 'outbox' && selected?.door) {
+   const running = await runningRecord(project.root);
+   if (!running?.door) throw new RerError('outbox_unavailable', 'The local application outbox is unavailable. Start rer dev first.', 1);
+   if (devKey) await verifyDoorFor(selected.url);
+   await routeRunning(running);
+  }
+  const { appFetch } = await shared('app-fetch.mjs');
   const emailKey = localSettingKeys(project).email;
   await adapter.run(project.root, input ?? { [emailKey]: options.ownerEmail ?? selected?.vars[emailKey] }, store,
    child => { app = child; }, signal,
@@ -99,11 +114,9 @@ export async function runCommand(project, options, out) {
   if (options.verb === 'setup') {
    await linkDependencies({project,input,origin:url,store,signal});
    if(project.setupManifest?.dependencies?.length) {
-    const { localVariables }=await shared('local/environment.mjs');
-    const values=localVariables(await readFile(new URL(project.adapter.hooks?.secrets?.file??'.dev.vars','file://'+project.root+'/'),'utf8'));
-    const proof=createHmac('sha256',values.SESSION_SECRET).update('local-cli\0sign-in').digest('hex');
+    const proof=await localCliSessionProof(project);
     store.addSecrets?.([proof]);
-    const completed=await fetch(url+'/auth/setup-complete',{method:'POST',headers:{Origin:url,'Content-Type':'application/json','x-rer-local-cli':proof},body:'{}',signal});
+    const completed=await appFetch(url+'/auth/setup-complete',{method:'POST',headers:{Origin:url,'Content-Type':'application/json','x-rer-local-cli':proof},body:'{}',signal});
     if(!completed.ok)throw missing('The dependency setup has not completed an owner claim.');
     await completed.body?.cancel();
    }
@@ -113,7 +126,7 @@ export async function runCommand(project, options, out) {
    else if (devKey) { out.human(`RER_SETUP_READY ${url}`); out.human(`Next: rer dev opens ${url} signed in as the owner; first-run setup finishes at ${url}/setup.`); }
    else { out.human(`RER_SETUP_READY ${url}`); signInInstructions(out, signInUrl); out.human(`Finish first-run setup at ${url}/setup after sign-in.`); out.human('Next: rer dev'); }
   } else if (options.verb === 'outbox') {
-   const response = await fetch(signInUrl, { headers: devKey ? { [DEV_KEY_HEADER]: devKey } : {}, signal: AbortSignal.any([signal, AbortSignal.timeout(5000)]) });
+   const response = await appFetch(signInUrl, { headers: devKey ? { [DEV_KEY_HEADER]: devKey } : {}, signal: AbortSignal.any([signal, AbortSignal.timeout(5000)]) }).catch(() => ({ ok: false }));
    if (!response.ok) throw new RerError('outbox_unavailable', 'The local application outbox is unavailable. Start rer dev first.', 1);
    await response.body?.cancel();
    const open = devKey ? openUrl(url, devKey, { path: '/__dev/key', next: '/__dev/outbox' }) : signInUrl;
@@ -132,8 +145,19 @@ export async function runCommand(project, options, out) {
  }
 }
 
+// This checkout's running server, from the shared registry (routeRunning
+// checks that it is alive and holds its proxy port).
+async function runningRecord(root) {
+ const { readJson } = await import('../modules/job-queue/storage.mjs');
+ const { serversDirectory } = await import('./server-registry.mjs');
+ const { realpath } = await import('node:fs/promises');
+ const checkout = await realpath(root), state = await readJson(join(serversDirectory(), 'state.json'), { running: [] });
+ return (state.running ?? []).find(record => record.checkout === checkout);
+}
+
 // One plain line saying which port this checkout uses, and what moved.
 function announcePort(out, options, selected) {
+ if (selected.door) { if (options.json) out.event('origin', { url: selected.url, door: true }); else out.human(`Using ${selected.url} for this checkout, served through the front door.`); return; }
  const { moved, skipped } = selected;
  const line = moved ? `Moving this checkout from port ${moved.from} to port ${moved.to}. Its data is kept.`
   : !selected.savedOrigin ? `Using port ${selected.port} for this checkout${skipped ? ` (${skipped} is in use)` : ''}.` : undefined;

package/cli/local.mjs

@@ -8,6 +8,8 @@ import { origin, loopback } from './parse.mjs';
 import { refuse } from './errors.mjs';
 import { defaultPort, firstFreePort, busyPortMessage } from './port.mjs';
 import { localSettingKeys } from './settings.mjs';
+import { doorSite } from './door.mjs';
+import { selectDoor } from './door-mode.mjs';
 
 export async function selectedOrigin(project, options, { setup = false } = {}) {
  const { readSettings } = await shared('adapter-settings.mjs');
@@ -18,8 +20,11 @@ export async function selectedOrigin(project, options, { setup = false } = {}) {
   try { previous = new URL(vars[originKey]); } catch { throw refuse('Saved origin is malformed. Restore private settings or use confirmed reset.'); }
   if (previous.origin !== vars[originKey] || previous.protocol !== 'http:' || !loopback(previous.hostname.replace(/^\[|\]$/g, ''))) throw refuse('Saved origin is unsafe. Restore private settings or use confirmed reset.');
  }
- const host = options.host ?? previous?.hostname.replace(/^\[|\]$/g, '') ?? '127.0.0.1';
- const savedPort = previous ? Number(previous.port || 80) : undefined;
+ // A front-door origin (saved, or --door on a fresh setup) serves through the door.
+ const door = await selectDoor(project, options, previous, { vars, savedOrigin: previous?.origin });
+ if (door) return door;
+ const host = options.host ?? (previous && !doorSite(previous.origin) ? previous.hostname.replace(/^\[|\]$/g, '') : '127.0.0.1');
+ const savedPort = previous && !doorSite(previous.origin) ? Number(previous.port || 80) : undefined;
  // A first setup with no port asked for takes the first free one, never a busy one.
  let port = options.port ?? savedPort, taken;
  if (port === undefined && setup) { port = await firstFreePort(host); taken = port !== defaultPort; }
@@ -95,6 +100,7 @@ export async function refuseLegacyProcess(project,{reset=false}={}) {
  // Confirmed reset can recover malformed settings; checkout/state custody is
  // still checked even when there is no usable saved origin.
  const {localProcessConflict}=await shared('process-diagnostics.mjs');
- const conflict=await localProcessConflict(project.root,selected?.savedOrigin);
+ // The front door holds a door origin's port, not this checkout.
+ const conflict=await localProcessConflict(project.root,selected?.door?undefined:selected?.savedOrigin);
  if(conflict)throw refuse(`A local process holds ${conflict.reason}: PID ${conflict.pid} (${conflict.command}). Stop it with kill -TERM ${conflict.pid}, then retry. Use rer dev --stop or rer preview --stop for a registered server.`);
 }

package/cli/main.mjs

@@ -38,6 +38,8 @@ export async function main(argv = process.argv.slice(2)) {
    if (!options.json) out.human(JSON.stringify(result, null, 2));
    out.result(result.ok, result.ok ? 0 : 3, { diagnostics: result }); return result.ok ? 0 : 3;
   }
+  // A checkout without a declared run site refuses --site before any effect.
+  if (options.site) (await import('./site.mjs')).declaredSite(project);
   const bounded=await (await import('./bounded.mjs')).boundedCommand(project,options,argv,out);
   if(bounded)return bounded.exitCode;
   if(options.platform==='container' && !['export','import'].includes(options.verb)) { const result = await (await import('./container.mjs')).containerCommand(project,options,out); out.result(true,0,result); return 0; }