heliumts 0.2.2

package/dist/client/routerManifest.js

@@ -0,0 +1,242 @@
+import React from "react";
+import { log } from "../utils/logger.js";
+/**
+ * Convert a file path to a route pattern
+ * Examples:
+ * - /src/pages/index.tsx → /
+ * - /src/pages/tasks/index.tsx → /tasks
+ * - /src/pages/tasks/[id].tsx → /tasks/:id
+ * - /src/pages/settings/profile.tsx → /settings/profile
+ * - /src/pages/blog/[...slug].tsx → /blog/*slug
+ * - /src/pages/404.tsx → __404__
+ * - /src/pages/(website)/contact.tsx → /contact
+ * - /src/pages/(portal)/dashboard.tsx → /dashboard
+ */
+function pathFromFile(file) {
+    // Remove /src/pages prefix and file extension
+    const withoutPrefix = file.replace("/src/pages", "").replace(/\.(tsx|jsx|ts|js)$/, "");
+    // Handle special files
+    if (withoutPrefix === "/404") {
+        return "__404__";
+    }
+    // Remove route groups (folders in parentheses)
+    // E.g., /(website)/contact → /contact
+    let pattern = withoutPrefix.replace(/\/\([^)]+\)/g, "");
+    // Convert /index to /
+    pattern = pattern.replace(/\/index$/, "") || "/";
+    // Convert [...param] to *param (catch-all)
+    pattern = pattern.replace(/\[\.\.\.(.+?)\]/g, "*$1");
+    // Convert [param] to :param (single dynamic segment)
+    pattern = pattern.replace(/\[(.+?)\]/g, ":$1");
+    return pattern;
+}
+/**
+ * Create a matcher function for a route pattern
+ * Supports dynamic segments like :id, :slug, etc.
+ * Supports catch-all segments like *slug for [...slug]
+ */
+function createMatcher(pattern) {
+    const segments = pattern.split("/").filter(Boolean);
+    return (path) => {
+        // Remove query string and hash
+        const cleanPath = path.split("?")[0].split("#")[0];
+        const pathSegments = cleanPath.split("/").filter(Boolean);
+        // For root path, handle specially
+        if (pattern === "/" && cleanPath === "/") {
+            return { params: {} };
+        }
+        const params = {};
+        // Check for catch-all segment (must be last)
+        const hasCatchAll = segments.some((seg) => seg.startsWith("*"));
+        if (hasCatchAll) {
+            const catchAllIndex = segments.findIndex((seg) => seg.startsWith("*"));
+            // Catch-all must be the last segment
+            if (catchAllIndex !== segments.length - 1) {
+                log("warn", `Catch-all segment must be last: ${pattern}`);
+                return null;
+            }
+            const catchAllParam = segments[catchAllIndex].slice(1); // Remove *
+            // Match segments before catch-all
+            for (let i = 0; i < catchAllIndex; i++) {
+                const seg = segments[i];
+                const value = pathSegments[i];
+                if (!value) {
+                    return null;
+                } // Not enough path segments
+                if (seg.startsWith(":")) {
+                    params[seg.slice(1)] = decodeURIComponent(value);
+                }
+                else if (seg !== value) {
+                    return null; // Static segment must match
+                }
+            }
+            // Collect remaining path segments into catch-all param as an array
+            const remainingSegments = pathSegments.slice(catchAllIndex);
+            params[catchAllParam] = remainingSegments.map((s) => decodeURIComponent(s));
+            return { params };
+        }
+        // Regular matching (no catch-all)
+        // If segment counts don't match, no match
+        if (segments.length !== pathSegments.length) {
+            return null;
+        }
+        for (let i = 0; i < segments.length; i++) {
+            const seg = segments[i];
+            const value = pathSegments[i];
+            if (seg.startsWith(":")) {
+                // Dynamic segment
+                params[seg.slice(1)] = decodeURIComponent(value);
+            }
+            else if (seg !== value) {
+                // Static segment must match exactly
+                return null;
+            }
+        }
+        return { params };
+    };
+}
+/**
+ * Get directory path from file path
+ * /src/pages/tasks/[id].tsx → /tasks
+ * /src/pages/(website)/contact.tsx → /(website)
+ */
+function getDirectoryPath(file) {
+    const withoutPrefix = file.replace("/src/pages", "").replace(/\.(tsx|jsx|ts|js)$/, "");
+    const parts = withoutPrefix.split("/");
+    parts.pop(); // Remove filename
+    return parts.join("/") || "/";
+}
+/**
+ * Build route manifest from pages directory
+ * Uses import.meta.glob to discover all page files
+ * Supports both eager and lazy loading for Suspense compatibility
+ */
+export function buildRoutes() {
+    // SSR check - return empty routes if running server-side
+    if (typeof window === "undefined") {
+        return { routes: [], NotFound: undefined, AppShell: undefined };
+    }
+    // Eagerly load all page components (for initial render and layouts)
+    const eagerPages = import.meta.glob("/src/pages/**/*.{tsx,jsx,ts,js}", {
+        eager: true,
+    });
+    // Lazy load all page components (for Suspense support)
+    const lazyPages = import.meta.glob("/src/pages/**/*.{tsx,jsx,ts,js}");
+    // Debug mode: set localStorage.setItem('helium_debug_routes', 'true') to enable
+    const debugRoutes = typeof localStorage !== "undefined" && localStorage.getItem("helium_debug_routes") === "true";
+    if (debugRoutes) {
+        console.group("[Helium Router] Discovered pages:");
+        for (const file of Object.keys(eagerPages)) {
+            console.log(`  ${file} → ${pathFromFile(file)}`);
+        }
+        console.groupEnd();
+    }
+    const routes = [];
+    let NotFound;
+    let AppShell;
+    // Build layout map: directory path -> layout component
+    const layoutMap = new Map();
+    // Track route patterns to detect collisions: pattern -> file path
+    const routePatternMap = new Map();
+    // First pass: collect all layouts
+    for (const [file, mod] of Object.entries(eagerPages)) {
+        if (file.includes("/_layout.")) {
+            const Component = mod.default;
+            if (Component) {
+                const dirPath = getDirectoryPath(file);
+                layoutMap.set(dirPath, Component);
+            }
+        }
+    }
+    // Second pass: build routes with their layouts
+    for (const [file, mod] of Object.entries(eagerPages)) {
+        // Skip layout files
+        if (file.includes("/_layout.")) {
+            continue;
+        }
+        const Component = mod.default;
+        if (!Component) {
+            log("warn", `No default export found in ${file}`);
+            continue;
+        }
+        const pathPattern = pathFromFile(file);
+        // Handle special pages
+        if (pathPattern === "__404__") {
+            NotFound = Component;
+            continue;
+        }
+        // Detect route collisions
+        const existingFile = routePatternMap.get(pathPattern);
+        if (existingFile) {
+            log("error", `Route collision detected! Multiple files resolve to the same path "${pathPattern}":`);
+            log("error", `  - ${existingFile}`);
+            log("error", `  - ${file}`);
+            log("error", `Only the first file will be used. Consider using different file names or paths.`);
+        }
+        else {
+            routePatternMap.set(pathPattern, file);
+        }
+        // Find all layouts for this route (from root to leaf)
+        const layouts = [];
+        const dirPath = getDirectoryPath(file);
+        const pathParts = dirPath.split("/").filter(Boolean);
+        // Always check for root layout first (applies to all pages)
+        const rootLayout = layoutMap.get("/");
+        if (rootLayout) {
+            layouts.push(rootLayout);
+        }
+        // Then check for layouts at each nested level
+        // This will include route group layouts and any nested folder layouts
+        for (let i = 1; i <= pathParts.length; i++) {
+            const checkPath = "/" + pathParts.slice(0, i).join("/");
+            const layout = layoutMap.get(checkPath);
+            if (layout) {
+                layouts.push(layout);
+            }
+        }
+        // Get the lazy loader for this page
+        const lazyLoader = lazyPages[file];
+        const LazyComponent = React.lazy(lazyLoader);
+        // Create route entry with both eager and lazy components
+        routes.push({
+            pathPattern,
+            matcher: createMatcher(pathPattern),
+            Component,
+            LazyComponent,
+            layouts,
+            preload: lazyLoader,
+        });
+    }
+    // Sort routes by specificity (static > dynamic > catch-all)
+    routes.sort((a, b) => {
+        const aHasCatchAll = a.pathPattern.includes("*");
+        const bHasCatchAll = b.pathPattern.includes("*");
+        const aHasDynamic = a.pathPattern.includes(":");
+        const bHasDynamic = b.pathPattern.includes(":");
+        // Catch-all routes should be last (least specific)
+        if (aHasCatchAll && !bHasCatchAll) {
+            return 1;
+        }
+        if (!aHasCatchAll && bHasCatchAll) {
+            return -1;
+        }
+        // Dynamic routes come after static routes
+        if (aHasDynamic && !bHasDynamic) {
+            return 1;
+        }
+        if (!aHasDynamic && bHasDynamic) {
+            return -1;
+        }
+        // Longer paths first (more specific)
+        return b.pathPattern.length - a.pathPattern.length;
+    });
+    if (debugRoutes) {
+        console.group("[Helium Router] Final route order:");
+        for (const route of routes) {
+            console.log(`  ${route.pathPattern}`);
+        }
+        console.groupEnd();
+    }
+    return { routes, NotFound, AppShell };
+}
+//# sourceMappingURL=routerManifest.js.map

