nukejs 0.0.1 → 0.0.3

package/dist/bundle.d.ts

@@ -0,0 +1,68 @@
+/**
+ * bundle.ts — NukeJS Client Runtime
+ *
+ * This file is compiled by esbuild into /__n.js and served to every page.
+ * It provides:
+ *
+ *   initRuntime(data)              — called once per page load to hydrate
+ *                                    "use client" components and wire up SPA nav
+ *   setupLocationChangeMonitor()   — patches history.pushState/replaceState so
+ *                                    SPA navigation fires a 'locationchange' event
+ *
+ * Hydration model (partial hydration):
+ *   - The server renders the full page to HTML, wrapping each client component
+ *     in a <span data-hydrate-id="cc_…" data-hydrate-props="…"> marker.
+ *   - initRuntime loads the matching JS bundle for each marker and calls
+ *     hydrateRoot() on it, letting React take over just that subtree.
+ *   - Props serialized by the server may include nested React elements
+ *     (serialized as { __re: 'html'|'client', … }), which are reconstructed
+ *     back into React.createElement calls before mounting.
+ *
+ * SPA navigation:
+ *   - Link clicks / programmatic navigation dispatch a 'locationchange' event.
+ *   - The handler fetches the target URL as HTML, diffs the #app container,
+ *     unmounts the old React roots, and re-hydrates the new ones.
+ *   - HMR navigations add ?__hmr=1 so the server skips client-SSR (faster).
+ */
+/**
+ * Patches history.pushState and history.replaceState to fire a custom
+ * 'locationchange' event on window.  Also listens to 'popstate' for
+ * back/forward navigation.
+ *
+ * This must be called after initRuntime sets up the navigation listener so
+ * there's no race between the event firing and the listener being registered.
+ */
+export declare function setupLocationChangeMonitor(): void;
+type ClientDebugLevel = 'silent' | 'error' | 'info' | 'verbose';
+/** Shape of the JSON blob embedded as #__n_data in every SSR page. */
+export interface RuntimeData {
+    /** IDs of client components actually rendered on this page (subset of allIds). */
+    hydrateIds: string[];
+    /** All client component IDs reachable from this page, including layouts.
+     *  Pre-loaded so SPA navigations to related pages feel instant. */
+    allIds: string[];
+    url: string;
+    params: Record<string, any>;
+    debug: ClientDebugLevel;
+}
+/**
+ * Bootstraps the NukeJS client runtime.
+ *
+ * Called once per page load from the inline <script type="module"> injected
+ * by the SSR renderer:
+ *
+ * ```js
+ * const { initRuntime } = await import('nukejs');
+ * const data = JSON.parse(document.getElementById('__n_data').textContent);
+ * await initRuntime(data);
+ * ```
+ *
+ * Order of operations:
+ *   1. Create the logger at the configured debug level.
+ *   2. Wire up SPA navigation listener.
+ *   3. Load all client component bundles in parallel.
+ *   4. Hydrate every [data-hydrate-id] node.
+ *   5. Patch history.pushState/replaceState so Link clicks trigger navigation.
+ */
+export declare function initRuntime(data: RuntimeData): Promise<void>;
+export {};

package/dist/bundle.js

