create-jen-app 1.2.2 → 1.2.4

package/templates/ssr-isr/lib/native/optimizer.d.ts

@@ -0,0 +1,21 @@
+export interface OptimizerOptions {
+  files: string[];
+  minify?: boolean;
+  compress?: boolean;
+  imageOptimization?: boolean;
+}
+export declare function optimize(opts: OptimizerOptions): Promise<{
+  originalSize: number;
+  optimizedSize: number;
+  savings: number;
+  files: string[];
+}>;
+export declare function optimizeImages(
+  inputDir: string,
+  outputDir: string,
+  options?: {
+    format?: "webp" | "avif";
+    quality?: number;
+  },
+): Promise<void>;
+export declare function minifyHTML(html: string): Promise<string>;

package/templates/ssr-isr/lib/native/optimizer.js

@@ -0,0 +1,20 @@
+export async function optimize(opts) {
+  console.log(`[OPTIMIZER] Optimizing ${opts.files.length} files`);
+  // Placeholder: simulated optimization results
+  const originalSize = 1024 * 100; // 100KB
+  const optimizedSize = 1024 * 75; // 75KB (25% reduction)
+  return {
+    originalSize,
+    optimizedSize,
+    savings: originalSize - optimizedSize,
+    files: opts.files,
+  };
+}
+export async function optimizeImages(inputDir, outputDir, options = {}) {
+  console.log(`[OPTIMIZER] Image optimization: ${inputDir} -> ${outputDir}`);
+  // Placeholder: would use native image processing
+}
+export async function minifyHTML(html) {
+  // Simple minification placeholder
+  return html.replace(/\s+/g, " ").replace(/>\s+</g, "><").trim();
+}

package/templates/ssr-isr/lib/native/style-compiler.d.ts

@@ -0,0 +1,19 @@
+export interface StyleCompilerOptions {
+  input: string;
+  output?: string;
+  minify?: boolean;
+  sourcemap?: boolean;
+  includePaths?: string[];
+}
+export declare function compileScss(
+  opts: StyleCompilerOptions,
+): Promise<string>;
+export declare function compileCSS(
+  input: string,
+  minify?: boolean,
+): Promise<string>;
+export declare function watchStyles(
+  input: string,
+  output: string,
+  onChange: (css: string) => void,
+): Promise<void>;

package/templates/ssr-isr/lib/native/style-compiler.js

@@ -0,0 +1,19 @@
+export async function compileScss(opts) {
+  // Placeholder: returns CSS placeholder
+  console.log(`[STYLE COMPILER] Compiling SCSS: ${opts.input}`);
+  const css = `
+    /* SCSS compiled from: ${opts.input} */
+    /* Note: Full SCSS compilation requires dart-sass or native Rust implementation */
+    body { margin: 0; padding: 0; }
+  `;
+  return css;
+}
+export async function compileCSS(input, minify = false) {
+  console.log(`[STYLE COMPILER] Processing CSS: ${input}`);
+  // Placeholder: returns input CSS
+  return input;
+}
+export async function watchStyles(input, output, onChange) {
+  // Placeholder watcher
+  console.log(`[STYLE COMPILER] Watching: ${input}`);
+}

package/templates/ssr-isr/lib/plugin/loader.d.ts

@@ -0,0 +1,10 @@
+export interface Plugin {
+  name: string;
+  version?: string;
+  onBuild?: () => void | Promise<void>;
+  onServe?: () => void | Promise<void>;
+  onDeploy?: () => void | Promise<void>;
+}
+export declare function runPlugins(
+  event?: "build" | "serve" | "deploy",
+): Promise<void>;

package/templates/ssr-isr/lib/plugin/loader.js

