nukejs 0.0.13 → 0.0.15

package/README.md

@@ -17,6 +17,7 @@ npm create nuke@latest
 - [Pages & Routing](#pages--routing)
 - [Layouts](#layouts)
 - [Client Components](#client-components)
+- [State Management](#state-management)
 - [API Routes](#api-routes)
 - [Middleware](#middleware)
 - [Static Files](#static-files)
@@ -292,7 +293,142 @@ Children and other React elements can be passed as props — NukeJS serializes t
 
 ---
 
-## API Routes
+## State Management
+
+NukeJS ships a lightweight built-in store for sharing state across client components. Because each `"use client"` component is hydrated into its own independent React root, React Context cannot cross component boundaries — the store solves this.
+
+All store state lives in `window.__nukeStores`, so it is shared across every bundle on the page regardless of how many times a store module is evaluated.
+
+### createStore
+
+```ts
+import { createStore } from 'nukejs';
+
+const counterStore = createStore('counter', { count: 0 });
+```
+
+The first argument is a unique name used to key the store in the global registry. The second is the initial state. If two bundles call `createStore` with the same name, the first one wins and subsequent calls reuse the existing entry.
+
+### useStore
+
+```tsx
+"use client"
+import { useStore } from 'nukejs';
+import { counterStore } from '../stores/counter';
+
+export default function Counter() {
+  const { count } = useStore(counterStore);
+  return (
+    <div>
+      <p>{count}</p>
+      <button onClick={() => counterStore.setState(s => ({ count: s.count + 1 }))}>
+        Increment
+      </button>
+    </div>
+  );
+}
+```
+
+Pass an optional selector to avoid re-renders when unrelated parts of state change:
+
+```tsx
+// Only re-renders when `count` changes, not on any other state update
+const count = useStore(counterStore, s => s.count);
+```
+
+### Sharing state across components
+
+Stores shine when two completely separate client components need to stay in sync. Define the store in its own file (no `"use client"` needed) and import it from both:
+
+```ts
+// app/stores/cart.ts
+import { createStore } from 'nukejs';
+
+export type CartItem = { id: string; name: string; price: number };
+
+export const cartStore = createStore('cart', {
+  items: [] as CartItem[],
+  total: 0,
+});
+```
+
+```tsx
+// app/components/AddToCartButton.tsx
+"use client"
+import { cartStore, type CartItem } from '../stores/cart';
+
+export default function AddToCartButton({ item }: { item: CartItem }) {
+  return (
+    <button onClick={() =>
+      cartStore.setState(s => ({
+        items: [...s.items, item],
+        total: s.total + item.price,
+      }))
+    }>
+      Add to cart
+    </button>
+  );
+}
+```
+
+```tsx
+// app/components/CartIcon.tsx
+"use client"
+import { useStore } from 'nukejs';
+import { cartStore } from '../stores/cart';
+
+export default function CartIcon() {
+  const { items, total } = useStore(cartStore);
+  return (
+    <span>
+      🛒 {items.length} items — ${total.toFixed(2)}
+    </span>
+  );
+}
+```
+
+```tsx
+// app/pages/shop.tsx — server component, no JS cost
+import AddToCartButton from '../components/AddToCartButton';
+import CartIcon from '../components/CartIcon';
+
+export default function ShopPage() {
+  const item = { id: '1', name: 'Widget', price: 9.99 };
+  return (
+    <div>
+      <CartIcon />
+      <AddToCartButton item={item} />
+    </div>
+  );
+}
+```
+
+`CartIcon` updates instantly when the button is clicked — they are separate React roots with separate bundles, but they write and read through the same `'cart'` entry in `window.__nukeStores`.
+
+### setState
+
+Accepts a full replacement value or an updater function:
+
+```ts
+// Replace
+cartStore.setState({ items: [], total: 0 });
+
+// Updater — receives current state, returns next state
+cartStore.setState(s => ({ ...s, total: s.total + 5 }));
+```
+
+### API reference
+
+| | Description |
+|---|---|
+| `createStore(name, initialState)` | Creates or retrieves a named store |
+| `useStore(store)` | Subscribes to the full state |
+| `useStore(store, selector)` | Subscribes to a derived slice (re-renders only when slice changes) |
+| `store.getState()` | Returns the current state snapshot |
+| `store.setState(updater)` | Updates state and notifies all subscribers |
+| `store.subscribe(listener)` | Registers a listener; returns an unsubscribe function |
+
+
 
 Export named HTTP method handlers from `.ts` files in your `server/` directory.
 

package/dist/build-common.js

@@ -149,7 +149,7 @@ function collectServerPages(pagesDir) {
   return walkFiles(pagesDir).filter((relPath) => {
     const stem = path.basename(relPath, path.extname(relPath));
     if (stem === "layout" || stem === "_404" || stem === "_500") return false;
-    return isServerComponent(path.join(pagesDir, relPath));
+    return true;
   }).map((relPath) => ({
     ...analyzeFile(relPath, "page"),
     absPath: path.join(pagesDir, relPath)
@@ -426,7 +426,8 @@ function buildWrapperAttrString(attrs: Record<string, any>): string {
     .map(([key, value]) => {
       if (key === 'className') key = 'class';
       if (key === 'style' && typeof value === 'object') {
-        const css = Object.entries(value as Record<string, any>)
+        // Always prepend display:contents so the wrapper span is invisible to layout.
+        const css = 'display:contents;' + Object.entries(value as Record<string, any>)
           .map(([p, val]) => \`\${p.replace(/[A-Z]/g, m => \`-\${m.toLowerCase()}\`)}:\${escapeHtml(String(val))}\`)
           .join(';');
         return \`style="\${css}"\`;
@@ -436,6 +437,8 @@ function buildWrapperAttrString(attrs: Record<string, any>): string {
       return \`\${key}="\${escapeHtml(String(value))}"\`;
     })
     .filter(Boolean);
+  // When no style prop was passed, still emit display:contents.
+  if (!('style' in attrs)) parts.push('style="display:contents"');
   return parts.length ? ' ' + parts.join(' ') : '';
 }
 

package/dist/builder.js

@@ -49,6 +49,7 @@ const PUBLIC_STEMS = /* @__PURE__ */ new Set([
   "request-store",
   "Link",
   "bundle",
+  "store",
   "utils",
   "logger"
 ]);

package/dist/bundle.js

@@ -10,7 +10,7 @@ function setupLocationChangeMonitor() {
     originalReplaceState(...args);
     dispatch(args[2]);
   };
-  window.addEventListener("popstate", () => dispatch(window.location.pathname));
+  window.addEventListener("popstate", () => dispatch(window.location.pathname + window.location.search));
 }
 function makeLogger(level) {
   return {
@@ -248,7 +248,15 @@ function syncAttrs(live, next) {
     if (!next.hasAttribute(name)) live.removeAttribute(name);
 }
 function setupNavigation(log) {
+  let hmrNavPending = false;
   window.addEventListener("locationchange", async ({ detail: { href, hmr } }) => {
+    if (hmr) {
+      if (hmrNavPending) {
+        log.info("[HMR] Navigation already in flight \u2014 skipping duplicate for", href);
+        return;
+      }
+      hmrNavPending = true;
+    }
     try {
       const fetchUrl = hmr ? href + (href.includes("?") ? "&" : "?") + "__hmr=1" : href;
       const response = await fetch(fetchUrl, { headers: { Accept: "text/html" } });
@@ -279,7 +287,7 @@ function setupNavigation(log) {
       activeRoots.splice(0).forEach((r) => r.unmount());
       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()));
+      const mods = await loadModules(navData.allIds ?? [], log, hmr ? String(Date.now()) : "");
       await mountNodes(mods, log);
       window.scrollTo(0, 0);
       log.info("\u{1F389} Navigation complete:", href);
@@ -287,6 +295,7 @@ function setupNavigation(log) {
       log.error("Navigation error, falling back to full reload:", err);
       window.location.href = href;
     } finally {
+      if (hmr) hmrNavPending = false;
       clientErrorPending = false;
     }
   });

package/dist/hmr-bundle.js

@@ -1,13 +1,25 @@
 import { log } from "./logger.js";
 function hmr() {
   const es = new EventSource("/__hmr");
+  let reconnecting = false;
   es.onopen = () => {
+    reconnecting = false;
     log.info("[HMR] Connected");
   };
   es.onerror = () => {
+    if (reconnecting) return;
+    reconnecting = true;
     es.close();
     waitForReconnect();
   };
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState !== "visible") return;
+    if (es.readyState === EventSource.OPEN) return;
+    if (reconnecting) return;
+    reconnecting = true;
+    es.close();
+    waitForReconnect(500, 20);
+  });
   es.onmessage = async (event) => {
     try {
       const msg = JSON.parse(event.data);
@@ -48,8 +60,18 @@ function hmr() {
     }
   };
 }
+let _navTimer = null;
+let _navHref = null;
 function navigate(href) {
-  window.dispatchEvent(new CustomEvent("locationchange", { detail: { href, hmr: true } }));
+  _navHref = href;
+  if (_navTimer) clearTimeout(_navTimer);
+  _navTimer = setTimeout(() => {
+    _navTimer = null;
+    if (_navHref !== null) {
+      window.dispatchEvent(new CustomEvent("locationchange", { detail: { href: _navHref, hmr: true } }));
+      _navHref = null;
+    }
+  }, 50);
 }
 function patternMatchesPathname(pattern, pathname) {
   const normPattern = pattern.length > 1 ? pattern.replace(/\/+$/, "") : pattern;

package/dist/index.d.ts

@@ -1,10 +1,12 @@
+export { createStore, useStore } from './store';
+export type { Store } from './store';
 export { useHtml } from './use-html';
 export type { HtmlOptions } from './use-html';
 export type { TitleValue, HtmlAttrs, BodyAttrs, MetaTag, LinkTag, ScriptTag, StyleTag, } from './html-store';
 export { default as useRouter } from './use-router';
 export { useRequest } from './use-request';
 export type { RequestContext } from './use-request';
-export { normaliseHeaders, sanitiseHeaders } from './request-store';
+export { normaliseHeaders, sanitiseHeaders, getRequestStore } from './request-store';
 export { default as Link } from './Link';
 export { setupLocationChangeMonitor, initRuntime } from './bundle';
 export type { RuntimeData } from './bundle';

package/dist/index.js

@@ -1,7 +1,8 @@
+import { createStore, useStore } from "./store.js";
 import { useHtml } from "./use-html.js";
 import { default as default2 } from "./use-router.js";
 import { useRequest } from "./use-request.js";
-import { normaliseHeaders, sanitiseHeaders } from "./request-store.js";
+import { normaliseHeaders, sanitiseHeaders, getRequestStore } from "./request-store.js";
 import { default as default3 } from "./Link.js";
 import { setupLocationChangeMonitor, initRuntime } from "./bundle.js";
 import { escapeHtml } from "./utils.js";
@@ -10,8 +11,10 @@ export {
   default3 as Link,
   ansi,
   c,
+  createStore,
   escapeHtml,
   getDebugLevel,
+  getRequestStore,
   initRuntime,
   log,
   normaliseHeaders,
@@ -20,5 +23,6 @@ export {
   setupLocationChangeMonitor,
   useHtml,
   useRequest,
-  default2 as useRouter
+  default2 as useRouter,
+  useStore
 };

package/dist/renderer.js

@@ -20,7 +20,7 @@ function buildWrapperAttrString(attrs) {
   const parts = Object.entries(attrs).map(([key, value]) => {
     if (key === "className") key = "class";
     if (key === "style" && typeof value === "object") {
-      const css = Object.entries(value).map(([k, v]) => {
+      const css = "display:contents;" + Object.entries(value).map(([k, v]) => {
         const prop = k.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
         const safeVal = String(v).replace(/[<>"'`\\]/g, "");
         return `${prop}:${safeVal}`;
@@ -31,6 +31,7 @@ function buildWrapperAttrString(attrs) {
     if (value == null) return "";
     return `${key}="${escapeHtml(String(value))}"`;
   }).filter(Boolean);
+  if (!("style" in attrs)) parts.push('style="display:contents"');
   return parts.length ? " " + parts.join(" ") : "";
 }
 async function renderElementToHtml(element, ctx) {

package/dist/request-store.d.ts

@@ -67,13 +67,9 @@ export declare function normaliseHeaders(raw: Record<string, string | string[] |
 export declare function sanitiseHeaders(raw: Record<string, string | string[] | undefined>): Record<string, string>;
 /**
  * Runs `fn` inside the context of the given request, then clears the store.
- *
- * Usage in the SSR pipeline:
- * ```ts
- * const store = await runWithRequestStore(ctx, async () => {
- *   appHtml = await renderElementToHtml(element, renderCtx);
- * });
- * ```
+ * The store is set synchronously before `fn` is called, so any code that
+ * reads getRequestStore() during the synchronous phase of a server component
+ * (before its first `await`) will always see the correct context.
  */
 export declare function runWithRequestStore<T>(ctx: RequestContext, fn: () => Promise<T>): Promise<T>;
 /**

package/dist/store.d.ts

@@ -0,0 +1,104 @@
+/**
+ * store.ts — NukeJS Client State Management
+ *
+ * Provides a lightweight, cross-boundary state system for "use client"
+ * components.  The core problem it solves: NukeJS hydrates every client
+ * component into its own independent React root (via hydrateRoot / createRoot),
+ * so React Context cannot carry state across component boundaries.  Each
+ * component's esbuild bundle is also a separate module instance, so a plain
+ * module-level variable would not be shared between bundles.
+ *
+ * Solution: all store state lives in `window.__nukeStores`, a Map that persists
+ * for the lifetime of the page regardless of how many times the store module
+ * is evaluated.  Every bundle that imports `createStore('counter', …)` gets
+ * a thin proxy object that reads from and writes to the same backing entry —
+ * state is automatically shared across roots and bundles.
+ *
+ * API:
+ *
+ *   const cartStore = createStore('cart', { items: [], total: 0 });
+ *
+ *   // Inside any "use client" component on the same page:
+ *   const items = useStore(cartStore, s => s.items);
+ *   cartStore.setState(s => ({ ...s, items: [...s.items, newItem] }));
+ *
+ * The store is safe to import in server components — it detects the absence of
+ * `window` and returns a lightweight no-op stub so SSR never throws.
+ */
+type Listener = () => void;
+type Unsubscribe = () => void;
+type Updater<T> = T | ((prev: T) => T);
+/**
+ * A NukeJS store handle.  Create it once at module scope; pass it into
+ * `useStore()` inside any client component to subscribe.
+ */
+export interface Store<T extends object> {
+    /** Returns the current state snapshot. */
+    getState(): T;
+    /**
+     * Updates the state and notifies every subscriber.
+     *
+     * Accepts a full replacement value or an updater function:
+     *   store.setState({ count: 0 })
+     *   store.setState(s => ({ ...s, count: s.count + 1 }))
+     */
+    setState(updater: Updater<T>): void;
+    /**
+     * Registers a change listener.  Returns an unsubscribe function.
+     * Compatible with `useSyncExternalStore`.
+     */
+    subscribe(listener: Listener): Unsubscribe;
+    /** The name this store is registered under in the global registry. */
+    readonly name: string;
+    /**
+     * The value passed to `createStore` as its second argument.
+     * Used internally as the server snapshot so `useSyncExternalStore` always
+     * reconciles against a value that matches the server-rendered HTML —
+     * the server never has mutations, so initial state is always what it renders.
+     */
+    readonly initialState: T;
+}
+interface StoreEntry<T> {
+    state: T;
+    listeners: Set<Listener>;
+}
+declare global {
+    interface Window {
+        __nukeStores?: Map<string, StoreEntry<any>>;
+    }
+}
+/**
+ * Creates (or retrieves) a named store backed by the page-global registry.
+ *
+ * If a store with the given `name` already exists in the registry (e.g.
+ * because another bundle called `createStore` first), the existing entry is
+ * reused and `initialState` is ignored.  This means the first bundle to run
+ * wins the initial value — define your stores in a single shared file, or
+ * treat `initialState` as a consistent default across all bundles.
+ *
+ * @param name          A unique string key for this store.
+ * @param initialState  Default state used when the store is first created.
+ */
+export declare function createStore<T extends object>(name: string, initialState: T): Store<T>;
+/**
+ * React hook that subscribes a component to a store.
+ *
+ * An optional `selector` lets you derive a slice of state.  The component
+ * only re-renders when the selected value changes (by reference equality),
+ * not on every store mutation.
+ *
+ * Works across independent React roots — any component on the page that calls
+ * `useStore` with the same store will re-render when that store changes,
+ * regardless of which component boundary each lives in.
+ *
+ * @example
+ * // Full state
+ * const state = useStore(cartStore);
+ *
+ * @example
+ * // Selected slice — re-renders only when `items` changes
+ * const items = useStore(cartStore, s => s.items);
+ */
+export declare function useStore<T extends object>(store: Store<T>): T;
+export declare function useStore<T extends object, U>(store: Store<T>, selector: (state: T) => U): U;
+export {};

package/dist/store.js

@@ -0,0 +1,45 @@
+import { useSyncExternalStore } from "react";
+function getRegistry() {
+  if (typeof window === "undefined") {
+    return /* @__PURE__ */ new Map();
+  }
+  if (!window.__nukeStores) {
+    window.__nukeStores = /* @__PURE__ */ new Map();
+  }
+  return window.__nukeStores;
+}
+function createStore(name, initialState) {
+  const registry = getRegistry();
+  if (!registry.has(name)) {
+    registry.set(name, {
+      state: initialState,
+      listeners: /* @__PURE__ */ new Set()
+    });
+  }
+  const entry = registry.get(name);
+  const subscribe = (listener) => {
+    entry.listeners.add(listener);
+    return () => {
+      entry.listeners.delete(listener);
+    };
+  };
+  const getState = () => entry.state;
+  const setState = (updater) => {
+    entry.state = typeof updater === "function" ? updater(entry.state) : updater;
+    for (const l of Array.from(entry.listeners)) l();
+  };
+  return { name, initialState, getState, setState, subscribe };
+}
+function useStore(store, selector) {
+  const getSnapshot = selector ? () => selector(store.getState()) : () => store.getState();
+  const getServerSnapshot = selector ? () => selector(store.initialState) : () => store.initialState;
+  return useSyncExternalStore(
+    store.subscribe,
+    getSnapshot,
+    getServerSnapshot
+  );
+}
+export {
+  createStore,
+  useStore
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nukejs",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "A minimal, opinionated full-stack React framework on Node.js that server-renders everything and hydrates only interactive parts.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",