create-jen-app 1.2.2 → 1.2.4

package/templates/static/lib/runtime/island-hydration-client.js

@@ -1,132 +1,146 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- */
 import { hydrate } from "preact";
 import { h } from "preact";
 /**
- * Extract islands from HTML markers
- * Format: <!--__ISLAND_LOAD__:id:componentPath:props-->
+ * 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;
-    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];
-        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}`);
-        }
+  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;
+  }
+  return islands;
 }
 /**
- * Hydrate a single island
+ * 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 the hydration module for this route
-        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;
-        }
-        const app = h(Component, island.props);
-        hydrate(app, target);
-    }
-    catch (err) {
-        console.error(`Failed to hydrate island ${island.id}:`, err);
+  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);
+  }
 }
 /**
- * Hydrate islands based on strategy
+ * 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
-                hydrateIsland(island);
-                break;
-            case "idle":
-                // Hydrate when browser is idle
-                if ("requestIdleCallback" in window) {
-                    requestIdleCallback(() => hydrateIsland(island));
-                }
-                else {
-                    // Fallback: hydrate after a delay
-                    setTimeout(() => hydrateIsland(island), 2000);
-                }
-                break;
-            case "visible":
-                // Hydrate when element is visible
-                if ("IntersectionObserver" in window) {
-                    const target = document.getElementById(island.id);
-                    if (target) {
-                        const observer = new IntersectionObserver((entries) => {
-                            if (entries[0].isIntersecting) {
-                                hydrateIsland(island);
-                                observer.disconnect();
-                            }
-                        }, { threshold: 0.1 });
-                        observer.observe(target);
-                    }
-                }
-                else {
-                    // Fallback: hydrate after delay
-                    setTimeout(() => hydrateIsland(island), 3000);
+  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();
                 }
-                break;
+              },
+              { 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
- * Called by framework at page load
+ * 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") {
-        document.addEventListener("DOMContentLoaded", () => {
-            const islands = extractIslands();
-            hydrateWithStrategy(islands);
-        });
-    }
-    else {
-        const islands = extractIslands();
-        hydrateWithStrategy(islands);
-    }
+  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
+// Auto-initialize on import (framework injects this script into HTML in dev mode)
 initializeIslands();

package/templates/static/lib/runtime/islands.js

@@ -1,89 +1,110 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- */
 /**
- * Mark a component as an interactive island.
- * Wraps component with hydration metadata.
+ * 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";
- *   const Counter = Island(CounterImpl, "load");
- *
- * Then use in JSX: <Counter count={5} />
+ *   import CounterImpl from "./counter.tsx";
+ *   export default function Page() {
+ *     const Counter = Island(CounterImpl, "load");
+ *     return <Counter count={5} />;
+ *   }
  *
- * Server will:
- * - Render the component to HTML
- * - Emit hydration markers
- * - Include serialized props
+ * 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
  *
- * Client will:
- * - Discover islands from markers
- * - Hydrate based on strategy
+ * @param Component - The Preact component to mark as an island.
+ * @param strategy - Hydration timing strategy.
+ * @returns The same component with island metadata attached.
  */
 export function Island(Component, strategy) {
-    // Mark component metadata for server-side detection
-    Component.__island = true;
-    Component.__hydrationStrategy = strategy;
-    return Component;
+  // Mark component metadata for server-side detection during SSR
+  Component.__island = true;
+  Component.__hydrationStrategy = strategy;
+  return Component;
 }
 /**
- * Generate island hydration markers for server-rendered HTML.
- * Call this after SSR to inject island metadata.
+ * 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 function createIslandMarker(id, componentPath, strategy, props) {
-    const propsJson = JSON.stringify(props).replace(/</g, "\\u003c");
-    return `<!--__ISLAND_${strategy.toUpperCase()}__:${id}:${componentPath}:${propsJson}-->`;
+  const propsJson = JSON.stringify(props).replace(/</g, "\\u003c");
+  return `<!--__ISLAND_${strategy.toUpperCase()}__:${id}:${componentPath}:${propsJson}-->`;
 }
 /**
- * Extract islands from server-rendered HTML.
- * Called by client to discover islands and their hydration strategy.
+ * 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 function extractIslandsFromHtml(html) {
-    const islands = [];
-    // Match: <!--__ISLAND_LOAD__:id:componentPath:props-->
-    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 componentPath = match[3];
-        const propsStr = match[4].replace(/\\u003c/g, "<");
-        // Validate island ID and component path
-        if (!id || !componentPath) {
-            console.warn('Invalid island marker: missing id or componentPath');
-            continue;
-        }
-        try {
-            // Validate props is valid JSON
-            const props = JSON.parse(propsStr);
-            if (typeof props !== 'object' || props === null) {
-                console.warn(`Invalid props for island ${id}: expected object, got ${typeof props}`);
-                continue;
-            }
-            islands.push({
-                id,
-                component: componentPath,
-                strategy,
-                props,
-            });
-        }
-        catch (err) {
-            console.warn(`Failed to parse props for island ${id}:`, err instanceof Error ? err.message : String(err));
-        }
+  const islands = [];
+  // Regex to match: <!--__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 componentPath = match[3];
+    // Unescape '<' back to literal character
+    const propsStr = match[4].replace(/\\u003c/g, "<");
+    // Validate required fields
+    if (!id || !componentPath) {
+      console.warn("Invalid island marker: missing id or componentPath");
+      continue;
+    }
+    try {
+      // Parse props JSON and validate it's an object
+      const props = JSON.parse(propsStr);
+      if (typeof props !== "object" || props === null) {
+        console.warn(
+          `Invalid props for island ${id}: expected object, got ${typeof props}`,
+        );
+        continue;
+      }
+      islands.push({
+        id,
+        component: componentPath,
+        strategy,
+        props,
+      });
+    } catch (err) {
+      console.warn(
+        `Failed to parse props for island ${id}:`,
+        err instanceof Error ? err.message : String(err),
+      );
     }
-    return islands;
+  }
+  return islands;
 }