@@ -0,0 +1,36 @@
+// Plugin loader
+// Migrated from Python src/python/plugins.py
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { log } from "../shared/log.js";
+const PLUGIN_DIR = "src/plugin/plugins";
+export async function runPlugins(event = "build") {
+  log.info(`Running plugins (${event})...`);
+  try {
+    const files = readdirSync(PLUGIN_DIR);
+    for (const file of files) {
+      if (!file.endsWith(".ts") && !file.endsWith(".js")) continue;
+      const pluginPath = join(process.cwd(), PLUGIN_DIR, file);
+      const pluginUrl = pathToFileURL(pluginPath).href;
+      try {
+        const module = await import(pluginUrl);
+        const plugin = module.default;
+        if (!plugin) continue;
+        log.info(`  Loading plugin: ${plugin.name}`);
+        if (event === "build" && plugin.onBuild) {
+          await plugin.onBuild();
+        } else if (event === "serve" && plugin.onServe) {
+          await plugin.onServe();
+        } else if (event === "deploy" && plugin.onDeploy) {
+          await plugin.onDeploy();
+        }
+      } catch (err) {
+        log.error(`  Plugin error: ${file} - ${String(err)}`);
+      }
+    }
+    log.info("Plugins executed.");
+  } catch (err) {
+    log.warn(`Plugin directory not found: ${PLUGIN_DIR}`);
+  }
+}

package/templates/ssr-isr/lib/runtime/client-runtime.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Retrieve framework data injected by the server into the page HTML.
+ * The server embeds loader result data, route params, and query parameters
+ * into a hidden DOM element with id "__FRAMEWORK_DATA__" as JSON.
+ *
+ * This data is passed to page components during hydration as props.
+ * Returns null if the element does not exist or JSON is malformed,
+ * allowing graceful degradation without throwing errors.
+ *
+ * Usage:
+ *   const data = getFrameworkData();
+ *   // data = { data: {...}, params: {...}, query: {...} }
+ *
+ * @returns Framework data object { data, params, query } or null if not found.
+ */
+export declare function getFrameworkData(): any;

package/templates/ssr-isr/lib/runtime/client-runtime.js

@@ -0,0 +1,25 @@
+/**
+ * Retrieve framework data injected by the server into the page HTML.
+ * The server embeds loader result data, route params, and query parameters
+ * into a hidden DOM element with id "__FRAMEWORK_DATA__" as JSON.
+ *
+ * This data is passed to page components during hydration as props.
+ * Returns null if the element does not exist or JSON is malformed,
+ * allowing graceful degradation without throwing errors.
+ *
+ * Usage:
+ *   const data = getFrameworkData();
+ *   // data = { data: {...}, params: {...}, query: {...} }
+ *
+ * @returns Framework data object { data, params, query } or null if not found.
+ */
+export function getFrameworkData() {
+  const el = document.getElementById("__FRAMEWORK_DATA__");
+  if (!el) return null;
+  try {
+    return JSON.parse(el.textContent || "null");
+  } catch {
+    // Silently return null if JSON is invalid; page hydrates with default props
+    return null;
+  }
+}

package/templates/ssr-isr/lib/runtime/hmr.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Client-side Hot Module Replacement (HMR) / Live Reload code.
+ * This script is injected into the browser during development mode.
+ *
+ * Features:
+ * - Establishes Server-Sent Events (SSE) connection to /__hmr endpoint
+ * - Listens for "reload" events (full page reload on route/component changes)
+ * - Listens for "style-update" events (CSS updates without full reload)
+ * - Automatically retries connection if lost
+ *
+ * The script uses IIFE (Immediately Invoked Function Expression) to avoid
+ * polluting the global scope.
+ *
+ * How it works:
+ * 1. Server watches file system for changes
+ * 2. On change, server sends SSE event to clients
+ * 3. Client receives event and either reloads or updates CSS
+ * 4. CSS updates use cache-busting query params to force fresh load
+ *
+ * Only injected in development mode; production builds do not include this.
+ */
+export declare const HMR_CLIENT_SCRIPT =
+  '\n(function() {\n  console.log("[Jen.js] Connecting to HMR...");\n  const evt = new EventSource("/__hmr");\n\n  evt.onopen = () => console.log("[Jen.js] HMR Connected");\n\n  // Full page reload on route or component changes\n  evt.addEventListener("reload", () => {\n    console.log("[Jen.js] Reloading...");\n    window.location.reload();\n  });\n\n  // CSS-only reload without full page reload (faster UX for style-only changes)\n  evt.addEventListener("style-update", (e) => {\n    const file = JSON.parse(e.data).file; // e.g., "styles.css"\n    console.log("[Jen.js] Style update:", file);\n    \n    // Find matching link tags by pathname\n    const links = document.querySelectorAll(\'link[rel="stylesheet"]\');\n    for (const link of links) {\n      const url = new URL(link.href);\n      if (url.pathname.endsWith(file)) {\n        // Force reload by updating cache-busting query param (timestamp)\n        url.searchParams.set("t", Date.now());\n        link.href = url.toString();\n        console.log("[Jen.js] Updated stylesheet:", file);\n      }\n    }\n  });\n\n  evt.onerror = () => {\n    // Connection closed; EventSource automatically retries\n    // (commented out: chatty in development; uncomment if needed for debugging)\n    // console.log("[Jen.js] HMR disconnected, retrying...");\n  };\n})();\n';