@@ -0,0 +1,166 @@
+function setupLocationChangeMonitor() {
+  const originalPushState = window.history.pushState.bind(window.history);
+  const originalReplaceState = window.history.replaceState.bind(window.history);
+  const dispatch = (href) => window.dispatchEvent(new CustomEvent("locationchange", { detail: { href } }));
+  window.history.pushState = function(...args) {
+    originalPushState(...args);
+    dispatch(args[2]);
+  };
+  window.history.replaceState = function(...args) {
+    originalReplaceState(...args);
+    dispatch(args[2]);
+  };
+  window.addEventListener("popstate", () => dispatch(window.location.pathname));
+}
+function makeLogger(level) {
+  return {
+    verbose: (...a) => {
+      if (level === "verbose") console.log(...a);
+    },
+    info: (...a) => {
+      if (level === "verbose" || level === "info") console.log(...a);
+    },
+    warn: (...a) => {
+      if (level === "verbose" || level === "info") console.warn(...a);
+    },
+    error: (...a) => {
+      if (level !== "silent") console.error(...a);
+    }
+  };
+}
+async function reconstructElement(node, mods) {
+  if (node === null || node === void 0) return node;
+  if (typeof node !== "object") return node;
+  if (Array.isArray(node)) {
+    const items = await Promise.all(node.map((n) => reconstructElement(n, mods)));
+    const React = await import("react");
+    return items.map(
+      (el, i) => el && typeof el === "object" && el.$$typeof ? React.default.cloneElement(el, { key: el.key ?? i }) : el
+    );
+  }
+  if (node.__re === "client") {
+    const n = node;
+    const Comp = mods.get(n.componentId);
+    if (!Comp) return null;
+    const React = await import("react");
+    return React.default.createElement(Comp, await reconstructProps(n.props, mods));
+  }
+  if (node.__re === "html") {
+    const n = node;
+    const React = await import("react");
+    return React.default.createElement(n.tag, await reconstructProps(n.props, mods));
+  }
+  return node;
+}
+async function reconstructProps(props, mods) {
+  if (!props || typeof props !== "object" || Array.isArray(props))
+    return reconstructElement(props, mods);
+  const out = {};
+  for (const [k, v] of Object.entries(props))
+    out[k] = await reconstructElement(v, mods);
+  return out;
+}
+async function loadModules(ids, log, bust = "") {
+  const mods = /* @__PURE__ */ new Map();
+  await Promise.all(
+    ids.map(async (id) => {
+      try {
+        const url = `/__client-component/${id}.js` + (bust ? `?t=${bust}` : "");
+        const m = await import(url);
+        mods.set(id, m.default);
+        log.verbose("\u2713 Loaded:", id);
+      } catch (err) {
+        log.error("\u2717 Load failed:", id, err);
+      }
+    })
+  );
+  return mods;
+}
+const activeRoots = [];
+async function mountNodes(mods, log, isNavigation) {
+  const { hydrateRoot, createRoot } = await import("react-dom/client");
+  const React = await import("react");
+  const nodes = document.querySelectorAll("[data-hydrate-id]");
+  log.verbose("Found", nodes.length, "hydration point(s)");
+  for (const node of nodes) {
+    if (node.parentElement?.closest("[data-hydrate-id]")) continue;
+    const id = node.getAttribute("data-hydrate-id");
+    const Comp = mods.get(id);
+    if (!Comp) {
+      log.warn("No module for", id);
+      continue;
+    }
+    let rawProps = {};
+    try {
+      rawProps = JSON.parse(node.getAttribute("data-hydrate-props") || "{}");
+    } catch (e) {
+      log.error("Props parse error for", id, e);
+    }
+    try {
+      const element = React.default.createElement(Comp, await reconstructProps(rawProps, mods));
+      const root = isNavigation ? createRoot(node) : hydrateRoot(node, element);
+      if (isNavigation) root.render(element);
+      activeRoots.push(root);
+      log.verbose("\u2713 Mounted:", id);
+    } catch (err) {
+      log.error("\u2717 Mount failed:", id, err);
+    }
+  }
+}
+function syncAttrs(live, next) {
+  for (const { name, value } of Array.from(next.attributes)) {
+    live.setAttribute(name, value);
+  }
+  for (const { name } of Array.from(live.attributes)) {
+    if (!next.hasAttribute(name)) live.removeAttribute(name);
+  }
+}
+function setupNavigation(log) {
+  window.addEventListener("locationchange", async ({ detail: { href, hmr } }) => {
+    try {
+      const fetchUrl = hmr ? href + (href.includes("?") ? "&" : "?") + "__hmr=1" : href;
+      const response = await fetch(fetchUrl, { headers: { Accept: "text/html" } });
+      if (!response.ok) {
+        log.error("Navigation fetch failed:", response.status);
+        return;
+      }
+      const parser = new DOMParser();
+      const doc = parser.parseFromString(await response.text(), "text/html");
+      const newApp = doc.getElementById("app");
+      const currApp = document.getElementById("app");
+      if (!newApp || !currApp) return;
+      activeRoots.splice(0).forEach((r) => r.unmount());
+      currApp.innerHTML = newApp.innerHTML;
+      const newDataEl = doc.getElementById("__n_data");
+      const currDataEl = document.getElementById("__n_data");
+      if (newDataEl && currDataEl) currDataEl.textContent = newDataEl.textContent;
+      const newTitle = doc.querySelector("title");
+      if (newTitle) document.title = newTitle.textContent ?? "";
+      syncAttrs(document.documentElement, doc.documentElement);
+      syncAttrs(document.body, doc.body);
+      const navData = JSON.parse(currDataEl?.textContent ?? "{}");
+      log.info("\u{1F504} Route \u2192", href, "\u2014 mounting", navData.hydrateIds?.length ?? 0, "component(s)");
+      const mods = await loadModules(navData.allIds ?? [], log, String(Date.now()));
+      await mountNodes(mods, log, true);
+      window.scrollTo(0, 0);
+      log.info("\u{1F389} Navigation complete:", href);
+    } catch (err) {
+      log.error("Navigation error, falling back to full reload:", err);
+      window.location.href = href;
+    }
+  });
+}
+async function initRuntime(data) {
+  const log = makeLogger(data.debug ?? "silent");
+  log.info("\u{1F680} Partial hydration:", data.hydrateIds.length, "root component(s)");
+  setupNavigation(log);
+  const mods = await loadModules(data.allIds, log);
+  await mountNodes(mods, log, false);
+  log.info("\u{1F389} Done!");
+  setupLocationChangeMonitor();
+}
+export {
+  initRuntime,
+  setupLocationChangeMonitor
+};
+//# sourceMappingURL=bundle.js.map

