rosefc 0.0.0-stage → 0.2.1

package/src/cli/shell.ts

@@ -0,0 +1,610 @@
+
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as esbuild from 'esbuild';
+import { createHash } from 'crypto';
+import { fnv1a32 } from '../hash.js';
+
+const OUT_DIR = path.join(process.cwd(), 'dist');
+
+let clientCache: { for: string; mtimeMs: number; source: string } | null = null;
+// Sliced mode caches one entry per slice file (a route's inline bundle), each
+// keyed by its own mtime: a dev rebuild that only touched one route rewrites
+// one slice, and the other routes' documents keep their cached source.
+const sliceCaches = new Map<string, { mtimeMs: number; source: string }>();
+
+
+let splitMode = false;
+let slicedMode = false;
+export function setBundleMode(mode: string): void {
+  splitMode = mode === 'split';
+  slicedMode = mode === 'sliced';
+}
+
+/**
+ * Extra connect-src sources from the app's rosefc.config.js
+ * (`export const csp = { connectSrc: 'https:' }`). The framework default is
+ * 'self' - a closed network. Apps whose client talks to an API host (a cloud
+ * gateway, a user-configured LLM endpoint) widen it here; the value is
+ * appended verbatim after 'self'.
+ */
+let extraConnectSrc = '';
+let extraImgSrc = '';
+export function setExtraCsp(connectSrc: string, imgSrc: string): void {
+  extraConnectSrc = connectSrc.trim();
+  extraImgSrc = imgSrc.trim();
+  cspCache = null;
+}
+
+function cspTail(): string {
+  let tail = CSP_TAIL;
+  if (extraConnectSrc !== '') tail = tail.replace("connect-src 'self'", `connect-src 'self' ${extraConnectSrc}`);
+  if (extraImgSrc !== '') tail = tail.replace("img-src 'self' data: https://fastly.picsum.photos", `img-src 'self' data: https://fastly.picsum.photos ${extraImgSrc}`);
+  return tail;
+}
+
+/**
+ * The inline bundle source for a document.
+ *
+ * - inline mode: dist/client.js (every route's code, inlined into every
+ *   interactive document).
+ * - split mode: null - the runtime is an external module fetch.
+ * - sliced mode: dist/slices/<key>.js when the server named a key (the route's
+ *   own runtime + render chain), dist/client.js otherwise (the runtime-only
+ *   core: mount.js embedders and 404/500 documents, which have no route of their
+ *   own to slice).
+ *
+ * `dir` defaults to this process's OUT_DIR (the CLI's project dist). The edge
+ * adapter serves a dist it was handed at creation, which is NOT the process
+ * cwd's dist - a slice resolved against the wrong directory would silently
+ * fall back to the core and ship every route's render chain in one document.
+ */
+export function getClientSource(routeKey?: string | null, dir: string = OUT_DIR): string | null {
+  if (splitMode) return null;
+  const file = slicedMode && routeKey
+    ? path.join(dir, 'slices', `${routeKey}.js`)
+    : path.join(dir, 'client.js');
+  try {
+    const st = fs.statSync(file);
+    if (slicedMode && routeKey) {
+      const hit = sliceCaches.get(routeKey + '\0' + dir);
+      if (hit && hit.mtimeMs === st.mtimeMs) return hit.source;
+      const source = fs.readFileSync(file, 'utf-8');
+      sliceCaches.set(routeKey + '\0' + dir, { mtimeMs: st.mtimeMs, source });
+      return source;
+    }
+    if (!clientCache || clientCache.for !== dir || clientCache.mtimeMs !== st.mtimeMs) {
+      clientCache = { for: dir, mtimeMs: st.mtimeMs, source: fs.readFileSync(file, 'utf-8') };
+    }
+    return clientCache.source;
+  } catch {
+    // A slice file that vanished (a route removed between the build and the
+    // serve) falls back to the core: the document still boots, every route
+    // riding the nav chunk.
+    if (slicedMode && routeKey) return getClientSource(null, dir);
+    return null;
+  }
+}
+
+// Content hash of dist/client.js for cache-busting the split-mode script URL.
+// The hash, not the mtime: deployment platforms normalize file mtimes, so an
+// mtime key would be identical across deploys and returning visitors would
+// keep executing the previous build's runtime.
+let clientVersionCache: { mtimeMs: number; v: string } | null = null;
+export function getClientVersion(): string {
+  try {
+    const file = path.join(OUT_DIR, 'client.js');
+    const st = fs.statSync(file);
+    if (!clientVersionCache || clientVersionCache.mtimeMs !== st.mtimeMs) {
+      clientVersionCache = { mtimeMs: st.mtimeMs, v: fnv1a32(fs.readFileSync(file)) };
+    }
+    return clientVersionCache.v;
+  } catch {
+    return '';
+  }
+}
+
+// The URL the document loads the split-mode runtime from: versioned when the bundle exists so a deploy is a new URL (fresh fetch, stale cache impossible), unversioned as the fallback.
+function clientSrcUrl(): string {
+  const v = getClientVersion();
+  return v ? `/client.js?v=${v}` : '/client.js';
+}
+
+let styleCache: { mtimeMs: number; source: string } | null = null;
+
+// Read dist/styles.css (every component's scoped <style>, merged at build time) with an mtime-based cache.
+export function getStyles(): string {
+  const file = path.join(OUT_DIR, 'styles.css');
+  try {
+    const st = fs.statSync(file);
+    if (!styleCache || styleCache.mtimeMs !== st.mtimeMs) {
+      styleCache = { mtimeMs: st.mtimeMs, source: fs.readFileSync(file, 'utf-8') };
+    }
+    return styleCache.source;
+  } catch {
+    return '';
+  }
+}
+
+// Bootstrap appended after the inlined bundle: client-side navigation. Distinct names avoid any collision with minified bundle identifiers.
+const BOOTSTRAP_SOURCE = `
+// shell = false: the document's SSR content sits directly in <body> - no
+// #app wrapper, no demo styles, so a real theme's CSS owns the document from
+// the first byte (and a JS-less visitor never sees either). The bundle still
+// runs, and it still needs its container: wrap the content once, here, before
+// any theme script executes (module scripts run before DOMContentLoaded). The
+// wrapper is a plain unstyled div, so the re-parent is visually inert; every
+// later path - adoption, navigation, forms - is then the ordinary one.
+let __app = document.getElementById('app');
+if (!__app) {
+  __app = document.createElement('div');
+  __app.id = 'app';
+  // scripts stay outside the wrapper, exactly where the dressed document
+  // keeps them: the state element and the running module must survive a
+  // navigation's innerHTML swap (they are the document's, not the route's).
+  for (const node of Array.from(document.body.children)) {
+    if (node.tagName !== 'SCRIPT') __app.appendChild(node);
+  }
+  document.body.appendChild(__app);
+}
+// Native View Transitions around client-side navigation (progressive:
+// browsers without the API navigate normally, no polyfill, no CSS required).
+// F35: stash the CURRENT entry's scroll position into its history state
+// before a new push - the browser only restores scroll on full page loads; a
+// pjax swap would land wherever the swap left it.
+function __saveScroll() {
+  try {
+    const s = history.state || {};
+    history.replaceState(Object.assign({}, s, { __rosefcScroll: window.scrollY }), '');
+  } catch (e) { /* history state unavailable (file:// edge): best effort */ }
+}
+function __navigate(pathname, restore) {
+  const paint = () => {
+    const p = start(__app, pathname);
+    if (restore) {
+      // back/forward: restore the entry's scroll (top when it has none)
+      const s = history.state || {};
+      const y = typeof s.__rosefcScroll === 'number' ? s.__rosefcScroll : 0;
+      return Promise.resolve(p).then(() => { window.scrollTo(0, y); }, () => { window.scrollTo(0, y); });
+    }
+    // a fresh navigation starts at the top, like a full page load
+    window.scrollTo(0, 0);
+    return p;
+  };
+  if (document.startViewTransition) {
+    return document.startViewTransition(paint).updateCallbackDone;
+  }
+  return paint();
+}
+window.addEventListener('popstate', () => __navigate(window.location.pathname, true));
+document.addEventListener('click', (e) => {
+  const a = e.target.tagName === 'A' ? e.target : e.target.closest && e.target.closest('a');
+  if (a && a.getAttribute('href') && a.getAttribute('href').startsWith('/')) {
+    e.preventDefault();
+    __saveScroll();
+    history.pushState(null, '', a.getAttribute('href'));
+    __navigate(window.location.pathname);
+  }
+});
+// Prefetch the target route's full render (including $data) on hover, keyboard
+// focus, or touch - the click that follows paints from cache: no await, no
+// request. Other frameworks prefetch data only; Rosefc prefetches the render
+// because the inlined bundle already contains every route.
+function __prefetchHandler(e) {
+  const a = e.target.closest && e.target.closest('a[href^="/"]');
+  if (a && prefetch) prefetch(a.getAttribute('href'), 'hover');
+}
+document.addEventListener('mouseover', __prefetchHandler);
+document.addEventListener('focusin', __prefetchHandler);
+document.addEventListener('touchstart', __prefetchHandler, { passive: true });
+// Viewport + idle prefetch (viewport-triggered): once a link scrolls into view and the
+// browser is idle, its route renders ahead of any interaction. trade-off: both
+// APIs are feature-detected; without them the hover/focus/touch path above
+// still covers every link.
+if (prefetch && 'IntersectionObserver' in window && 'requestIdleCallback' in window) {
+  const io = new IntersectionObserver((entries) => {
+    for (const e of entries) {
+      if (!e.isIntersecting) continue;
+      io.unobserve(e.target); // one-shot per element; fresh links re-observe after nav
+      requestIdleCallback(() => prefetch(e.target.getAttribute('href'), 'viewport'));
+    }
+  });
+  // observing an already-observed element is a no-op, so re-sweeping is cheap
+  const observeLinks = () => {
+    for (const a of document.querySelectorAll('a[href^="/"]')) io.observe(a);
+  };
+  observeLinks();
+  // navigation swaps the container's innerHTML: re-observe the fresh links
+  const __rawNav = __navigate;
+  __navigate = (p) => __rawNav(p).then(observeLinks, () => {});
+}
+// Progressive-enhancement forms: <form method="POST"> backed by a server
+// action. With JS the submit is intercepted and handed to postForm (one
+// request, in-place adopt). Without JS the browser performs the native POST
+// and the server re-renders the page: the same form works with JavaScript
+// disabled, which Server Actions in other frameworks do not.
+document.addEventListener('submit', (e) => {
+  const f = e.target;
+  if (!f || f.tagName !== 'FORM' || f.hasAttribute('data-on-submit')) return;
+  if ((f.getAttribute('method') || '').toLowerCase() !== 'post') return;
+  e.preventDefault();
+  postForm(new FormData(f));
+});
+// Dev seam: the live signal graph, readable as JSON. Three callers, one
+// implementation: the dev server's reload bridge snapshots it before a
+// rebuild-triggered reload so the edit lands on the state the developer had,
+// and the devtools extension (devtools/) reads it the same way - the signal
+// graph plus the prefetch counters, which is the whole observable state of a
+// running page. Both are DIRECT references (no wrapper arrow): the names take
+// no arguments, so the call is identical and every document that carries the
+// bundle pays eleven bytes for the pair instead of forty.
+window.__rosefc = { state: serializeState, prefetch: prefetchStats };
+// initial=true: DOM is SSR output, resume state + wire markers (zero hydration).
+// If the document was rendered for a DIFFERENT route (a static-file server's
+// SPA fallback serves index.html for unknown paths), adopt nothing - let the
+// client router render the requested route from scratch.
+const __st = document.getElementById('__rosefc_state');
+let __state = __st ? JSON.parse(__st.textContent || '{}') : {};
+// The dev server's reload bridge hands the pre-reload signal graph back inside
+// the next document (window.__rosefc_resume). The resumed values win over the
+// fresh render's, but the ROUTE stays the one the server just rendered - and
+// the route renders client-side from the bundle rather than adopting the SSR
+// DOM, because a resumed list can be longer than the document's rows and
+// adoption could not add them. Absent in every non-dev document.
+const __resumed = window.__rosefc_resume ? JSON.parse(window.__rosefc_resume) : null;
+if (__resumed) {
+  const __route = __state.__route;
+  __state = Object.assign(__state, __resumed);
+  __state.__route = __route;
+}
+// A NOT-FOUND document (the server stamps __notFound onto its state) boots
+// into the app's own 404 route: the URL matches no route - or a catch-all
+// whose resolver threw notFound(), whose key sits null in the resumed state
+// and whose template would dereference it into a 500. startNotFound paints
+// the not-found route from the resumed state instead (zero requests).
+if (__state.__notFound) {
+  startNotFound(__app, window.location.pathname);
+} else if (__resumed) {
+  start(__app, window.location.pathname);
+} else if (__state.__route === window.location.pathname) {
+  // Lazy hydration (opt-in via export const lazyHydration = true in the root
+  // layout): defer the initial wire() until the browser is idle so the SSR
+  // paint is interactive-to-paint without blocking on the event wiring. Falls
+  // back to eager wiring where requestIdleCallback is unavailable.
+  if (window.__rosefcLazy && typeof requestIdleCallback === 'function') {
+    requestIdleCallback(() => start(__app, window.location.pathname, true));
+  } else {
+    start(__app, window.location.pathname, true);
+  }
+} else {
+  start(__app, window.location.pathname);
+}
+`;
+// Lazy + best-effort: the transform runs on first use, not at module load - the bundled prod server (dist/prod.mjs) boots without esbuild's worker.
+let BOOTSTRAP_CACHE: string | null = null;
+function bootstrap(): string {
+  if (BOOTSTRAP_CACHE === null) {
+    // The bundled prod server (dist/prod.mjs) sets the skip flag: esbuild's transformSync spawns a worker thread whose entry is the bundle itself.
+    if ((globalThis as any).__ROSEFC_SKIP_MINIFY) {
+      BOOTSTRAP_CACHE = BOOTSTRAP_SOURCE;
+    } else {
+      try {
+        BOOTSTRAP_CACHE = esbuild.transformSync(BOOTSTRAP_SOURCE, { minify: true }).code;
+      } catch {
+        BOOTSTRAP_CACHE = BOOTSTRAP_SOURCE;
+      }
+    }
+  }
+  return BOOTSTRAP_CACHE;
+}
+
+
+const CSP_TAIL = `style-src 'unsafe-inline'; img-src 'self' data: https://fastly.picsum.photos; font-src 'self' data:; connect-src 'self'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'; object-src 'none'`;
+
+
+const BASELINE_SECURITY_HEADERS: Record<string, string> = {
+  'x-content-type-options': 'nosniff',
+  'x-frame-options': 'DENY',
+  'referrer-policy': 'strict-origin-when-cross-origin',
+  'permissions-policy': 'accelerometer=(), autoplay=(), camera=(), display-capture=(), encrypted-media=(), fullscreen=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), midi=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), serial=(), usb=(), xr-spatial-tracking=()',
+};
+
+let cspCache: { for: string | null; v: string; value: string } | null = null;
+// The exact bytes between the external bootstrap's script tags - the single source of truth shared by the tag and the CSP hash.
+let EXTERNAL_BOOTSTRAP_CACHE: { v: string; s: string } | null = null;
+function externalBootstrap(): string {
+  const v = getClientVersion();
+  if (EXTERNAL_BOOTSTRAP_CACHE === null || EXTERNAL_BOOTSTRAP_CACHE.v !== v) {
+    EXTERNAL_BOOTSTRAP_CACHE = { v, s: `\nimport { start, startNotFound, prefetch, postForm, prefetchStats, serializeState } from '${clientSrcUrl()}';\n${bootstrap()}` };
+  }
+  return EXTERNAL_BOOTSTRAP_CACHE.s;
+}
+// The inlined bundle is byte-identical for every document of a build, so the
+// regex scan + slice + concat over the whole client.js is computed once and
+// reused: prerender paid it per route, and a per-request document paid it per
+// request. Keyed by the source string itself (getClientSource() hands back the
+// same instance while dist/client.js is unchanged).
+let inlineScriptCache: { for: string; out: string } | null = null;
+function inlineScript(client: string): string {
+  if (inlineScriptCache !== null && inlineScriptCache.for === client) return inlineScriptCache.out;
+  const m = /\bexport\s*\{([^}]*)\}\s*;?\s*$/.exec(client);
+  let body = client;
+  let aliases = "";
+  if (m) {
+    body = client.slice(0, m.index) + client.slice(m.index + m[0].length);
+    aliases = m[1]
+      .split(",")
+      .map((pair) => {
+        const parts = pair.split(" as ").map((x) => x.trim());
+        if (parts.length === 1 || parts[0] === parts[1]) return "";
+        return parts[0] && parts[1] ? `var ${parts[1]} = ${parts[0]};` : "";
+      })
+      .join("");
+  }
+  const out = `\n${body}\n${aliases}\n${bootstrap()}`;
+  inlineScriptCache = { for: client, out };
+  return out;
+}
+/**
+ * A fresh CSP nonce: 128 bits from the platform RNG, base64 - the syntax the
+ * header and the tag share . Web Crypto on purpose: the same helper
+ * serves the Node server and the edge adapter, and an edge runtime has no
+ * node:crypto. Minted per response and never reused: a nonce is only worth
+ * anything an attacker cannot predict, and a repeated one would hand a
+ * guessed value unlimited script execution.
+ */
+export function mintNonce(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  let raw = '';
+  for (const b of bytes) raw += String.fromCharCode(b);
+  return btoa(raw);
+}
+
+/**
+ * The document's CSP. Two shapes, chosen per response:
+ *
+ * - no nonce (the default): `script-src 'sha256-…'` over the exact bytes the
+ *   tag will carry. Nothing else may run - the strongest policy Rosefc has,
+ *   and the reason a Rosefc document needs no 'unsafe-inline'.
+ * - a nonce (a route exporting `csp = { nonce: true }`):
+ *   `script-src 'nonce-…' 'strict-dynamic'`. A hash dies the moment anything
+ *   between the server and the browser touches the document - a CDN, a WAF,
+ *   an A/B injector that adds one byte blocks the page's own bundle. A nonce
+ *   survives that, and 'strict-dynamic' lets the page's own code load more
+ *   code (a third-party loader, a lazily imported chunk), which is the reason
+ *   a deployment reaches for a nonce in the first place. It is weaker in one
+ *   way: whatever the document's script loads is trusted. That is the trade
+ *   the route opts into, per route, not a framework default.
+ */
+export function securityHeaders(client: string | null, nonce = ''): Record<string, string> {
+  const headers: Record<string, string> = { ...BASELINE_SECURITY_HEADERS };
+  if (nonce) {
+    headers['Content-Security-Policy'] = `script-src 'nonce-${nonce}' 'strict-dynamic'; ${cspTail()}`;
+    return headers;
+  }
+  if (!cspCache || cspCache.for !== client || cspCache.v !== (client ? '' : getClientVersion())) {
+    // Sliced mode: the document's own bytes are hash-locked as usual, and
+    // 'self' is added because the first cross-route navigation dynamically
+    // imports /nav.js - a same-origin module fetch the hash alone would block.
+    // (Split mode has the same shape: its external runtime needs 'self'.)
+    const scriptSrc = client
+      ? `'sha256-${createHash('sha256').update(inlineScript(client), 'utf-8').digest('base64')}'${slicedMode ? " 'self'" : ''}`
+      : `'self' 'sha256-${createHash('sha256').update(externalBootstrap(), 'utf-8').digest('base64')}'`;
+    cspCache = {
+      for: client,
+      v: client ? '' : getClientVersion(),
+      value: `script-src ${scriptSrc}; ${cspTail()}`,
+    };
+  }
+  headers['Content-Security-Policy'] = cspCache.value;
+  return headers;
+}
+
+const FAVICON = '<link rel="icon" href="data:image/svg+xml,<svg xmlns=\'http://www.w3.org/2000/svg\' viewBox=\'0 0 100 100\'><text y=\'.9em\' font-size=\'90\'>🌹</text></svg>">';
+
+const STYLES = `
+    body { font-family: system-ui, sans-serif; margin: 0; padding: 2rem; }
+    button { padding: 0.5rem 1rem; font-size: 1rem; margin-right: 0.5rem; }
+    a { color: #e91e63; text-decoration: none; font-weight: bold; }
+    a:hover { text-decoration: underline; }
+    nav a { margin-right: 1rem; }
+    .rh { border-bottom: 2px solid #e91e63; margin-bottom: 1.5rem; padding-bottom: 0.75rem; }
+    .rb { font-size: 1.25rem; }
+    .rn { display: inline-block; margin-left: 1.5rem; }
+    .rf { margin-top: 2rem; color: #888; font-size: 0.85rem; }
+    ::view-transition-old(root), ::view-transition-new(root) { animation-duration: .18s; }
+  `;
+
+/** The shell's own global stylesheet, exported for the native exporters: the
+ *  mini-program emitter filters it (no `<body>` there) instead of re-inventing
+ *  a base theme, so an exported app keeps the layout it was designed with. */
+export const SHELL_STYLES = STYLES;
+
+const STYLES_MIN = STYLES.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|[^"']+/g, (m) =>
+  m[0] === '"' || m[0] === "'" ? m : m.replace(/\s+/g, ' ').replace(/\s*([:;{},])\s*/g, '$1').trim()
+).trim();
+
+/**
+ * Merge the route chain's <head> blocks (document order: page first, then its
+ * layouts) into one clean <head> fragment. First occurrence wins per key, so a
+ * page overrides its layouts - matching the client's reverse-order applyHead.
+ *
+ * Bug report 2026.9.22 11:46: the keyed whitelist used to be title plus
+ * meta/link/base and NOTHING else, so a `<style>` block, a
+ * `<script type="application/ld+json">` data block and a `<noscript>`
+ * fallback were dropped here in silence - the compiler collected them, the
+ * merge threw them away, and a CMS theme system had no way to ship its
+ * per-request CSS. Every head element now passes through: the keyed
+ * singletons keep their name/property identity, and everything
+ * else is keyed by id when it has one and by tag+position when it does not,
+ * so two layouts' <style> blocks coexist and a page still overrides its
+ * layout's. Passthrough elements carry HEAD_ATTR too (the attribute the
+ * runtime manages) so a client-side navigation replaces or drops them like
+ * any other managed element instead of leaking the previous route's CSS
+ * into every route visited after it.
+ *
+ * Bug report 2026-10-13 (Oboext): a `<link>` keyed by its bare `rel` meant the
+ * SECOND link of any same-rel group was silently dropped - hreflang alternates,
+ * multi-size icons, font preloads, several feeds all lost every member but the
+ * first. A rel-only key now carries the link's target (`href`, or `type`/`as`
+ * when it has no href), so same-rel links coexist. `rel="canonical"` is the
+ * one documented singleton and keeps the bare-rel key, so a page's canonical
+ * still overrides its layout's. The client's applyHead derives keys the same
+ * way, so the two halves keep agreeing without talking to each other.
+ */
+function mergeHeadBlocks(blocks: string[]): string {
+  const byKey = new Map<string, string>();
+  const order: string[] = [];
+  const positional = new Map<string, number>();
+  const put = (key: string, html: string) => {
+    if (!byKey.has(key)) {
+      byKey.set(key, html);
+      order.push(key);
+    }
+  };
+  for (const block of blocks) {
+    for (const m of block.matchAll(/<title[^>]*>[\s\S]*?<\/title>/gi)) put('title', m[0]);
+    for (const m of block.matchAll(/<(\w+)((?:\s+[\w:-]+(?:=(?:"[^"]*"|'[^']*'|[^\s"'>]+))?)*)\s*(?:\/>|>([\s\S]*?)<\/\1\s*>|>)/gi)) {
+      const tag = m[1].toLowerCase();
+      if (tag === 'title') continue;
+      const attrs = m[2];
+      const attr = (name: string): string | null => {
+        const mm = attrs.match(new RegExp(`\\s${name}=(?:"([^"]*)"|'([^']*)')`, 'i'));
+        return mm ? (mm[1] ?? mm[2]) : null;
+      };
+      const idMatch = attrs.match(/\sid=(?:"([^"]*)"|'([^']*)')/i);
+      const name = attr('name');
+      const property = attr('property');
+      const rel = attr('rel');
+      const charset = attr('charset');
+      let key: string;
+      if (name !== null) key = `${tag}:${name}`;
+      else if (property !== null) key = `${tag}:${property}`;
+      else if (rel !== null) key = `${tag}:${rel}${linkIdentitySuffix(rel, attr)}`;
+      else if (charset !== null) key = `${tag}:${charset}`;
+      else if (idMatch) key = `${tag}:${idMatch[1] ?? idMatch[2]}`;
+      else {
+        key = `${tag}:#${positional.get(tag) ?? 0}`;
+        positional.set(tag, (positional.get(tag) ?? 0) + 1);
+      }
+      // The key is stamped into a double-quoted attribute value, so a quote
+      // inside a (pathological) href must not break the markup.
+      key = key.replace(/"/g, '');
+      const marked = m[0].replace(/^<\w+/, (t) => `${t} data-rosefc-head="${key}"`);
+      put(key, marked);
+    }
+  }
+  return order.map((k) => byKey.get(k)!).join('\n  ');
+}
+
+/**
+ * The suffix that joins a rel-only link's identity key. `canonical` is a
+ * spec singleton - the first one wins so a page overrides its layout's. Every
+ * other rel may legitimately repeat with a different target, so the target
+ * (`href`, falling back to `type`/`as`) becomes part of the key.
+ */
+function linkIdentitySuffix(rel: string, attr: (name: string) => string | null): string {
+  if (/(^|\s)canonical(\s|$)/i.test(rel)) return '';
+  return `@${attr('href') ?? attr('type') ?? attr('as') ?? ''}`;
+}
+
+/**
+ * The script tag carrying the inlined bundle (+ bootstrap), or the external
+ * fallback. `nonce` stamps the same value the CSP header carries, so
+ * a route running a nonce policy has its own code allowed to run; without it
+ * the tag is byte-identical to what the sha256 in the header was computed
+ * over. Both tags in split mode get it: the external module and the inline
+ * bootstrap are the same trust root.
+ */
+export function clientScriptTag(client: string | null, nonce = ''): string {
+  const n = nonce ? ` nonce="${nonce}"` : '';
+  if (client) {
+    return `<script type="module"${n}>${inlineScript(client)}</script>`;
+  }
+  // Split / external path: the framework runtime is a separate module fetch.
+  // modulepreload (+ crossorigin, matching the module's CORS mode) starts it
+  // early, and fetchpriority=high lets it jump the image/style queue so the
+  // interactive layer lands before the browser would otherwise schedule it.
+  // The URL carries the bundle's content hash: a deploy changes the hash, the
+  // browser sees a new URL, and yesterday's cached runtime can never execute
+  // against today's documents.
+  const src = clientSrcUrl();
+  const preload = `<link rel="modulepreload" href="${src}" crossorigin>`;
+  return `${preload}\n<script type="module"${n} src="${src}" fetchpriority="high"></script>\n<script type="module"${n}>${externalBootstrap()}</script>`;
+}
+
+/**
+ * The static half of the document for streaming SSR: everything up to (and
+ * including) the open `<div id="app">`. No route tags - the route's <head>
+ * content is applied by the client at boot from the body's head markers.
+ *
+ * `lang`/`dir` are the document's locale and reading direction ( the
+ * servers compute them from the [lang] segment with the server bundle's
+ * docAttrs). The streaming path flushes this string BEFORE the render, so
+ * the browser gets the language metadata in the first byte.
+ */
+export function shellOpen(styles: string = getStyles(), lang = 'en', dir = '', shell = true): string {
+  const styleTag = styles ? `\n  <style>${styles}</style>` : '';
+  const demoStyles = shell ? `\n  <style>${STYLES_MIN}</style>` : '';
+  const appOpen = shell ? `\n  <div id="app">` : '';
+  return `<!DOCTYPE html>
+<html lang="${lang}"${dir ? ` dir="${dir}"` : ''}>
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Rosefc</title>${demoStyles}${styleTag}
+  ${FAVICON}
+</head>
+<body>${appOpen}`;
+}
+
+/** Build the document from an explicit client source (edge runtimes have no fs). */
+export function buildShell(ssrHtml: string, stateJson: string, client: string | null, head: string[] = [], styles: string = getStyles(), js = true, lang = 'en', dir = '', nonce = '', shell = true): string {
+  const mergedHead = mergeHeadBlocks(head);
+  const headStamped = nonce
+    ? mergedHead.replace(/<script\b([^>]*)>/gi, (m, attrs: string) => (/\bnonce=/.test(attrs) ? m : `<script${attrs} nonce="${nonce}">`))
+    : mergedHead;
+  let htmlAttrs = ` lang="${lang}"${dir ? ` dir="${dir}"` : ''}`;
+  let bodyAttrs = '';
+  const headClean = headStamped.replace(/<(html|body)\b([^>]*)>/gi, (_m, tag: string, attrs: string) => {
+    // mergeHeadBlocks stamps every passthrough element with its key; the
+    const clean = attrs.replace(/\s*data-rosefc-head="[^"]*"/, '');
+    if (tag === 'html') htmlAttrs = clean;
+    else bodyAttrs = clean;
+    return '';
+  });
+  
+  const titleTag = /<title>/i.test(mergedHead) ? '' : '<title>Rosefc</title>';
+  
+  const iconTag = /rel=["']?icon/i.test(mergedHead) ? '' : `\n  ${FAVICON}`;
+  const headTags = headClean ? `\n  ${headClean}` : '';
+  const styleTag = styles ? `\n  <style>${styles}</style>` : '';
+  const stateSafe = stateJson.replace(/</g, '\\u003c');
+  const jsTail = js
+    ? `\n  <script type="application/json" id="__rosefc_state">${stateSafe}</script>\n  ${clientScriptTag(client, nonce)}`
+    : '';
+  const open = js && shell ? '<div id="app">' : '';
+  const close = js && shell ? '</div>' : '';
+  const shellStyles = js && shell ? `\n  <style>${STYLES_MIN}</style>` : '';
+
+  return `<!DOCTYPE html>
+<html${htmlAttrs}>
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">${headTags}${iconTag}
+  ${titleTag}${shellStyles}${styleTag}
+</head>
+<body${bodyAttrs}>
+  ${open}${ssrHtml}${close}${jsTail}
+</body>
+</html>`;
+}
+
+/** Node entry: reads dist/client.js from disk (mtime-cached). */
+export function getHtmlShell(ssrHtml: string, stateJson: string, head: string[] = [], js = true, lang = 'en', dir = '', nonce = '', shell = true, routeKey: string | null = null): string {
+  // Sliced mode: routeKey names the route's own inline bundle (the server's
+  // sliceKeyFor); null keeps the runtime-only core.
+  return buildShell(ssrHtml, stateJson, getClientSource(routeKey), head, getStyles(), js, lang, dir, nonce, shell);
+}

package/src/cli/shutdown.ts

@@ -0,0 +1,56 @@
+
+
+type ShutdownHook = {
+  name: string;
+  fn: () => void | Promise<void>;
+};
+
+type HookResult = { name: string; ok: boolean; error?: string };
+
+const shutdownHooks: ShutdownHook[] = [];
+
+
+let draining: Promise<HookResult[]> | null = null;
+
+// Exposed on globalThis because esbuild bundles app code with no external allowlist: a static import from the app would be inlined as a SECOND copy.
+(globalThis as unknown as { __rosefcOnShutdown?: typeof onShutdown }).__rosefcOnShutdown =
+  onShutdown;
+(globalThis as unknown as { __rosefcRunShutdownHooks?: typeof runShutdownHooks }).__rosefcRunShutdownHooks =
+  runShutdownHooks;
+
+/** Returns an unregister function - a hot-swapped client must drop its old hook. */
+export function onShutdown(name: string, fn: () => void | Promise<void>): () => void {
+  const hook: ShutdownHook = { name, fn };
+  shutdownHooks.push(hook);
+  return () => {
+    const at = shutdownHooks.indexOf(hook);
+    if (at !== -1) shutdownHooks.splice(at, 1);
+  };
+}
+
+/** Never rejects; a throwing hook is reported and the rest still run. */
+export function runShutdownHooks(reason: string): Promise<HookResult[]> {
+  if (draining) return draining;
+  draining = (async () => {
+    const results: HookResult[] = [];
+    
+    for (const hook of shutdownHooks.slice()) {
+      try {
+        await hook.fn();
+        results.push({ name: hook.name, ok: true });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        results.push({ name: hook.name, ok: false, error: message });
+        console.error(`[rosefc] shutdown hook ${hook.name} failed (${reason}):`, message);
+      }
+    }
+    return results;
+  })().finally(() => {
+    draining = null;
+  });
+  return draining;
+}
+
+export function shutdownHookCount(): number {
+  return shutdownHooks.length;
+}