@ionify/ionify 0.1.2 → 0.1.4

package/dist/client/hmr.js

@@ -12,6 +12,29 @@ const ERROR_URL = "/__ionify_hmr/error";
 const log = (...args) => console.log("[Ionify HMR]", ...args);
 const warn = (...args) => console.warn("[Ionify HMR]", ...args);
 
+// Surface runtime errors even when they don't occur during an HMR import().
+// This catches errors thrown during module evaluation and async rejections.
+globalThis.addEventListener?.("error", (event) => {
+  try {
+    const message = event?.message || "Runtime error";
+    const details = event?.error?.stack || event?.error?.message;
+    showErrorOverlay(message, details);
+  } catch {
+    // ignore
+  }
+});
+
+globalThis.addEventListener?.("unhandledrejection", (event) => {
+  try {
+    const reason = event?.reason;
+    const message = reason instanceof Error ? reason.message : "Unhandled promise rejection";
+    const details = reason instanceof Error ? reason.stack : String(reason ?? "");
+    showErrorOverlay(message, details);
+  } catch {
+    // ignore
+  }
+});
+
 // Establish SSE channel used to notify about pending graph diffs.
 const source = new EventSource(SSE_URL);
 
@@ -22,14 +45,15 @@ source.addEventListener("ready", () => {
 source.addEventListener("error", (e) => {
   warn("SSE error", e);
   // Show overlay if server streamed a structured error payload.
-  if (e?.data) {
+  const data = e && typeof e === "object" && "data" in e ? e.data : undefined;
+  if (data) {
     try {
-      const payload = JSON.parse(e.data);
+      const payload = JSON.parse(data);
       if (payload?.message) {
         showErrorOverlay(payload.message, payload.id ? `Update ${payload.id}` : undefined);
       }
     } catch {
-      showErrorOverlay(String(e.data || "HMR connection error"));
+      showErrorOverlay(String(data || "HMR connection error"));
     }
   }
 });
@@ -119,6 +143,18 @@ async function applyUpdate(payload) {
       return;
     }
   }
+
+  // If React Refresh runtime is present, trigger it after importing updated modules.
+  try {
+    const refreshRuntime = globalThis.__IONIFY_REACT_REFRESH__;
+    if (refreshRuntime?.performReactRefresh) {
+      refreshRuntime.performReactRefresh();
+      log("react refresh performed");
+    }
+  } catch (err) {
+    warn("React Refresh failed", err);
+  }
+
   log(`update ${payload?.id ?? "unknown"} applied`);
   clearErrorOverlay();
 }

package/dist/client/overlay.js

@@ -1,42 +1,157 @@
-// Basic DOM overlay used to surface build/transform errors during HMR.
-const OVERLAY_ID = "ionify-error-overlay";
+// Basic DOM overlay used to surface build/transform errors (and warnings) during HMR.
+const ERROR_OVERLAY_ID = "ionify-error-overlay";
+const WARNING_OVERLAY_ID = "ionify-warning-overlay";
 
-function ensureOverlay() {
-  let overlay = document.getElementById(OVERLAY_ID);
+function ensureOverlay(id) {
+  let overlay = document.getElementById(id);
   if (!overlay) {
     overlay = document.createElement("div");
-    overlay.id = OVERLAY_ID;
-    overlay.style.position = "fixed";
-    overlay.style.inset = "0";
-    overlay.style.background = "rgba(0,0,0,0.8)";
-    overlay.style.color = "#f87171";
-    overlay.style.fontFamily = "Menlo, Consolas, monospace";
-    overlay.style.fontSize = "14px";
-    overlay.style.padding = "32px";
-    overlay.style.zIndex = "2147483647";
-    overlay.style.overflowY = "auto";
-    overlay.style.whiteSpace = "pre-wrap";
+    overlay.id = id;
     document.body.appendChild(overlay);
   }
   return overlay;
 }
 
+function buildOverlayContent({
+  title,
+  message,
+  details,
+  onClose,
+  accentColor,
+}) {
+  const root = document.createElement("div");
+  root.style.display = "flex";
+  root.style.flexDirection = "column";
+  root.style.gap = "12px";
+
+  const headerRow = document.createElement("div");
+  headerRow.style.display = "flex";
+  headerRow.style.alignItems = "flex-start";
+  headerRow.style.justifyContent = "space-between";
+  headerRow.style.gap = "12px";
+
+  const header = document.createElement("div");
+  header.style.fontWeight = "600";
+  header.style.fontSize = "16px";
+  header.textContent = title;
+
+  const close = document.createElement("button");
+  close.type = "button";
+  close.setAttribute("aria-label", "Close overlay");
+  close.textContent = "×";
+  close.style.border = "1px solid rgba(255,255,255,0.25)";
+  close.style.background = "transparent";
+  close.style.color = "inherit";
+  close.style.borderRadius = "8px";
+  close.style.width = "32px";
+  close.style.height = "32px";
+  close.style.cursor = "pointer";
+  close.style.fontSize = "20px";
+  close.style.lineHeight = "28px";
+  close.style.padding = "0";
+  close.onclick = onClose;
+
+  headerRow.appendChild(header);
+  headerRow.appendChild(close);
+
+  const body = document.createElement("div");
+  body.textContent = message ?? "";
+
+  root.appendChild(headerRow);
+  root.appendChild(body);
+
+  if (details) {
+    const pre = document.createElement("pre");
+    pre.style.margin = "0";
+    pre.style.whiteSpace = "pre-wrap";
+    pre.style.color = accentColor;
+    pre.textContent = details;
+    root.appendChild(pre);
+  }
+
+  return root;
+}
+
 export function showErrorOverlay(message, details) {
   if (typeof document === "undefined") return;
-  const overlay = ensureOverlay();
-  const header = "Ionify Build Error";
-  overlay.innerHTML = `
-    <div style="font-weight:600;font-size:16px;margin-bottom:16px;">
-      ${header}
-    </div>
-    <div>${message ?? "Unknown error"}</div>
-    ${details ? `<pre style="margin-top:16px;color:#fca5a5;">${details}</pre>` : ""}
-  `;
+  const overlay = ensureOverlay(ERROR_OVERLAY_ID);
+
+  overlay.style.position = "fixed";
+  overlay.style.inset = "0";
+  overlay.style.background = "rgba(0,0,0,0.86)";
+  overlay.style.color = "#f87171";
+  overlay.style.fontFamily = "Menlo, Consolas, monospace";
+  overlay.style.fontSize = "14px";
+  overlay.style.padding = "32px";
+  overlay.style.zIndex = "2147483647";
+  overlay.style.overflowY = "auto";
+  overlay.style.whiteSpace = "pre-wrap";
+
+  overlay.replaceChildren(
+    buildOverlayContent({
+      title: "Ionify Build Error",
+      message: message ?? "Unknown error",
+      details,
+      onClose: clearErrorOverlay,
+      accentColor: "#fca5a5",
+    })
+  );
 }
 
 export function clearErrorOverlay() {
   if (typeof document === "undefined") return;
-  const overlay = document.getElementById(OVERLAY_ID);
+  const overlay = document.getElementById(ERROR_OVERLAY_ID);
+  if (overlay && overlay.parentElement) {
+    overlay.parentElement.removeChild(overlay);
+  }
+}
+
+export function showWarningOverlay(message, details) {
+  if (typeof document === "undefined") return;
+  const overlay = ensureOverlay(WARNING_OVERLAY_ID);
+
+  // Full-screen, transparent backdrop with a top-center panel.
+  // Keep the app interactive by letting only the panel receive pointer events.
+  overlay.style.position = "fixed";
+  overlay.style.inset = "0";
+  overlay.style.background = "rgba(0,0,0,0.35)";
+  overlay.style.zIndex = "2147483646";
+  overlay.style.pointerEvents = "none";
+
+  const panel = document.createElement("div");
+  panel.style.position = "absolute";
+  panel.style.top = "16px";
+  panel.style.left = "50%";
+  panel.style.transform = "translateX(-50%)";
+  panel.style.maxWidth = "min(760px, calc(100vw - 32px))";
+  panel.style.width = "fit-content";
+  panel.style.background = "rgba(17,24,39,0.92)";
+  panel.style.color = "#fbbf24";
+  panel.style.fontFamily = "Menlo, Consolas, monospace";
+  panel.style.fontSize = "13px";
+  panel.style.padding = "16px";
+  panel.style.border = "1px solid rgba(251,191,36,0.45)";
+  panel.style.borderRadius = "12px";
+  panel.style.boxShadow = "0 10px 30px rgba(0,0,0,0.35)";
+  panel.style.overflow = "hidden";
+  panel.style.pointerEvents = "auto";
+
+  panel.appendChild(
+    buildOverlayContent({
+      title: "Ionify Warning",
+      message: message ?? "",
+      details,
+      onClose: clearWarningOverlay,
+      accentColor: "#fde68a",
+    })
+  );
+
+  overlay.replaceChildren(panel);
+}
+
+export function clearWarningOverlay() {
+  if (typeof document === "undefined") return;
+  const overlay = document.getElementById(WARNING_OVERLAY_ID);
   if (overlay && overlay.parentElement) {
     overlay.parentElement.removeChild(overlay);
   }

package/dist/client/react-refresh-runtime.js

@@ -4,6 +4,31 @@ let installed = false;
 const moduleInfo = new Map();
 const warnedClassModules = new Set();
 
+export function normalizeRefreshModuleId(url) {
+  if (typeof url !== "string") return "";
+  if (!url.includes("?") && !url.includes("#")) return url;
+
+  // Absolute URL: keep origin + pathname + hash, drop search.
+  try {
+    const parsed = new URL(url);
+    return parsed.origin + parsed.pathname + parsed.hash;
+  } catch {
+    // Fall through for non-absolute URLs.
+  }
+
+  // Relative URL: keep pathname + hash, drop search.
+  try {
+    const parsed = new URL(url, "http://ionify.invalid");
+    return parsed.pathname + parsed.hash;
+  } catch {
+    // Final fallback: conservative string manipulation.
+  }
+
+  const [beforeHash, hash = ""] = url.split("#", 2);
+  const [pathPart] = beforeHash.split("?", 2);
+  return pathPart + (hash ? `#${hash}` : "");
+}
+
 function ensureRuntime() {
   if (installed) return RefreshRuntime;
   RefreshRuntime.injectIntoGlobalHook(window);
@@ -14,26 +39,55 @@ function ensureRuntime() {
   return RefreshRuntime;
 }
 
+// Ensure the global hook is installed as early as possible (before React modules execute).
+// Guarded so Node-side unit tests can import helpers from this file.
+if (typeof window !== "undefined") {
+  try {
+    ensureRuntime();
+  } catch {
+    // Runtime injection is best-effort; transform-side warnings handle failures.
+  }
+}
+
 export function setupReactRefresh(importMetaHot, moduleId) {
   if (!importMetaHot) return null;
   const runtime = ensureRuntime();
+  const stableModuleId = normalizeRefreshModuleId(moduleId);
 
   // Track metadata for this module so we can make refresh decisions later.
   const record = {
     hasReactExport: false,
     hasClassComponent: false,
   };
-  moduleInfo.set(moduleId, record);
+  moduleInfo.set(stableModuleId, record);
 
   const prevReg = window.$RefreshReg$;
   const prevSig = window.$RefreshSig$;
 
   window.$RefreshReg$ = (type, id) => {
-    runtime.register(type, moduleId + " " + id);
+    runtime.register(type, stableModuleId + " " + id);
     if (type) {
       record.hasReactExport = true;
       if (type.prototype && type.prototype.isReactComponent) {
         record.hasClassComponent = true;
+
+        // Show the warning even if a refresh never runs (e.g. first load),
+        // but dedupe per stable module id.
+        if (!warnedClassModules.has(stableModuleId)) {
+          const warning = `[Ionify] React Fast Refresh cannot preserve state for class components (module: ${stableModuleId}). State will reset after edits.`;
+          console.warn(warning);
+
+          if (typeof document !== "undefined") {
+            import("/__ionify_overlay.js")
+              .then((mod) => {
+                if (typeof mod?.showWarningOverlay === "function") {
+                  mod.showWarningOverlay(warning, stableModuleId);
+                }
+              })
+              .catch(() => {});
+          }
+          warnedClassModules.add(stableModuleId);
+        }
       }
     }
   };
@@ -45,17 +99,11 @@ export function setupReactRefresh(importMetaHot, moduleId) {
   };
 
   const dispose = () => {
-    moduleInfo.delete(moduleId);
+    moduleInfo.delete(stableModuleId);
   };
 
   const refresh = () => {
     if (!record.hasReactExport) return false;
-    if (record.hasClassComponent && !warnedClassModules.has(moduleId)) {
-      console.warn(
-        `[Ionify] React Fast Refresh cannot preserve state for class components (module: ${moduleId}). State will reset after edits.`
-      );
-      warnedClassModules.add(moduleId);
-    }
     queueMicrotask(() => {
       runtime.performReactRefresh();
     });

package/dist/index.d.cts

@@ -2,7 +2,21 @@ interface IonifyResolveConfig {
     baseUrl?: string;
     paths?: Record<string, string[]>;
     alias?: Record<string, string>;
+    /**
+     * File extensions to try when resolving imports.
+     * @default ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']
+     */
     extensions?: string[];
+    /**
+     * Conditions to use when resolving package.json "exports" field.
+     * @default ['import', 'module', 'browser', 'default']
+     */
+    conditions?: string[];
+    /**
+     * Fields to check in package.json for entry point resolution.
+     * @default ['module', 'jsnext:main', 'jsnext', 'main']
+     */
+    mainFields?: string[];
 }
 interface IonifyServerConfig {
     port?: number;
@@ -51,7 +65,19 @@ interface IonifyScopeHoistConfig {
     combineVariables?: boolean;
 }
 interface IonifyConfig {
+    /**
+     * Project root directory. All paths are resolved relative to root.
+     * Affects: module resolution, watcher, public URLs, CAS location.
+     * @default process.cwd()
+     */
     root?: string;
+    /**
+     * Entry point(s) for the application (relative to root or project-relative with leading '/').
+     * Accepts a single entry or multiple entries.
+     * @example '/src/main.tsx'
+     * @example ['src/main.tsx', 'src/admin.tsx']
+     */
+    entry?: string | string[];
     base?: string;
     mode?: string;
     /** Runtime-resolved minifier selection ('auto' by default). */
@@ -74,11 +100,56 @@ interface IonifyConfig {
     build?: IonifyBuildConfig;
     css?: IonifyCSSConfig;
     optimizeDeps?: {
+        /**
+         * Dependencies to pre-optimize on server start.
+         * Useful for ensuring common dependencies are bundled before first request.
+         * @example ['react', 'react-dom', 'lodash']
+         */
         include?: string[];
         exclude?: string[];
+        /**
+         * Generate sourcemaps for optimized dependencies.
+         * Disabled by default to speed up dependency optimization.
+         */
+        sourcemap?: boolean;
+        /**
+         * Bundle ESM dependencies instead of serving them as-is with proxies.
+         * When `true` (default), ESM deps are bundled into single self-contained
+         * files with synthesized named exports, eliminating request waterfalls.
+         * Set to `false` for debugging (to inspect original package source).
+         * @default true
+         */
+        bundleEsm?: boolean;
+        /**
+         * Build a framework "vendor preloader" module in dev to reduce cold-start waterfalls.
+         * - `'auto'` (default): detect framework deps from package.json and generate `vendor.<depsHash>.js`
+         * - `string[]`: explicit vendor specifiers (e.g. ['react','react-dom/client'])
+         * - `false`: disable vendor preloading
+         */
+        vendor?: "auto" | string[] | false;
+        /**
+         * @deprecated esbuildOptions are not supported in Ionify.
+         * Ionify uses native Rust optimizer. This option is ignored with a warning.
+         */
+        esbuildOptions?: Record<string, unknown>;
     };
     plugins?: any[];
+    /**
+     * Define global constant replacements.
+     * Values are JSON-stringified and replaced at compile time using AST transformation.
+     * @example
+     * define: {
+     *   __APP_VERSION__: JSON.stringify('1.0.0'),
+     *   __API_URL__: JSON.stringify('https://api.example.com'),
+     *   'process.env.NODE_ENV': JSON.stringify('production')
+     * }
+     */
     define?: Record<string, any>;
+    /**
+     * Environment variables to expose to the client.
+     * All variables starting with VITE_ or IONIFY_ are automatically exposed as import.meta.env.*
+     */
+    envPrefix?: string | string[];
 }
 
 interface BuildChunkAsset {

package/dist/index.d.ts

@@ -2,7 +2,21 @@ interface IonifyResolveConfig {
     baseUrl?: string;
     paths?: Record<string, string[]>;
     alias?: Record<string, string>;
+    /**
+     * File extensions to try when resolving imports.
+     * @default ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']
+     */
     extensions?: string[];
+    /**
+     * Conditions to use when resolving package.json "exports" field.
+     * @default ['import', 'module', 'browser', 'default']
+     */
+    conditions?: string[];
+    /**
+     * Fields to check in package.json for entry point resolution.
+     * @default ['module', 'jsnext:main', 'jsnext', 'main']
+     */
+    mainFields?: string[];
 }
 interface IonifyServerConfig {
     port?: number;
@@ -51,7 +65,19 @@ interface IonifyScopeHoistConfig {
     combineVariables?: boolean;
 }
 interface IonifyConfig {
+    /**
+     * Project root directory. All paths are resolved relative to root.
+     * Affects: module resolution, watcher, public URLs, CAS location.
+     * @default process.cwd()
+     */
     root?: string;
+    /**
+     * Entry point(s) for the application (relative to root or project-relative with leading '/').
+     * Accepts a single entry or multiple entries.
+     * @example '/src/main.tsx'
+     * @example ['src/main.tsx', 'src/admin.tsx']
+     */
+    entry?: string | string[];
     base?: string;
     mode?: string;
     /** Runtime-resolved minifier selection ('auto' by default). */
@@ -74,11 +100,56 @@ interface IonifyConfig {
     build?: IonifyBuildConfig;
     css?: IonifyCSSConfig;
     optimizeDeps?: {
+        /**
+         * Dependencies to pre-optimize on server start.
+         * Useful for ensuring common dependencies are bundled before first request.
+         * @example ['react', 'react-dom', 'lodash']
+         */
         include?: string[];
         exclude?: string[];
+        /**
+         * Generate sourcemaps for optimized dependencies.
+         * Disabled by default to speed up dependency optimization.
+         */
+        sourcemap?: boolean;
+        /**
+         * Bundle ESM dependencies instead of serving them as-is with proxies.
+         * When `true` (default), ESM deps are bundled into single self-contained
+         * files with synthesized named exports, eliminating request waterfalls.
+         * Set to `false` for debugging (to inspect original package source).
+         * @default true
+         */
+        bundleEsm?: boolean;
+        /**
+         * Build a framework "vendor preloader" module in dev to reduce cold-start waterfalls.
+         * - `'auto'` (default): detect framework deps from package.json and generate `vendor.<depsHash>.js`
+         * - `string[]`: explicit vendor specifiers (e.g. ['react','react-dom/client'])
+         * - `false`: disable vendor preloading
+         */
+        vendor?: "auto" | string[] | false;
+        /**
+         * @deprecated esbuildOptions are not supported in Ionify.
+         * Ionify uses native Rust optimizer. This option is ignored with a warning.
+         */
+        esbuildOptions?: Record<string, unknown>;
     };
     plugins?: any[];
+    /**
+     * Define global constant replacements.
+     * Values are JSON-stringified and replaced at compile time using AST transformation.
+     * @example
+     * define: {
+     *   __APP_VERSION__: JSON.stringify('1.0.0'),
+     *   __API_URL__: JSON.stringify('https://api.example.com'),
+     *   'process.env.NODE_ENV': JSON.stringify('production')
+     * }
+     */
     define?: Record<string, any>;
+    /**
+     * Environment variables to expose to the client.
+     * All variables starting with VITE_ or IONIFY_ are automatically exposed as import.meta.env.*
+     */
+    envPrefix?: string | string[];
 }
 
 interface BuildChunkAsset {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@ionify/ionify",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "description": "A web infrastructure intelligence engine",
   "bin": {
-    "ionify": "./dist/cli/index.js"
+    "ionify": "dist/cli/index.js"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -68,6 +68,7 @@
     "@types/node": "^22.0.0",
     "esbuild-plugin-alias": "^0.2.1",
     "eslint": "^9.14.0",
+    "lodash": "4.17.21",
     "tsconfig-paths": "^4.2.0",
     "tsup": "^8.0.0",
     "tsx": "^4.19.0",