package/dist/bundle.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/bundle.ts"],
+  "sourcesContent": ["/**\r\n * bundle.ts \u2014 NukeJS Client Runtime\r\n *\r\n * This file is compiled by esbuild into /__n.js and served to every page.\r\n * It provides:\r\n *\r\n *   initRuntime(data)              \u2014 called once per page load to hydrate\r\n *                                    \"use client\" components and wire up SPA nav\r\n *   setupLocationChangeMonitor()   \u2014 patches history.pushState/replaceState so\r\n *                                    SPA navigation fires a 'locationchange' event\r\n *\r\n * Hydration model (partial hydration):\r\n *   - The server renders the full page to HTML, wrapping each client component\r\n *     in a <span data-hydrate-id=\"cc_\u2026\" data-hydrate-props=\"\u2026\"> marker.\r\n *   - initRuntime loads the matching JS bundle for each marker and calls\r\n *     hydrateRoot() on it, letting React take over just that subtree.\r\n *   - Props serialized by the server may include nested React elements\r\n *     (serialized as { __re: 'html'|'client', \u2026 }), which are reconstructed\r\n *     back into React.createElement calls before mounting.\r\n *\r\n * SPA navigation:\r\n *   - Link clicks / programmatic navigation dispatch a 'locationchange' event.\r\n *   - The handler fetches the target URL as HTML, diffs the #app container,\r\n *     unmounts the old React roots, and re-hydrates the new ones.\r\n *   - HMR navigations add ?__hmr=1 so the server skips client-SSR (faster).\r\n */\r\n\r\n// \u2500\u2500\u2500 History patch \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/**\r\n * Patches history.pushState and history.replaceState to fire a custom\r\n * 'locationchange' event on window.  Also listens to 'popstate' for\r\n * back/forward navigation.\r\n *\r\n * This must be called after initRuntime sets up the navigation listener so\r\n * there's no race between the event firing and the listener being registered.\r\n */\r\nexport function setupLocationChangeMonitor(): void {\r\n  const originalPushState = window.history.pushState.bind(window.history);\r\n  const originalReplaceState = window.history.replaceState.bind(window.history);\r\n\r\n  const dispatch = (href?: any) =>\r\n    window.dispatchEvent(new CustomEvent('locationchange', { detail: { href } }));\r\n\r\n  window.history.pushState = function (...args) {\r\n    originalPushState(...args);\r\n    dispatch(args[2]); // args[2] is the URL\r\n  };\r\n\r\n  window.history.replaceState = function (...args) {\r\n    originalReplaceState(...args);\r\n    dispatch(args[2]);\r\n  };\r\n\r\n  // Back/forward navigation via the browser's native UI.\r\n  window.addEventListener('popstate', () => dispatch(window.location.pathname));\r\n}\r\n\r\n// \u2500\u2500\u2500 Logger \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\ntype ClientDebugLevel = 'silent' | 'error' | 'info' | 'verbose';\r\n\r\n/**\r\n * Returns a thin logger whose methods are no-ops unless `level` allows them.\r\n * The server embeds the active debug level in the __n_data JSON blob so the\r\n * client respects the same setting as the server.\r\n */\r\nfunction makeLogger(level: ClientDebugLevel) {\r\n  return {\r\n    verbose: (...a: any[]) => { if (level === 'verbose') console.log(...a); },\r\n    info: (...a: any[]) => { if (level === 'verbose' || level === 'info') console.log(...a); },\r\n    warn: (...a: any[]) => { if (level === 'verbose' || level === 'info') console.warn(...a); },\r\n    error: (...a: any[]) => { if (level !== 'silent') console.error(...a); },\r\n  };\r\n}\r\n\r\n// \u2500\u2500\u2500 Serialized node types \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/** The wire format for React elements embedded in hydration props. */\r\ntype SerializedNode =\r\n  | null\r\n  | undefined\r\n  | string\r\n  | number\r\n  | boolean\r\n  | SerializedNode[]\r\n  | { __re: 'html'; tag: string; props: Record<string, any> }   // native DOM element\r\n  | { __re: 'client'; componentId: string; props: Record<string, any> } // client component\r\n  | Record<string, any>;                                             // plain object\r\n\r\ntype ModuleMap = Map<string, any>; // componentId \u2192 default export\r\n\r\n// \u2500\u2500\u2500 Prop reconstruction \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/**\r\n * Recursively turns the server's serialized node tree back into real React\r\n * elements so they can be passed as props to hydrated components.\r\n *\r\n * The server serializes JSX passed as props (e.g. `<Button icon={<Icon />}>`)\r\n * into a JSON-safe format.  This function reverses that process.\r\n */\r\nasync function reconstructElement(node: SerializedNode, mods: ModuleMap): Promise<any> {\r\n  if (node === null || node === undefined) return node;\r\n  if (typeof node !== 'object') return node; // primitive \u2014 pass through\r\n\r\n  if (Array.isArray(node)) {\r\n    const items = await Promise.all(node.map(n => reconstructElement(n, mods)));\r\n    // Add index-based keys to any React elements in the array so React doesn't\r\n    // warn about \"Each child in a list should have a unique key prop\".\r\n    const React = await import('react');\r\n    return items.map((el, i) =>\r\n      el && typeof el === 'object' && el.$$typeof\r\n        ? React.default.cloneElement(el, { key: el.key ?? i })\r\n        : el,\r\n    );\r\n  }\r\n\r\n  // Client component \u2014 look up the loaded module by ID.\r\n  if ((node as any).__re === 'client') {\r\n    const n = node as { __re: 'client'; componentId: string; props: Record<string, any> };\r\n    const Comp = mods.get(n.componentId);\r\n    if (!Comp) return null;\r\n    const React = await import('react');\r\n    return React.default.createElement(Comp, await reconstructProps(n.props, mods));\r\n  }\r\n\r\n  // Native HTML element (e.g. <div>, <span>).\r\n  if ((node as any).__re === 'html') {\r\n    const n = node as { __re: 'html'; tag: string; props: Record<string, any> };\r\n    const React = await import('react');\r\n    return React.default.createElement(n.tag, await reconstructProps(n.props, mods));\r\n  }\r\n\r\n  // Plain object \u2014 reconstruct each value.\r\n  return node;\r\n}\r\n\r\n/** Reconstructs every value in a props object, handling nested serialized nodes. */\r\nasync function reconstructProps(\r\n  props: Record<string, any> | null | undefined,\r\n  mods: ModuleMap,\r\n): Promise<Record<string, any>> {\r\n  if (!props || typeof props !== 'object' || Array.isArray(props))\r\n    return reconstructElement(props as any, mods);\r\n\r\n  const out: Record<string, any> = {};\r\n  for (const [k, v] of Object.entries(props))\r\n    out[k] = await reconstructElement(v, mods);\r\n  return out;\r\n}\r\n\r\n// \u2500\u2500\u2500 Module loading \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/**\r\n * Dynamically imports each client component bundle from /__client-component/.\r\n * All fetches are issued in parallel; failures are logged but do not abort\r\n * the rest of the hydration pass.\r\n *\r\n * @param bust  Optional cache-busting suffix appended as `?t=<bust>`.\r\n *              Used during HMR navigation to bypass the module cache.\r\n */\r\nasync function loadModules(\r\n  ids: string[],\r\n  log: ReturnType<typeof makeLogger>,\r\n  bust = '',\r\n): Promise<ModuleMap> {\r\n  const mods: ModuleMap = new Map();\r\n  await Promise.all(\r\n    ids.map(async (id) => {\r\n      try {\r\n        const url = `/__client-component/${id}.js` + (bust ? `?t=${bust}` : '');\r\n        const m = await import(url);\r\n        mods.set(id, m.default);\r\n        log.verbose('\u2713 Loaded:', id);\r\n      } catch (err) {\r\n        log.error('\u2717 Load failed:', id, err);\r\n      }\r\n    }),\r\n  );\r\n  return mods;\r\n}\r\n\r\n// \u2500\u2500\u2500 Root mounting \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/** All active React roots \u2014 tracked so they can be unmounted before navigation. */\r\ntype ReactRoot = { unmount(): void };\r\nconst activeRoots: ReactRoot[] = [];\r\n\r\n/**\r\n * Finds every `[data-hydrate-id]` span in the document and either:\r\n *   - hydrateRoot()  \u2014 on initial page load (server HTML already present)\r\n *   - createRoot()   \u2014 after SPA navigation (innerHTML was set by us)\r\n *\r\n * Nested markers (a client component inside another client component) are\r\n * skipped here because the parent's React tree will handle its children.\r\n */\r\nasync function mountNodes(\r\n  mods: ModuleMap,\r\n  log: ReturnType<typeof makeLogger>,\r\n  isNavigation: boolean,\r\n): Promise<void> {\r\n  const { hydrateRoot, createRoot } = await import('react-dom/client');\r\n  const React = await import('react');\r\n\r\n  const nodes = document.querySelectorAll<HTMLElement>('[data-hydrate-id]');\r\n  log.verbose('Found', nodes.length, 'hydration point(s)');\r\n\r\n  for (const node of nodes) {\r\n    // Skip nested markers \u2014 the outer component owns its children.\r\n    if (node.parentElement?.closest('[data-hydrate-id]')) continue;\r\n\r\n    const id = node.getAttribute('data-hydrate-id')!;\r\n    const Comp = mods.get(id);\r\n    if (!Comp) { log.warn('No module for', id); continue; }\r\n\r\n    // Deserialize props from the data attribute (JSON set by the server).\r\n    let rawProps: Record<string, any> = {};\r\n    try {\r\n      rawProps = JSON.parse(node.getAttribute('data-hydrate-props') || '{}');\r\n    } catch (e) {\r\n      log.error('Props parse error for', id, e);\r\n    }\r\n\r\n    try {\r\n      const element = React.default.createElement(Comp, await reconstructProps(rawProps, mods));\r\n\r\n      // hydrateRoot reconciles React's virtual DOM against the server-rendered\r\n      // HTML without fully re-rendering.  createRoot replaces the content\r\n      // entirely \u2014 safe after navigation because we set innerHTML ourselves.\r\n      const root = isNavigation ? createRoot(node) : hydrateRoot(node, element);\r\n      if (isNavigation) (root as any).render(element);\r\n      activeRoots.push(root);\r\n      log.verbose('\u2713 Mounted:', id);\r\n    } catch (err) {\r\n      log.error('\u2717 Mount failed:', id, err);\r\n    }\r\n  }\r\n}\r\n\r\n// \u2500\u2500\u2500 SPA navigation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/**\r\n * Listens for 'locationchange' events (fired by setupLocationChangeMonitor\r\n * or by Link clicks) and performs a soft navigation:\r\n *\r\n *   1. Fetch the target URL as HTML (adds ?__hmr=1 during HMR updates so the\r\n *      server skips client-side SSR for a faster response).\r\n *   2. Parse the response with DOMParser.\r\n *   3. Replace #app innerHTML and __n_data.\r\n *   4. Unmount old React roots, then re-hydrate new ones.\r\n *   5. Scroll to top.\r\n *\r\n * Falls back to a full page reload if anything goes wrong.\r\n */\r\n/**\r\n * Syncs attributes from a parsed element onto the live document element.\r\n * Adds/updates attributes present in `next`, and removes any that were set\r\n * on `live` but are absent in `next` (so stale bodyAttrs/htmlAttrs are cleared).\r\n */\r\nfunction syncAttrs(live: Element, next: Element): void {\r\n  // Apply / update attributes from the new document.\r\n  for (const { name, value } of Array.from(next.attributes)) {\r\n    live.setAttribute(name, value);\r\n  }\r\n  // Remove attributes that no longer exist in the new document.\r\n  for (const { name } of Array.from(live.attributes)) {\r\n    if (!next.hasAttribute(name)) live.removeAttribute(name);\r\n  }\r\n}\r\n\r\nfunction setupNavigation(log: ReturnType<typeof makeLogger>): void {\r\n  window.addEventListener('locationchange', async ({ detail: { href, hmr } }: any) => {\r\n    try {\r\n      // Append ?__hmr=1 for HMR-triggered reloads so SSR skips the slower\r\n      // client-component renderToString path.\r\n      const fetchUrl = hmr\r\n        ? href + (href.includes('?') ? '&' : '?') + '__hmr=1'\r\n        : href;\r\n\r\n      const response = await fetch(fetchUrl, { headers: { Accept: 'text/html' } });\r\n      if (!response.ok) {\r\n        log.error('Navigation fetch failed:', response.status);\r\n        return;\r\n      }\r\n\r\n      const parser = new DOMParser();\r\n      const doc = parser.parseFromString(await response.text(), 'text/html');\r\n      const newApp = doc.getElementById('app');\r\n      const currApp = document.getElementById('app');\r\n      if (!newApp || !currApp) return;\r\n\r\n      // Tear down existing React trees before mutating the DOM \u2014 avoids React\r\n      // warnings about unmounting from a detached node.\r\n      activeRoots.splice(0).forEach(r => r.unmount());\r\n\r\n      // Swap content in-place (avoids a full document.write / navigation).\r\n      currApp.innerHTML = newApp.innerHTML;\r\n\r\n      // Update the runtime data blob so subsequent navigations use the new page's\r\n      // client component IDs.\r\n      const newDataEl = doc.getElementById('__n_data');\r\n      const currDataEl = document.getElementById('__n_data');\r\n      if (newDataEl && currDataEl) currDataEl.textContent = newDataEl.textContent;\r\n\r\n      // Update <title>.\r\n      const newTitle = doc.querySelector('title');\r\n      if (newTitle) document.title = newTitle.textContent ?? '';\r\n\r\n      // Sync <html> attributes (e.g. lang, class, style from useHtml({ htmlAttrs })).\r\n      syncAttrs(document.documentElement, doc.documentElement);\r\n\r\n      // Sync <body> attributes (e.g. style, class from useHtml({ bodyAttrs })).\r\n      syncAttrs(document.body, doc.body);\r\n\r\n      const navData = JSON.parse(currDataEl?.textContent ?? '{}') as RuntimeData;\r\n      log.info('\uD83D\uDD04 Route \u2192', href, '\u2014 mounting', navData.hydrateIds?.length ?? 0, 'component(s)');\r\n\r\n      // Load bundles with a cache-buster timestamp so stale modules are evicted.\r\n      const mods = await loadModules(navData.allIds ?? [], log, String(Date.now()));\r\n      await mountNodes(mods, log, true);\r\n\r\n      window.scrollTo(0, 0);\r\n      log.info('\uD83C\uDF89 Navigation complete:', href);\r\n    } catch (err) {\r\n      log.error('Navigation error, falling back to full reload:', err);\r\n      window.location.href = href;\r\n    }\r\n  });\r\n}\r\n\r\n// \u2500\u2500\u2500 Public API \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/** Shape of the JSON blob embedded as #__n_data in every SSR page. */\r\nexport interface RuntimeData {\r\n  /** IDs of client components actually rendered on this page (subset of allIds). */\r\n  hydrateIds: string[];\r\n  /** All client component IDs reachable from this page, including layouts.\r\n   *  Pre-loaded so SPA navigations to related pages feel instant. */\r\n  allIds: string[];\r\n  url: string;\r\n  params: Record<string, any>;\r\n  debug: ClientDebugLevel;\r\n}\r\n\r\n/**\r\n * Bootstraps the NukeJS client runtime.\r\n *\r\n * Called once per page load from the inline <script type=\"module\"> injected\r\n * by the SSR renderer:\r\n *\r\n * ```js\r\n * const { initRuntime } = await import('nukejs');\r\n * const data = JSON.parse(document.getElementById('__n_data').textContent);\r\n * await initRuntime(data);\r\n * ```\r\n *\r\n * Order of operations:\r\n *   1. Create the logger at the configured debug level.\r\n *   2. Wire up SPA navigation listener.\r\n *   3. Load all client component bundles in parallel.\r\n *   4. Hydrate every [data-hydrate-id] node.\r\n *   5. Patch history.pushState/replaceState so Link clicks trigger navigation.\r\n */\r\nexport async function initRuntime(data: RuntimeData): Promise<void> {\r\n  const log = makeLogger(data.debug ?? 'silent');\r\n\r\n  log.info('\uD83D\uDE80 Partial hydration:', data.hydrateIds.length, 'root component(s)');\r\n\r\n  // Set up navigation first so any 'locationchange' fired during hydration\r\n  // is captured.\r\n  setupNavigation(log);\r\n\r\n  // Load all component bundles (not just hydrateIds) so SPA navigations can\r\n  // mount components for other pages without an extra network round-trip.\r\n  const mods = await loadModules(data.allIds, log);\r\n  await mountNodes(mods, log, false);\r\n\r\n  log.info('\uD83C\uDF89 Done!');\r\n\r\n  // Patch history last so pushState calls during hydration (e.g. redirect\r\n  // side-effects) don't trigger a navigation before roots are ready.\r\n  setupLocationChangeMonitor();\r\n}"],
+  "mappings": "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",
+  "names": []
+}

