nukejs 0.0.5 → 0.0.6

package/README.md

@@ -1,9 +1,11 @@
-# ☢️ NukeJS
+[![NukeJS Banner](.github/banner.png)](https://nukejs.com)
+
+# NukeJS
 
 A **minimal**, opinionated full-stack React framework on Node.js that server-renders everything and hydrates only interactive parts.
 
 ```
-npm create nuke
+npm create nuke@latest
 ```
 
 ## Table of Contents
@@ -129,8 +131,9 @@ Each `.tsx` file in `app/pages/` maps to a URL route:
 | `about.tsx` | `/about` |
 | `blog/index.tsx` | `/blog` |
 | `blog/[slug].tsx` | `/blog/:slug` |
-| `docs/[...path].tsx` | `/docs/*` (catch-all) |
-| `files/[[...path]].tsx` | `/files` or `/files/*` (optional) |
+| `docs/[...path].tsx` | `/docs/*` (catch-all, required) |
+| `users/[[id]].tsx` | `/users` or `/users/42` (optional single segment) |
+| `files/[[...path]].tsx` | `/files` or `/files/*` (optional catch-all) |
 
 ### Page component
 
@@ -168,9 +171,12 @@ When multiple routes could match a URL, the most specific one wins:
 ```
 /users/profile  → users/profile.tsx   (static, wins)
 /users/42       → users/[id].tsx      (dynamic)
+/users          → users/[[id]].tsx    (optional single, matches with no id)
 /users/a/b/c    → users/[...rest].tsx (catch-all)
 ```
 
+Specificity order, highest to lowest: static → `[param]` → `[[param]]` → `[...catchAll]` → `[[...optionalCatchAll]]`.
+
 ---
 
 ## Layouts
@@ -526,4 +532,4 @@ Just import the code from GitHub.
 
 ## License
 
-MIT
+MIT

package/dist/as-is/Link.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+const Link = ({ href, children, className }) => {
+  const handleClick = (e) => {
+    e.preventDefault();
+    window.history.pushState({}, "", href);
+  };
+  return /* @__PURE__ */ jsx("a", { href, onClick: handleClick, className, children });
+};
+var Link_default = Link;
+export {
+  Link_default as default
+};
+//# sourceMappingURL=Link.js.map

package/dist/as-is/Link.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/as-is/Link.tsx"],
+  "sourcesContent": ["\"use client\"\r\n\r\nconst Link = ({ href, children, className }: {\r\n    href: string;\r\n    children: React.ReactNode;\r\n    className?: string;\r\n}) => {\r\n    const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {\r\n        e.preventDefault();\r\n        window.history.pushState({}, '', href);\r\n    };\r\n\r\n    return (\r\n        <a href={href} onClick={handleClick} className={className}>\r\n            {children}\r\n        </a>\r\n    );\r\n};\r\n\r\nexport default Link;\r\n"],
+  "mappings": ";AAaQ;AAXR,MAAM,OAAO,CAAC,EAAE,MAAM,UAAU,UAAU,MAIpC;AACF,QAAM,cAAc,CAAC,MAA2C;AAC5D,MAAE,eAAe;AACjB,WAAO,QAAQ,UAAU,CAAC,GAAG,IAAI,IAAI;AAAA,EACzC;AAEA,SACI,oBAAC,OAAE,MAAY,SAAS,aAAa,WAChC,UACL;AAER;AAEA,IAAO,eAAQ;",
+  "names": []
+}

package/dist/as-is/useRouter.js

@@ -0,0 +1,28 @@
+import { useCallback, useEffect, useState } from "react";
+function useRouter() {
+  try {
+    const [path, setPath] = useState(() => window.location.pathname);
+    useEffect(() => {
+      const handleLocationChange = () => setPath(window.location.pathname);
+      window.addEventListener("locationchange", handleLocationChange);
+      return () => window.removeEventListener("locationchange", handleLocationChange);
+    }, []);
+    const push = useCallback((url) => {
+      window.history.pushState({}, "", url);
+      setPath(url);
+    }, []);
+    const replace = useCallback((url) => {
+      window.history.replaceState({}, "", url);
+      setPath(url);
+    }, []);
+    return { path, push, replace };
+  } catch {
+    return { push: () => {
+    }, replace: () => {
+    }, path: "" };
+  }
+}
+export {
+  useRouter as default
+};
+//# sourceMappingURL=useRouter.js.map

