@punkestu/react-html 0.1.0 → 1.0.0

package/README.md

@@ -33,9 +33,12 @@ npm link
 ### CLI Usage
 
 ```bash
-# Build static site to dist/
+# Build static site to dist/ (with code splitting, islands are ~800 B each)
 react-html build
 
+# Ultra-light Preact mode (drops total framework chunk to ~24 KB!)
+react-html build --preact
+
 # Build with custom pages or output directory
 react-html build --pages src/pages --out dist
 
@@ -114,20 +117,15 @@ export default function AboutPage() {
 
 ---
 
-### 2. Reactive Components (Islands Architecture)
+### 2. Reactive Components (Island Auto-Discovery)
 
-When a component needs client-side state and interactivity, wrap it with `island()`:
+When a component needs client-side state and interactivity, simply name the file `*.island.tsx` (or place it inside an `islands/` directory) and **export default** your pure React component. Zero wrapping required!
 
 ```tsx
-// src/components/Counter.island.tsx
+// src/components/Counter.island.tsx (or src/islands/Counter.tsx)
 import React, { useState } from 'react';
-import { island } from 'react-html';
-
-export interface CounterProps {
-  initial?: number;
-}
 
-function CounterComponent({ initial = 0 }: CounterProps) {
+export default function Counter({ initial = 0 }: { initial?: number }) {
   const [count, setCount] = useState(initial);
 
   return (
@@ -138,10 +136,6 @@ function CounterComponent({ initial = 0 }: CounterProps) {
     </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:
@@ -150,7 +144,7 @@ Now import and use it in any page just like a normal React component:
 // src/pages/index.tsx
 import React from 'react';
 import { Layout } from '../components/Layout.js';
-import { Counter } from '../components/Counter.island.js';
+import Counter from '../components/Counter.island.js';
 
 export default function HomePage() {
   return (
@@ -163,6 +157,8 @@ export default function HomePage() {
 }
 ```
 
+> 💡 **Manual Island Wrapping (Optional)**: If you prefer explicit wrapping or have dynamic component references, `island(Component, import.meta.url, 'Name')` and `<Island component={...} />` are also supported for full backward compatibility.
+
 **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`.
@@ -171,6 +167,53 @@ export default function HomePage() {
 
 ---
 
+### 3. Pure Vanilla DOM Islands (Zero-React Client Compilation)
+
+Want client-side interactivity but **zero React or VDOM runtime on the client**?
+
+You can write standard React JSX on the server for DRY markup, and export a native `client(element, props)` controller function in the same island file:
+
+```tsx
+// src/components/VanillaCounter.island.tsx
+import React from 'react';
+
+// 1. Server: Pure modular HTML via standard React JSX
+export default function VanillaCounter({ initialCount = 0, step = 1 }: { initialCount?: number; step?: number }) {
+  return (
+    <div className="counter-box">
+      <span className="counter-value">{initialCount}</span>
+      <button data-action="dec">- {step}</button>
+      <button data-action="inc">+ {step}</button>
+    </div>
+  );
+}
+
+// 2. Client: Pure native DOM controller (Zero React/VDOM runtime!)
+export function client(el: HTMLElement, props: { initialCount?: number; step?: number }) {
+  let count = props.initialCount || 0;
+  const step = props.step || 1;
+  const display = el.querySelector('.counter-value');
+
+  el.querySelector('[data-action="dec"]')?.addEventListener('click', () => {
+    count -= step;
+    if (display) display.textContent = String(count);
+  });
+
+  el.querySelector('[data-action="inc"]')?.addEventListener('click', () => {
+    count += step;
+    if (display) display.textContent = String(count);
+  });
+}
+```
+
+**Why this is huge:**
+- **0 KB React, 0 KB ReactDOM, 0 KB Preact**: The engine completely stubs React in the client bundle.
+- **Zero Chunk Imports**: Outputs a single, self-contained standalone `.js` file (~1 KB uncompressed, ~450 bytes gzipped).
+- **Zero Hydration Overhead**: Bypasses VDOM reconciliation and binds native event listeners directly to existing DOM nodes.
+- **Mix & Match**: You can use Pure Vanilla DOM islands and standard React/Preact islands in the very same project without conflict!
+
+---
+
 ## 🛠️ Hydration Directives
 
 `react-html` supports client loading directives to maximize performance:
@@ -183,6 +226,20 @@ export default function HomePage() {
 
 ---
 
+## ⚡ Tiny Island Bundles & Preact Ultra-Light Mode
+
+`react-html` uses ESM multi-entry code splitting and comment stripping to keep island bundles tiny:
+
+- **Code Splitting by Default**: Component logic is separated from runtime code. `Counter.js` and `Tabs.js` weigh only **~800 bytes to 1 KB** each, importing a shared vendor chunk that the browser caches across all pages.
+- **Ultra-Light Preact Mode (`--preact`)**: Want microscopic client bundles? Pass `--preact` to alias client hydration to `preact/compat`. You still write standard React JSX, but the shared runtime shrinks by **90%** down to **~24 KB uncompressed (~8 KB gzipped)**!
+
+```bash
+# Build with Preact ultra-light runtime
+react-html build --preact
+```
+
+---
+
 ## 💻 Programmatic API
 
 You can also run `react-html` programmatically from your Node.js scripts:

package/dist/cli/docs-content.d.ts

@@ -0,0 +1,8 @@
+export interface DocSection {
+    id: string;
+    title: string;
+    summary: string;
+    content: string[];
+}
+export declare const DOC_SECTIONS: DocSection[];
+//# sourceMappingURL=docs-content.d.ts.map

package/dist/cli/docs-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-content.d.ts","sourceRoot":"","sources":["../../src/cli/docs-content.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,eAAO,MAAM,YAAY,EAAE,UAAU,EAsUpC,CAAC"}

package/dist/cli/docs-content.js

@@ -0,0 +1,328 @@
+export const DOC_SECTIONS = [
+    {
+        id: 'intro',
+        title: '1. Overview & Philosophy',
+        summary: 'Core concepts: pure HTML output, zero-JS by default, and modular JSX.',
+        content: [
+            '# 1. Overview & Philosophy',
+            '',
+            'react-html bridges the gap between modern component-based developer experience',
+            'and lightweight, blazing-fast static websites.',
+            '',
+            '* ZERO JAVASCRIPT BY DEFAULT:',
+            '  Standard components (layouts, navigation, typography, cards, footers) render into',
+            '  100% clean, semantic HTML5. No React runtime, no data-reactroot attributes,',
+            '  and 0 KB JavaScript sent to the browser.',
+            '',
+            '* MODULAR & DRY (DON\'T REPEAT YOURSELF):',
+            '  Eliminate copy-pasting HTML boilerplate. Compose pages with reusable React',
+            '  components (<Layout>, <Header>, <Card>, <Footer>) with typed props.',
+            '',
+            '* SELECTIVE REACTIVITY (ISLANDS ARCHITECTURE):',
+            '  Only components that explicitly require client-side interactivity are bundled',
+            '  into isolated, tiny JavaScript files. Everything around them remains pure HTML.'
+        ]
+    },
+    {
+        id: 'quickstart',
+        title: '2. Getting Started & Setup',
+        summary: 'Installation, Node.js environment, and initial directory structure.',
+        content: [
+            '# 2. Getting Started & Setup',
+            '',
+            '* PREREQUISITES:',
+            '  - Node.js v20.0.0 or higher (runs natively on standard Node.js & npm)',
+            '',
+            '* INSTALLATION:',
+            '  $ npm install react-html',
+            '',
+            '* RECOMMENDED PROJECT STRUCTURE:',
+            '  my-project/',
+            '  ├── package.json',
+            '  ├── public/                  # Static assets (CSS, images, icons)',
+            '  │   └── styles.css',
+            '  └── src/',
+            '      ├── components/          # Reusable UI components',
+            '      │   ├── Layout.tsx       # Master HTML shell',
+            '      │   ├── Header.tsx       # Navigation bar',
+            '      │   └── Counter.island.tsx # Interactive island component',
+            '      └── pages/               # Multi-page entries',
+            '          ├── index.tsx        # -> dist/index.html',
+            '          ├── about.tsx        # -> dist/about.html',
+            '          └── blog/',
+            '              └── first.tsx    # -> dist/blog/first.html'
+        ]
+    },
+    {
+        id: 'modular-html',
+        title: '3. Modular HTML with React',
+        summary: 'Creating reusable layouts, header partials, and nested components.',
+        content: [
+            '# 3. Modular HTML with React',
+            '',
+            'Stop repeating HTML boilerplate. Create a single Layout component:',
+            '',
+            '// src/components/Layout.tsx',
+            'import React, { ReactNode } from "react";',
+            'import { Header } from "./Header.js";',
+            'import { Footer } from "./Footer.js";',
+            '',
+            '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 />',
+            '        <main>{children}</main>',
+            '        <Footer />',
+            '      </body>',
+            '    </html>',
+            '  );',
+            '}',
+            '',
+            'Every page simply wraps its content in <Layout>: no copy-pasting required!'
+        ]
+    },
+    {
+        id: 'islands',
+        title: '4. Reactive Islands Architecture (Auto-Discovery)',
+        summary: 'Zero-boilerplate islands: export default pure React components from *.island.tsx.',
+        content: [
+            '# 4. Reactive Islands Architecture (Auto-Discovery)',
+            '',
+            'When you need client-side state (useState, useEffect, event listeners):',
+            '',
+            '1. Simply name your file *.island.tsx (or place in islands/) and export default:',
+            '// src/components/Counter.island.tsx',
+            'import React, { useState } from "react";',
+            '',
+            'export default function Counter({ initial = 0 }) {',
+            '  const [count, setCount] = useState(initial);',
+            '  return (',
+            '    <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>',
+            '  );',
+            '}',
+            '',
+            'No island() wrapping required! The engine auto-discovers and wraps it for SSR.',
+            '',
+            '2. Use it in any page just like a normal React component:',
+            '// src/pages/index.tsx',
+            'import Counter from "../components/Counter.island.js";',
+            '<Counter initial={10} />',
+            '',
+            '* HOW THE ENGINE COMPILES IT:',
+            '  - Initial HTML is pre-rendered for instant paint and SEO.',
+            '  - esbuild bundles ONLY Counter into dist/assets/islands/Counter.js.',
+            '  - Only pages containing <Counter> will have the <script> tag injected.'
+        ]
+    },
+    {
+        id: 'vanilla-islands',
+        title: '5. Pure Vanilla DOM Islands (Zero-React Client)',
+        summary: 'Compile islands to pure native DOM JavaScript with zero React/VDOM runtime.',
+        content: [
+            '# 5. Pure Vanilla DOM Islands (Zero-React Client)',
+            '',
+            'Author layouts and components with React JSX on the server, but compile to',
+            'pure native DOM JavaScript on the client with ZERO React or VDOM overhead!',
+            '',
+            '* HOW TO WRITE A VANILLA ISLAND:',
+            '  In your *.island.tsx file, export both:',
+            '  1. `export default function`: React JSX markup rendered on the server.',
+            '  2. `export function client(el, props)`: Pure native DOM controller on the client.',
+            '',
+            '  // src/components/VanillaCounter.island.tsx',
+            '  import React from "react";',
+            '',
+            '  export default function VanillaCounter({ initialCount = 0, step = 1 }) {',
+            '    return (',
+            '      <div className="counter-box">',
+            '        <span className="counter-value">{initialCount}</span>',
+            '        <button data-action="dec">- {step}</button>',
+            '        <button data-action="inc">+ {step}</button>',
+            '      </div>',
+            '    );',
+            '  }',
+            '',
+            '  export function client(el: HTMLElement, props: { initialCount?: number; step?: number }) {',
+            '    let count = props.initialCount || 0;',
+            '    const step = props.step || 1;',
+            '    const display = el.querySelector(".counter-value");',
+            '    el.querySelector(\'[data-action="inc"]\')?.addEventListener("click", () => {',
+            '      count += step;',
+            '      if (display) display.textContent = String(count);',
+            '    });',
+            '  }',
+            '',
+            '* THE COMPILED OUTPUT:',
+            '  - 0 KB React, 0 KB ReactDOM, 0 KB Preact (React is completely stubbed).',
+            '  - Self-contained standalone bundle (~1 KB uncompressed, ~450 B gzipped).',
+            '  - Zero framework chunk dependencies (no imports).',
+            '  - Full support for client="load", client="idle", and client="visible".'
+        ]
+    },
+    {
+        id: 'directives',
+        title: '6. Hydration Directives (Performance)',
+        summary: 'Controlling client hydration timing with load, idle, and visible.',
+        content: [
+            '# 6. Hydration Directives (Performance)',
+            '',
+            'Control when JavaScript executes on the user\'s device with the `client` prop:',
+            '',
+            '* client="load" (Default):',
+            '  <Counter client="load" />',
+            '  Hydrates as soon as DOMContentLoaded fires. Use for critical UI above the fold.',
+            '',
+            '* client="idle":',
+            '  <Counter client="idle" />',
+            '  Hydrates during browser idle time via requestIdleCallback. Perfect for widgets',
+            '  or floating elements that do not block immediate interaction.',
+            '',
+            '* client="visible":',
+            '  <Counter client="visible" />',
+            '  Hydrates only when scrolled into the viewport using IntersectionObserver.',
+            '  Ideal for carousels, comment sections, or widgets further down the page.'
+        ]
+    },
+    {
+        id: 'optimization',
+        title: '7. Island Size Optimization (Code Splitting & Preact)',
+        summary: 'Multi-entry code splitting (~800 B islands) and optional Preact ultra-light mode (~24 KB).',
+        content: [
+            '# 7. Island Size Optimization',
+            '',
+            '* MULTI-ENTRY CODE SPLITTING (DEFAULT):',
+            '  - react-html automatically splits shared dependencies (React, ReactDOM) into',
+            '    a shared chunk (chunks/chunk-[hash].js).',
+            '  - Individual island files (Counter.js, Tabs.js) drop to ~800 bytes to 1 KB each!',
+            '  - The browser downloads the framework chunk once and caches it across all pages.',
+            '',
+            '* PREACT ULTRA-LIGHT MODE (--preact):',
+            '  - Pass `--preact` to drop the entire framework chunk to ~24 KB uncompressed (~8 KB gzipped):',
+            '    $ react-html build --preact',
+            '  - Automatically aliases react and react-dom to preact/compat for hydration.',
+            '  - Zero component changes needed: write standard React JSX and hooks!'
+        ]
+    },
+    {
+        id: 'cli',
+        title: '8. CLI Commands & Options',
+        summary: 'Full guide for build, dev, and docs commands.',
+        content: [
+            '# 8. CLI Commands & Options',
+            '',
+            '* BUILD PRODUCTION STATIC SITE:',
+            '  $ react-html build [options]',
+            '  Flags:',
+            '    --pages <dir>             Directory containing pages (default: src/pages or pages)',
+            '    --out <dir>               Output directory (default: dist)',
+            '    --root <dir>              Root directory of the project (default: cwd)',
+            '    --client-runtime <type>   Island hydration runtime (react | preact, default: react)',
+            '    --preact                  Shortcut for --client-runtime preact (ultra-light ~24 KB)',
+            '    --no-minify               Disable JS minification for debugging',
+            '',
+            '* START DEV SERVER (LIVE PREVIEW & WATCH):',
+            '  $ react-html dev [options]',
+            '  Flags:',
+            '    --port <number>   Port to listen on (default: 3000)',
+            '    --host <string>   Host to bind to (default: localhost)',
+            '',
+            '* TERMINAL UI DOCUMENTATION (TUI):',
+            '  $ react-html docs               # Interactive TUI navigator',
+            '  $ react-html docs --all         # Print entire manual to stdout',
+            '  $ react-html docs <section-id>  # Print specific section'
+        ]
+    },
+    {
+        id: 'api',
+        title: '9. Programmatic API Reference',
+        summary: 'Using build(), renderPageToHtml(), and createDevServer() in Node.js.',
+        content: [
+            '# 9. Programmatic API Reference',
+            '',
+            'import { build, renderPageToHtml, island, Island } from "react-html";',
+            '',
+            '* build(config):',
+            '  const result = await build({',
+            '    root: process.cwd(),',
+            '    pagesDir: "src/pages",',
+            '    outDir: "dist",',
+            '    minify: true,',
+            '    clientRuntime: "preact" // optional ultra-light mode',
+            '  });',
+            '  // Returns: { pages: [...], islands: [...], outDir: string }',
+            '',
+            '* renderPageToHtml({ pagePath, Component, props, metadata }):',
+            '  const { html, islands } = renderPageToHtml({',
+            '    pagePath: "/path/to/page.tsx",',
+            '    Component: MyPage,',
+            '    metadata: { title: "Custom Title" }',
+            '  });',
+            '  // Returns pure HTML string and list of detected islands.'
+        ]
+    },
+    {
+        id: 'server',
+        title: '10. Server App Integration (Express, Fastify, Node HTTP)',
+        summary: 'Using createEngine() for production static hosting and development live rebuilds.',
+        content: [
+            '# 10. Server App Integration (Express, Fastify, Node HTTP)',
+            '',
+            'You can import and use react-html directly inside your backend server application:',
+            '',
+            '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 checks process.env.NODE_ENV === "production"',
+            '});',
+            '',
+            '* 1. CONNECT / EXPRESS MIDDLEWARE:',
+            '  app.use(engine.middleware);',
+            '  // In production: finds and streams pre-built static HTML from dist/.',
+            '  // In development: dynamically rebuilds TSX on the fly and returns fresh HTML.',
+            '',
+            '* 2. PROGRAMMATIC ROUTE RENDERING:',
+            '  app.get("/custom", async (req, res) => {',
+            '    const html = await engine.render("index", { 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);'
+        ]
+    },
+    {
+        id: 'troubleshooting',
+        title: '11. Best Practices & Troubleshooting',
+        summary: 'Avoiding hydration mismatch, React error #418, and styling rules.',
+        content: [
+            '# 11. Best Practices & Troubleshooting',
+            '',
+            '* PREVENTING HYDRATION MISMATCH (React Error #418):',
+            '  - Ensure server and initial client props match.',
+            '  - Do not use client-only objects (window.innerWidth, localStorage) in initial render.',
+            '    Instead, read them inside useEffect() or an event handler.',
+            '  - react-html automatically protects island markup during formatting and uses',
+            '    renderToString for interactive inner trees to guarantee matching text nodes.',
+            '',
+            '* ISOLATE STATEFUL LOGIC:',
+            '  Keep non-interactive parts (headers, card shells, footers) pure React components.',
+            '  Only place state hooks (useState, useReducer) inside *.island.tsx files.'
+        ]
+    }
+];
+//# sourceMappingURL=docs-content.js.map

package/dist/cli/docs-content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-content.js","sourceRoot":"","sources":["../../src/cli/docs-content.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export declare function runCli(args?: string[]): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAWA,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAsHlF"}

package/dist/cli/index.js

@@ -0,0 +1,135 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { build } from '../index.js';
+import { createDevServer } from '../server/dev-server.js';
+import { launchDocsTui } from './tui-docs.js';
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    return `${(bytes / 1024).toFixed(1)} KB`;
+}
+export async function runCli(args = process.argv.slice(2)) {
+    const command = args[0] || 'help';
+    function getArgValue(flag) {
+        const idx = args.indexOf(flag);
+        return idx !== -1 && args[idx + 1] ? args[idx + 1] : undefined;
+    }
+    const hasFlag = (flag) => args.includes(flag);
+    if (hasFlag('--help') || hasFlag('-h') || command === 'help') {
+        console.log(`
+react-html - Engine to convert React to pure HTML with reactive islands
+
+Usage:
+  react-html <command> [options]
+
+Commands:
+  build         Compile pages into pure HTML & bundle reactive islands
+  dev           Start live preview development server with auto-rebuild
+  docs          Browse interactive documentation in Terminal UI (TUI)
+  help          Show this help message
+
+Options:
+  --pages <dir>             Pages directory (default: src/pages or pages)
+  --out <dir>               Output directory (default: dist)
+  --port <number>           Dev server port (default: 3000)
+  --host <string>           Dev server host (default: localhost)
+  --client-runtime <type>   Island hydration runtime ('react' | 'preact', default: 'react')
+  --preact                  Shortcut for '--client-runtime preact' (ultra-light ~4 KB runtime)
+  --no-minify               Disable minification for island bundles
+  --root <path>             Project root directory (default: cwd)
+
+Docs Options:
+  react-html docs              Launch interactive Terminal UI
+  react-html docs --all        Print complete manual to terminal
+  react-html docs <section>    Print a specific section (e.g. islands, api, cli)
+`);
+        return;
+    }
+    if (hasFlag('--version') || hasFlag('-v')) {
+        console.log(`react-html v0.1.1`);
+        return;
+    }
+    const root = getArgValue('--root') || process.cwd();
+    const pagesDir = getArgValue('--pages');
+    const outDir = getArgValue('--out') || 'dist';
+    const minify = !hasFlag('--no-minify');
+    const clientRuntime = (hasFlag('--preact') || getArgValue('--client-runtime') === 'preact')
+        ? 'preact'
+        : 'react';
+    if (command === 'build') {
+        console.log(`\n🚀 [react-html] Building static site (${clientRuntime === 'preact' ? '⚡ Preact Ultra-Light' : 'React 19'})...`);
+        const startTime = Date.now();
+        try {
+            const result = await build({
+                root,
+                pagesDir,
+                outDir,
+                minify,
+                clientRuntime
+            });
+            console.log(`✅ [react-html] Build successful in ${Date.now() - startTime}ms`);
+            console.log(`📄 Pages compiled (${result.pages.length}):`);
+            result.pages.forEach(p => {
+                console.log(`   - ${path.relative(root, p.output)}`);
+            });
+            if (result.islands.length > 0) {
+                console.log(`🏝️  Reactive islands bundled (${result.islands.length}):`);
+                for (const isl of result.islands) {
+                    let sizeStr = '';
+                    try {
+                        const st = await fs.stat(isl);
+                        sizeStr = ` (${formatBytes(st.size)})`;
+                    }
+                    catch {
+                        // ignore
+                    }
+                    const isChunk = isl.includes('/chunks/') || isl.includes('\\chunks\\');
+                    const chunkLabel = isChunk ? ' [shared chunk]' : '';
+                    console.log(`   - ${path.relative(root, isl)}${sizeStr}${chunkLabel}`);
+                }
+            }
+            else {
+                console.log(`✨ Pure 100% HTML generated (0 KB JavaScript overhead)`);
+            }
+        }
+        catch (err) {
+            console.error(`❌ [react-html] Build failed:`, err?.message || err);
+            process.exit(1);
+        }
+    }
+    else if (command === 'dev') {
+        const port = parseInt(getArgValue('--port') || '3000', 10);
+        const host = getArgValue('--host') || 'localhost';
+        try {
+            await createDevServer({
+                root,
+                pagesDir,
+                outDir,
+                port,
+                host
+            });
+        }
+        catch (err) {
+            console.error(`❌ [react-html] Dev server failed:`, err?.message || err);
+            process.exit(1);
+        }
+    }
+    else if (command === 'docs') {
+        try {
+            await launchDocsTui(args[1]);
+        }
+        catch (err) {
+            console.error(`❌ [react-html] Docs error:`, err?.message || err);
+            process.exit(1);
+        }
+    }
+    else {
+        console.error(`Unknown command "${command}". Run "react-html --help" for available commands.`);
+        process.exit(1);
+    }
+}
+// Direct invocation check
+if (import.meta.url === `file://${process.argv[1]}`) {
+    runCli();
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/cli/tui-docs.d.ts

@@ -0,0 +1,5 @@
+import { DocSection } from './docs-content.js';
+export declare function printSectionDirect(section: DocSection): void;
+export declare function printAllDocs(): void;
+export declare function launchDocsTui(initialArg?: string): Promise<void>;
+//# sourceMappingURL=tui-docs.d.ts.map

package/dist/cli/tui-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tui-docs.d.ts","sourceRoot":"","sources":["../../src/cli/tui-docs.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAgC7D,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAM5D;AAED,wBAAgB,YAAY,IAAI,IAAI,CAQnC;AAED,wBAAsB,aAAa,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiKtE"}