package/dist/client/routerManifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routerManifest.js","sourceRoot":"","sources":["../../src/client/routerManifest.ts"],"names":[],"mappings":"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"}

package/dist/client/rpcClient.d.ts

@@ -0,0 +1,33 @@
+import type { RpcStats } from "../runtime/protocol.js";
+export type RpcResult<T> = {
+    data: T;
+    stats: RpcStats;
+};
+/**
+ * Transport mode for RPC calls.
+ * - "http": Uses HTTP POST requests (faster on mobile/high-latency networks, benefits from HTTP/2)
+ * - "websocket": Uses persistent WebSocket connection (lower latency on desktop/low-latency networks)
+ * - "auto": Automatically selects based on connection type
+ */
+export type RpcTransport = "http" | "websocket" | "auto";
+/**
+ * Get the configured RPC transport mode (from helium.config.js).
+ */
+export declare function getRpcTransport(): RpcTransport;
+/**
+ * Check if auto HTTP on mobile is enabled (from helium.config.js).
+ */
+export declare function isAutoHttpOnMobileEnabled(): boolean;
+/**
+ * Make an RPC call using the appropriate transport.
+ * Automatically selects HTTP or WebSocket based on network conditions and configuration.
+ */
+export declare function rpcCall<TResult = unknown, TArgs = unknown>(methodId: string, args?: TArgs): Promise<RpcResult<TResult>>;
+/**
+ * Pre-establishes the WebSocket connection.
+ * Call this early (e.g., on page load) to avoid connection latency on first RPC call.
+ * This is especially beneficial on high-latency networks like mobile LTE.
+ * Note: Only effective when using WebSocket transport (not HTTP transport).
+ */
+export declare function preconnect(): void;
+//# sourceMappingURL=rpcClient.d.ts.map