package/dist/as-is/useRouter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/as-is/useRouter.ts"],
+  "sourcesContent": ["import { useCallback, useEffect, useState } from \"react\";\r\n\r\ntype Router = {\r\n    path: string;\r\n    push: (url: string) => void;\r\n    replace: (url: string) => void;\r\n};\r\n\r\nexport default function useRouter(): Router {\r\n    try {\r\n        const [path, setPath] = useState(() => window.location.pathname);\r\n\r\n        useEffect(() => {\r\n            const handleLocationChange = () => setPath(window.location.pathname);\r\n            window.addEventListener(\"locationchange\", handleLocationChange);\r\n            return () => window.removeEventListener(\"locationchange\", handleLocationChange);\r\n        }, []);\r\n\r\n        const push = useCallback((url: string) => {\r\n            window.history.pushState({}, \"\", url);\r\n            setPath(url);\r\n        }, []);\r\n\r\n        const replace = useCallback((url: string) => {\r\n            window.history.replaceState({}, \"\", url);\r\n            setPath(url);\r\n        }, []);\r\n\r\n        return { path, push, replace };\r\n    } catch {\r\n        return { push: () => {}, replace: () => {}, path: \"\" };\r\n    }\r\n}\r\n"],
+  "mappings": "AAAA,SAAS,aAAa,WAAW,gBAAgB;AAQlC,SAAR,YAAqC;AACxC,MAAI;AACA,UAAM,CAAC,MAAM,OAAO,IAAI,SAAS,MAAM,OAAO,SAAS,QAAQ;AAE/D,cAAU,MAAM;AACZ,YAAM,uBAAuB,MAAM,QAAQ,OAAO,SAAS,QAAQ;AACnE,aAAO,iBAAiB,kBAAkB,oBAAoB;AAC9D,aAAO,MAAM,OAAO,oBAAoB,kBAAkB,oBAAoB;AAAA,IAClF,GAAG,CAAC,CAAC;AAEL,UAAM,OAAO,YAAY,CAAC,QAAgB;AACtC,aAAO,QAAQ,UAAU,CAAC,GAAG,IAAI,GAAG;AACpC,cAAQ,GAAG;AAAA,IACf,GAAG,CAAC,CAAC;AAEL,UAAM,UAAU,YAAY,CAAC,QAAgB;AACzC,aAAO,QAAQ,aAAa,CAAC,GAAG,IAAI,GAAG;AACvC,cAAQ,GAAG;AAAA,IACf,GAAG,CAAC,CAAC;AAEL,WAAO,EAAE,MAAM,MAAM,QAAQ;AAAA,EACjC,QAAQ;AACJ,WAAO,EAAE,MAAM,MAAM;AAAA,IAAC,GAAG,SAAS,MAAM;AAAA,IAAC,GAAG,MAAM,GAAG;AAAA,EACzD;AACJ;",
+  "names": []
+}

package/dist/build-common.d.ts

@@ -1,41 +1,59 @@
 /**
- * build-common.ts
+ * build-common.ts — Shared Build Logic
  *
- * Shared build logic used by both build-vercel.ts and build-node.ts.
+ * Used by both build-node.ts and build-vercel.ts.
  *
  * Exports:
- *   — utility helpers   : walkFiles, analyzeFile, isServerComponent,
- *                         findPageLayouts, extractDefaultExportName
- *   — collection        : collectServerPages, collectGlobalClientRegistry
- *   — template codegen  : makeApiAdapterSource, makePageAdapterSource
- *   — bundle operations : bundleApiHandler, bundlePageHandler,
- *                         bundleClientComponents, buildCombinedBundle
+ *   — types            : AnalyzedRoute, ServerPage, BuiltPage,
+ *                        PageAdapterOptions, PageBundleOptions
+ *   — utility helpers  : walkFiles, analyzeFile, isServerComponent,
+ *                        findPageLayouts, extractDefaultExportName
+ *   — collection       : collectServerPages, collectGlobalClientRegistry,
+ *                        buildPerPageRegistry
+ *   — template codegen : makeApiAdapterSource, makePageAdapterSource
+ *   — bundle ops       : bundleApiHandler, bundlePageHandler,
+ *                        bundleClientComponents, buildPages,
+ *                        buildCombinedBundle, copyPublicFiles
  */
 export interface AnalyzedRoute {
+    /** Regex string matching the URL path, e.g. '^/users/([^/]+)$' */
     srcRegex: string;
+    /** Names of captured groups in srcRegex order */
     paramNames: string[];
-    /** Path used as function namespace, e.g. '/api/users' or '/page/about'. */
+    /**
+     * Subset of paramNames that are catch-all ([...slug] or [[...path]]).
+     * Their runtime values are string[] not string.
+     */
+    catchAllNames: string[];
+    /** Function namespace path, e.g. '/api/users' or '/page/about' */
     funcPath: string;
     specificity: number;
 }
 export interface ServerPage extends AnalyzedRoute {
     absPath: string;
 }
