ziex 0.1.0-dev.547 → 0.1.0-dev.562

package/README.md

@@ -122,6 +122,7 @@ const zx = @import("zx");
     - [x] Page
     - [ ] Assets
 - [x] API Route
+    - [x] Websocket Route
 - [ ] Plugin (_Alpha_)
     - [x] Builtin TailwindCSS and Esbuild
     - [x] Command based plugin system

package/index.js

@@ -1,7 +1,7 @@
 // src/index.ts
 var zx = {
   name: "zx",
-  version: "0.1.0-dev.547",
+  version: "0.1.0-dev.562",
   description: "ZX is a framework for building web applications with Zig.",
   repository: "https://github.com/nurulhudaapon/zx",
   fingerprint: 14616285862371232000,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ziex",
-  "version": "0.1.0-dev.547",
+  "version": "0.1.0-dev.562",
   "description": "ZX is a framework for building web applications with Zig.",
   "main": "index.js",
   "type": "module",

package/react/dom.d.ts

@@ -1,162 +1,21 @@
 import type { ComponentMetadata } from "./types";
-/**
- * Result of preparing a component for hydration.
- *
- * Contains all the necessary data to render a React component into its server-rendered container.
- */
 export type PreparedComponent = {
-    /**
-     * The HTML element where the component should be rendered.
-     *
-     * This is a container element created between the comment markers. The server-rendered
-     * content is moved into this container, and React will hydrate it with the interactive component.
-     *
-     * @example
-     * ```tsx
-     * // Server-rendered HTML with comment markers:
-     * // <!--$zx-abc123-0 CounterComponent {"max_count":10}-->
-     * // <button>0</button>
-     * // <!--/$zx-abc123-0-->
-     *
-     * const { domNode } = await prepareComponent(component);
-     * createRoot(domNode).render(<Component {...props} />);
-     * ```
-     */
     domNode: HTMLElement;
-    /**
-     * Component props parsed from the comment marker.
-     *
-     * Props are extracted from the start comment marker content. The comment format is:
-     * `<!--$id name props-->` where props is JSON-encoded.
-     *
-     * @example
-     * ```tsx
-     * // Server-rendered HTML:
-     * // <!--$zx-abc123-0 CounterComponent {"max_count":10,"label":"Counter"}-->
-     * // <button>0</button>
-     * // <!--/$zx-abc123-0-->
-     *
-     * const { props } = await prepareComponent(component);
-     * // props = { max_count: 10, label: "Counter" }
-     * ```
-     */
     props: Record<string, any> & {
-        /**
-         * React's special prop for setting inner HTML directly.
-         *
-         * May be used when the component has server-rendered children that should
-         * be preserved during hydration.
-         */
         dangerouslySetInnerHTML?: {
             __html: string;
         };
     };
-    /**
-     * The loaded React component function ready to render.
-     *
-     * This is the default export from the component module, lazy-loaded via the component's
-     * import function. The component is ready to be rendered with React's `createRoot().render()`.
-     *
-     * @example
-     * ```tsx
-     * const { Component, props, domNode } = await prepareComponent(component);
-     *
-     * // Component is the default export from the component file:
-     * // export default function CounterComponent({ max_count }: { max_count: number }) {
-     * //   return <div>Count: {max_count}</div>;
-     * // }
-     *
-     * createRoot(domNode).render(<Component {...props} />);
-     * ```
-     */
     Component: (props: any) => React.ReactElement;
 };
-/**
- * Prepares a client-side component for hydration by locating its comment markers, extracting
- * props from the marker content, and lazy-loading the component module.
- *
- * This function bridges server-rendered HTML (from ZX's Zig transpiler) and client-side React
- * components. It searches for comment markers in the format `<!--$id name props-->...<!--/$id-->`
- * and extracts the component data from the marker content.
- *
- * @param component - The component metadata containing ID, import function, and other metadata
- *                    needed to locate and load the component
- *
- * @returns A Promise that resolves to a `PreparedComponent` object containing the DOM node,
- *          parsed props, and the loaded React component function
- *
- * @throws {Error} If the component's comment markers cannot be found in the DOM. This typically
- *                 happens if the component ID doesn't match any marker, the script runs before
- *                 the HTML is loaded, or there's a mismatch between server and client metadata
- *
- * @example
- * ```tsx
- * // Basic usage with React:
- * import { createRoot } from "react-dom/client";
- * import { prepareComponent } from "ziex";
- * import { components } from "@ziex/components";
- *
- * for (const component of components) {
- *   prepareComponent(component).then(({ domNode, Component, props }) => {
- *     createRoot(domNode).render(<Component {...props} />);
- *   }).catch(console.error);
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Server-rendered HTML with comment markers:
- * // <!--$zx-abc123-0 CounterComponent {"max_count":10}-->
- * // <button>0</button>
- * // <!--/$zx-abc123-0-->
- * ```
- */
 export declare function prepareComponent(component: ComponentMetadata): Promise<PreparedComponent>;
 export declare function filterComponents(components: ComponentMetadata[]): ComponentMetadata[];
-/**
- * Discovered component from DOM traversal.
- * Contains all metadata needed to hydrate the component.
- */
 export type DiscoveredComponent = {
     id: string;
     name: string;
     props: Record<string, any>;
     container: HTMLElement;
 };
-/**
- * Finds all React component markers in the DOM and returns their metadata.
- *
- * This is a DOM-first approach that:
- * 1. Walks the DOM to find all `<!--$id name props-->` comment markers
- * 2. Extracts name and props directly from the comment content (JSON-encoded)
- * 3. Creates containers for React to render into
- *
- * @returns Array of discovered components with their containers and props
- */
 export declare function discoverComponents(): DiscoveredComponent[];
-/**
- * Component registry mapping component names to their import functions.
- */
 export type ComponentRegistry = Record<string, () => Promise<(props: any) => React.ReactElement>>;
-/**
- * Hydrates all React components found in the DOM.
- *
- * This is the simplest way to hydrate React islands - it automatically:
- * 1. Discovers all component markers in the DOM
- * 2. Looks up components by name in the registry
- * 3. Renders each component into its container
- *
- * @param registry - Map of component names to import functions
- * @param render - Function to render a component (e.g., `(el, Component, props) => createRoot(el).render(<Component {...props} />)`)
- *
- * @example
- * ```ts
- * import { hydrateAll } from "ziex/react";
- *
- * hydrateAll({
- *   CounterComponent: () => import("./Counter"),
- *   ToggleComponent: () => import("./Toggle"),
- * });
- * ```
- */
 export declare function hydrateAll(registry: ComponentRegistry, render: (container: HTMLElement, Component: (props: any) => React.ReactElement, props: Record<string, any>) => void): Promise<void>;

package/react/index.js

@@ -72,6 +72,9 @@ function discoverComponents() {
       if (spaceIdx !== -1) {
         const id = text.slice(1, spaceIdx);
         const content = text.slice(spaceIdx + 1);
+        if (content.startsWith("[")) {
+          continue;
+        }
         const jsonStart = content.indexOf("{");
         let name = "";
         let props = {};

package/wasm/index.d.ts

@@ -1,7 +1,7 @@
 import { ZigJS } from "../../../../vendor/jsz/js/src";
 /**
  * ZX Client Bridge - Unified JS↔WASM communication layer
- * Handles events, fetch, timers, and other async callbacks using jsz
+ * Handles events, fetch, WebSocket, timers, and other async callbacks using jsz
  */
 export declare const CallbackType: {
     readonly Event: 0;
@@ -9,6 +9,10 @@ export declare const CallbackType: {
     readonly FetchError: 2;
     readonly Timeout: 3;
     readonly Interval: 4;
+    readonly WebSocketOpen: 5;
+    readonly WebSocketMessage: 6;
+    readonly WebSocketError: 7;
+    readonly WebSocketClose: 8;
 };
 export type CallbackTypeValue = typeof CallbackType[keyof typeof CallbackType];
 export declare const jsz: ZigJS;
@@ -29,6 +33,15 @@ export declare class ZxBridge {
     setInterval(callbackId: bigint, intervalMs: number): void;
     /** Clear an interval */
     clearInterval(callbackId: bigint): void;
+    /**
+     * Create and connect a WebSocket.
+     * Calls __zx_ws_onopen, __zx_ws_onmessage, __zx_ws_onerror, __zx_ws_onclose.
+     */
+    wsConnect(wsId: bigint, urlPtr: number, urlLen: number, protocolsPtr: number, protocolsLen: number): void;
+    /** Send data over WebSocket */
+    wsSend(wsId: bigint, dataPtr: number, dataLen: number, isBinary: number): void;
+    /** Close WebSocket connection */
+    wsClose(wsId: bigint, code: number, reasonPtr: number, reasonLen: number): void;
     /** Handle a DOM event (called by event delegation) */
     eventbridge(velementId: bigint, eventTypeId: number, event: Event): void;
     /** Create the import object for WASM instantiation */

package/wasm/index.js

@@ -173,7 +173,11 @@ var CallbackType = {
   FetchSuccess: 1,
   FetchError: 2,
   Timeout: 3,
-  Interval: 4
+  Interval: 4,
+  WebSocketOpen: 5,
+  WebSocketMessage: 6,
+  WebSocketError: 7,
+  WebSocketClose: 8
 };
 var jsz = new ZigJS;
 var tempRefBuffer = new ArrayBuffer(8);
@@ -197,6 +201,7 @@ function writeBytes(ptr, data) {
 class ZxBridge {
   #exports;
   #intervals = new Map;
+  #websockets = new Map;
   constructor(exports) {
     this.#exports = exports;
   }
@@ -206,6 +211,18 @@ class ZxBridge {
   get #fetchCompleteHandler() {
     return this.#exports.__zx_fetch_complete;
   }
+  get #wsOnOpenHandler() {
+    return this.#exports.__zx_ws_onopen;
+  }
+  get #wsOnMessageHandler() {
+    return this.#exports.__zx_ws_onmessage;
+  }
+  get #wsOnErrorHandler() {
+    return this.#exports.__zx_ws_onerror;
+  }
+  get #wsOnCloseHandler() {
+    return this.#exports.__zx_ws_onclose;
+  }
   #invoke(type, id, data) {
     const handler = this.#handler;
     if (!handler) {
@@ -289,6 +306,105 @@ class ZxBridge {
       this.#intervals.delete(callbackId);
     }
   }
+  wsConnect(wsId, urlPtr, urlLen, protocolsPtr, protocolsLen) {
+    const url = readString(urlPtr, urlLen);
+    const protocolsStr = protocolsLen > 0 ? readString(protocolsPtr, protocolsLen) : "";
+    const protocols = protocolsStr ? protocolsStr.split(",").map((p) => p.trim()).filter(Boolean) : undefined;
+    try {
+      const ws = protocols && protocols.length > 0 ? new WebSocket(url, protocols) : new WebSocket(url);
+      ws.binaryType = "arraybuffer";
+      ws.onopen = () => {
+        const handler = this.#wsOnOpenHandler;
+        if (!handler)
+          return;
+        const protocol = ws.protocol || "";
+        const { ptr, len } = this.#writeStringToWasm(protocol);
+        handler(wsId, ptr, len);
+      };
+      ws.onmessage = (event) => {
+        const handler = this.#wsOnMessageHandler;
+        if (!handler)
+          return;
+        const isBinary = event.data instanceof ArrayBuffer;
+        let data;
+        if (isBinary) {
+          data = new Uint8Array(event.data);
+        } else {
+          data = new TextEncoder().encode(event.data);
+        }
+        const { ptr, len } = this.#writeBytesToWasm(data);
+        handler(wsId, ptr, len, isBinary ? 1 : 0);
+      };
+      ws.onerror = (event) => {
+        const handler = this.#wsOnErrorHandler;
+        if (!handler)
+          return;
+        const msg = "WebSocket error";
+        const { ptr, len } = this.#writeStringToWasm(msg);
+        handler(wsId, ptr, len);
+      };
+      ws.onclose = (event) => {
+        const handler = this.#wsOnCloseHandler;
+        if (!handler)
+          return;
+        const reason = event.reason || "";
+        const { ptr, len } = this.#writeStringToWasm(reason);
+        handler(wsId, event.code, ptr, len, event.wasClean ? 1 : 0);
+        this.#websockets.delete(wsId);
+      };
+      this.#websockets.set(wsId, ws);
+    } catch (error) {
+      const handler = this.#wsOnErrorHandler;
+      if (handler) {
+        const msg = error instanceof Error ? error.message : "WebSocket connection failed";
+        const { ptr, len } = this.#writeStringToWasm(msg);
+        handler(wsId, ptr, len);
+      }
+    }
+  }
+  wsSend(wsId, dataPtr, dataLen, isBinary) {
+    const ws = this.#websockets.get(wsId);
+    if (!ws || ws.readyState !== WebSocket.OPEN)
+      return;
+    const memory = new Uint8Array(jsz.memory.buffer);
+    const data = memory.slice(dataPtr, dataPtr + dataLen);
+    if (isBinary) {
+      ws.send(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength));
+    } else {
+      ws.send(new TextDecoder().decode(data));
+    }
+  }
+  wsClose(wsId, code, reasonPtr, reasonLen) {
+    const ws = this.#websockets.get(wsId);
+    if (!ws)
+      return;
+    const reason = reasonLen > 0 ? readString(reasonPtr, reasonLen) : undefined;
+    try {
+      if (reason) {
+        ws.close(code, reason);
+      } else {
+        ws.close(code);
+      }
+    } catch {
+      ws.close();
+    }
+  }
+  #writeStringToWasm(str) {
+    const encoded = new TextEncoder().encode(str);
+    return this.#writeBytesToWasm(encoded);
+  }
+  #writeBytesToWasm(data) {
+    const allocFn = this.#exports.__zx_alloc;
+    let ptr = 0;
+    if (allocFn) {
+      ptr = allocFn(data.length);
+    } else {
+      const heapBase = this.#exports.__heap_base?.value ?? 65536;
+      ptr = heapBase + Date.now() % 256 * 4096;
+    }
+    writeBytes(ptr, data);
+    return { ptr, len: data.length };
+  }
   eventbridge(velementId, eventTypeId, event) {
     const eventRef = storeValueGetRef(event);
     const eventbridge = this.#exports.__zx_eventbridge;
@@ -310,6 +426,15 @@ class ZxBridge {
         },
         _clearInterval: (callbackId) => {
           bridgeRef.current?.clearInterval(callbackId);
+        },
+        _wsConnect: (wsId, urlPtr, urlLen, protocolsPtr, protocolsLen) => {
+          bridgeRef.current?.wsConnect(wsId, urlPtr, urlLen, protocolsPtr, protocolsLen);
+        },
+        _wsSend: (wsId, dataPtr, dataLen, isBinary) => {
+          bridgeRef.current?.wsSend(wsId, dataPtr, dataLen, isBinary);
+        },
+        _wsClose: (wsId, code, reasonPtr, reasonLen) => {
+          bridgeRef.current?.wsClose(wsId, code, reasonPtr, reasonLen);
         }
       }
     };

