zexus 1.6.8 → 1.7.2

package/src/zexus/renderer/tk_backend.py

@@ -0,0 +1,208 @@
+"""
+Tk GUI Backend for the Zexus Renderer.
+
+Provides a real windowed GUI using Python's built-in ``tkinter``.
+The backend translates the existing ``Screen`` / ``Canvas`` / ``Component``
+model into Tk widgets.
+
+Usage from Zexus::
+
+    @zexus gui_backend = "tk"
+
+    screen main {
+        title: "My App"
+        width: 400
+        height: 300
+    }
+
+    component greeting label {
+        text: "Hello from Zexus!"
+        x: 50
+        y: 30
+    }
+
+    add greeting to main
+    show main
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+try:
+    import tkinter as tk
+    from tkinter import font as tkfont
+    TK_AVAILABLE = True
+except ImportError:
+    TK_AVAILABLE = False
+
+from .layout import Screen, ScreenComponent, ScreenRegistry, Button, Label, TextBox
+from .canvas import Canvas, CanvasRegistry
+from .color_system import RGBColor
+
+
+def _rgb_hex(color: Optional[RGBColor]) -> str:
+    """Convert ``RGBColor`` to Tk hex string."""
+    if color is None:
+        return "#000000"
+    return f"#{color.r:02x}{color.g:02x}{color.b:02x}"
+
+
+class TkBackend:
+    """Windowed GUI backend backed by tkinter.
+
+    The Tk event loop runs on a **dedicated thread** so the Zexus
+    evaluator thread isn't blocked.
+    """
+
+    def __init__(self, screen_registry: Optional[ScreenRegistry] = None,
+                 canvas_registry: Optional[CanvasRegistry] = None) -> None:
+        if not TK_AVAILABLE:
+            raise RuntimeError(
+                "tkinter is not available. On Ubuntu: sudo apt install python3-tk"
+            )
+        self.screen_registry = screen_registry or ScreenRegistry()
+        self.canvas_registry = canvas_registry or CanvasRegistry()
+        self._root: Optional[tk.Tk] = None
+        self._windows: Dict[str, tk.Toplevel] = {}
+        self._tk_canvases: Dict[str, tk.Canvas] = {}
+        self._event_handlers: Dict[str, Callable] = {}
+        self._thread: Optional[threading.Thread] = None
+        self._ready = threading.Event()
+
+    # -- Lifecycle ---------------------------------------------------------
+
+    def start(self) -> None:
+        """Launch the Tk main loop on a background thread."""
+        if self._thread and self._thread.is_alive():
+            return
+        self._thread = threading.Thread(target=self._run_mainloop, daemon=True)
+        self._thread.start()
+        self._ready.wait(timeout=5)
+
+    def stop(self) -> None:
+        """Destroy all windows and shut down the Tk loop."""
+        if self._root:
+            self._root.after(0, self._root.destroy)
+
+    def _run_mainloop(self) -> None:
+        self._root = tk.Tk()
+        self._root.withdraw()  # hide root window
+        self._ready.set()
+        self._root.mainloop()
+
+    # -- Screen rendering --------------------------------------------------
+
+    def show_screen(self, name: str) -> None:
+        """Render a registered ``Screen`` as a Tk window."""
+        screen = self.screen_registry.get_screen(name)
+        width = int(screen.get("width", 400))
+        height = int(screen.get("height", 300))
+        title = str(screen.get("title", name))
+        bg = str(screen.get("background", "#ffffff"))
+
+        def _create():
+            win = tk.Toplevel(self._root)
+            win.title(title)
+            win.geometry(f"{width}x{height}")
+            win.configure(bg=bg)
+            self._windows[name] = win
+
+            for child in screen.children:
+                self._render_component(win, child)
+
+        self._root.after(0, _create)
+
+    def close_screen(self, name: str) -> None:
+        win = self._windows.pop(name, None)
+        if win:
+            self._root.after(0, win.destroy)
+
+    # -- Component rendering -----------------------------------------------
+
+    def _render_component(self, parent: tk.Toplevel, comp: ScreenComponent) -> None:
+        x = int(comp.get("x", 10))
+        y = int(comp.get("y", 10))
+        fg = str(comp.get("color", "black"))
+        text = str(comp.get("text", comp.name))
+
+        if isinstance(comp, Button):
+            handler = self._event_handlers.get(f"{comp.name}:click")
+            btn = tk.Button(parent, text=text, fg=fg,
+                            command=handler if handler else lambda: None)
+            btn.place(x=x, y=y)
+
+        elif isinstance(comp, TextBox):
+            w = int(comp.get("width", 20))
+            entry = tk.Entry(parent, width=w, fg=fg)
+            entry.insert(0, text)
+            entry.place(x=x, y=y)
+
+        elif isinstance(comp, Label):
+            size = int(comp.get("fontSize", 12))
+            lbl = tk.Label(parent, text=text, fg=fg,
+                           font=("TkDefaultFont", size))
+            lbl.place(x=x, y=y)
+
+        else:
+            # Generic component → label
+            lbl = tk.Label(parent, text=text)
+            lbl.place(x=x, y=y)
+
+    # -- Canvas rendering --------------------------------------------------
+
+    def show_canvas(self, canvas_id: str) -> None:
+        """Render a ``Canvas`` in a new Tk window."""
+        canvas = self.canvas_registry.get(canvas_id)
+
+        def _create():
+            win = tk.Toplevel(self._root)
+            win.title(f"Canvas: {canvas_id}")
+            tk_c = tk.Canvas(win, width=canvas.width * 4,
+                             height=canvas.height * 4, bg="white")
+            tk_c.pack()
+            self._tk_canvases[canvas_id] = tk_c
+            self._draw_canvas(tk_c, canvas)
+
+        self._root.after(0, _create)
+
+    def _draw_canvas(self, tk_c: tk.Canvas, canvas: Canvas) -> None:
+        scale = 4
+        for op_type, args in canvas.operations:
+            if op_type == "line":
+                x1, y1, x2, y2 = args
+                tk_c.create_line(
+                    x1 * scale, y1 * scale,
+                    x2 * scale, y2 * scale,
+                    fill="black", width=2,
+                )
+            elif op_type == "text":
+                x, y, text = args
+                tk_c.create_text(x * scale, y * scale, text=text, anchor="nw")
+
+    # -- Event binding -----------------------------------------------------
+
+    def on(self, component_name: str, event: str, handler: Callable) -> None:
+        """Register an event handler for a component.
+
+        Example: ``backend.on("my_button", "click", my_handler)``
+        """
+        self._event_handlers[f"{component_name}:{event}"] = handler
+
+    # -- Utility -----------------------------------------------------------
+
+    def wait(self) -> None:
+        """Block until the Tk loop terminates (all windows closed)."""
+        if self._thread:
+            self._thread.join()
+
+
+# ---------------------------------------------------------------------------
+# Public factory
+# ---------------------------------------------------------------------------
+
+def create_tk_backend(**kwargs) -> TkBackend:
+    backend = TkBackend(**kwargs)
+    backend.start()
+    return backend

package/src/zexus/renderer/web_backend.py

@@ -0,0 +1,260 @@
+"""
+Web GUI Backend for the Zexus Renderer.
+
+Serves the rendered UI as HTML over a local HTTP server.  The evaluator
+creates screens/components normally and then calls ``show_screen()`` which
+opens a browser tab to ``http://localhost:<port>/``.
+
+The server uses only the Python standard library (``http.server`` +
+``json``).  No Flask/Django/etc. dependency.
+
+Usage from Zexus::
+
+    @zexus gui_backend = "web"
+
+    screen dashboard {
+        title: "Dashboard"
+        width: 600
+        height: 400
+    }
+
+    component counter label {
+        text: "Count: 0"
+        x: 20
+        y: 30
+    }
+
+    add counter to dashboard
+    show dashboard
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import threading
+import webbrowser
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from typing import Any, Dict, List, Optional
+
+from .layout import Screen, ScreenComponent, ScreenRegistry, Button, Label, TextBox
+from .canvas import Canvas, CanvasRegistry
+from .color_system import RGBColor
+
+
+# ---------------------------------------------------------------------------
+# HTML generation
+# ---------------------------------------------------------------------------
+
+_HTML_TEMPLATE = """\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>{title}</title>
+<style>
+  * {{ margin: 0; padding: 0; box-sizing: border-box; }}
+  body {{ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+         background: {bg}; }}
+  .zx-screen {{ position: relative; width: {width}px; height: {height}px;
+                margin: 20px auto; border: 1px solid #ddd; border-radius: 8px;
+                background: {bg}; overflow: hidden; box-shadow: 0 2px 8px rgba(0,0,0,.12); }}
+  .zx-label {{ position: absolute; }}
+  .zx-button {{ position: absolute; padding: 6px 16px; border: 1px solid #888;
+                border-radius: 4px; cursor: pointer; background: #f4f4f4; }}
+  .zx-button:hover {{ background: #e0e0e0; }}
+  .zx-textbox {{ position: absolute; padding: 4px 8px; border: 1px solid #aaa;
+                 border-radius: 3px; }}
+  .zx-canvas {{ position: relative; }}
+</style>
+</head>
+<body>
+<div class="zx-screen">
+{components}
+</div>
+{canvas_section}
+<script>
+  // Event relay — POST click events back to /event
+  document.querySelectorAll('.zx-button').forEach(btn => {{
+    btn.addEventListener('click', () => {{
+      fetch('/event', {{
+        method: 'POST',
+        headers: {{'Content-Type': 'application/json'}},
+        body: JSON.stringify({{component: btn.dataset.name, event: 'click'}})
+      }});
+    }});
+  }});
+</script>
+</body>
+</html>
+"""
+
+
+def _component_html(comp: ScreenComponent) -> str:
+    x = int(comp.get("x", 10))
+    y = int(comp.get("y", 10))
+    color = comp.get("color", "black")
+    text = comp.get("text", comp.name)
+
+    if isinstance(comp, Button):
+        return (f'<button class="zx-button" data-name="{comp.name}" '
+                f'style="left:{x}px;top:{y}px;color:{color}">{text}</button>')
+    if isinstance(comp, TextBox):
+        w = int(comp.get("width", 20))
+        return (f'<input class="zx-textbox" '
+                f'style="left:{x}px;top:{y}px;width:{w*8}px;color:{color}" '
+                f'value="{text}" />')
+    # Default: Label
+    size = int(comp.get("fontSize", 14))
+    return (f'<span class="zx-label" '
+            f'style="left:{x}px;top:{y}px;font-size:{size}px;color:{color}">{text}</span>')
+
+
+def _canvas_svg(canvas: Canvas) -> str:
+    """Render a ``Canvas`` as an inline SVG element."""
+    scale = 4
+    w, h = canvas.width * scale, canvas.height * scale
+    lines: List[str] = [f'<svg class="zx-canvas" width="{w}" height="{h}" '
+                        f'style="margin:20px auto;display:block;border:1px solid #ddd">']
+    for op_type, args in canvas.operations:
+        if op_type == "line":
+            x1, y1, x2, y2 = args
+            lines.append(f'<line x1="{x1*scale}" y1="{y1*scale}" '
+                         f'x2="{x2*scale}" y2="{y2*scale}" stroke="black" stroke-width="2"/>')
+        elif op_type == "text":
+            x, y, text = args
+            lines.append(f'<text x="{x*scale}" y="{y*scale+12}">{text}</text>')
+    lines.append("</svg>")
+    return "\n".join(lines)
+
+
+def build_html(screen: Screen, canvases: Optional[Dict[str, Canvas]] = None) -> str:
+    title = str(screen.get("title", screen.name))
+    width = int(screen.get("width", 600))
+    height = int(screen.get("height", 400))
+    bg = str(screen.get("background", "#ffffff"))
+
+    components = "\n".join(_component_html(c) for c in screen.children)
+    canvas_section = ""
+    if canvases:
+        canvas_section = "\n".join(_canvas_svg(c) for c in canvases.values())
+
+    return _HTML_TEMPLATE.format(
+        title=title, width=width, height=height, bg=bg,
+        components=components, canvas_section=canvas_section,
+    )
+
+
+# ---------------------------------------------------------------------------
+# HTTP server
+# ---------------------------------------------------------------------------
+
+class _Handler(BaseHTTPRequestHandler):
+    """Serves the screen HTML and accepts event POSTs."""
+
+    backend: "WebBackend"  # set on class before server starts
+
+    def do_GET(self):
+        html = self.backend._current_html or "<h1>No screen loaded</h1>"
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.end_headers()
+        self.wfile.write(html.encode())
+
+    def do_POST(self):
+        length = int(self.headers.get("Content-Length", 0))
+        body = self.rfile.read(length)
+        try:
+            data = json.loads(body)
+            comp_name = data.get("component", "")
+            event = data.get("event", "")
+            handler = self.backend._event_handlers.get(f"{comp_name}:{event}")
+            if handler:
+                handler()
+        except Exception:
+            pass
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(b'{"ok":true}')
+
+    def log_message(self, format, *args):
+        pass  # silence request logs
+
+
+# ---------------------------------------------------------------------------
+# WebBackend
+# ---------------------------------------------------------------------------
+
+class WebBackend:
+    """Serves Zexus UI as HTML on a local HTTP port."""
+
+    def __init__(self, screen_registry: Optional[ScreenRegistry] = None,
+                 canvas_registry: Optional[CanvasRegistry] = None,
+                 port: int = 0) -> None:
+        self.screen_registry = screen_registry or ScreenRegistry()
+        self.canvas_registry = canvas_registry or CanvasRegistry()
+        self._port = port
+        self._server: Optional[HTTPServer] = None
+        self._thread: Optional[threading.Thread] = None
+        self._current_html: Optional[str] = None
+        self._event_handlers: Dict[str, Any] = {}
+
+    @property
+    def url(self) -> str:
+        if self._server:
+            return f"http://localhost:{self._server.server_address[1]}"
+        return ""
+
+    # -- Lifecycle ---------------------------------------------------------
+
+    def start(self) -> None:
+        handler_cls = type("H", (_Handler,), {"backend": self})
+        self._server = HTTPServer(("127.0.0.1", self._port), handler_cls)
+        self._port = self._server.server_address[1]
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        if self._server:
+            self._server.shutdown()
+
+    # -- Screen rendering --------------------------------------------------
+
+    def show_screen(self, name: str, open_browser: bool = True) -> str:
+        """Build HTML from a registered screen and serve it.
+
+        Returns the URL.
+        """
+        if self._server is None:
+            self.start()
+
+        screen = self.screen_registry.get_screen(name)
+        canvases = self.canvas_registry.snapshot() if self.canvas_registry else None
+        # Convert snapshot dicts back to Canvas objects for rendering
+        canvas_objs: Dict[str, Canvas] = {}
+        if self.canvas_registry:
+            canvas_objs = dict(self.canvas_registry.canvases)
+        self._current_html = build_html(screen, canvas_objs or None)
+
+        url = self.url
+        if open_browser:
+            webbrowser.open(url)
+        return url
+
+    # -- Event binding -----------------------------------------------------
+
+    def on(self, component_name: str, event: str, handler) -> None:
+        self._event_handlers[f"{component_name}:{event}"] = handler
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+def create_web_backend(**kwargs) -> WebBackend:
+    backend = WebBackend(**kwargs)
+    backend.start()
+    return backend