package/dist/bundler.d.ts

@@ -0,0 +1,58 @@
+/**
+ * bundler.ts — Dev-Mode On-Demand Bundler
+ *
+ * Handles the three internal JS routes served only in `nuke dev`:
+ *
+ *   /__react.js                — Full React + ReactDOM browser bundle.
+ *                                All hooks, jsx-runtime, hydrateRoot, createRoot.
+ *                                Served once and cached by the browser.
+ *
+ *   /__n.js                    — NukeJS client runtime (bundle.ts compiled to ESM).
+ *                                Provides initRuntime and SPA navigation.
+ *
+ *   /__client-component/<id>   — Individual "use client" component bundles.
+ *                                Built on-demand the first time they're requested.
+ *                                Re-built on every request in dev (no disk cache).
+ *
+ * In production (`nuke build`), equivalent bundles are written to dist/static/
+ * by build-common.ts instead of being served dynamically.
+ */
+import type { ServerResponse } from 'http';
+/**
+ * Bundles a single "use client" file for the browser.
+ *
+ * React and react-dom/client are kept external so the importmap can resolve
+ * them to the already-loaded /__react.js bundle (avoids shipping React twice).
+ *
+ * @param filePath  Absolute path to the source file.
+ * @returns         ESM string ready to serve as application/javascript.
+ */
+export declare function bundleClientComponent(filePath: string): Promise<string>;
+/**
+ * Looks up a client component by its content-hash ID (e.g. `cc_a1b2c3d4`),
+ * bundles it on-demand, and writes the result to the HTTP response.
+ *
+ * The ID→path mapping comes from the component analyzer cache, which is
+ * populated during SSR as pages and their layouts are rendered.
+ */
+export declare function serveClientComponentBundle(componentId: string, res: ServerResponse): Promise<void>;
+/**
+ * Builds and serves the unified React browser bundle to /__react.js.
+ *
+ * Exports every public React API so client components can import from 'react'
+ * or 'react-dom/client' and have them resolve via the importmap to this single
+ * pre-loaded bundle — no duplicate copies of React in the browser.
+ *
+ * esbuild aliases point at the project's installed React version so the bundle
+ * always matches what the server is actually running.
+ */
+export declare function serveReactBundle(res: ServerResponse): Promise<void>;
+/**
+ * Bundles and serves the NukeJS client runtime to /__n.js.
+ *
+ * The entry point is bundle.ts (or bundle.js in production dist/).
+ * React is kept external so it resolves via the importmap to /__react.js.
+ *
+ * Minified because this script is loaded on every page request.
+ */
+export declare function serveNukeBundle(res: ServerResponse): Promise<void>;