package/wasm/init.js

@@ -173,7 +173,11 @@ var CallbackType = {
   FetchSuccess: 1,
   FetchError: 2,
   Timeout: 3,
-  Interval: 4
+  Interval: 4,
+  WebSocketOpen: 5,
+  WebSocketMessage: 6,
+  WebSocketError: 7,
+  WebSocketClose: 8
 };
 var jsz = new ZigJS;
 var tempRefBuffer = new ArrayBuffer(8);
@@ -197,6 +201,7 @@ function writeBytes(ptr, data) {
 class ZxBridge {
   #exports;
   #intervals = new Map;
+  #websockets = new Map;
   constructor(exports) {
     this.#exports = exports;
   }
@@ -206,6 +211,18 @@ class ZxBridge {
   get #fetchCompleteHandler() {
     return this.#exports.__zx_fetch_complete;
   }
+  get #wsOnOpenHandler() {
+    return this.#exports.__zx_ws_onopen;
+  }
+  get #wsOnMessageHandler() {
+    return this.#exports.__zx_ws_onmessage;
+  }
+  get #wsOnErrorHandler() {
+    return this.#exports.__zx_ws_onerror;
+  }
+  get #wsOnCloseHandler() {
+    return this.#exports.__zx_ws_onclose;
+  }
   #invoke(type, id, data) {
     const handler = this.#handler;
     if (!handler) {
@@ -289,6 +306,105 @@ class ZxBridge {
       this.#intervals.delete(callbackId);
     }
   }
