@punkestu/react-html 0.0.0-stage → 0.1.0

package/src/server/dev-server.ts

@@ -0,0 +1,125 @@
+import http from 'node:http';
+import fs from 'node:fs/promises';
+import { existsSync, watch } from 'node:fs';
+import path from 'node:path';
+import { build, BuildConfig } from '../index.js';
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.mjs': 'application/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff2': 'font/woff2'
+};
+
+export interface DevServerOptions extends BuildConfig {
+  port?: number;
+  host?: string;
+}
+
+export async function createDevServer(options: DevServerOptions = {}): Promise<http.Server> {
+  const port = options.port || 3000;
+  const host = options.host || 'localhost';
+  const root = path.resolve(options.root || process.cwd());
+  const outDir = path.resolve(root, options.outDir || 'dist');
+
+  console.log(`[react-html] Performing initial build...`);
+  await build({ ...options, minify: false });
+  console.log(`[react-html] Build completed.`);
+
+  // Setup file watcher with debounce
+  let isRebuilding = false;
+  let rebuildTimeout: NodeJS.Timeout | null = null;
+
+  const triggerRebuild = () => {
+    if (rebuildTimeout) clearTimeout(rebuildTimeout);
+    rebuildTimeout = setTimeout(async () => {
+      if (isRebuilding) return;
+      isRebuilding = true;
+      try {
+        console.log(`[react-html] Change detected, rebuilding...`);
+        const startTime = Date.now();
+        await build({ ...options, minify: false });
+        console.log(`[react-html] Rebuild finished in ${Date.now() - startTime}ms`);
+      } catch (err) {
+        console.error(`[react-html] Rebuild error:`, err);
+      } finally {
+        isRebuilding = false;
+      }
+    }, 100);
+  };
+
+  const watchDirs = ['src', 'pages', 'public'].map(d => path.join(root, d)).filter(existsSync);
+  for (const dir of watchDirs) {
+    try {
+      watch(dir, { recursive: true }, (event, filename) => {
+        if (filename && !filename.includes('.react-html') && !filename.includes('dist')) {
+          triggerRebuild();
+        }
+      });
+    } catch {
+      // Fallback
+    }
+  }
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url || '/', `http://${host}:${port}`);
+      let pathname = decodeURIComponent(url.pathname);
+
+      if (pathname.endsWith('/')) {
+        pathname += 'index.html';
+      }
+
+      let filePath = path.join(outDir, pathname);
+
+      // If no extension, check if an .html file exists
+      if (!path.extname(filePath)) {
+        if (existsSync(`${filePath}.html`)) {
+          filePath = `${filePath}.html`;
+        } else if (existsSync(path.join(filePath, 'index.html'))) {
+          filePath = path.join(filePath, 'index.html');
+        }
+      }
+
+      if (!existsSync(filePath)) {
+        res.writeHead(404, { 'Content-Type': 'text/html' });
+        res.end(`<h1>404 Not Found</h1><p>File not found: ${pathname}</p>`);
+        return;
+      }
+
+      const stat = await fs.stat(filePath);
+      if (stat.isDirectory()) {
+        filePath = path.join(filePath, 'index.html');
+      }
+
+      const ext = path.extname(filePath).toLowerCase();
+      const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+
+      const content = await fs.readFile(filePath);
+      res.writeHead(200, {
+        'Content-Type': contentType,
+        'Content-Length': content.length
+      });
+      res.end(content);
+    } catch (err: any) {
+      res.writeHead(500, { 'Content-Type': 'text/plain' });
+      res.end(`500 Internal Server Error: ${err?.message || err}`);
+    }
+  });
+
+  return new Promise((resolve) => {
+    server.listen(port, host, () => {
+      console.log(`[react-html] Dev server running at http://${host}:${port}/`);
+      resolve(server);
+    });
+  });
+}
+

package/src/server/engine.ts