package/dist/bundler.js

@@ -0,0 +1,100 @@
+import path from "path";
+import { fileURLToPath } from "url";
+import { build } from "esbuild";
+import { log } from "./logger.js";
+import { getComponentById } from "./component-analyzer.js";
+let reactBundlePromise = null;
+let nukeBundlePromise = null;
+async function bundleClientComponent(filePath) {
+  const result = await build({
+    entryPoints: [filePath],
+    bundle: true,
+    format: "esm",
+    platform: "browser",
+    write: false,
+    jsx: "automatic",
+    // Keep React external — resolved by the importmap to /__react.js
+    external: ["react", "react-dom/client", "react/jsx-runtime"]
+  });
+  return result.outputFiles[0].text;
+}
+async function serveClientComponentBundle(componentId, res) {
+  const filePath = getComponentById(componentId);
+  if (filePath) {
+    log.verbose(`Bundling client component: ${componentId} (${path.basename(filePath)})`);
+    res.setHeader("Content-Type", "application/javascript");
+    res.end(await bundleClientComponent(filePath));
+    return;
+  }
+  log.error(`Client component not found: ${componentId}`);
+  res.statusCode = 404;
+  res.end("Client component not found");
+}
+async function serveReactBundle(res) {
+  log.verbose("Bundling React runtime");
+  if (!reactBundlePromise) {
+    reactBundlePromise = build({
+      stdin: {
+        contents: `
+        import React, {
+          useState, useEffect, useContext, useReducer, useCallback, useMemo,
+          useRef, useImperativeHandle, useLayoutEffect, useDebugValue,
+          useDeferredValue, useTransition, useId, useSyncExternalStore,
+          useInsertionEffect, createContext, forwardRef, memo, lazy,
+          Suspense, Fragment, StrictMode, Component, PureComponent
+        } from 'react';
+        import { jsx, jsxs } from 'react/jsx-runtime';
+        import { hydrateRoot, createRoot } from 'react-dom/client';
+
+        export {
+          useState, useEffect, useContext, useReducer, useCallback, useMemo,
+          useRef, useImperativeHandle, useLayoutEffect, useDebugValue,
+          useDeferredValue, useTransition, useId, useSyncExternalStore,
+          useInsertionEffect, createContext, forwardRef, memo, lazy,
+          Suspense, Fragment, StrictMode, Component, PureComponent,
+          hydrateRoot, createRoot, jsx, jsxs
+        };
+        export default React;
+      `,
+        loader: "ts"
+      },
+      bundle: true,
+      write: false,
+      treeShaking: true,
+      minify: false,
+      format: "esm",
+      jsx: "automatic",
+      alias: {
+        react: path.dirname(fileURLToPath(import.meta.resolve("react/package.json"))),
+        "react-dom": path.dirname(fileURLToPath(import.meta.resolve("react-dom/package.json")))
+      },
+      define: { "process.env.NODE_ENV": '"development"' }
+    }).then((r) => r.outputFiles[0].text);
+  }
+  res.setHeader("Content-Type", "application/javascript");
+  res.end(await reactBundlePromise);
+}
+async function serveNukeBundle(res) {
+  log.verbose("Bundling nuke runtime");
+  if (!nukeBundlePromise) {
+    const dir = path.dirname(fileURLToPath(import.meta.url));
+    const entry = path.join(dir, `bundle.${dir.endsWith("dist") ? "js" : "ts"}`);
+    nukeBundlePromise = build({
+      entryPoints: [entry],
+      write: false,
+      format: "esm",
+      minify: true,
+      bundle: true,
+      external: ["react", "react-dom/client"]
+    }).then((r) => r.outputFiles[0].text);
+  }
+  res.setHeader("Content-Type", "application/javascript");
+  res.end(await nukeBundlePromise);
+}
+export {
+  bundleClientComponent,
+  serveClientComponentBundle,
+  serveNukeBundle,
+  serveReactBundle
+};
+//# sourceMappingURL=bundler.js.map