+  wsConnect(wsId, urlPtr, urlLen, protocolsPtr, protocolsLen) {
+    const url = readString(urlPtr, urlLen);
+    const protocolsStr = protocolsLen > 0 ? readString(protocolsPtr, protocolsLen) : "";
+    const protocols = protocolsStr ? protocolsStr.split(",").map((p) => p.trim()).filter(Boolean) : undefined;
+    try {
+      const ws = protocols && protocols.length > 0 ? new WebSocket(url, protocols) : new WebSocket(url);
+      ws.binaryType = "arraybuffer";
+      ws.onopen = () => {
+        const handler = this.#wsOnOpenHandler;
+        if (!handler)
+          return;
+        const protocol = ws.protocol || "";
+        const { ptr, len } = this.#writeStringToWasm(protocol);
+        handler(wsId, ptr, len);
+      };
+      ws.onmessage = (event) => {
+        const handler = this.#wsOnMessageHandler;
+        if (!handler)
+          return;
+        const isBinary = event.data instanceof ArrayBuffer;
+        let data;
+        if (isBinary) {
+          data = new Uint8Array(event.data);
+        } else {
+          data = new TextEncoder().encode(event.data);
+        }
+        const { ptr, len } = this.#writeBytesToWasm(data);
+        handler(wsId, ptr, len, isBinary ? 1 : 0);
+      };
+      ws.onerror = (event) => {
+        const handler = this.#wsOnErrorHandler;
+        if (!handler)
+          return;
+        const msg = "WebSocket error";
+        const { ptr, len } = this.#writeStringToWasm(msg);
+        handler(wsId, ptr, len);
+      };
+      ws.onclose = (event) => {
+        const handler = this.#wsOnCloseHandler;
+        if (!handler)
+          return;
+        const reason = event.reason || "";
+        const { ptr, len } = this.#writeStringToWasm(reason);
+        handler(wsId, event.code, ptr, len, event.wasClean ? 1 : 0);
+        this.#websockets.delete(wsId);
+      };
+      this.#websockets.set(wsId, ws);
+    } catch (error) {
+      const handler = this.#wsOnErrorHandler;
+      if (handler) {
+        const msg = error instanceof Error ? error.message : "WebSocket connection failed";
+        const { ptr, len } = this.#writeStringToWasm(msg);
+        handler(wsId, ptr, len);
+      }
+    }
+  }
+  wsSend(wsId, dataPtr, dataLen, isBinary) {
+    const ws = this.#websockets.get(wsId);
+    if (!ws || ws.readyState !== WebSocket.OPEN)
+      return;
+    const memory = new Uint8Array(jsz.memory.buffer);
+    const data = memory.slice(dataPtr, dataPtr + dataLen);
+    if (isBinary) {
+      ws.send(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength));
+    } else {
+      ws.send(new TextDecoder().decode(data));
+    }
+  }
+  wsClose(wsId, code, reasonPtr, reasonLen) {
+    const ws = this.#websockets.get(wsId);
+    if (!ws)
+      return;
+    const reason = reasonLen > 0 ? readString(reasonPtr, reasonLen) : undefined;
+    try {
+      if (reason) {
+        ws.close(code, reason);
+      } else {
+        ws.close(code);
+      }
+    } catch {
+      ws.close();
+    }
+  }
+  #writeStringToWasm(str) {
+    const encoded = new TextEncoder().encode(str);
+    return this.#writeBytesToWasm(encoded);
+  }
+  #writeBytesToWasm(data) {
+    const allocFn = this.#exports.__zx_alloc;
+    let ptr = 0;
+    if (allocFn) {
+      ptr = allocFn(data.length);
+    } else {
+      const heapBase = this.#exports.__heap_base?.value ?? 65536;
+      ptr = heapBase + Date.now() % 256 * 4096;
+    }
+    writeBytes(ptr, data);
+    return { ptr, len: data.length };
+  }
   eventbridge(velementId, eventTypeId, event) {
     const eventRef = storeValueGetRef(event);
     const eventbridge = this.#exports.__zx_eventbridge;
@@ -310,6 +426,15 @@ class ZxBridge {
         },
         _clearInterval: (callbackId) => {
           bridgeRef.current?.clearInterval(callbackId);
+        },
+        _wsConnect: (wsId, urlPtr, urlLen, protocolsPtr, protocolsLen) => {
+          bridgeRef.current?.wsConnect(wsId, urlPtr, urlLen, protocolsPtr, protocolsLen);
+        },
+        _wsSend: (wsId, dataPtr, dataLen, isBinary) => {
+          bridgeRef.current?.wsSend(wsId, dataPtr, dataLen, isBinary);
+        },
+        _wsClose: (wsId, code, reasonPtr, reasonLen) => {
+          bridgeRef.current?.wsClose(wsId, code, reasonPtr, reasonLen);
         }
       }
     };