@@ -0,0 +1,270 @@
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { loadPageModule } from '../core/loader.js';
+import { renderPageToHtml } from '../core/renderer.js';
+import { bundleIslands } from '../core/bundler.js';
+import { IslandInstance } from '../core/island-registry.js';
+
+export interface EngineOptions {
+  /** Project root directory (default: process.cwd()) */
+  root?: string;
+  /** Source pages directory (default: 'src/pages' or 'pages') */
+  pagesDir?: string;
+  /** Production build output directory (default: 'dist') */
+  distDir?: string;
+  /** Static public directory (default: 'public') */
+  publicDir?: string;
+  /** Force production mode. If omitted, checks process.env.NODE_ENV === 'production' */
+  isProduction?: boolean;
+  /** Base asset URL prefix (default: '/') */
+  basePath?: string;
+}
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.mjs': 'application/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff2': 'font/woff2'
+};
+
+export class ReactHtmlEngine {
+  public readonly root: string;
+  public readonly pagesDir: string;
+  public readonly distDir: string;
+  public readonly publicDir: string;
+  public readonly isProduction: boolean;
+  public readonly basePath: string;
+
+  constructor(options: EngineOptions = {}) {
+    this.root = path.resolve(options.root || process.cwd());
+    this.isProduction =
+      options.isProduction !== undefined
+        ? options.isProduction
+        : process.env.NODE_ENV === 'production';
+    this.basePath = options.basePath || '/';
+
+    // Resolve distDir
+    this.distDir = path.resolve(this.root, options.distDir || 'dist');
+    this.publicDir = path.resolve(this.root, options.publicDir || 'public');
+
+    // Resolve pagesDir
+    if (options.pagesDir) {
+      this.pagesDir = path.resolve(this.root, options.pagesDir);
+    } else {
+      const candidates = ['src/pages', 'pages'];
+      let found = path.join(this.root, 'src/pages');
+      for (const cand of candidates) {
+        const p = path.join(this.root, cand);
+        if (existsSync(p)) {
+          found = p;
+          break;
+        }
+      }
+      this.pagesDir = found;
+    }
+  }
+
+  /**
+   * Render a page by name or route.
+   * - In production: checks for pre-built static HTML in dist/ first.
+   * - In development: recompiles the TSX page on the fly and bundles any needed reactive islands.
+   */
+  public async render(
+    pageRoute: string,
+    props: Record<string, unknown> = {},
+    metadata: Record<string, unknown> = {}
+  ): Promise<string> {
+    const cleanRoute = pageRoute.replace(/^\/+/, '').replace(/\.html$/, '');
+    const normalizedName = cleanRoute === '' ? 'index' : cleanRoute;
+
+    // In production, check for pre-built static HTML
+    if (this.isProduction) {
+      const candidatePaths = [
+        path.join(this.distDir, `${normalizedName}.html`),
+        path.join(this.distDir, normalizedName, 'index.html')
+      ];
+
+      for (const candidate of candidatePaths) {
+        if (existsSync(candidate)) {
+          return await fs.readFile(candidate, 'utf8');
+        }
+      }
+    }
+
+    // In development (or if production pre-build not found), compile on-the-fly
+    const sourceFilePath = await this.resolveSourcePage(normalizedName);
+    if (!sourceFilePath) {
+      throw new Error(
+        `[react-html] Page "${pageRoute}" not found in "${this.pagesDir}".`
+      );
+    }
+
+    const { Component, metadata: pageMeta } = await loadPageModule(sourceFilePath);
+    const mergedMetadata = { ...pageMeta, ...metadata };
+
+    const { html, islands } = renderPageToHtml({
+      pagePath: sourceFilePath,
+      Component,
+      props,
+      metadata: mergedMetadata,
+      basePath: this.basePath
+    });
+
+    // In development, bundle reactive islands on-the-fly into distDir/assets/islands
+    if (islands.length > 0) {
+      await bundleIslands(islands, {
+        outDir: this.distDir,
+        minify: this.isProduction
+      });
+    }
+
+    return html;
+  }
+
+  /**
+   * Universal Connect / Express / Node.js HTTP middleware.
+   * Handles page routes and static assets according to environment mode.
+   */
+  public middleware = async (
+    req: IncomingMessage,
+    res: ServerResponse,
+    next?: () => void
+  ): Promise<void> => {
+    const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+    let pathname = decodeURIComponent(url.pathname);
+
+    // 1. Check if request matches an asset in dist/ or public/
+    const assetResponse = await this.tryServeStaticAsset(pathname);
+    if (assetResponse) {
+      res.writeHead(200, {
+        'Content-Type': assetResponse.contentType,
+        'Content-Length': assetResponse.content.length
+      });
+      res.end(assetResponse.content);
+      return;
+    }
+
+    // 2. Normalize page route
+    let route = pathname.replace(/^\/+/, '').replace(/\/+$/, '');
+    if (route === '' || route.endsWith('.html')) {
+      route = route.replace(/\.html$/, '') || 'index';
+    }
+
+    // 3. Try rendering the page
+    try {
+      // In production: check if dist HTML exists
+      if (this.isProduction) {
+        const candidatePaths = [
+          path.join(this.distDir, `${route}.html`),
+          path.join(this.distDir, route, 'index.html')
+        ];
+        for (const candidate of candidatePaths) {
+          if (existsSync(candidate)) {
+            const content = await fs.readFile(candidate);
+            res.writeHead(200, {
+              'Content-Type': 'text/html; charset=utf-8',
+              'Content-Length': content.length
+            });
+            res.end(content);
+            return;
+          }
+        }
+      } else {
+        // In development: check if source page exists
+        const sourcePath = await this.resolveSourcePage(route);
+        if (sourcePath) {
+          const html = await this.render(route);
+          const buffer = Buffer.from(html, 'utf8');
+          res.writeHead(200, {
+            'Content-Type': 'text/html; charset=utf-8',
+            'Content-Length': buffer.length
+          });
+          res.end(buffer);
+          return;
+        }
+      }
+    } catch (err: any) {
+      console.error(`[react-html] Engine rendering error for route "${pathname}":`, err);
+      res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+      res.end(`500 Internal Server Error: ${err?.message || err}`);
+      return;
+    }
+
+    // If not handled, pass to next middleware if available
+    if (typeof next === 'function') {
+      next();
+    } else {
+      res.writeHead(404, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(`<h1>404 Not Found</h1><p>Route "${pathname}" not found.</p>`);
+    }
+  };
+
+  /**
+   * Standalone HTTP request handler suitable for http.createServer(engine.handle)
+   */
+  public handle = (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    return this.middleware(req, res);
+  };
+
+  private async resolveSourcePage(normalizedName: string): Promise<string | null> {
+    const extensions = ['.tsx', '.jsx', '.ts', '.js'];
+    const candidates = [
+      ...extensions.map(ext => path.join(this.pagesDir, `${normalizedName}${ext}`)),
+      ...extensions.map(ext => path.join(this.pagesDir, normalizedName, `index${ext}`))
+    ];
+
+    for (const cand of candidates) {
+      if (existsSync(cand)) {
+        return cand;
+      }
+    }
+    return null;
+  }
+
+  private async tryServeStaticAsset(
+    pathname: string
+  ): Promise<{ content: Buffer; contentType: string } | null> {
+    const ext = path.extname(pathname).toLowerCase();
+    if (!ext || ext === '.html') return null;
+
+    const cleanPath = pathname.replace(/^\/+/, '');
+    const candidateFiles = [
+      path.join(this.distDir, cleanPath),
+      path.join(this.publicDir, cleanPath)
+    ];
+
+    for (const filePath of candidateFiles) {
+      if (existsSync(filePath)) {
+        try {
+          const stat = await fs.stat(filePath);
+          if (stat.isFile()) {
+            const content = await fs.readFile(filePath);
+            const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+            return { content, contentType };
+          }
+        } catch {
+          // Continue searching
+        }
+      }
+    }
+    return null;
+  }
+}
+
+/**
+ * Factory function to create a new ReactHtmlEngine instance
+ */
+export function createEngine(options: EngineOptions = {}): ReactHtmlEngine {
+  return new ReactHtmlEngine(options);
+}
+

package/src/server/index.ts

@@ -0,0 +1,5 @@
+export { ReactHtmlEngine, createEngine } from './engine.js';
+export type { EngineOptions } from './engine.js';
+export { createDevServer } from './dev-server.js';
+export type { DevServerOptions } from './dev-server.js';
+

package/tests/engine.test.mjs

@@ -0,0 +1,288 @@
+import { test, describe, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import React from 'react';
+import { renderPageToHtml, build, Island, island } from '../dist/index.js';
+
+describe('react-html Engine Test Suite', () => {
+  describe('Static HTML Rendering', () => {
+    test('renders pure static component to HTML with zero script tags', () => {
+      function StaticPage() {
+        return React.createElement(
+          'div',
+          { className: 'hero' },
+          React.createElement('h1', null, 'Hello Pure World'),
+          React.createElement('p', null, 'This is pure static HTML without JS.')
+        );
+      }
+
+      const result = renderPageToHtml({
+        pagePath: '/test/page.tsx',
+        Component: StaticPage,
+        metadata: { title: 'Static Test' }
+      });
+
+      assert.ok(result.html.includes('<!DOCTYPE html>'));
+      assert.ok(result.html.includes('<title>Static Test</title>'));
+      assert.ok(result.html.includes('<h1>Hello Pure World</h1>') || result.html.includes('Hello Pure World'));
+      assert.ok(!result.html.includes('<script'));
+      assert.equal(result.islands.length, 0);
+    });
+
+    test('preserves full html document when component returns html tag', () => {
+      function FullDoc() {
+        return React.createElement(
+          'html',
+          { lang: 'fr' },
+          React.createElement('head', null, React.createElement('title', null, 'French Page')),
+          React.createElement('body', null, React.createElement('h1', null, 'Bonjour'))
+        );
+      }
+
+      const result = renderPageToHtml({
+        pagePath: '/test/french.tsx',
+        Component: FullDoc
+      });
+
+      assert.ok(result.html.startsWith('<!DOCTYPE html>'));
+      assert.ok(result.html.includes('<html lang="fr">'));
+      assert.ok(result.html.includes('Bonjour'));
+      assert.ok(!result.html.includes('<script'));
+    });
+  });
+
+  describe('Reactive Island Architecture', () => {
+    test('registers island and injects script tag for interactive component', () => {
+      function MyCounter({ initial = 5 }) {
+        return React.createElement('button', null, `Count: ${initial}`);
+      }
+
+      const InteractiveCounter = island(MyCounter, '/fake/path/Counter.tsx', 'MyCounter');
+
+      function PageWithIsland() {
+        return React.createElement(
+          'main',
+          null,
+          React.createElement('h1', null, 'Island Page'),
+          React.createElement(InteractiveCounter, { initial: 10 })
+        );
+      }
+
+      const result = renderPageToHtml({
+        pagePath: '/test/island-page.tsx',
+        Component: PageWithIsland
+      });
+
+      assert.equal(result.islands.length, 1);
+      assert.equal(result.islands[0].name, 'MyCounter');
+      assert.deepEqual(result.islands[0].props, { initial: 10 });
+      assert.ok(result.html.includes('data-island="MyCounter"'));
+      assert.ok(result.html.includes('data-props="{&quot;initial&quot;:10}"'));
+      assert.ok(result.html.includes('<script type="module" src="/assets/islands/MyCounter.js">'));
+    });
+  });
+
+  describe('End-to-End Build Pipeline', () => {
+    const testFixtureDir = path.resolve(process.cwd(), '.test-fixture');
+    const outDir = path.join(testFixtureDir, 'dist');
+
+    before(async () => {
+      await fs.mkdir(path.join(testFixtureDir, 'src/pages'), { recursive: true });
+      await fs.mkdir(path.join(testFixtureDir, 'src/components'), { recursive: true });
+
+      // Create a pure static page
+      await fs.writeFile(
+        path.join(testFixtureDir, 'src/pages/pure.tsx'),
+        `
+        import React from 'react';
+        export const title = "Pure Static";
+        export default function Pure() {
+          return <div><h1>Zero JS</h1></div>;
+        }
+        `
+      );
+
+      // Create an island component
+      await fs.writeFile(
+        path.join(testFixtureDir, 'src/components/Toggle.island.tsx'),
+        `
+        import React, { useState } from 'react';
+        import { island } from '${path.resolve(process.cwd(), 'dist/index.js')}';
+        function ToggleComp({ label = 'Click' }) {
+          const [on, setOn] = useState(false);
+          return <button onClick={() => setOn(!on)}>{label}: {on ? 'ON' : 'OFF'}</button>;
+        }
+        export const Toggle = island(ToggleComp, import.meta.url, 'Toggle');
+        export default Toggle;
+        `
+      );
+
+      // Create a page using the island
+      await fs.writeFile(
+        path.join(testFixtureDir, 'src/pages/interactive.tsx'),
+        `
+        import React from 'react';
+        import { Toggle } from '../components/Toggle.island.js';
+        export default function Interactive() {
+          return <div><h1>Interactive</h1><Toggle label="Power" /></div>;
+        }
+        `
+      );
+    });
+
+    after(async () => {
+      await fs.rm(testFixtureDir, { recursive: true, force: true });
+    });
+
+    test('builds static pages and bundles reactive islands correctly', async () => {
+      const result = await build({
+        root: testFixtureDir,
+        outDir: 'dist',
+        minify: true
+      });
+
+      assert.equal(result.pages.length, 2);
+
+      // Check pure static HTML output: absolutely NO script tags
+      const pureHtml = await fs.readFile(path.join(outDir, 'pure.html'), 'utf8');
+      assert.ok(pureHtml.includes('Zero JS'));
+      assert.ok(!pureHtml.includes('<script'));
+
+      // Check interactive page HTML output: has island markup & script tag
+      const interactiveHtml = await fs.readFile(path.join(outDir, 'interactive.html'), 'utf8');
+      assert.ok(interactiveHtml.includes('Interactive'));
+      assert.ok(interactiveHtml.includes('data-island="Toggle"'));
+      assert.ok(interactiveHtml.includes('<script type="module" src="/assets/islands/Toggle.js">'));
+
+      // Check island JS bundle was generated
+      const islandJsExists = await fs.stat(path.join(outDir, 'assets/islands/Toggle.js')).then(() => true).catch(() => false);
+      assert.ok(islandJsExists, 'Toggle.js island bundle should exist in assets/islands');
+    });
+  });
+
+  describe('Terminal Documentation (TUI)', () => {
+    test('contains comprehensive documentation sections', async () => {
+      const { DOC_SECTIONS } = await import('../dist/cli/docs-content.js');
+      assert.ok(DOC_SECTIONS.length >= 8, 'Expected at least 8 doc sections');
+      
+      const ids = DOC_SECTIONS.map(s => s.id);
+      assert.ok(ids.includes('intro'));
+      assert.ok(ids.includes('islands'));
+      assert.ok(ids.includes('directives'));
+      assert.ok(ids.includes('cli'));
+      assert.ok(ids.includes('troubleshooting'));
+    });
+  });
+
+  describe('Server Application Library (createEngine)', () => {
+    const fixtureDir = path.resolve(process.cwd(), '.server-test-fixture');
+    const pagesDir = path.join(fixtureDir, 'src/pages');
+    const distDir = path.join(fixtureDir, 'dist');
+
+    before(async () => {
+      await fs.mkdir(pagesDir, { recursive: true });
+      await fs.mkdir(distDir, { recursive: true });
+
+      // Create pre-built production HTML in dist
+      await fs.writeFile(
+        path.join(distDir, 'index.html'),
+        '<!DOCTYPE html><html><body><h1>PRE-BUILT PRODUCTION HTML</h1></body></html>'
+      );
+
+      // Create development source page in src/pages
+      await fs.writeFile(
+        path.join(pagesDir, 'index.tsx'),
+        `
+        import React from 'react';
+        export default function Home() {
+          return <h1>LIVE REBUILT DEV HTML</h1>;
+        }
+        `
+      );
+    });
+
+    after(async () => {
+      await fs.rm(fixtureDir, { recursive: true, force: true });
+    });
+
+    test('production mode: loads and returns pre-built static HTML from dist', async () => {
+      const { createEngine } = await import('../dist/index.js');
+      const engine = createEngine({
+        root: fixtureDir,
+        pagesDir,
+        distDir,
+        isProduction: true
+      });
+
+      const html = await engine.render('index');
+      assert.ok(html.includes('PRE-BUILT PRODUCTION HTML'), 'Production should return pre-built dist HTML');
+      assert.ok(!html.includes('LIVE REBUILT DEV HTML'));
+    });
+
+    test('development mode: dynamically rebuilds and returns fresh HTML string', async () => {
+      const { createEngine } = await import('../dist/index.js');
+      const engine = createEngine({
+        root: fixtureDir,
+        pagesDir,
+        distDir,
+        isProduction: false
+      });
+
+      const html = await engine.render('index');
+      assert.ok(html.includes('LIVE REBUILT DEV HTML'), 'Development should rebuild from source TSX');
+      assert.ok(!html.includes('PRE-BUILT PRODUCTION HTML'));
+
+      // Modify the source file on the fly
+      await fs.writeFile(
+        path.join(pagesDir, 'index.tsx'),
+        `
+        import React from 'react';
+        export default function Home() {
+          return <h1>UPDATED LIVE IN DEV</h1>;
+        }
+        `
+      );
+
+      // Re-render: should reflect the immediate update without server restart!
+      const updatedHtml = await engine.render('index');
+      assert.ok(updatedHtml.includes('UPDATED LIVE IN DEV'), 'Dev mode should reflect immediate code edits');
+    });
+
+    test('middleware: serves request via connect/express-compatible middleware', async () => {
+      const { createEngine } = await import('../dist/index.js');
+      const engine = createEngine({
+        root: fixtureDir,
+        pagesDir,
+        distDir,
+        isProduction: true
+      });
+
+      let statusCode = 0;
+      let headers = {};
+      let body = '';
+
+      const fakeReq = {
+        url: '/',
+        headers: { host: 'localhost:3000' }
+      };
+
+      const fakeRes = {
+        writeHead(status, h) {
+          statusCode = status;
+          headers = h;
+        },
+        end(data) {
+          body = data.toString();
+        }
+      };
+
+      await engine.middleware(fakeReq, fakeRes);
+
+      assert.equal(statusCode, 200);
+      assert.equal(headers['Content-Type'], 'text/html; charset=utf-8');
+      assert.ok(body.includes('PRE-BUILT PRODUCTION HTML'));
+    });
+  });
+});
+