package/dist/bundler.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/bundler.ts"],
+  "sourcesContent": ["/**\n * bundler.ts \u2014 Dev-Mode On-Demand Bundler\n *\n * Handles the three internal JS routes served only in `nuke dev`:\n *\n *   /__react.js                \u2014 Full React + ReactDOM browser bundle.\n *                                All hooks, jsx-runtime, hydrateRoot, createRoot.\n *                                Served once and cached by the browser.\n *\n *   /__n.js                    \u2014 NukeJS client runtime (bundle.ts compiled to ESM).\n *                                Provides initRuntime and SPA navigation.\n *\n *   /__client-component/<id>   \u2014 Individual \"use client\" component bundles.\n *                                Built on-demand the first time they're requested.\n *                                Re-built on every request in dev (no disk cache).\n *\n * In production (`nuke build`), equivalent bundles are written to dist/static/\n * by build-common.ts instead of being served dynamically.\n */\n\nimport path from 'path';\nimport { fileURLToPath } from 'url';\nimport { build } from 'esbuild';\nimport type { ServerResponse } from 'http';\nimport { log } from './logger';\nimport { getComponentById } from './component-analyzer';\n\n// \u2500\u2500\u2500 Bundle caches \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n// Cache Promises (not just results) so concurrent requests share one build\n// instead of each spawning their own esbuild process.\nlet reactBundlePromise: Promise<string> | null = null;\nlet nukeBundlePromise: Promise<string> | null = null;\n\n// \u2500\u2500\u2500 Client component bundle \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Bundles a single \"use client\" file for the browser.\n *\n * React and react-dom/client are kept external so the importmap can resolve\n * them to the already-loaded /__react.js bundle (avoids shipping React twice).\n *\n * @param filePath  Absolute path to the source file.\n * @returns         ESM string ready to serve as application/javascript.\n */\nexport async function bundleClientComponent(filePath: string): Promise<string> {\n  const result = await build({\n    entryPoints: [filePath],\n    bundle: true,\n    format: 'esm',\n    platform: 'browser',\n    write: false,\n    jsx: 'automatic',\n    // Keep React external \u2014 resolved by the importmap to /__react.js\n    external: ['react', 'react-dom/client', 'react/jsx-runtime'],\n  });\n  return result.outputFiles[0].text;\n}\n\n/**\n * Looks up a client component by its content-hash ID (e.g. `cc_a1b2c3d4`),\n * bundles it on-demand, and writes the result to the HTTP response.\n *\n * The ID\u2192path mapping comes from the component analyzer cache, which is\n * populated during SSR as pages and their layouts are rendered.\n */\nexport async function serveClientComponentBundle(\n  componentId: string,\n  res: ServerResponse,\n): Promise<void> {\n  const filePath = getComponentById(componentId);\n  if (filePath) {\n    log.verbose(`Bundling client component: ${componentId} (${path.basename(filePath)})`);\n    res.setHeader('Content-Type', 'application/javascript');\n    res.end(await bundleClientComponent(filePath));\n    return;\n  }\n\n  // ID not found \u2014 either the page hasn't been visited yet (cache is empty)\n  // or the ID is stale.\n  log.error(`Client component not found: ${componentId}`);\n  res.statusCode = 404;\n  res.end('Client component not found');\n}\n\n// \u2500\u2500\u2500 React bundle \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Builds and serves the unified React browser bundle to /__react.js.\n *\n * Exports every public React API so client components can import from 'react'\n * or 'react-dom/client' and have them resolve via the importmap to this single\n * pre-loaded bundle \u2014 no duplicate copies of React in the browser.\n *\n * esbuild aliases point at the project's installed React version so the bundle\n * always matches what the server is actually running.\n */\nexport async function serveReactBundle(res: ServerResponse): Promise<void> {\n  log.verbose('Bundling React runtime');\n\n  if (!reactBundlePromise) {\n    reactBundlePromise = build({\n      stdin: {\n        contents: `\n        import React, {\n          useState, useEffect, useContext, useReducer, useCallback, useMemo,\n          useRef, useImperativeHandle, useLayoutEffect, useDebugValue,\n          useDeferredValue, useTransition, useId, useSyncExternalStore,\n          useInsertionEffect, createContext, forwardRef, memo, lazy,\n          Suspense, Fragment, StrictMode, Component, PureComponent\n        } from 'react';\n        import { jsx, jsxs } from 'react/jsx-runtime';\n        import { hydrateRoot, createRoot } from 'react-dom/client';\n\n        export {\n          useState, useEffect, useContext, useReducer, useCallback, useMemo,\n          useRef, useImperativeHandle, useLayoutEffect, useDebugValue,\n          useDeferredValue, useTransition, useId, useSyncExternalStore,\n          useInsertionEffect, createContext, forwardRef, memo, lazy,\n          Suspense, Fragment, StrictMode, Component, PureComponent,\n          hydrateRoot, createRoot, jsx, jsxs\n        };\n        export default React;\n      `,\n        loader: 'ts',\n      },\n      bundle: true,\n      write: false,\n      treeShaking: true,\n      minify: false,\n      format: 'esm',\n      jsx: 'automatic',\n      alias: {\n        react: path.dirname(fileURLToPath(import.meta.resolve('react/package.json'))),\n        'react-dom': path.dirname(fileURLToPath(import.meta.resolve('react-dom/package.json'))),\n      },\n      define: { 'process.env.NODE_ENV': '\"development\"' },\n    }).then(r => r.outputFiles[0].text);\n  }\n\n  res.setHeader('Content-Type', 'application/javascript');\n  res.end(await reactBundlePromise);\n}\n\n// \u2500\u2500\u2500 NukeJS runtime bundle \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Bundles and serves the NukeJS client runtime to /__n.js.\n *\n * The entry point is bundle.ts (or bundle.js in production dist/).\n * React is kept external so it resolves via the importmap to /__react.js.\n *\n * Minified because this script is loaded on every page request.\n */\nexport async function serveNukeBundle(res: ServerResponse): Promise<void> {\n  log.verbose('Bundling nuke runtime');\n\n  if (!nukeBundlePromise) {\n    const dir = path.dirname(fileURLToPath(import.meta.url));\n    const entry = path.join(dir, `bundle.${dir.endsWith('dist') ? 'js' : 'ts'}`);\n    nukeBundlePromise = build({\n      entryPoints: [entry],\n      write: false,\n      format: 'esm',\n      minify: true,\n      bundle: true,\n      external: ['react', 'react-dom/client'],\n    }).then(r => r.outputFiles[0].text);\n  }\n\n  res.setHeader('Content-Type', 'application/javascript');\n  res.end(await nukeBundlePromise);\n}"],
+  "mappings": "AAoBA,OAAO,UAAU;AACjB,SAAS,qBAAqB;AAC9B,SAAS,aAAa;AAEtB,SAAS,WAAW;AACpB,SAAS,wBAAwB;AAMjC,IAAI,qBAA6C;AACjD,IAAI,oBAA4C;AAahD,eAAsB,sBAAsB,UAAmC;AAC7E,QAAM,SAAS,MAAM,MAAM;AAAA,IACzB,aAAa,CAAC,QAAQ;AAAA,IACtB,QAAQ;AAAA,IACR,QAAQ;AAAA,IACR,UAAU;AAAA,IACV,OAAO;AAAA,IACP,KAAK;AAAA;AAAA,IAEL,UAAU,CAAC,SAAS,oBAAoB,mBAAmB;AAAA,EAC7D,CAAC;AACD,SAAO,OAAO,YAAY,CAAC,EAAE;AAC/B;AASA,eAAsB,2BACpB,aACA,KACe;AACf,QAAM,WAAW,iBAAiB,WAAW;AAC7C,MAAI,UAAU;AACZ,QAAI,QAAQ,8BAA8B,WAAW,KAAK,KAAK,SAAS,QAAQ,CAAC,GAAG;AACpF,QAAI,UAAU,gBAAgB,wBAAwB;AACtD,QAAI,IAAI,MAAM,sBAAsB,QAAQ,CAAC;AAC7C;AAAA,EACF;AAIA,MAAI,MAAM,+BAA+B,WAAW,EAAE;AACtD,MAAI,aAAa;AACjB,MAAI,IAAI,4BAA4B;AACtC;AAcA,eAAsB,iBAAiB,KAAoC;AACzE,MAAI,QAAQ,wBAAwB;AAEpC,MAAI,CAAC,oBAAoB;AACvB,yBAAqB,MAAM;AAAA,MACzB,OAAO;AAAA,QACL,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAqBV,QAAQ;AAAA,MACV;AAAA,MACA,QAAQ;AAAA,MACR,OAAO;AAAA,MACP,aAAa;AAAA,MACb,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,KAAK;AAAA,MACL,OAAO;AAAA,QACL,OAAO,KAAK,QAAQ,cAAc,YAAY,QAAQ,oBAAoB,CAAC,CAAC;AAAA,QAC5E,aAAa,KAAK,QAAQ,cAAc,YAAY,QAAQ,wBAAwB,CAAC,CAAC;AAAA,MACxF;AAAA,MACA,QAAQ,EAAE,wBAAwB,gBAAgB;AAAA,IACpD,CAAC,EAAE,KAAK,OAAK,EAAE,YAAY,CAAC,EAAE,IAAI;AAAA,EACpC;AAEA,MAAI,UAAU,gBAAgB,wBAAwB;AACtD,MAAI,IAAI,MAAM,kBAAkB;AAClC;AAYA,eAAsB,gBAAgB,KAAoC;AACxE,MAAI,QAAQ,uBAAuB;AAEnC,MAAI,CAAC,mBAAmB;AACtB,UAAM,MAAM,KAAK,QAAQ,cAAc,YAAY,GAAG,CAAC;AACvD,UAAM,QAAQ,KAAK,KAAK,KAAK,UAAU,IAAI,SAAS,MAAM,IAAI,OAAO,IAAI,EAAE;AAC3E,wBAAoB,MAAM;AAAA,MACxB,aAAa,CAAC,KAAK;AAAA,MACnB,OAAO;AAAA,MACP,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,UAAU,CAAC,SAAS,kBAAkB;AAAA,IACxC,CAAC,EAAE,KAAK,OAAK,EAAE,YAAY,CAAC,EAAE,IAAI;AAAA,EACpC;AAEA,MAAI,UAAU,gBAAgB,wBAAwB;AACtD,MAAI,IAAI,MAAM,iBAAiB;AACjC;",
+  "names": []
+}

