@punkestu/react-html 0.0.0-stage → 0.1.0

package/.react-html/cache/page-fefe905ae5d2.mjs

@@ -0,0 +1,9 @@
+// .server-test-fixture/src/pages/index.tsx
+import { jsx } from "react/jsx-runtime";
+function Home() {
+  return /* @__PURE__ */ jsx("h1", { children: "UPDATED LIVE IN DEV" });
+}
+export {
+  Home as default
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLnNlcnZlci10ZXN0LWZpeHR1cmUvc3JjL3BhZ2VzL2luZGV4LnRzeCJdLAogICJzb3VyY2VzQ29udGVudCI6IFsiXG4gICAgICAgIGltcG9ydCBSZWFjdCBmcm9tICdyZWFjdCc7XG4gICAgICAgIGV4cG9ydCBkZWZhdWx0IGZ1bmN0aW9uIEhvbWUoKSB7XG4gICAgICAgICAgcmV0dXJuIDxoMT5VUERBVEVEIExJVkUgSU4gREVWPC9oMT47XG4gICAgICAgIH1cbiAgICAgICAgIl0sCiAgIm1hcHBpbmdzIjogIjtBQUdpQjtBQURNLFNBQVIsT0FBd0I7QUFDN0IsU0FBTyxvQkFBQyxRQUFHLGlDQUFtQjtBQUNoQzsiLAogICJuYW1lcyI6IFtdCn0K

package/DOCS.md

@@ -0,0 +1,317 @@
+# 📖 react-html Complete Manual & Documentation
+
+A high-performance static engine to compile React/JSX to **pure, semantic HTML** with selective reactive compilation for interactive components via an **Islands Architecture**.
+
+> 💡 **Terminal UI Access**: You can also browse this documentation interactively in your terminal by running:
+> ```bash
+> npx react-html docs
+> # Or print a specific section:
+> npx react-html docs islands
+> ```
+
+---
+
+## Table of Contents
+
+1. [Overview & Philosophy](#1-overview--philosophy)
+2. [Getting Started & Setup](#2-getting-started--setup)
+3. [Modular HTML with React](#3-modular-html-with-react)
+4. [Reactive Islands Architecture](#4-reactive-islands-architecture)
+5. [Hydration Directives](#5-hydration-directives)
+6. [CLI Commands & Options](#6-cli-commands--options)
+7. [Programmatic API Reference](#7-programmatic-api-reference)
+8. [Server App Integration (Express, Fastify, Node HTTP)](#8-server-app-integration-express-fastify-node-http)
+9. [Best Practices & Troubleshooting](#9-best-practices--troubleshooting)
+
+---
+
+## 1. Overview & Philosophy
+
+Modern web development often forces a painful choice:
+- **Write raw HTML/handlebars/nunjucks**: You lose type safety, component modularity, and rich JSX composition.
+- **Use modern React frameworks (Next.js, CRA, Remix)**: You inadvertently ship massive megabytes of JavaScript, client routers, and heavy hydration runtimes even for mostly static pages.
+
+**`react-html` gives you the best of both worlds**:
+1. **Zero JavaScript by Default**:
+   Pages without interactive islands output 100% pure, clean HTML5. No client-side React runtime, no `data-reactroot` attributes, and 0 KB JavaScript sent to visitors.
+2. **Modular & DRY Components**:
+   Compose your pages with `<Layout>`, `<Header>`, `<Card>`, `<Footer>`, loops, and conditionals using standard React and TypeScript.
+3. **Selective Reactivity**:
+   Interactive components (counters, carousels, modals, filters) are marked as **Islands**. The engine pre-renders their initial markup for instant paint and bundles only that component into a standalone client script using `esbuild`.
+
+---
+
+## 2. Getting Started & Setup
+
+### Prerequisites
+- Standard **Node.js v20.0.0 or higher** with `npm` (no Bun dependencies).
+
+### Installation
+```bash
+npm install react-html
+```
+
+Or clone and link locally:
+```bash
+git clone https://github.com/microapes/react-html.git
+cd react-html
+npm install
+npm run build
+npm link
+```
+
+### Recommended Directory Structure
+
+```text
+my-project/
+├── package.json
+├── public/                     # Static files copied to dist/ verbatim
+│   ├── favicon.ico
+│   └── styles.css
+└── src/
+    ├── components/             # Reusable modular UI components
+    │   ├── Layout.tsx          # Master HTML wrapper (<head>, <body>)
+    │   ├── Header.tsx          # Navigation header
+    │   ├── Footer.tsx          # Footer component
+    │   └── Counter.island.tsx  # Interactive island component
+    └── pages/                  # Page entrypoints
+        ├── index.tsx           # -> dist/index.html
+        ├── about.tsx           # -> dist/about.html
+        └── docs/
+            └── guide.tsx       # -> dist/docs/guide.html
+```
+
+---
+
+## 3. Modular HTML with React
+
+Eliminate repetitive HTML across your project by creating reusable layout components:
+
+```tsx
+// src/components/Layout.tsx
+import React, { ReactNode } from 'react';
+import { Header } from './Header.js';
+import { Footer } from './Footer.js';
+
+export interface LayoutProps {
+  title?: string;
+  description?: string;
+  children: ReactNode;
+}
+
+export function Layout({
+  title = 'Default Title',
+  description = 'My static site',
+  children
+}: LayoutProps) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>{title}</title>
+        <meta name="description" content={description} />
+        <link rel="stylesheet" href="/styles.css" />
+      </head>
+      <body>
+        <Header />
+        <main className="container">{children}</main>
+        <Footer />
+      </body>
+    </html>
+  );
+}
+```
+
+Now, every page simply wraps its content without repeating `<head>`, stylesheets, or `<header>`/`<footer>`:
+
+```tsx
+// src/pages/about.tsx
+import React from 'react';
+import { Layout } from '../components/Layout.js';
+
+export const title = 'About Us';
+
+export default function AboutPage() {
+  return (
+    <Layout title={title}>
+      <h1>About Our Project</h1>
+      <p>This entire page compiles into pure static HTML with 0 KB JavaScript!</p>
+    </Layout>
+  );
+}
+```
+
+---
+
+## 4. Reactive Islands Architecture
+
+When a component needs client-side state (`useState`, `useEffect`, event listeners):
+
+### Step 1: Wrap Component with `island()`
+
+```tsx
+// src/components/Counter.island.tsx
+import React, { useState } from 'react';
+import { island } from 'react-html';
+
+export interface CounterProps {
+  initialCount?: number;
+  step?: number;
+}
+
+function CounterComponent({ initialCount = 0, step = 1 }: CounterProps) {
+  const [count, setCount] = useState(initialCount);
+
+  return (
+    <div className="counter">
+      <p>Current: {count}</p>
+      <button onClick={() => setCount(c => c - step)}>- {step}</button>
+      <button onClick={() => setCount(c => c + step)}>+ {step}</button>
+    </div>
+  );
+}
+
+// Wrap with island helper providing Component, source path, and identifier
+export const Counter = island(CounterComponent, import.meta.url, 'Counter');
+export default Counter;
+```
+
+### Step 2: Use in Any Page
+
+```tsx
+// src/pages/index.tsx
+import React from 'react';
+import { Layout } from '../components/Layout.js';
+import { Counter } from '../components/Counter.island.js';
+
+export default function HomePage() {
+  return (
+    <Layout title="Home">
+      <h1>Interactive Page</h1>
+      {/* Pre-rendered to HTML for instant paint, then hydrated with tiny JS */}
+      <Counter initialCount={10} step={2} />
+    </Layout>
+  );
+}
+```
+
+### What Happens Behind the Scenes:
+1. **Server Phase**: The island is pre-rendered with `renderToString` and placed inside a container `<div data-island="Counter" data-props="...">`.
+2. **Bundler Phase**: `esbuild` extracts and bundles only `CounterComponent` into `dist/assets/islands/Counter.js`.
+3. **Injection Phase**: `<script type="module" src="/assets/islands/Counter.js"></script>` is injected right before `</body>`.
+4. **Client Hydration**: The script queries `[data-island="Counter"]` and attaches listeners using React 19's `hydrateRoot`.
+
+---
+
+## 5. Hydration Directives
+
+Fine-tune client performance using the `client` prop:
+
+| Directive | Code Example | When It Hydrates |
+| :--- | :--- | :--- |
+| `load` *(default)* | `<Counter client="load" />` | Immediately upon `DOMContentLoaded`. Ideal for primary UI. |
+| `idle` | `<Counter client="idle" />` | During browser idle time via `requestIdleCallback`. Ideal for background widgets. |
+| `visible` | `<Counter client="visible" />` | When scrolled into view via `IntersectionObserver`. Ideal for below-the-fold content. |
+
+---
+
+## 6. CLI Commands & Options
+
+```bash
+# Build static site to dist/
+react-html build
+
+# Customize directories
+react-html build --pages src/pages --out dist --root .
+
+# Start local preview server with auto-rebuild on file changes
+react-html dev --port 3000 --host localhost
+
+# Terminal UI documentation viewer
+react-html docs
+react-html docs --all
+react-html docs islands
+```
+
+---
+
+## 7. Programmatic API Reference
+
+You can import and trigger `react-html` within custom build scripts or Node.js services:
+
+```ts
+import { build, renderPageToHtml, createDevServer } from 'react-html';
+
+// 1. Run static build
+const result = await build({
+  root: process.cwd(),
+  pagesDir: 'src/pages',
+  outDir: 'dist',
+  minify: true
+});
+console.log(`Generated ${result.pages.length} pages.`);
+
+// 2. Programmatic dev server
+const server = await createDevServer({
+  port: 8080,
+  host: '127.0.0.1'
+});
+```
+
+---
+
+## 8. Server App Integration (Express, Fastify, Node HTTP)
+
+You can import and use `react-html` directly inside your backend server application:
+
+```ts
+import express from 'express';
+import { createEngine } from 'react-html';
+// or: import { createEngine } from 'react-html/server';
+
+const app = express();
+
+const engine = createEngine({
+  pagesDir: 'src/pages',
+  distDir: 'dist',
+  // Automatically detects process.env.NODE_ENV === 'production'
+});
+
+// 1. Connect / Express Middleware
+// In Production: finds and serves pre-built static HTML from dist/
+// In Development: dynamically rebuilds TSX on the fly and returns the fresh HTML string!
+app.use(engine.middleware);
+
+// 2. Programmatic Route Rendering
+app.get('/dashboard', async (req, res) => {
+  const html = await engine.render('dashboard', { user: req.user });
+  res.setHeader('Content-Type', 'text/html; charset=utf-8');
+  res.send(html);
+});
+
+// 3. Native Node HTTP Server
+import http from 'node:http';
+const server = http.createServer(engine.handle);
+server.listen(3000);
+```
+
+### Environment Behavior:
+- **`process.env.NODE_ENV === 'production'`**:
+  - Automatically searches for pre-built `.html` files in `distDir` (`dist/index.html`, `dist/about.html`).
+  - Streams them immediately to clients with 0 rebuild overhead.
+  - Serves static assets (`dist/assets/islands/*.js`, `dist/styles.css`).
+- **`process.env.NODE_ENV !== 'production'` (Development)**:
+  - Dynamically rebuilds the corresponding `.tsx` page on each request.
+  - Bundles any reactive islands on-the-fly.
+  - Returns the fresh HTML string directly in the response—code edits in `src/pages` or `src/components` are reflected instantly on reload without server restarts!
+
+---
+
+## 9. Best Practices & Troubleshooting
+
+### Preventing Hydration Mismatches (React Error #418)
+- **Do not read browser globals during initial render**: Avoid `window.innerWidth` or `localStorage.getItem()` directly in the component body. Read them inside a `useEffect()`.
+- **Props consistency**: Ensure initial props passed from the page match what the component expects.
+- **Protected formatting**: `react-html` automatically preserves the exact inner markup of islands so whitespace insertion does not invalidate React's DOM reconciliation.
+

package/README.md

@@ -1,3 +1,216 @@
-# Temporary Holding Version
+# react-html ⚛️ ➡️ 📄
+
+A blazing-fast engine to convert React/JSX components into **pure, semantic HTML** with selective compilation of interactive components into **micro JavaScript islands**.
+
+Write DRY, modular HTML using React components without shipping any React runtime or JavaScript to the client by default.
+
+---
+
+## 🌟 Why react-html?
+
+- **Zero-JS by Default**: Static pages are rendered to 100% pure HTML. No client-side React runtime, no `<script>` tags, and 0 KB JavaScript overhead.
+- **Modular & DRY**: Stop duplicating headers, footers, meta tags, and layouts. Build reusable components (`<Layout>`, `<Header>`, `<Card>`, `<Footer>`) using familiar React JSX syntax.
+- **Selective Reactivity (Islands Architecture)**: When a component needs client-side interactivity (counters, modals, tabs, forms), the engine bundles only that component into a standalone, micro ESM script using `esbuild`.
+- **Fast Build Pipeline**: Powered by `esbuild` for instantaneous static site generation and sub-100ms builds.
+- **Node.js Native**: Runs strictly on standard Node.js (v20+) with npm.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install react-html
+```
+
+Or install globally / link locally:
+
+```bash
+npm link
+```
+
+### CLI Usage
+
+```bash
+# Build static site to dist/
+react-html build
+
+# Build with custom pages or output directory
+react-html build --pages src/pages --out dist
+
+# Start dev server with watch & live recompile
+react-html dev --port 3000
+```
+
+---
+
+## 📖 How It Works
+
+### 1. Pure Modular HTML (Zero JavaScript)
+
+Create your reusable layout and page components using standard JSX:
+
+```tsx
+// src/components/Layout.tsx
+import React, { ReactNode } from 'react';
+
+export function Layout({ title, children }: { title: string; children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>{title}</title>
+        <link rel="stylesheet" href="/styles.css" />
+      </head>
+      <body>
+        <header>
+          <h1>My Modular Site</h1>
+        </header>
+        <main>{children}</main>
+      </body>
+    </html>
+  );
+}
+```
+
+```tsx
+// src/pages/about.tsx
+import React from 'react';
+import { Layout } from '../components/Layout.js';
+
+export default function AboutPage() {
+  return (
+    <Layout title="About Us">
+      <h2>About Our Project</h2>
+      <p>This entire page compiles into pure static HTML with 0 KB JavaScript!</p>
+    </Layout>
+  );
+}
+```
+
+**Output in `dist/about.html`:**
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charSet="UTF-8"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+    <title>About Us</title>
+    <link rel="stylesheet" href="/styles.css"/>
+  </head>
+  <body>
+    <header>
+      <h1>My Modular Site</h1>
+    </header>
+    <main>
+      <h2>About Our Project</h2>
+      <p>This entire page compiles into pure static HTML with 0 KB JavaScript!</p>
+    </main>
+  </body>
+</html>
+```
+
+---
+
+### 2. Reactive Components (Islands Architecture)
+
+When a component needs client-side state and interactivity, wrap it with `island()`:
+
+```tsx
+// src/components/Counter.island.tsx
+import React, { useState } from 'react';
+import { island } from 'react-html';
+
+export interface CounterProps {
+  initial?: number;
+}
+
+function CounterComponent({ initial = 0 }: CounterProps) {
+  const [count, setCount] = useState(initial);
+
+  return (
+    <div className="counter">
+      <button onClick={() => setCount(c => c - 1)}>-</button>
+      <span>Count: {count}</span>
+      <button onClick={() => setCount(c => c + 1)}>+</button>
+    </div>
+  );
+}
+
+// Export the island with its unique name and source path
+export const Counter = island(CounterComponent, import.meta.url, 'Counter');
+export default Counter;
+```
+
+Now import and use it in any page just like a normal React component:
+
+```tsx
+// src/pages/index.tsx
+import React from 'react';
+import { Layout } from '../components/Layout.js';
+import { Counter } from '../components/Counter.island.js';
+
+export default function HomePage() {
+  return (
+    <Layout title="Home">
+      <h2>Welcome!</h2>
+      {/* Pre-rendered to HTML for instant paint, then hydrated with tiny JS */}
+      <Counter initial={10} />
+    </Layout>
+  );
+}
+```
+
+**What the engine does:**
+1. Renders the initial static markup during SSR for instant paint.
+2. Compiles a dedicated micro-bundle `dist/assets/islands/Counter.js`.
+3. Injects `<script type="module" src="/assets/islands/Counter.js"></script>` into `index.html`.
+4. Hydrates only the island element in-place using React 19's `hydrateRoot`.
+
+---
+
+## 🛠️ Hydration Directives
+
+`react-html` supports client loading directives to maximize performance:
+
+| Directive | Syntax | Behavior |
+| :--- | :--- | :--- |
+| `load` (default) | `<Counter client="load" />` | Hydrates immediately on DOM ready |
+| `idle` | `<Counter client="idle" />` | Hydrates during browser idle time (`requestIdleCallback`) |
+| `visible` | `<Counter client="visible" />` | Hydrates when scrolled into view (`IntersectionObserver`) |
+
+---
+
+## 💻 Programmatic API
+
+You can also run `react-html` programmatically from your Node.js scripts:
+
+```ts
+import { build } from 'react-html';
+
+const result = await build({
+  root: process.cwd(),
+  pagesDir: 'src/pages',
+  outDir: 'dist',
+  minify: true
+});
+
+console.log(`Compiled ${result.pages.length} pages and ${result.islands.length} reactive islands.`);
+```
+
+---
+
+## 🧪 Testing
+
+Run the automated test suite powered by Node.js test runner:
+
+```bash
+npm test
+```
+
+## 📄 License
+
+MIT
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/bin/react-html.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runCli } from '../dist/cli/index.js';
+
+runCli().catch((err) => {
+  console.error('[react-html] Fatal error:', err);
+  process.exit(1);
+});
+