-/** A server page together with its fully bundled ESM text, ready to emit. */
 export interface BuiltPage extends ServerPage {
     bundleText: string;
 }
 export declare function walkFiles(dir: string, base?: string): string[];
 /**
  * Parses dynamic-route segments from a relative file path and returns a regex,
- * captured param names, a function path, and a specificity score.
+ * captured param names, catch-all param names, a function path, and a
+ * specificity score.
+ *
+ * Supported patterns per segment:
+ *   [[...name]]  optional catch-all  → regex (.*)      → string[]
+ *   [...name]    required catch-all  → regex (.+)      → string[]
+ *   [[name]]     optional single     → regex ([^/]*)?  → string
+ *   [name]       required single     → regex ([^/]+)   → string
+ *   literal      static              → escaped literal
  *
  * @param relPath  Relative path from the dir root (e.g. 'users/[id].tsx').
  * @param prefix   Namespace for funcPath ('api' | 'page').
  */
 export declare function analyzeFile(relPath: string, prefix?: string): AnalyzedRoute;
 /**
- * Returns true when a file does NOT begin with a "use client" directive —
+ * Returns true when a file does NOT begin with a "use client" directive,
  * i.e. it is a server component.
  */
 export declare function isServerComponent(filePath: string): boolean;
@@ -50,23 +68,20 @@ export declare function findPageLayouts(routeFilePath: string, pagesDir: string)
  */
 export declare function extractDefaultExportName(filePath: string): string | null;
 /**
- * Returns all server-component pages inside `pagesDir`, sorted by specificity
- * (most-specific first so more-precise routes shadow catch-alls in routers).
+ * Returns all server-component pages inside `pagesDir`, sorted most-specific
+ * first so precise routes shadow catch-alls in routers.
  * layout.tsx files and "use client" files are excluded.
  */
 export declare function collectServerPages(pagesDir: string): ServerPage[];
 /**
  * Walks every server page and its layout chain to collect all client component
- * IDs reachable anywhere in the app.  Deduplication is automatic because the
- * Map key is the stable content-hash ID produced by component-analyzer.ts.
+ * IDs reachable anywhere in the app.
  */
 export declare function collectGlobalClientRegistry(serverPages: ServerPage[], pagesDir: string): Map<string, string>;
 /**
- * Builds the per-page client component registry (page + its layout chain) and
- * returns both the id→path map and the name→id map needed by bundlePageHandler.
- *
- * Extracted here to eliminate the identical loop duplicated across
- * build-node.ts and build-vercel.ts.
+ * Builds the per-page client component registry (page + its layout chain)
+ * and returns both the id→path map and the name→id map needed by
+ * bundlePageHandler.
  */
 export declare function buildPerPageRegistry(absPath: string, layoutPaths: string[], pagesDir: string): {
     registry: Map<string, string>;
@@ -79,19 +94,11 @@ export declare function buildPerPageRegistry(absPath: string, layoutPaths: strin
  *             and collects pre-rendered HTML for each.
  *   Pass 2 — bundles every server-component page into a self-contained ESM
  *             handler and returns the results as `BuiltPage[]`.
- *
- * Callers (build-node, build-vercel) only need to write the bundled text to
- * their respective output destinations — the format-specific logic stays local.
- *
- * Returns an empty array when there are no server pages.
  */
 export declare function buildPages(pagesDir: string, staticDir: string): Promise<BuiltPage[]>;
 /**
  * Returns the TypeScript source for a thin HTTP adapter that wraps an API
  * route module and exposes a single `handler(req, res)` default export.
- *
- * @param handlerFilename  Basename of the handler file relative to the adapter
- *                         (e.g. 'users.ts').  Must be in the same directory.
  */
 export declare function makeApiAdapterSource(handlerFilename: string): string;
 export interface PageAdapterOptions {
@@ -107,27 +114,24 @@ export interface PageAdapterOptions {
     layoutArrayItems: string;
     /** Pre-rendered HTML per client component ID, computed at build time */
     prerenderedHtml: Record<string, string>;
+    /** Catch-all param names whose runtime values are string[] not string */
+    catchAllNames: string[];
 }
 /**
  * Returns the TypeScript source for a fully self-contained page handler.
  *
  * The adapter:
  *   • Inlines the html-store so useHtml() works without external deps.
- *   • Contains an async recursive renderer that handles server + client
- *     components without react-dom/server.
+ *   • Contains an async recursive renderer for server + client components.
  *   • Client components are identified via the pre-computed CLIENT_COMPONENTS
- *     map (no fs.readFileSync at runtime).
- *   • Emits the same full HTML document structure as ssr.ts including the
- *     __n_data blob, importmap, and initRuntime bootstrap.
+ *     map — no fs.readFileSync at runtime.
+ *   • Emits the full HTML document including the __n_data blob and bootstrap.
  */
 export declare function makePageAdapterSource(opts: PageAdapterOptions): string;
 /**
  * Bundles an API route handler into a single self-contained ESM string.
- *
- * Writes a temporary adapter next to `absPath`, bundles them together with
- * esbuild (node_modules kept external), then removes the temp file.
- *
- * @returns The bundled ESM text ready to write to disk.
+ * node_modules are kept external — they exist at runtime on both Node and
+ * Vercel (Vercel bundles them separately via the pages dispatcher).
  */
 export declare function bundleApiHandler(absPath: string): Promise<string>;
 export interface PageBundleOptions {
@@ -137,59 +141,26 @@ export interface PageBundleOptions {
     allClientIds: string[];
     layoutPaths: string[];
     prerenderedHtml: Record<string, string>;
+    catchAllNames: string[];
 }
 /**
  * Bundles a server-component page into a single self-contained ESM string.
- *
- * Writes a temporary adapter next to `absPath` (so relative imports inside
- * the component resolve from the correct base directory), bundles it with
- * esbuild (React and all npm deps inlined, only Node built-ins stay external),
- * then removes the temp file.
- *
- * @returns The bundled ESM text ready to write to disk.
+ * All npm packages are kept external — the Node production server has
+ * node_modules available at runtime.
  */
 export declare function bundlePageHandler(opts: PageBundleOptions): Promise<string>;
 /**
  * Bundles every client component in `globalRegistry` to
- * `<staticDir>/__client-component/<id>.js`.
- *
- * Mirrors bundleClientComponent() in bundler.ts:
- *   • browser ESM, JSX automatic
- *   • react / react-dom/client / react/jsx-runtime kept external so the
- *     importmap can resolve them to the already-loaded /__react.js bundle.
+ * `<staticDir>/__client-component/<id>.js` and pre-renders each to HTML.
  */
 export declare function bundleClientComponents(globalRegistry: Map<string, string>, pagesDir: string, staticDir: string): Promise<Map<string, string>>;
 /**
- * Builds a single combined browser bundle to `<staticDir>/__n.js`.
- *
- * Inlines the full React + ReactDOM runtime together with the NukeJS client
- * runtime (bundle.ts) so the browser only needs one file instead of two.
- * The importmap in every page points 'react', 'react-dom/client',
- * 'react/jsx-runtime', and 'nukejs' all to /__n.js, so dynamic imports
- * inside the runtime (e.g. `await import('react')`) hit the module cache
- * and return the same singleton that was already loaded.
- *
- * Dev mode (bundler.ts) keeps separate /__react.js and /__n.js files for
- * easier debugging — this function is production-only.
+ * Builds the combined browser bundle (__n.js) that contains the full React
+ * runtime + NukeJS client runtime in a single file.
  */
 export declare function buildCombinedBundle(staticDir: string): Promise<void>;
 /**
- * Recursively copies every file from `app/public/` into `destDir`,
- * preserving the directory structure.
- *
- * Called by both build-vercel.ts (dest = .vercel/output/static/) and
- * build-node.ts (dest = dist/static/) so that:
- *
- *   app/public/favicon.ico        → <destDir>/favicon.ico
- *   app/public/images/logo.png    → <destDir>/images/logo.png
- *
- * On Vercel, the Build Output API v3 serves everything in .vercel/output/static/
- * directly — no route entry needed, same as __react.js and __n.js.
- *
- * On Node, the serverEntry template serves files from dist/static/ with the
- * same MIME-type logic as the dev middleware.
- *
- * Skips silently when the public directory does not exist so projects without
- * one don't need any special configuration.
+ * Recursively copies every file from `publicDir` into `destDir`, preserving
+ * the directory structure.  Skips silently when `publicDir` does not exist.
  */
 export declare function copyPublicFiles(publicDir: string, destDir: string): void;