package/dist/component-analyzer.d.ts

@@ -0,0 +1,72 @@
+/**
+ * component-analyzer.ts — Static Import Analyzer & Client Component Registry
+ *
+ * This module solves a core problem in NukeJS's partial hydration model:
+ * the server needs to know *at render time* which components in a page's
+ * import tree are "use client" boundaries so it can:
+ *
+ *   1. Emit <span data-hydrate-id="…"> markers instead of rendering them.
+ *   2. Inject the matching bundle URLs into the page's runtime data blob.
+ *   3. Serialize the props passed to those components so the browser can
+ *      reconstruct them after loading the bundle.
+ *
+ * How it works:
+ *   - analyzeComponent()         checks whether a file starts with "use client"
+ *                                 and assigns a stable content-hash ID if it does.
+ *   - extractImports()           parses `import … from '…'` statements with a
+ *                                 regex and resolves relative/absolute paths.
+ *   - findClientComponentsInTree() recursively walks the import graph, stopping
+ *                                 at client boundaries (they own their subtree).
+ *
+ * Results are memoised in `componentCache` (process-lifetime) so repeated SSR
+ * renders don't re-read and re-hash files they've already seen.
+ *
+ * ID scheme:
+ *   The ID for a client component is `cc_` + the first 8 hex chars of the MD5
+ *   hash of its path relative to pagesDir.  This is stable across restarts and
+ *   matches what the browser will request from /__client-component/<id>.js.
+ */
+export interface ComponentInfo {
+    filePath: string;
+    /** True when the file's first non-comment line is "use client". */
+    isClientComponent: boolean;
+    /** Stable hash-based ID, present only for client components. */
+    clientComponentId?: string;
+}
+/**
+ * Analyses a component file and returns cached results on subsequent calls.
+ *
+ * @param filePath  Absolute path to the source file.
+ * @param pagesDir  Absolute path to the pages root (used for ID generation).
+ */
+export declare function analyzeComponent(filePath: string, pagesDir: string): ComponentInfo;
+/**
+ * Recursively walks the import graph from `filePath`, collecting every
+ * "use client" file encountered.
+ *
+ * The walk stops at client boundaries: a "use client" file is collected and
+ * its own imports are NOT walked (the client runtime handles their subtree).
+ *
+ * The `visited` set prevents infinite loops from circular imports.
+ *
+ * @returns  Map<id, absoluteFilePath> for every client component reachable
+ *           from `filePath` (including `filePath` itself if it's a client).
+ */
+export declare function findClientComponentsInTree(filePath: string, pagesDir: string, visited?: Set<string>): Map<string, string>;
+/**
+ * Looks up the absolute file path for a client component by its ID.
+ * O(1) reverse lookup — avoids the O(n) linear scan in bundler.ts.
+ *
+ * Returns undefined when the ID is not in the cache (page not yet visited
+ * in dev, or stale ID after a file change).
+ */
+export declare function getComponentById(id: string): string | undefined;
+/** Returns the live component cache (used by bundler.ts for ID→path lookup). */
+export declare function getComponentCache(): Map<string, ComponentInfo>;
+/**
+ * Removes a single file's analysis entry from the cache.
+ * Call this whenever a source file changes in dev mode so the next render
+ * re-analyses the file (picks up added/removed "use client" directives and
+ * changed import graphs).
+ */
+export declare function invalidateComponentCache(filePath: string): void;

