create-jen-app 1.2.1 → 1.2.3

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

@@ -15,14 +15,28 @@
  * You should have received a copy of the GNU General Public License
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
+/**
+ * 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 {
-        return null;
-    }
+  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/static/lib/runtime/hmr.d.ts

@@ -1 +1,23 @@
-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  evt.addEventListener(\"reload\", () => {\n    console.log(\"[Jen.js] Reloading...\");\n    window.location.reload();\n  });\n\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\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 query param\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    // console.log(\"[Jen.js] HMR disconnected, retrying...\");\n    // EventSource automatically retries\n  };\n})();\n";
+/**
+ * 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/static/lib/runtime/hmr.js

@@ -15,8 +15,27 @@
  * You should have received a copy of the GNU General Public License
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
-// Client-side Hot Module Replacement (HMR) / Live Reload
-// Injected into the browser during development
+/**
+ * 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...");
@@ -24,21 +43,23 @@ export const HMR_CLIENT_SCRIPT = `
 
   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
+    // 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 query param
+        // 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);
@@ -47,8 +68,9 @@ export const HMR_CLIENT_SCRIPT = `
   });
 
   evt.onerror = () => {
+    // Connection closed; EventSource automatically retries
+    // (commented out: chatty in development; uncomment if needed for debugging)
     // console.log("[Jen.js] HMR disconnected, retrying...");
-    // EventSource automatically retries
   };
 })();
 `;

package/templates/static/lib/runtime/hydrate.d.ts

@@ -1 +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/static/lib/runtime/hydrate.js

@@ -18,28 +18,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 {
-        const data = getFrameworkData();
-        const mod = await import(entryPath);
-        if (!mod.default) {
-            console.error(`Failed to hydrate: route module does not export default component`);
-            return;
-        }
-        const Page = mod.default;
-        const app = h(Page, {
-            data: data?.data ?? null,
-            params: data?.params ?? {},
-            query: data?.query ?? {},
-        });
-        const root = document.getElementById("app");
-        if (!root) {
-            console.error("Failed to hydrate: #app element not found in DOM");
-            return;
-        }
-        hydrate(app, root);
+  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;
     }
-    catch (err) {
-        console.error("Hydration failed:", err instanceof Error ? err.message : String(err));
+    // 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/static/lib/runtime/island-hydration-client.d.ts

@@ -1,5 +1,8 @@
 /**
- * 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 declare function initializeIslands(): void;

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

@@ -18,115 +18,146 @@
 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.d.ts

@@ -1,46 +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;
+  "client:load"?: boolean;
+  "client:idle"?: boolean;
+  "client:visible"?: boolean;
 }
 /**
- * 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 declare function Island<P extends Record<string, any>>(Component: any, strategy: HydrationStrategy): any;
+export declare function Island<P extends Record<string, any>>(
+  Component: any,
+  strategy: HydrationStrategy,
+): any;
 /**
- * Detect islands in a component tree (called by server renderer).
- * Returns array of island metadata to inject into HTML.
+ * 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 {
-    id: string;
-    component: string;
-    strategy: HydrationStrategy;
-    props: any;
+  /** 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 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 declare function createIslandMarker(id: string, componentPath: string, strategy: HydrationStrategy, props: any): string;
+export declare function createIslandMarker(
+  id: string,
+  componentPath: string,
+  strategy: HydrationStrategy,
+  props: any,
+): string;
 /**
- * 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 declare function extractIslandsFromHtml(html: string): DetectedIsland[];