ziex 0.0.1-dev.7 → 0.1.0-dev.517

package/README.md

@@ -1,10 +1,10 @@
 # ZX
 
-A Zig library for building web applications with JSX-like syntax. Write declarative UI components using familiar JSX patterns, transpiled to efficient Zig code.
+A full-stack web framework for Zig. Write declarative UI components using familiar JSX patterns, transpiled to efficient Zig code.
 
-ZX combines the power and performance of Zig with the expressiveness of JSX, enabling you to build fast, type-safe web applications. ZX is significantly faster than frameworks like Next.js at SSR.
+ZX combines the power and performance of Zig with the expressiveness of JSX, enabling you to build fast, type-safe web applications.
 
-**[Full Documentation →](https://ziex.dev)**
+**[Documentation →](https://ziex.dev/learn)**
 
 ## Installation
 
@@ -31,7 +31,7 @@ winget install -e --id zig.zig # Windows
 pub fn QuickExample(allocator: zx.Allocator) zx.Component {
     const is_loading = true;
     const chars = "Hello, ZX Dev!";
-
+    var i: usize = 0;
     return (
         <main @allocator={allocator}>
             <section>
@@ -39,7 +39,7 @@ pub fn QuickExample(allocator: zx.Allocator) zx.Component {
             </section>
         
             <section>
-                {for (chars) |char| (<span>{[char:c]}</span>)}
+                {for (chars) |char| (<span>{char}</span>)}
             </section>
         
             <section>
@@ -47,6 +47,10 @@ pub fn QuickExample(allocator: zx.Allocator) zx.Component {
                     <Profile name={user.name} age={user.age} role={user.role} />
                 )}
             </section>
+
+            <section>
+                {while (i < 10) : (i += 1) (<p>{i}</p>)}
+            </section>
         </main>
     );
 }
@@ -55,7 +59,7 @@ fn Profile(allocator: zx.Allocator, user: User) zx.Component {
     return (
         <div @allocator={allocator}>
             <h1>{user.name}</h1>
-            <p>{[user.age:d]}</p>
+            <p>{user.age}</p>
             {switch (user.role) {
                 .admin => (<p>Admin</p>),
                 .member => (<p>Member</p>),
@@ -77,10 +81,19 @@ const zx = @import("zx");
 ## Feature Checklist
 
 - [x] Server Side Rendering (SSR)
+    - [ ] `on`event handler
+    - [x] Streaming
 - [x] Static Site Generation (SSG)
+    - [ ] `getStaticParams`, `getStaticProps`
 - [ ] Client Side Rendering (CSR) via WebAssembly (_WIP_)
+    - [x] Virtual DOM and diffing
+    - [x] Rendering only changed nodes
+    - [x] `on`event handler
+    - [x] State managment
+    - [x] Hydration
+    - [ ] Lifecycle hook
+    - [ ] Server Actions
 - [x] Client Side Rendering (CSR) via React
-- [x] Type Safety
 - [x] Routing
     - [x] File-system Routing
     - [x] Search Parameters
@@ -88,65 +101,98 @@ const zx = @import("zx");
 - [x] Components
 - [x] Control Flow
     - [x] `if`
-    - [ ] `if` nested
     - [x] `if/else`
-    - [x] `if/else` nested
     - [x] `for`
-    - [x] `for` nested
     - [x] `switch`
-    - [x] `switch` nested
     - [x] `while`
-    - [x] `while` nested
+    - [x] nesting control flows
+    - [x] error/optional captures in `while` and `if`
 - [x] Assets
     - [x] Copying
     - [x] Serving
 - [ ] Assets Optimization
     - [ ] Image
-    - [ ] CSS
-    - [ ] JS
-    - [ ] HTML
-- [ ] Middleware
-- [ ] API Endpoints
-- [ ] Server Actions
+    - [x] CSS (via plugins such as Tailwind)
+    - [x] JS/TS (via esbuild)
+    - [x] HTML (optimized by default)
+- [ ] Middleware (_cancalled_)
+- [ ] Caching (configurable)
+    - [x] Component
+    - [ ] Layout
+    - [x] Page
+    - [ ] Assets
+- [ ] API Route
+- [ ] Plugin (_Alpha_)
+    - [x] Builtin TailwindCSS and Esbuild
+    - [x] Command based plugin system
+    - [ ] Source based plugin system
+- [ ] Context (configurable)
+    - [ ] App
+    - [ ] Layout
+    - [ ] Page
+    - [x] Component
+- [x] `error.zx` for default and per-route error page
+- [x] `notfound.zx` for default and per-route error page
 - [x] CLI
     - [x] `init` Project Template
     - [x] `transpile` Transpile .zx files to Zig source code
     - [x] `serve` Serve the project
     - [x] `dev` HMR or Rebuild on Change
-    - [x] `fmt` Format the ZX source code (_Alpha_)
+    - [x] `fmt` Format the ZX source code
     - [x] `export` Generate static site assets
     - [x] `bundle` Bundle the ZX executable with public/assets and exe
     - [x] `version` Show the version of the ZX CLI
     - [x] `update` Update the version of ZX dependency
     - [x] `upgrade` Upgrade the version of ZX CLI
+- [ ] Platform
+    - [x] Server
+    - [x] Browser
+    - [ ] iOS
+    - [ ] Android
+    - [ ] macOS
+    - [ ] Windows
 
 #### Editor Support
 
-* [VSCode](https://marketplace.visualstudio.com/items?itemName=nurulhudaapon.zx)/[Cursor](https://marketplace.visualstudio.com/items?itemName=nurulhudaapon.zx) Extension
-    - [x] Syntax Highlighting
-    - [x] LSP Support
-    - [x] Auto Format
-
-* Neovim
-    - [ ] Syntax Highlighting
-    - [ ] LSP Support
-    - [ ] Auto Format
+- ##### [VSCode](https://marketplace.visualstudio.com/items?itemName=nurulhudaapon.zx)/[VSCode Forks](https://marketplace.visualstudio.com/items?itemName=nurulhudaapon.zx) Extension
+- ##### [Neovim](/editors/neovim/)
+- ##### [Zed](/editors/zed/)
 
 ## Similar Projects
 
-* [Yew](https://github.com/yewstack/yew) - Rust / Wasm framework for creating reliable and efficient web applications
-* [ZTS](https://github.com/zigster64/zts) — Zig Templates made Simple, a templating system for Zig
-* [zmpl](https://github.com/jetzig-framework/zmpl) — Mode-based templating language that compiles to Zig functions at build time, used in Jetzig
-* [mustache-zig](https://github.com/batiati/mustache-zig) — Mustache template engine implementation in Zig
-* [etch](https://github.com/haze/etch) — Compile-time tuned templating engine focusing on speed and simplicity
-* [Zap](https://github.com/zigzap/zap) — High-performance backend framework in Zig
-* [http.zig](https://github.com/karlseguin/http.zig) — Low-level HTTP/1.1 server written entirely in Zig (_ZX_'s backend)
-* [tokamak](https://github.com/cztomsik/tokamak) — Server-side framework for Zig
-* [zig-router](https://github.com/Cloudef/zig-router) — Straightforward HTTP-like request routing library for Zig
-* [zig-webui](https://github.com/webui-dev/zig-webui/) — Zig library that allows using any web browser as a GUI
-* [Zine](https://github.com/kristoff-it/zine) — Fast, scalable, flexible static site generator (SSG) written in Zig
-* [Zinc](https://github.com/zon-dev/zinc/) — Web framework written in pure Zig with focus on high performance, usability, security, and extensibility
-* [zUI](https://github.com/thienpow/zui) — UI kit for Jetzig framework with reusable components and styles
+### Rust
+
+* [Leptos](https://github.com/leptos-rs/leptos) - Full-stack, isomorphic Rust web framework with fine-grained reactivity and JSX-like syntax
+* [Dioxus](https://github.com/DioxusLabs/dioxus) - Cross-platform GUI framework with React-like API, supporting web, desktop, mobile, and SSR
+* [Yew](https://github.com/yewstack/yew) - Rust / Wasm framework for creating reliable and efficient web applications with component-based architecture
+* [Sycamore](https://github.com/sycamore-rs/sycamore) - Reactive web framework with fine-grained reactivity and minimal bundle sizes
+* [Perseus](https://github.com/framesurge/perseus) - Full-stack framework built on Sycamore with SSR, SSG, and incremental regeneration
+
+### Zig
+
+* [Jetzig](https://github.com/jetzig-framework/jetzig) - Zig web framework with MVC architecture, built-in ORM, and powerful templating
+* [ZTS](https://github.com/zigster64/zts) - Zig Templates made Simple, a templating system for Zig
+* [zmpl](https://github.com/jetzig-framework/zmpl) - Mode-based templating language that compiles to Zig functions at build time, used in Jetzig
+* [mustache-zig](https://github.com/batiati/mustache-zig) - Mustache template engine implementation in Zig
+* [etch](https://github.com/haze/etch) - Compile-time tuned templating engine focusing on speed and simplicity
+* [Zap](https://github.com/zigzap/zap) - High-performance backend framework in Zig
+* [http.zig](https://github.com/karlseguin/http.zig) - Low-level HTTP/1.1 server written entirely in Zig (_ZX_'s backend)
+* [tokamak](https://github.com/cztomsik/tokamak) - Server-side framework for Zig
+* [zig-router](https://github.com/Cloudef/zig-router) - Straightforward HTTP-like request routing library for Zig
+* [zig-webui](https://github.com/webui-dev/zig-webui/) - Zig library that allows using any web browser as a GUI
+* [Zine](https://github.com/kristoff-it/zine) - Fast, scalable, flexible static site generator (SSG) written in Zig
+* [Zinc](https://github.com/zon-dev/zinc/) - Web framework written in pure Zig with focus on high performance, usability, security, and extensibility
+* [zUI](https://github.com/thienpow/zui) - UI kit for Jetzig framework with reusable components and styles
+* [zig-pek](https://github.com/nektro/zig-pek) - Comptime HTML/XML parser and renderer in Zig
+* [zigomponent](https://zigomp.prjct.dev/) - HTML compoenents in pure zig
+
+## Related Projects
+
+* [Codeberg Mirror](https://codeberg.org/nurulhudaapon/zx) - ZX repository mirror on Codeberg
+* [zx-vscode](https://github.com/nurulhudaapon/zx-vscode) - Official VSCode/Cursor extension with syntax highlighting, LSP support, and auto-formatting
+* [ziex.dev](https://github.com/nurulhudaapon/zx/tree/main/site) - Official documentation site of ZX made using ZX.
+* [zx-example-portfolio](https://github.com/nurulhudaapon/zx-example-portfolio) - Demo portfolio web application built with ZX
+* [thegates.dev](https://github.com/nurulhudaapon/thegates.dev) - Example clone demonstrating ZX capabilities
 
 ## Contributing
 

package/index.js

@@ -1,7 +1,7 @@
 // src/index.ts
 var zx = {
   name: "zx",
-  version: "0.0.1-dev.270",
+  version: "0.1.0-dev.517",
   description: "ZX is a framework for building web applications with Zig.",
   repository: "https://github.com/nurulhudaapon/zx",
   fingerprint: 14616285862371232000,
@@ -12,18 +12,30 @@ var zx = {
       hash: "httpz-0.0.0-PNVzrBgtBwCVkSJyophIX6WHwDR0r8XhBGQr96Kk-1El"
     },
     zli: {
-      url: "git+https://github.com/nurulhudaapon/cliz.git#aff3b54879e7514afaf8c87f1abe22121b8992d4",
-      hash: "zli-4.3.0-LeUjpu_fAABOSVASSCW2fFh8SFVNHrxQGDXGPNzcSE_i"
+      path: "vendor/cliz"
     },
     zig_js: {
-      url: "git+https://github.com/nurulhudaapon/jsz.git#04db83c617da1956ac5adc1cb9ba1e434c1cb6fd",
-      hash: "zig_js-0.0.0-rjCAV-6GAADxFug7rDmPH-uM_XcnJ5NmuAMJCAscMjhi"
+      path: "vendor/jsz"
+    },
+    tree_sitter: {
+      path: "vendor/zig-tree-sitter"
+    },
+    tree_sitter_zx: {
+      path: "packages/tree-sitter-zx"
+    },
+    cachez: {
+      path: "vendor/cachez"
     }
   },
   paths: [
     "build.zig",
     "build.zig.zon",
-    "src"
+    "src",
+    "packages/tree-sitter-zx",
+    "vendor/cachez",
+    "vendor/cliz",
+    "vendor/jsz",
+    "vendor/zig-tree-sitter"
   ]
 };
 export {

package/package.json

@@ -1,5 +1,6 @@
 {
   "name": "ziex",
+  "version": "0.1.0-dev.517",
   "description": "ZX is a framework for building web applications with Zig.",
   "main": "index.js",
   "type": "module",
@@ -28,6 +29,5 @@
   "author": "Nurul Huda (Apon) <me@nurulhudaapon.com>",
   "license": "MIT",
   "module": "index.js",
-  "types": "index.d.ts",
-  "version": "0.0.1-dev.7"
+  "types": "index.d.ts"
 }

package/react/dom.d.ts

@@ -8,14 +8,15 @@ export type PreparedComponent = {
     /**
      * The HTML element where the component should be rendered.
      *
-     * This is the DOM node that was server-rendered by ZX with the component's unique ID.
-     * The element already exists in the DOM and contains the server-rendered fallback content.
-     * React will hydrate this element, replacing its contents with the interactive component.
+     * 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
-     * // The DOM node corresponds to HTML like:
-     * // <div id="zx-dcde04c415da9d1b15ca2690d8b497ae" data-props="...">...</div>
+     * // 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} />);
@@ -23,42 +24,28 @@ export type PreparedComponent = {
      */
     domNode: HTMLElement;
     /**
-     * Component props parsed from the server-rendered HTML.
+     * Component props parsed from the comment marker.
      *
-     * Props are extracted from the `data-props` attribute (JSON-encoded) on the component's
-     * container element. If the component has children from server side then they are automatically converted to
-     * `dangerouslySetInnerHTML` for React compatibility.
+     * 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:
-     * // <div data-props='{"max_count":10,"label":"Counter"}' data-children="<span>0</span>">...</div>
+     * // <!--$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",
-     * //   dangerouslySetInnerHTML: { __html: "<span>0</span>" }
-     * // }
+     * // props = { max_count: 10, label: "Counter" }
      * ```
      */
     props: Record<string, any> & {
         /**
          * React's special prop for setting inner HTML directly.
          *
-         * Automatically added when the component has children in the ZX file. The HTML string
-         * is extracted from the `data-children` attribute on the server-rendered element.
-         *
-         * @example
-         * ```tsx
-         * // In ZX file:
-         * <MyComponent @rendering={.csr}>
-         *   <p>Child content</p>
-         * </MyComponent>
-         *
-         * // Results in:
-         * // props.dangerouslySetInnerHTML = { __html: "<p>Child content</p>" }
-         * ```
+         * May be used when the component has server-rendered children that should
+         * be preserved during hydration.
          */
         dangerouslySetInnerHTML?: {
             __html: string;
@@ -85,12 +72,12 @@ export type PreparedComponent = {
     Component: (props: any) => React.ReactElement;
 };
 /**
- * Prepares a client-side component for hydration by locating its DOM container, extracting
- * props and children from server-rendered HTML attributes, and lazy-loading the component module.
+ * 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 reads data attributes (`data-props`, `data-children`) from the DOM element
- * with the component's unique ID, then lazy-loads the component module for rendering.
+ * 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
@@ -98,8 +85,8 @@ export type PreparedComponent = {
  * @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 container element cannot be found in the DOM. This typically
- *                 happens if the component ID doesn't match any element, the script runs before
+ * @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
@@ -118,18 +105,58 @@ export type PreparedComponent = {
  *
  * @example
  * ```tsx
- * // With async/await:
- * async function hydrateComponent(component: ComponentMetadata) {
- *   try {
- *     const { domNode, Component, props } = await prepareComponent(component);
- *     createRoot(domNode).render(<Component {...props} />);
- *   } catch (error) {
- *     console.error(`Failed to hydrate ${component.name}:`, error);
- *   }
- * }
- *
- * Promise.all(components.map(hydrateComponent));
+ * // 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 once to find all `<!--$id-->` markers
+ * 2. Reads metadata from companion `<script data-zx="id">` elements
+ * 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.d.ts

@@ -1,2 +1,2 @@
-export { prepareComponent, filterComponents, type PreparedComponent } from "./dom";
+export { prepareComponent, filterComponents, discoverComponents, hydrateAll, type PreparedComponent, type DiscoveredComponent, type ComponentRegistry, } from "./dom";
 export type { ComponentMetadata } from "./types";

package/react/index.js

@@ -1,13 +1,56 @@
 // src/react/dom.ts
+function findCommentMarker(id) {
+  const startMarker = `$${id}`;
+  const endMarker = `/$${id}`;
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_COMMENT, null);
+  let startComment = null;
+  let endComment = null;
+  let node;
+  while (node = walker.nextNode()) {
+    const text = node.textContent?.trim() || "";
+    if (text === startMarker) {
+      startComment = node;
+    }
+    if (text === endMarker) {
+      endComment = node;
+      break;
+    }
+  }
+  if (startComment && endComment) {
+    return { startComment, endComment };
+  }
+  return null;
+}
+function getComponentMetadata(id) {
+  const script = document.querySelector(`script[data-zx="${id}"]`);
+  if (script?.textContent) {
+    try {
+      const data = JSON.parse(script.textContent);
+      return { name: data.name || "", props: data.props || {} };
+    } catch {}
+  }
+  return { name: "", props: {} };
+}
+function createContainerBetweenMarkers(startComment, endComment) {
+  const container = document.createElement("div");
+  container.style.display = "contents";
+  let current = startComment.nextSibling;
+  while (current && current !== endComment) {
+    const next = current.nextSibling;
+    container.appendChild(current);
+    current = next;
+  }
+  endComment.parentNode?.insertBefore(container, endComment);
+  return container;
+}
 async function prepareComponent(component) {
-  const domNode = document.getElementById(component.id);
-  if (!domNode)
-    throw new Error(`Root element ${component.id} not found`, { cause: component });
-  const props = JSON.parse(domNode.getAttribute("data-props") || "{}");
-  const htmlChildren = domNode.getAttribute("data-children") ?? undefined;
-  if (htmlChildren) {
-    props.dangerouslySetInnerHTML = { __html: htmlChildren };
+  const marker = findCommentMarker(component.id);
+  if (!marker) {
+    throw new Error(`Comment marker for ${component.id} not found`, { cause: component });
   }
+  const metadata = getComponentMetadata(component.id);
+  const props = metadata.props;
+  const domNode = createContainerBetweenMarkers(marker.startComment, marker.endComment);
   const Component = await component.import();
   return { domNode, props, Component };
 }
@@ -15,7 +58,49 @@ function filterComponents(components) {
   const currentPath = window.location.pathname;
   return components.filter((component) => component.route === currentPath || !component.route);
 }
+function discoverComponents() {
+  const components = [];
+  const scripts = Array.from(document.querySelectorAll("script[data-zx]"));
+  for (const script of scripts) {
+    const id = script.getAttribute("data-zx");
+    if (!id)
+      continue;
+    let name = "";
+    let props = {};
+    try {
+      const data = JSON.parse(script.textContent || "{}");
+      name = data.name || "";
+      props = data.props || {};
+    } catch {
+      continue;
+    }
+    const marker = findCommentMarker(id);
+    if (!marker)
+      continue;
+    const container = createContainerBetweenMarkers(marker.startComment, marker.endComment);
+    components.push({ id, name, props, container });
+  }
+  return components;
+}
+async function hydrateAll(registry, render) {
+  const components = discoverComponents();
+  await Promise.all(components.map(async ({ name, props, container }) => {
+    const importer = registry[name];
+    if (!importer) {
+      console.warn(`Component "${name}" not found in registry`);
+      return;
+    }
+    try {
+      const Component = await importer();
+      render(container, Component, props);
+    } catch (error) {
+      console.error(`Failed to hydrate "${name}":`, error);
+    }
+  }));
+}
 export {
   prepareComponent,
-  filterComponents
+  hydrateAll,
+  filterComponents,
+  discoverComponents
 };

package/react/types.d.ts

@@ -2,14 +2,14 @@
  * Metadata for a client-side component used within a ZX file.
  *
  * This type represents the metadata for components that are marked with the `@rendering` attribute
- * in ZX files. When a component is declared with `@rendering={.csr}` or `@rendering={.csz}` in a
+ * in ZX files. When a component is declared with `@rendering={.react}` or `@rendering={.client}` in a
  * `.zx` file, the ZX transpiler generates a `ComponentMetadata` entry that is included in the
  * generated `components` array.
  *
  * @example
  * ```tsx
  * // In a ZX file (page.zx):
- * <CounterComponent @rendering={.csr} max_count={10} />
+ * <CounterComponent @rendering={.react} max_count={10} />
  *
  * // Generated components array (components.ts):
  * export const components: ComponentMetadata[] = [
@@ -17,7 +17,7 @@
  *     name: "CounterComponent",
  *     path: "./components/CounterComponent.tsx",
  *     id: "zx-dcde04c415da9d1b15ca2690d8b497ae",
- *     type: "csr",
+ *     type: "react",
  *     import: () => import('./components/CounterComponent.tsx')
  *   }
  * ];
@@ -44,7 +44,7 @@ export type ComponentMetadata = {
      * @example
      * ```tsx
      * // In ZX file:
-     * <CounterComponent @rendering={.csr} />
+     * <CounterComponent @rendering={.react} />
      *
      * // name will be: "CounterComponent"
      * ```
@@ -54,7 +54,7 @@ export type ComponentMetadata = {
      * The file path to the component module.
      *
      * This is the relative or absolute path to the component file that will be dynamically imported
-     * at runtime. For CSR components, this typically points to a `.tsx` or `.jsx` file. For CSZ
+     * at runtime. For CSR components, this typically points to a `.tsx` or `.jsx` file. For Client
      * components, this points to a Zig component file.
      *
      * The path is determined from the `@jsImport` directive in the ZX file, or defaults to
@@ -64,7 +64,7 @@ export type ComponentMetadata = {
      * ```tsx
      * // In ZX file:
      * const CounterComponent = @jsImport("components/Counter.tsx");
-     * <CounterComponent @rendering={.csr} />
+     * <CounterComponent @rendering={.react} />
      *
      * // path will be: "components/Counter.tsx"
      * ```
@@ -72,7 +72,7 @@ export type ComponentMetadata = {
      * @example
      * ```tsx
      * // Without explicit @jsImport:
-     * <MyComponent @rendering={.csr} />
+     * <MyComponent @rendering={.react} />
      *
      * // path will default to: "./MyComponent.tsx"
      * ```
@@ -85,17 +85,16 @@ export type ComponentMetadata = {
      */
     route: string | null;
     /**
-     * A unique HTML element identifier for the component's root DOM node.
+     * A unique identifier for the component's hydration boundary.
      *
      * This ID is generated by hashing the component's path and name using MD5, then formatting it
-     * as a hex string with the "zx-" prefix. The ID is used to locate the component's container
-     * element in the DOM during client-side hydration.
+     * as a hex string with the "zx-" prefix and a counter suffix. The ID is used to locate the
+     * component's comment markers in the DOM during client-side hydration.
      *
-     * The ID format is: `zx-{32 hex characters}` (e.g., `zx-dcde04c415da9d1b15ca2690d8b497ae`)
+     * The ID format is: `zx-{32 hex characters}-{counter}` (e.g., `zx-dcde04c415da9d1b15ca2690d8b497ae-0`)
      *
-     * When the same component is used multiple times on a page, each instance gets the same base ID
-     * since they share the same path and name. The ZX runtime uses this ID along with `data-props`
-     * and `data-children` attributes to hydrate the component with the correct props and children.
+     * The ZX runtime renders components with comment markers in the format:
+     * `<!--$id name props-->...<!--/$id-->`
      *
      * @example
      * ```tsx
@@ -103,36 +102,34 @@ export type ComponentMetadata = {
      * {
      *   name: "CounterComponent",
      *   path: "./components/Counter.tsx",
-     *   id: "zx-dcde04c415da9d1b15ca2690d8b497ae"
+     *   id: "zx-dcde04c415da9d1b15ca2690d8b497ae-0"
      * }
      *
-     * // Generated HTML:
-     * <div id="zx-dcde04c415da9d1b15ca2690d8b497ae"
-     *      data-props='{"max_count":10}'
-     *      data-children="...">
-     *   <!-- Server-rendered content -->
-     * </div>
+     * // Generated HTML with comment markers:
+     * <!--$zx-dcde04c415da9d1b15ca2690d8b497ae-0 CounterComponent {"max_count":10}-->
+     * <button>0</button>
+     * <!--/$zx-dcde04c415da9d1b15ca2690d8b497ae-0-->
      * ```
      */
     id: string;
     /**
      * The rendering type of the component, determining how it will be rendered on the client.
      *
-     * - **"csr"** (Client Side React): The component is a React component that will be rendered
+     * - **"react"** (Client Side React): The component is a React component that will be rendered
      *   using React's client-side rendering. The component file should export a default React
      *   component function. This is the most common type for interactive UI components.
      *
-     * - **"csz"** (Client Side Zig): The component is a Zig component that will be compiled to
+     * - **"client"** (Client Side Zig): The component is a Zig component that will be compiled to
      *   WebAssembly and rendered on the client side. This allows you to use Zig's performance
      *   and type safety for client-side components.
      *
-     * The type is determined by the `@rendering` attribute value in the ZX file (`.csr` or `.csz`).
+     * The type is determined by the `@rendering` attribute value in the ZX file (`.react` or `.client`).
      *
      * @example
      * ```tsx
      * // CSR component (React):
-     * <CounterComponent @rendering={.csr} max_count={10} />
-     * // type: "csr"
+     * <CounterComponent @rendering={.react} max_count={10} />
+     * // type: "react"
      *
      * // Component file (CounterComponent.tsx):
      * export default function CounterComponent({ max_count }: { max_count: number }) {
@@ -142,9 +139,9 @@ export type ComponentMetadata = {
      *
      * @example
      * ```tsx
-     * // CSZ component (Zig/WASM):
-     * <CounterComponent @rendering={.csz} />
-     * // type: "csz"
+     * // Client component (Zig/WASM):
+     * <CounterComponent @rendering={.client} />
+     * // type: "client"
      *
      * // Component file (CounterComponent.zig):
      * pub fn CounterComponent(allocator: zx.Allocator) zx.Component {
@@ -152,7 +149,7 @@ export type ComponentMetadata = {
      * }
      * ```
      */
-    type: "csr" | "csz";
+    type: "react" | "client";
     /**
      * A lazy-loading function that dynamically imports the component module.
      *
@@ -161,7 +158,7 @@ export type ComponentMetadata = {
      * by only loading components when they are needed.
      *
      * For CSR components, the imported module should export a default React component.
-     * For CSZ components, the import mechanism depends on the WASM module structure.
+     * For Client components, the import mechanism depends on the WASM module structure.
      *
      * The function is called during client-side hydration to load and render the component
      * into its corresponding DOM container element.

package/wasm/index.d.ts

@@ -1,14 +1,26 @@
+import { ZigJS } from "../../../../vendor/jsz/js/src";
+export declare const jsz: ZigJS;
 declare class ZXInstance {
     #private;
     exports: WebAssembly.Exports;
     events: Event[];
-    actions: Record<string, (eventId: number) => void>;
     constructor({ exports, events }: ZXInstanceOptions);
     addEvent(event: Event): number;
+    /**
+     * Initialize event delegation on a root element
+     * This attaches a single event listener for each event type at the root,
+     * and uses __zx_ref to look up the corresponding VElement in WASM
+     */
+    initEventDelegation(rootSelector?: string): void;
+    getZxRef(element: HTMLElement): number | undefined;
 }
-export declare function init(options?: InitOptions): Promise<void>;
+export declare function init(options?: InitOptions): Promise<WebAssembly.WebAssemblyInstantiatedSource>;
 export type InitOptions = {
+    /** URL to the WASM file (default: /assets/main.wasm) */
     url?: string;
+    /** CSS selector for the event delegation root element (default: 'body') */
+    eventDelegationRoot?: string;
+    importObject?: WebAssembly.Imports;
 };
 type ZXInstanceOptions = {
     exports: ZXInstance['exports'];
@@ -18,5 +30,11 @@ declare global {
     interface Window {
         _zx: ZXInstance;
     }
+    interface HTMLElement {
+        /**
+         * The VElement ID of the element
+         */
+        __zx_ref?: number;
+    }
 }
 export {};

package/wasm/index.js

@@ -1,4 +1,4 @@
-// node_modules/jsz/js/src/zigjs.ts
+// ../../vendor/jsz/js/src/zigjs.ts
 var NAN_PREFIX = 2146959360;
 var predefined = {
   nan: 0,
@@ -170,26 +170,60 @@ class ZigJS {
 // src/wasm/index.ts
 var DEFAULT_URL = "/assets/main.wasm";
 var MAX_EVENTS = 100;
+var DELEGATED_EVENTS = [
+  "click",
+  "dblclick",
+  "input",
+  "change",
+  "submit",
+  "focus",
+  "blur",
+  "keydown",
+  "keyup",
+  "keypress",
+  "mouseenter",
+  "mouseleave",
+  "mousedown",
+  "mouseup",
+  "mousemove",
+  "touchstart",
+  "touchend",
+  "touchmove",
+  "scroll"
+];
+var EVENT_TYPE_MAP = {
+  click: 0,
+  dblclick: 1,
+  input: 2,
+  change: 3,
+  submit: 4,
+  focus: 5,
+  blur: 6,
+  keydown: 7,
+  keyup: 8,
+  keypress: 9,
+  mouseenter: 10,
+  mouseleave: 11,
+  mousedown: 12,
+  mouseup: 13,
+  mousemove: 14,
+  touchstart: 15,
+  touchend: 16,
+  touchmove: 17,
+  scroll: 18
+};
 var jsz = new ZigJS;
 var importObject = {
-  module: {},
-  env: {},
   ...jsz.importObject()
 };
 
 class ZXInstance {
   exports;
   events;
-  actions;
+  #eventDelegationInitialized = false;
   constructor({ exports, events = [] }) {
     this.exports = exports;
     this.events = events;
-    this.actions = {};
-    Object.entries(exports).forEach(([name, func]) => {
-      if (typeof func !== "function")
-        return;
-      this.actions[name] = this.#actionWrapper.bind(this, name);
-    });
   }
   addEvent(event) {
     if (this.events.length >= MAX_EVENTS)
@@ -197,23 +231,52 @@ class ZXInstance {
     const idx = this.events.push(event);
     return idx - 1;
   }
-  #actionWrapper(name, ...args) {
-    const func = this.exports[name];
-    if (typeof func !== "function")
-      throw new Error(`Action ${name} is not a function`);
-    const eventId = this.addEvent(args[0]);
-    return func(eventId);
+  initEventDelegation(rootSelector = "body") {
+    if (this.#eventDelegationInitialized)
+      return;
+    const root = document.querySelector(rootSelector);
+    if (!root)
+      return;
+    for (const eventType of DELEGATED_EVENTS) {
+      root.addEventListener(eventType, (event) => {
+        this.#handleDelegatedEvent(eventType, event);
+      }, { passive: eventType.startsWith("touch") || eventType === "scroll" });
+    }
+    this.#eventDelegationInitialized = true;
+  }
+  #handleDelegatedEvent(eventType, event) {
+    let target = event.target;
+    while (target && target !== document.body) {
+      const zxRef = target.__zx_ref;
+      if (zxRef !== undefined) {
+        const eventId = this.addEvent(event);
+        const handleEvent = this.exports.handleEvent;
+        if (typeof handleEvent === "function") {
+          const eventTypeId = EVENT_TYPE_MAP[eventType] ?? 0;
+          handleEvent(BigInt(zxRef), eventTypeId, BigInt(eventId));
+        }
+        break;
+      }
+      target = target.parentElement;
+    }
+  }
+  getZxRef(element) {
+    return element.__zx_ref;
   }
 }
 async function init(options = {}) {
   const url = options?.url ?? DEFAULT_URL;
-  const { instance } = await WebAssembly.instantiateStreaming(fetch(url), importObject);
+  const wasmInstiatedSource = await WebAssembly.instantiateStreaming(fetch(url), Object.assign({}, importObject, options.importObject));
+  const { instance } = wasmInstiatedSource;
   jsz.memory = instance.exports.memory;
   window._zx = new ZXInstance({ exports: instance.exports });
+  window._zx.initEventDelegation(options.eventDelegationRoot ?? "body");
   const main = instance.exports.mainClient;
   if (typeof main === "function")
     main();
+  return wasmInstiatedSource;
 }
 export {
+  jsz,
   init
 };

package/zx.d.ts

@@ -0,0 +1 @@
+export declare function getZxInfo(): any;