package/dist/component-analyzer.js

@@ -0,0 +1,102 @@
+import path from "path";
+import fs from "fs";
+import crypto from "crypto";
+import { fileURLToPath } from "url";
+const componentCache = /* @__PURE__ */ new Map();
+function isClientComponent(filePath) {
+  const content = fs.readFileSync(filePath, "utf-8");
+  for (const line of content.split("\n").slice(0, 5)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("//") || trimmed.startsWith("/*")) continue;
+    if (/^["']use client["'];?$/.test(trimmed)) return true;
+    break;
+  }
+  return false;
+}
+function getClientComponentId(filePath, pagesDir) {
+  const hash = crypto.createHash("md5").update(path.relative(pagesDir, filePath)).digest("hex").substring(0, 8);
+  return `cc_${hash}`;
+}
+function analyzeComponent(filePath, pagesDir) {
+  if (componentCache.has(filePath)) return componentCache.get(filePath);
+  const isClient = isClientComponent(filePath);
+  const info = {
+    filePath,
+    isClientComponent: isClient,
+    clientComponentId: isClient ? getClientComponentId(filePath, pagesDir) : void 0
+  };
+  componentCache.set(filePath, info);
+  return info;
+}
+function extractImports(filePath) {
+  const content = fs.readFileSync(filePath, "utf-8");
+  const dir = path.dirname(filePath);
+  const imports = [];
+  const importRegex = /import\s+(?:(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+)?['"]([^'"]+)['"]/g;
+  let match;
+  while ((match = importRegex.exec(content)) !== null) {
+    const importPath = match[1];
+    if (importPath === "nukejs") {
+      const selfDir = path.dirname(fileURLToPath(import.meta.url));
+      for (const candidate of [
+        path.join(selfDir, "index.ts"),
+        path.join(selfDir, "index.js")
+      ]) {
+        if (fs.existsSync(candidate)) {
+          imports.push(candidate);
+          break;
+        }
+      }
+      continue;
+    }
+    if (!importPath.startsWith(".") && !importPath.startsWith("/")) continue;
+    let resolved = path.resolve(dir, importPath);
+    if (!fs.existsSync(resolved)) {
+      for (const ext of [".tsx", ".ts", ".jsx", ".js"]) {
+        const candidate = resolved + ext;
+        if (fs.existsSync(candidate)) {
+          resolved = candidate;
+          break;
+        }
+      }
+    }
+    if (fs.existsSync(resolved)) imports.push(resolved);
+  }
+  return imports;
+}
+function findClientComponentsInTree(filePath, pagesDir, visited = /* @__PURE__ */ new Set()) {
+  const clientComponents = /* @__PURE__ */ new Map();
+  if (visited.has(filePath)) return clientComponents;
+  visited.add(filePath);
+  const info = analyzeComponent(filePath, pagesDir);
+  if (info.isClientComponent && info.clientComponentId) {
+    clientComponents.set(info.clientComponentId, filePath);
+    return clientComponents;
+  }
+  for (const importPath of extractImports(filePath)) {
+    for (const [id, p] of findClientComponentsInTree(importPath, pagesDir, visited)) {
+      clientComponents.set(id, p);
+    }
+  }
+  return clientComponents;
+}
+function getComponentById(id) {
+  for (const [filePath, info] of componentCache) {
+    if (info.clientComponentId === id) return filePath;
+  }
+  return void 0;
+}
+function getComponentCache() {
+  return componentCache;
+}
+function invalidateComponentCache(filePath) {
+  componentCache.delete(filePath);
+}
+export {
+  analyzeComponent,
+  findClientComponentsInTree,
+  getComponentById,
+  getComponentCache,
+  invalidateComponentCache
+};
+//# sourceMappingURL=component-analyzer.js.map