package/src/zexus/runtime/__init__.py

@@ -8,7 +8,12 @@ from .async_runtime import (
     Task,
     get_event_loop,
     set_event_loop,
-    new_event_loop
+    new_event_loop,
+)
+from .load_manager import (
+    get_load_manager,
+    register_provider,
+    clear_load_caches,
 )
 
 __all__ = [
@@ -16,5 +21,8 @@ __all__ = [
     'Task',
     'get_event_loop',
     'set_event_loop',
-    'new_event_loop'
+    'new_event_loop',
+    'get_load_manager',
+    'register_provider',
+    'clear_load_caches',
 ]

package/src/zexus/runtime/file_flags.py

@@ -0,0 +1,137 @@
+"""Parse and apply inline file flags for Zexus execution.
+
+Supported directive formats (first 25 lines):
+- // @zexus: {"use_vm": true, "vm_mode": "stack", "no_optimize": false}
+- # @zexus: use_vm=true; vm_mode=auto; debug=full
+
+Values accept booleans, ints, floats, or strings.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+import json
+import re
+
+_MAX_SCAN_LINES = 25
+
+
+def parse_file_flags(source: str) -> Dict[str, Any]:
+    flags: Dict[str, Any] = {}
+    if not source:
+        return flags
+
+    lines = source.splitlines()[:_MAX_SCAN_LINES]
+    for line in lines:
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if "@zexus" not in stripped:
+            continue
+
+        # Strip leading comment markers
+        directive = stripped
+        for prefix in ("//", "#", "/*", "*/"):
+            if directive.startswith(prefix):
+                directive = directive[len(prefix):].strip()
+        # Remove leading @zexus marker
+        if directive.lower().startswith("@zexus"):
+            directive = directive[len("@zexus"):].strip()
+        if directive.startswith(":"):
+            directive = directive[1:].strip()
+
+        # JSON object form
+        if "{" in directive:
+            json_part = directive[directive.find("{"):].strip()
+            try:
+                parsed = json.loads(json_part)
+                if isinstance(parsed, dict):
+                    flags.update(parsed)
+            except Exception:
+                pass
+            continue
+
+        # key=value form (semicolon or comma separated)
+        for part in re.split(r"[;,]", directive):
+            part = part.strip()
+            if not part:
+                continue
+            if "=" not in part:
+                continue
+            key, raw_val = part.split("=", 1)
+            key = key.strip()
+            raw_val = raw_val.strip()
+            flags[key] = _parse_value(raw_val)
+
+    return flags
+
+
+def _parse_value(raw: str) -> Any:
+    if not raw:
+        return raw
+    lowered = raw.lower()
+    if lowered in ("true", "yes", "on"):
+        return True
+    if lowered in ("false", "no", "off"):
+        return False
+    # numbers
+    try:
+        if "." in raw:
+            return float(raw)
+        return int(raw)
+    except Exception:
+        pass
+    # quoted string
+    if (raw.startswith("\"") and raw.endswith("\"")) or (raw.startswith("'") and raw.endswith("'")):
+        return raw[1:-1]
+    return raw
+
+
+def apply_vm_config(vm, vm_config: Dict[str, Any]) -> None:
+    if not vm_config:
+        return
+
+    mode_value = vm_config.get("mode")
+    if isinstance(mode_value, str):
+        try:
+            from ..vm.vm import VMMode
+            vm.mode = VMMode(mode_value.lower())
+        except Exception:
+            pass
+
+    # Explicit gas metering disable
+    if vm_config.get("enable_gas_metering") is False:
+        try:
+            vm.enable_gas_metering = False
+            vm.gas_metering = None
+        except Exception:
+            pass
+
+    # perf fast dispatch
+    if vm_config.get("perf_fast_dispatch") is True:
+        try:
+            vm._perf_fast_dispatch = True
+        except Exception:
+            pass
+
+    if vm_config.get("prefer_register") is True:
+        try:
+            vm.prefer_register = True
+        except Exception:
+            pass
+
+    if vm_config.get("prefer_parallel") is True:
+        try:
+            vm.prefer_parallel = True
+        except Exception:
+            pass
+
+    # generic attribute setters
+    for key, value in vm_config.items():
+        if key == "mode":
+            continue
+        if hasattr(vm, key):
+            try:
+                setattr(vm, key, value)
+            except Exception:
+                continue