package/dist/client/rpcClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpcClient.d.ts","sourceRoot":"","sources":["../../src/client/rpcClient.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAA2B,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEhF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACvB,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE,QAAQ,CAAC;CACnB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAUzD;;GAEG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AA4XD;;;GAGG;AACH,wBAAsB,OAAO,CAAC,OAAO,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAY7H;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAYjC"}

package/dist/client/rpcClient.js

@@ -0,0 +1,383 @@
+import { decode as msgpackDecode, encode as msgpackEncode } from "@msgpack/msgpack";
+// Read build-time config with fallback defaults
+const configuredTransport = typeof __HELIUM_RPC_TRANSPORT__ !== "undefined" ? __HELIUM_RPC_TRANSPORT__ : "websocket";
+const configuredAutoHttpOnMobile = typeof __HELIUM_RPC_AUTO_HTTP_ON_MOBILE__ !== "undefined" ? __HELIUM_RPC_AUTO_HTTP_ON_MOBILE__ : false;
+/**
+ * Get the configured RPC transport mode (from helium.config.js).
+ */
+export function getRpcTransport() {
+    return configuredTransport;
+}
+/**
+ * Check if auto HTTP on mobile is enabled (from helium.config.js).
+ */
+export function isAutoHttpOnMobileEnabled() {
+    return configuredAutoHttpOnMobile;
+}
+// Detect if we should prefer HTTP transport (mobile/slow networks)
+function shouldUseHttpTransport() {
+    if (configuredTransport === "http") {
+        return true;
+    }
+    if (configuredTransport === "websocket") {
+        return false;
+    }
+    // Auto mode: check if mobile HTTP optimization is enabled
+    if (!configuredAutoHttpOnMobile) {
+        return false;
+    }
+    // Prefer HTTP on mobile/slow connections
+    if (typeof navigator !== "undefined") {
+        const conn = navigator.connection;
+        if (conn) {
+            // Use HTTP for cellular connections or slow effective types
+            const slowTypes = ["slow-2g", "2g", "3g"];
+            if (conn.type === "cellular" || (conn.effectiveType && slowTypes.includes(conn.effectiveType))) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+let pendingBatch = [];
+let isBatchScheduled = false;
+function scheduleBatch() {
+    if (isBatchScheduled) {
+        return;
+    }
+    isBatchScheduled = true;
+    queueMicrotask(() => {
+        isBatchScheduled = false;
+        flushBatch();
+    });
+}
+async function flushBatch() {
+    const batch = pendingBatch;
+    pendingBatch = [];
+    if (batch.length === 0) {
+        return;
+    }
+    try {
+        if (shouldUseHttpTransport()) {
+            await sendBatchHttp(batch);
+        }
+        else {
+            await sendBatchWebSocket(batch);
+        }
+    }
+    catch (err) {
+        // Transport error, fail all
+        for (const item of batch) {
+            item.reject(err);
+        }
+    }
+}
+async function sendBatchHttp(batch) {
+    const requests = batch.map((b) => b.req);
+    const encoded = msgpackEncode(requests);
+    const response = await fetch("/__helium__/rpc", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/msgpack",
+            Accept: "application/msgpack",
+        },
+        body: encoded,
+    });
+    if (!response.ok) {
+        throw new Error(`HTTP RPC failed: ${response.status}`);
+    }
+    const responseBuffer = await response.arrayBuffer();
+    const msg = msgpackDecode(new Uint8Array(responseBuffer));
+    const responses = Array.isArray(msg) ? msg : [msg];
+    const responseMap = new Map(responses.map((r) => [r.id, r]));
+    for (const item of batch) {
+        const res = responseMap.get(item.req.id);
+        if (res) {
+            if (res.ok) {
+                item.resolve({ data: res.result, stats: res.stats });
+            }
+            else {
+                item.reject({ error: res.error, stats: res.stats });
+            }
+        }
+        else {
+            item.reject(new Error("No response for request"));
+        }
+    }
+}
+async function sendBatchWebSocket(batch) {
+    const ws = await ensureSocketReady();
+    const requests = batch.map((b) => b.req);
+    // Register pending promises
+    batch.forEach((item) => {
+        pending.set(item.req.id, {
+            resolve: (v) => item.resolve(v),
+            reject: item.reject,
+        });
+    });
+    try {
+        // Always use msgpack encoding
+        const encoded = msgpackEncode(requests);
+        ws.send(encoded);
+    }
+    catch (err) {
+        batch.forEach((item) => {
+            pending.delete(item.req.id);
+            item.reject(err);
+        });
+    }
+}
+// ============================================================================
+// WebSocket Transport (original implementation)
+// ============================================================================
+let socket = null;
+let connectionPromise = null;
+const pending = new Map();
+// Clean up WebSocket connection on HMR (Hot Module Replacement)
+if (import.meta.hot) {
+    import.meta.hot.dispose(() => {
+        if (socket) {
+            // Close the socket gracefully
+            socket.close();
+            socket = null;
+            connectionPromise = null;
+        }
+        // Reject all pending requests
+        pending.forEach((entry) => {
+            entry.reject(new Error("Module reloaded"));
+        });
+        pending.clear();
+    });
+}
+let msgId = 0;
+function nextId() {
+    return msgId++;
+}
+async function fetchFreshToken() {
+    try {
+        const response = await fetch("/__helium__/refresh-token");
+        if (!response.ok) {
+            console.warn("Failed to fetch fresh token:", response.status);
+            return undefined;
+        }
+        const data = await response.json();
+        return data.token;
+    }
+    catch (error) {
+        console.warn("Error fetching fresh token:", error);
+        return undefined;
+    }
+}
+async function createSocket() {
+    // Fetch a fresh token before creating the WebSocket connection
+    const token = await fetchFreshToken();
+    // Use the same protocol, hostname and port as the current page
+    const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+    const host = window.location.host; // includes hostname and port
+    const url = `${protocol}//${host}/rpc${token ? `?token=${token}` : ""}`;
+    const ws = new WebSocket(url);
+    ws.binaryType = "arraybuffer";
+    ws.onmessage = async (event) => {
+        let data = new Uint8Array(event.data);
+        // Check for Gzip header (0x1f 0x8b) to detect compressed messages
+        if (data.length > 2 && data[0] === 0x1f && data[1] === 0x8b) {
+            try {
+                // Use DecompressionStream if available (Chrome 80+, Firefox 113+, Safari 16.4+)
+                if (typeof DecompressionStream !== "undefined") {
+                    const ds = new DecompressionStream("gzip");
+                    const stream = new Response(data).body;
+                    if (stream) {
+                        const decompressed = stream.pipeThrough(ds);
+                        const buffer = await new Response(decompressed).arrayBuffer();
+                        data = new Uint8Array(buffer);
+                    }
+                }
+            }
+            catch (err) {
+                console.error("Failed to decompress WebSocket message:", err);
+                return;
+            }
+        }
+        // Always expect binary MessagePack
+        const msg = msgpackDecode(data);
+        const handleResponse = (res) => {
+            const entry = pending.get(res.id);
+            if (!entry) {
+                return;
+            }
+            pending.delete(res.id);
+            if (res.ok) {
+                entry.resolve({ data: res.result, stats: res.stats });
+            }
+            else {
+                entry.reject({ error: res.error, stats: res.stats });
+            }
+        };
+        if (Array.isArray(msg)) {
+            msg.forEach(handleResponse);
+        }
+        else {
+            handleResponse(msg);
+        }
+    };
+    ws.onclose = () => {
+        if (socket === ws) {
+            socket = null;
+            connectionPromise = null;
+        }
+    };
+    return ws;
+}
+async function ensureSocketReady() {
+    // If we have an open socket, return it immediately
+    if (socket && socket.readyState === WebSocket.OPEN) {
+        return socket;
+    }
+    // If we have a connection in progress, reuse that promise
+    if (connectionPromise) {
+        return connectionPromise;
+    }
+    // If we have a socket that's connecting, wait for it
+    if (socket && socket.readyState === WebSocket.CONNECTING) {
+        connectionPromise = new Promise((resolve, reject) => {
+            const cleanup = () => {
+                socket.removeEventListener("open", handleOpen);
+                socket.removeEventListener("error", handleError);
+                socket.removeEventListener("close", handleClose);
+            };
+            const handleOpen = () => {
+                cleanup();
+                connectionPromise = null;
+                resolve(socket);
+            };
+            const handleError = () => {
+                cleanup();
+                socket = null;
+                connectionPromise = null;
+                reject(new Error("WebSocket connection failed"));
+            };
+            const handleClose = () => {
+                cleanup();
+                socket = null;
+                connectionPromise = null;
+                reject(new Error("WebSocket closed before opening"));
+            };
+            socket.addEventListener("open", handleOpen);
+            socket.addEventListener("error", handleError);
+            socket.addEventListener("close", handleClose);
+        });
+        return connectionPromise;
+    }
+    // Create a new socket and connection promise
+    connectionPromise = (async () => {
+        socket = await createSocket();
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                socket.removeEventListener("open", handleOpen);
+                socket.removeEventListener("error", handleError);
+                socket.removeEventListener("close", handleClose);
+            };
+            const handleOpen = () => {
+                cleanup();
+                connectionPromise = null;
+                resolve(socket);
+            };
+            const handleError = () => {
+                cleanup();
+                socket = null;
+                connectionPromise = null;
+                reject(new Error("WebSocket connection failed"));
+            };
+            const handleClose = () => {
+                cleanup();
+                socket = null;
+                connectionPromise = null;
+                reject(new Error("WebSocket closed before opening"));
+            };
+            socket.addEventListener("open", handleOpen);
+            socket.addEventListener("error", handleError);
+            socket.addEventListener("close", handleClose);
+        });
+    })();
+    return connectionPromise;
+}
+async function rpcCallWebSocket(methodId, args) {
+    // Optimization: If socket is open, send immediately without awaiting ensureSocketReady (which adds a microtask tick)
+    if (socket && socket.readyState === WebSocket.OPEN) {
+        const id = nextId();
+        const req = { id, method: methodId, args };
+        return new Promise((resolve, reject) => {
+            pending.set(id, {
+                resolve: (v) => resolve(v),
+                reject,
+            });
+            try {
+                const encoded = msgpackEncode(req);
+                socket.send(encoded);
+            }
+            catch (err) {
+                pending.delete(id);
+                reject(err);
+            }
+        });
+    }
+    const ws = await ensureSocketReady();
+    const id = nextId();
+    const req = { id, method: methodId, args };
+    return new Promise((resolve, reject) => {
+        pending.set(id, {
+            resolve: (v) => resolve(v),
+            reject,
+        });
+        try {
+            // Always use msgpack encoding
+            const encoded = msgpackEncode(req);
+            ws.send(encoded);
+        }
+        catch (err) {
+            pending.delete(id);
+            reject(err);
+        }
+    });
+}
+/**
+ * Make an RPC call using the appropriate transport.
+ * Automatically selects HTTP or WebSocket based on network conditions and configuration.
+ */
+export async function rpcCall(methodId, args) {
+    if (shouldUseHttpTransport()) {
+        const id = nextId();
+        const req = { id, method: methodId, args };
+        return new Promise((resolve, reject) => {
+            pendingBatch.push({ req, resolve: resolve, reject });
+            scheduleBatch();
+        });
+    }
+    return rpcCallWebSocket(methodId, args);
+}
+/**
+ * Pre-establishes the WebSocket connection.
+ * Call this early (e.g., on page load) to avoid connection latency on first RPC call.
+ * This is especially beneficial on high-latency networks like mobile LTE.
+ * Note: Only effective when using WebSocket transport (not HTTP transport).
+ */
+export function preconnect() {
+    if (typeof window === "undefined") {
+        return;
+    }
+    // Only preconnect if we're using WebSocket transport
+    if (shouldUseHttpTransport()) {
+        return;
+    }
+    // Fire and forget - establishes connection in background
+    ensureSocketReady().catch(() => {
+        // Silently ignore preconnect failures, will retry on actual call
+    });
+}
+// Auto-preconnect when the module loads (browser only, WebSocket transport only)
+if (typeof window !== "undefined" && typeof document !== "undefined") {
+    // Use requestIdleCallback if available, otherwise setTimeout
+    const schedulePreconnect = window.requestIdleCallback || ((cb) => setTimeout(cb, 1));
+    schedulePreconnect(() => preconnect());
+}
+//# sourceMappingURL=rpcClient.js.map