package/templates/ssr-isr/lib/runtime/hmr.js

@@ -0,0 +1,59 @@
+/**
+ * Client-side Hot Module Replacement (HMR) / Live Reload code.
+ * This script is injected into the browser during development mode.
+ *
+ * Features:
+ * - Establishes Server-Sent Events (SSE) connection to /__hmr endpoint
+ * - Listens for "reload" events (full page reload on route/component changes)
+ * - Listens for "style-update" events (CSS updates without full reload)
+ * - Automatically retries connection if lost
+ *
+ * The script uses IIFE (Immediately Invoked Function Expression) to avoid
+ * polluting the global scope.
+ *
+ * How it works:
+ * 1. Server watches file system for changes
+ * 2. On change, server sends SSE event to clients
+ * 3. Client receives event and either reloads or updates CSS
+ * 4. CSS updates use cache-busting query params to force fresh load
+ *
+ * Only injected in development mode; production builds do not include this.
+ */
+export const HMR_CLIENT_SCRIPT = `
+(function() {
+  console.log("[Jen.js] Connecting to HMR...");
+  const evt = new EventSource("/__hmr");
+
+  evt.onopen = () => console.log("[Jen.js] HMR Connected");
+
+  // Full page reload on route or component changes
+  evt.addEventListener("reload", () => {
+    console.log("[Jen.js] Reloading...");
+    window.location.reload();
+  });
+
+  // CSS-only reload without full page reload (faster UX for style-only changes)
+  evt.addEventListener("style-update", (e) => {
+    const file = JSON.parse(e.data).file; // e.g., "styles.css"
+    console.log("[Jen.js] Style update:", file);
+    
+    // Find matching link tags by pathname
+    const links = document.querySelectorAll('link[rel="stylesheet"]');
+    for (const link of links) {
+      const url = new URL(link.href);
+      if (url.pathname.endsWith(file)) {
+        // Force reload by updating cache-busting query param (timestamp)
+        url.searchParams.set("t", Date.now());
+        link.href = url.toString();
+        console.log("[Jen.js] Updated stylesheet:", file);
+      }
+    }
+  });
+
+  evt.onerror = () => {
+    // Connection closed; EventSource automatically retries
+    // (commented out: chatty in development; uncomment if needed for debugging)
+    // console.log("[Jen.js] HMR disconnected, retrying...");
+  };
+})();
+`;

package/templates/ssr-isr/lib/runtime/hydrate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hydrate a server-rendered page with client-side interactivity.
+ * This function is called once on page load in the browser.
+ * It attaches Preact event listeners and state management to existing DOM without re-rendering.
+ *
+ * Flow:
+ * 1. Retrieve framework data (loader result, route params, query) injected by server into page HTML
+ * 2. Dynamically import the route component module
+ * 3. Construct Preact component tree passing data as props
+ * 4. Attach to existing #app element (matches server-rendered HTML structure)
+ *
+ * Errors during hydration are logged but do not throw; the page remains functional
+ * with reduced interactivity if hydration fails.
+ *
+ * @param entryPath - Path to the route component module (e.g., "./routes/index.js")
+ *   This path is typically injected into the HTML as a script attribute by the server.
+ */
+export declare function hydrateClient(entryPath: string): Promise<void>;

package/templates/ssr-isr/lib/runtime/hydrate.js

@@ -0,0 +1,55 @@
+import { hydrate } from "preact";
+import { h } from "preact";
+import { getFrameworkData } from "./client-runtime.js";
+/**
+ * Hydrate a server-rendered page with client-side interactivity.
+ * This function is called once on page load in the browser.
+ * It attaches Preact event listeners and state management to existing DOM without re-rendering.
+ *
+ * Flow:
+ * 1. Retrieve framework data (loader result, route params, query) injected by server into page HTML
+ * 2. Dynamically import the route component module
+ * 3. Construct Preact component tree passing data as props
+ * 4. Attach to existing #app element (matches server-rendered HTML structure)
+ *
+ * Errors during hydration are logged but do not throw; the page remains functional
+ * with reduced interactivity if hydration fails.
+ *
+ * @param entryPath - Path to the route component module (e.g., "./routes/index.js")
+ *   This path is typically injected into the HTML as a script attribute by the server.
+ */
+export async function hydrateClient(entryPath) {
+  try {
+    // Retrieve loader data, params, and query injected into page HTML by server
+    const data = getFrameworkData();
+    // Dynamically import route component
+    const mod = await import(entryPath);
+    // Validate that route exports a default component
+    if (!mod.default) {
+      console.error(
+        `Failed to hydrate: route module does not export default component`,
+      );
+      return;
+    }
+    // Construct Preact VDOM tree with data as props
+    const Page = mod.default;
+    const app = h(Page, {
+      data: data?.data ?? null,
+      params: data?.params ?? {},
+      query: data?.query ?? {},
+    });
+    // Find root DOM element for hydration
+    const root = document.getElementById("app");
+    if (!root) {
+      console.error("Failed to hydrate: #app element not found in DOM");
+      return;
+    }
+    // Attach Preact to existing DOM tree without re-rendering
+    hydrate(app, root);
+  } catch (err) {
+    console.error(
+      "Hydration failed:",
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+}

package/templates/ssr-isr/lib/runtime/island-hydration-client.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Initialize island hydration when DOM is ready.
+ * Waits for DOMContentLoaded if the page is still loading, otherwise starts immediately.
+ * This ensures island DOM elements exist before hydration attempts.
+ *
+ * Called automatically on module import.
+ */
+export declare function initializeIslands(): void;

package/templates/ssr-isr/lib/runtime/island-hydration-client.js

@@ -0,0 +1,146 @@
+import { hydrate } from "preact";
+import { h } from "preact";
+/**
+ * Extract island metadata from HTML comment markers.
+ * Scans the entire document for markers in the format:
+ * <!--__ISLAND_{LOAD|IDLE|VISIBLE}__:id:componentPath:propsJson-->
+ *
+ * Silently skips malformed markers and continues processing remaining islands.
+ * This resilience allows graceful degradation if some islands fail to parse.
+ *
+ * @returns Array of detected islands ready for hydration.
+ */
+function extractIslands() {
+  const islands = [];
+  const html = document.documentElement.outerHTML;
+  // Regex matches: <!--__ISLAND_{LOAD|IDLE|VISIBLE}__:id:componentPath:propsJson-->
+  const regex = /<!--__ISLAND_(LOAD|IDLE|VISIBLE)__:([^:]+):([^:]+):(.+?)-->/g;
+  let match;
+  while ((match = regex.exec(html)) !== null) {
+    const strategy = match[1].toLowerCase();
+    const id = match[2];
+    const component = match[3];
+    // Unescape '<' that was escaped to prevent HTML parsing issues
+    const propsStr = match[4].replace(/\\u003c/g, "<");
+    try {
+      islands.push({
+        id,
+        component,
+        strategy,
+        props: JSON.parse(propsStr),
+      });
+    } catch {
+      console.warn(`Failed to parse island ${id}`);
+    }
+  }
+  return islands;
+}
+/**
+ * Hydrate a single island by importing its component and attaching Preact listeners.
+ * Dynamically imports the component module via a hydration endpoint to ensure
+ * the component code is loaded before hydration.
+ *
+ * If the DOM element (island.id) is not found, logs a warning and returns early.
+ * If the component import or hydration fails, logs an error but does not propagate.
+ * This resilience prevents one failed island from breaking others.
+ *
+ * @param island - Island metadata including id, component path, and props.
+ */
+async function hydrateIsland(island) {
+  const target = document.getElementById(island.id);
+  if (!target) {
+    console.warn(`Island target #${island.id} not found`);
+    return;
+  }
+  try {
+    // Import component via hydration endpoint which ensures proper module resolution
+    const hydrationUrl = `/__hydrate?file=${encodeURIComponent(island.component)}`;
+    const mod = await import(hydrationUrl);
+    const Component = mod.default;
+    if (!Component) {
+      console.warn(`Component not exported from ${island.component}`);
+      return;
+    }
+    // Construct Preact VDOM with island props and attach to DOM element
+    const app = h(Component, island.props);
+    hydrate(app, target);
+  } catch (err) {
+    console.error(`Failed to hydrate island ${island.id}:`, err);
+  }
+}
+/**
+ * Orchestrate island hydration based on strategy.
+ * Distributes hydration across the timeline to optimize page load performance.
+ *
+ * Strategies:
+ * - "load": Hydrate immediately (for critical above-the-fold interactive components)
+ * - "idle": Hydrate when browser is idle (requestIdleCallback, or 2000ms fallback)
+ * - "visible": Hydrate when element scrolls into view (IntersectionObserver, or 3000ms fallback)
+ *
+ * Fallbacks ensure older browsers still hydrate despite missing modern APIs.
+ *
+ * @param islands - Array of islands to hydrate.
+ */
+function hydrateWithStrategy(islands) {
+  for (const island of islands) {
+    switch (island.strategy) {
+      case "load":
+        // Hydrate immediately for critical interactive components
+        hydrateIsland(island);
+        break;
+      case "idle":
+        // Hydrate when browser is idle to avoid blocking user interaction
+        if ("requestIdleCallback" in window) {
+          requestIdleCallback(() => hydrateIsland(island));
+        } else {
+          // Fallback: hydrate after 2 seconds (allows critical path to complete)
+          setTimeout(() => hydrateIsland(island), 2000);
+        }
+        break;
+      case "visible":
+        // Hydrate only when element becomes visible in the viewport
+        if ("IntersectionObserver" in window) {
+          const target = document.getElementById(island.id);
+          if (target) {
+            const observer = new IntersectionObserver(
+              (entries) => {
+                // Hydrate on first intersection and stop observing
+                if (entries[0].isIntersecting) {
+                  hydrateIsland(island);
+                  observer.disconnect();
+                }
+              },
+              { threshold: 0.1 },
+            );
+            observer.observe(target);
+          }
+        } else {
+          // Fallback: hydrate after 3 seconds (reasonable delay for below-fold elements)
+          setTimeout(() => hydrateIsland(island), 3000);
+        }
+        break;
+    }
+  }
+}
+/**
+ * Initialize island hydration when DOM is ready.
+ * Waits for DOMContentLoaded if the page is still loading, otherwise starts immediately.
+ * This ensures island DOM elements exist before hydration attempts.
+ *
+ * Called automatically on module import.
+ */
+export function initializeIslands() {
+  if (document.readyState === "loading") {
+    // DOM still loading; wait for DOMContentLoaded before extracting islands
+    document.addEventListener("DOMContentLoaded", () => {
+      const islands = extractIslands();
+      hydrateWithStrategy(islands);
+    });
+  } else {
+    // DOM already loaded; hydrate immediately
+    const islands = extractIslands();
+    hydrateWithStrategy(islands);
+  }
+}
+// Auto-initialize on import (framework injects this script into HTML in dev mode)
+initializeIslands();

package/templates/ssr-isr/lib/runtime/islands.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Hydration strategy for interactive islands.
+ * Determines when client-side JavaScript is loaded and hydration occurs:
+ * - "load": Hydrate immediately on page load (eager)
+ * - "idle": Hydrate when browser is idle via requestIdleCallback (deferred, low-priority)
+ * - "visible": Hydrate when island becomes visible via IntersectionObserver (viewport-based)
+ */
+export type HydrationStrategy = "load" | "idle" | "visible";
+/**
+ * Props interface for islands (not actively used, provided for type reference).
+ */
+export interface IslandProps {
+  "client:load"?: boolean;
+  "client:idle"?: boolean;
+  "client:visible"?: boolean;
+}
+/**
+ * Mark a component as an interactive island for partial hydration.
+ * Islands are components that require client-side interactivity while the rest of the page
+ * remains static HTML. This enables efficient selective hydration.
+ *
+ * How it works:
+ * - Marks component with metadata (__island, __hydrationStrategy)
+ * - Server renderer detects marked components and emits HTML comments with island metadata
+ * - Client JavaScript discovers islands from HTML comments and hydrates based on strategy
+ *
+ * Usage in route:
+ *   import { Island } from "jenjs";
+ *   import CounterImpl from "./counter.tsx";
+ *   export default function Page() {
+ *     const Counter = Island(CounterImpl, "load");
+ *     return <Counter count={5} />;
+ *   }
+ *
+ * Strategies:
+ * - "load": Best for above-the-fold critical interactive components
+ * - "idle": Good for secondary interactive elements (lighter priority)
+ * - "visible": Best for below-the-fold components; hydrates only when scrolled into view
+ *
+ * @param Component - The Preact component to mark as an island.
+ * @param strategy - Hydration timing strategy.
+ * @returns The same component with island metadata attached.
+ */
+export declare function Island<P extends Record<string, any>>(
+  Component: any,
+  strategy: HydrationStrategy,
+): any;
+/**
+ * Metadata for a detected island extracted from server-rendered HTML.
+ * Includes the island's unique ID, component path, hydration strategy, and serialized props.
+ */
+export interface DetectedIsland {
+  /** Unique identifier for this island instance on the page. */
+  id: string;
+  /** Path to the component module (e.g., "./components/counter.js"). */
+  component: string;
+  /** Hydration strategy: when to hydrate this island. */
+  strategy: HydrationStrategy;
+  /** Serialized component props (deserialized from JSON in HTML comment). */
+  props: any;
+}
+/**
+ * Generate an HTML comment marker that encodes island metadata.
+ * Server renderer calls this after rendering each island component.
+ * The marker is embedded in the HTML and later parsed by the client.
+ *
+ * Format: <!--__ISLAND_{STRATEGY}__:{id}:{componentPath}:{propsJson}-->
+ * Example: <!--__ISLAND_LOAD__:island-1:./counter.js:{"count":5}-->
+ *
+ * Note: '<' in JSON is escaped to '\\u003c' to prevent breaking HTML parsing
+ * (literal '<' in props could confuse the HTML parser or regex extraction).
+ *
+ * @param id - Unique identifier for the island (e.g., "island-1", "counter-2").
+ * @param componentPath - Path to the component module.
+ * @param strategy - Hydration timing strategy.
+ * @param props - Component props object (will be JSON.stringify'd).
+ * @returns HTML comment string encoding the island metadata.
+ */
+export declare function createIslandMarker(
+  id: string,
+  componentPath: string,
+  strategy: HydrationStrategy,
+  props: any,
+): string;
+/**
+ * Extract island metadata from server-rendered HTML.
+ * Client-side function that parses island markers from HTML comments.
+ * Called during page initialization to discover which components need hydration.
+ *
+ * Parsing strategy:
+ * - Regex finds HTML comments matching the island marker format
+ * - Extracts strategy, id, componentPath, and props from comment
+ * - Validates all fields are present and props are valid JSON
+ * - Logs warnings for invalid markers but continues processing remaining islands
+ *
+ * Return value includes only valid, parseable islands; invalid ones are skipped.
+ *
+ * @param html - Server-rendered HTML string (typically document.body.innerHTML or full page HTML).
+ * @returns Array of detected islands with complete metadata ready for hydration.
+ */
+export declare function extractIslandsFromHtml(html: string): DetectedIsland[];