zexus 1.6.8 → 1.7.2

package/src/zexus/renderer/canvas.py

@@ -0,0 +1,78 @@
+"""Lightweight drawing canvas used for renderer CANVAS helpers."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Tuple
+
+from .color_system import RGBColor
+
+
+@dataclass
+class Canvas:
+    width: int
+    height: int
+    pixels: List[List[str]] = field(init=False)
+    colours: List[List[RGBColor | None]] = field(init=False)
+    operations: List[Tuple[str, Tuple[object, ...]]] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        self.pixels = [[" " for _ in range(self.width)] for _ in range(self.height)]
+        self.colours = [[None for _ in range(self.width)] for _ in range(self.height)]
+
+    # ------------------------------------------------------------------
+    def draw_line(self, x1: int, y1: int, x2: int, y2: int, *, char: str = "█", colour: RGBColor | None = None) -> None:
+        orig = (x1, y1, x2, y2)
+        dx = abs(x2 - x1)
+        dy = -abs(y2 - y1)
+        sx = 1 if x1 < x2 else -1
+        sy = 1 if y1 < y2 else -1
+        err = dx + dy
+        while True:
+            self._plot(x1, y1, char, colour)
+            if x1 == x2 and y1 == y2:
+                break
+            e2 = 2 * err
+            if e2 >= dy:
+                err += dy
+                x1 += sx
+            if e2 <= dx:
+                err += dx
+                y1 += sy
+        self.operations.append(("line", orig))
+
+    def draw_text(self, x: int, y: int, text: str, *, colour: RGBColor | None = None) -> None:
+        for offset, ch in enumerate(text):
+            self._plot(x + offset, y, ch, colour)
+        self.operations.append(("text", (x, y, text)))
+
+    def snapshot(self) -> Dict[str, object]:
+        return {
+            "width": self.width,
+            "height": self.height,
+            "pixels": ["".join(row) for row in self.pixels],
+            "draw_ops": list(self.operations),
+        }
+
+    # ------------------------------------------------------------------
+    def _plot(self, x: int, y: int, char: str, colour: RGBColor | None) -> None:
+        if 0 <= x < self.width and 0 <= y < self.height:
+            self.pixels[y][x] = char
+            self.colours[y][x] = colour
+
+
+@dataclass
+class CanvasRegistry:
+    canvases: Dict[str, Canvas] = field(default_factory=dict)
+
+    def create(self, *, width: int, height: int) -> str:
+        identifier = f"canvas_{len(self.canvases) + 1}"
+        self.canvases[identifier] = Canvas(width, height)
+        return identifier
+
+    def get(self, identifier: str) -> Canvas:
+        if identifier not in self.canvases:
+            raise KeyError(f"canvas '{identifier}' not found")
+        return self.canvases[identifier]
+
+    def snapshot(self) -> Dict[str, Dict[str, object]]:
+        return {name: canvas.snapshot() for name, canvas in self.canvases.items()}

package/src/zexus/renderer/color_system.py

@@ -0,0 +1,201 @@
+"""Colour utilities for the Zexus renderer.
+
+The previous implementation lived at ``renderer/color_system.py``.  The new
+version adopts dataclasses, immutability and richer typing to make the colour
+pipeline easier to reason about and safer to share between the interpreter and
+VM backends.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Tuple
+
+
+def _clamp(value: float, lo: float, hi: float) -> float:
+    return max(lo, min(hi, value))
+
+
+@dataclass(frozen=True)
+class RGBColor:
+    """Simple immutable RGB colour representation."""
+
+    r: int
+    g: int
+    b: int
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "r", int(_clamp(self.r, 0, 255)))
+        object.__setattr__(self, "g", int(_clamp(self.g, 0, 255)))
+        object.__setattr__(self, "b", int(_clamp(self.b, 0, 255)))
+
+    # ------------------------------------------------------------------
+    # Blending helpers
+    # ------------------------------------------------------------------
+    def mix(self, other: "RGBColor", ratio: float = 0.5) -> "RGBColor":
+        ratio = _clamp(ratio, 0.0, 1.0)
+        inv = 1.0 - ratio
+        return RGBColor(
+            int(self.r * inv + other.r * ratio),
+            int(self.g * inv + other.g * ratio),
+            int(self.b * inv + other.b * ratio),
+        )
+
+    def lighten(self, amount: float = 0.1) -> "RGBColor":
+        return self.mix(RGBColor(255, 255, 255), amount)
+
+    def darken(self, amount: float = 0.1) -> "RGBColor":
+        return self.mix(RGBColor(0, 0, 0), amount)
+
+    # ------------------------------------------------------------------
+    # Conversions
+    # ------------------------------------------------------------------
+    def to_hsv(self) -> Tuple[float, float, float]:
+        r, g, b = self.r / 255.0, self.g / 255.0, self.b / 255.0
+        c_max = max(r, g, b)
+        c_min = min(r, g, b)
+        delta = c_max - c_min
+
+        if delta == 0:
+            hue = 0.0
+        elif c_max == r:
+            hue = (60 * ((g - b) / delta)) % 360
+        elif c_max == g:
+            hue = 60 * (((b - r) / delta) + 2)
+        else:
+            hue = 60 * (((r - g) / delta) + 4)
+
+        saturation = 0.0 if c_max == 0 else delta / c_max
+        value = c_max
+        return hue, saturation, value
+
+    @staticmethod
+    def from_hsv(h: float, s: float, v: float) -> "RGBColor":
+        h = h % 360
+        s = _clamp(s, 0.0, 1.0)
+        v = _clamp(v, 0.0, 1.0)
+
+        c = v * s
+        x = c * (1 - abs(((h / 60.0) % 2) - 1))
+        m = v - c
+
+        if 0 <= h < 60:
+            r, g, b = c, x, 0
+        elif 60 <= h < 120:
+            r, g, b = x, c, 0
+        elif 120 <= h < 180:
+            r, g, b = 0, c, x
+        elif 180 <= h < 240:
+            r, g, b = 0, x, c
+        elif 240 <= h < 300:
+            r, g, b = x, 0, c
+        else:
+            r, g, b = c, 0, x
+
+        return RGBColor(int((r + m) * 255), int((g + m) * 255), int((b + m) * 255))
+
+    # ------------------------------------------------------------------
+    def to_ansi(self, *, background: bool = False) -> str:
+        code = 48 if background else 38
+        return f"\033[{code};2;{self.r};{self.g};{self.b}m"
+
+    def __str__(self) -> str:  # pragma: no cover - human-friendly repr
+        return f"#{self.r:02x}{self.g:02x}{self.b:02x}"
+
+
+class ColorPalette:
+    """Palette of named colours with simple mixing helpers."""
+
+    def __init__(self) -> None:
+        self._base = self._build_base_palette()
+        self._custom: Dict[str, RGBColor] = {}
+        self._gradients: Dict[str, List[RGBColor]] = {}
+
+    @staticmethod
+    def _build_base_palette() -> Dict[str, RGBColor]:
+        values = {
+            "red": (255, 59, 48),
+            "orange": (255, 149, 0),
+            "yellow": (255, 204, 0),
+            "green": (52, 199, 89),
+            "mint": (0, 199, 190),
+            "teal": (48, 176, 199),
+            "cyan": (50, 173, 230),
+            "blue": (0, 122, 255),
+            "indigo": (88, 86, 214),
+            "purple": (175, 82, 222),
+            "pink": (255, 45, 85),
+            "brown": (162, 132, 94),
+            "white": (255, 255, 255),
+            "gray": (142, 142, 147),
+            "gray2": (174, 174, 178),
+            "gray3": (199, 199, 204),
+            "gray4": (209, 209, 214),
+            "gray5": (229, 229, 234),
+            "gray6": (242, 242, 247),
+            "black": (0, 0, 0),
+        }
+        base = {name: RGBColor(*rgb) for name, rgb in values.items()}
+        for name, colour in list(base.items()):
+            base[f"light_{name}"] = colour.lighten(0.3)
+            base[f"dark_{name}"] = colour.darken(0.3)
+        return base
+
+    # ------------------------------------------------------------------
+    def get(self, name: str) -> RGBColor:
+        if name in self._base:
+            return self._base[name]
+        if name in self._custom:
+            return self._custom[name]
+        raise KeyError(f"unknown colour '{name}'")
+
+    def define(self, name: str, colour: RGBColor) -> None:
+        self._custom[name] = colour
+
+    def mix(self, colour_a: str, colour_b: str, ratio: float = 0.5) -> RGBColor:
+        colour = self.get(colour_a).mix(self.get(colour_b), ratio)
+        return colour
+
+    def gradient(self, start: str, end: str, steps: int, *, name: str | None = None) -> List[RGBColor]:
+        steps = max(2, steps)
+        start_colour = self.get(start)
+        end_colour = self.get(end)
+        values = [start_colour.mix(end_colour, i / (steps - 1)) for i in range(steps)]
+        if name:
+            self._gradients[name] = values
+        return values
+
+    def list_names(self) -> Iterable[str]:
+        yield from self._base.keys()
+        yield from self._custom.keys()
+
+
+class Theme:
+    """Collection of palette-derived colours."""
+
+    def __init__(self, name: str, palette: ColorPalette) -> None:
+        self.name = name
+        self._palette = palette
+        self._colours: Dict[str, RGBColor] = {}
+
+    def set_colour(self, key: str, colour_name: str) -> None:
+        self._colours[key] = self._palette.get(colour_name)
+
+    def derive_from(self, colour_name: str) -> None:
+        base = self._palette.get(colour_name)
+        self._colours.update(
+            {
+                "primary": base,
+                "primary_light": base.lighten(0.2),
+                "primary_dark": base.darken(0.2),
+            }
+        )
+
+    def get(self, key: str, default: str | None = None) -> RGBColor:
+        if key in self._colours:
+            return self._colours[key]
+        if default:
+            return self._palette.get(default)
+        return self._palette.get("black")
+
+    def snapshot(self) -> Dict[str, str]:
+        return {key: str(colour) for key, colour in self._colours.items()}

package/src/zexus/renderer/graphics.py

@@ -0,0 +1,31 @@
+"""Utility helpers for higher-level graphics composition.
+
+The original module exposed a number of free-form helpers.  For now we provide
+lightweight primitives that are sufficient for interpreter driven demos while
+keeping the door open for future expansion.
+"""
+from __future__ import annotations
+
+from typing import Iterable, List
+
+
+def merge_layers(layers: Iterable[List[str]]) -> List[str]:
+    """Merge multiple ASCII layers, preferring non-space characters."""
+    merged: List[str] = []
+    for layer in layers:
+        if not merged:
+            merged = list(layer)
+            continue
+        merged = [
+            "".join(c2 if c2 != " " else c1 for c1, c2 in zip(row1, row2))
+            for row1, row2 in zip(merged, layer)
+        ]
+    return merged
+
+
+def frame(text: str, *, padding: int = 1) -> str:
+    lines = text.splitlines() or [""]
+    width = max(len(line) for line in lines)
+    padded = [" " * padding + line.ljust(width) + " " * padding for line in lines]
+    horizontal = "─" * (width + padding * 2)
+    return "\n".join([f"┌{horizontal}┐", *[f"│{line}│" for line in padded], f"└{horizontal}┘"])

package/src/zexus/renderer/layout.py

@@ -0,0 +1,222 @@
+"""Screen/component hierarchy used by the renderer backend.
+
+The API mirrors the original ``renderer.layout`` module but embraces dataclasses
+and type hints.  Rendering still produces ASCII output so existing snapshot
+based tests continue to work.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, List, Optional
+
+
+@dataclass
+class ScreenComponent:
+    name: str
+    properties: Dict[str, object] = field(default_factory=dict)
+    children: List["ScreenComponent"] = field(default_factory=list)
+    parent: Optional["ScreenComponent"] = None
+    type: str = "component"
+
+    def add_child(self, component: "ScreenComponent") -> None:
+        component.parent = self
+        self.children.append(component)
+
+    # ------------------------------------------------------------------
+    def get(self, key: str, default: object | None = None) -> object | None:
+        if key in self.properties:
+            return self.properties[key]
+        if self.parent:
+            return self.parent.get(key, default)
+        return default
+
+    def clone(self, name: Optional[str] = None) -> "ScreenComponent":
+        copied = type(self)(name or self.name, **dict(self.properties))
+        for child in self.children:
+            copied.add_child(child.clone())
+        return copied
+
+    # Rendering ---------------------------------------------------------
+    def render(self, width: int, height: int) -> List[str]:  # pragma: no cover - overridden
+        raise NotImplementedError
+
+
+@dataclass
+class Screen(ScreenComponent):
+    type: str = "screen"
+
+    def __post_init__(self) -> None:
+        self.properties.setdefault("width", 80)
+        self.properties.setdefault("height", 24)
+        self.properties.setdefault("border", True)
+        self.properties.setdefault("title", "")
+
+    def render(self, width: int, height: int) -> List[str]:
+        screen_width = int(self.get("width", width))
+        screen_height = int(self.get("height", height))
+        show_border = bool(self.get("border", True))
+
+        canvas = [[" " for _ in range(screen_width)] for _ in range(screen_height)]
+
+        if show_border:
+            _draw_border(canvas)
+
+        title = str(self.get("title", ""))
+        if title:
+            _draw_title(canvas, title)
+
+        for child in self.children:
+            child_canvas = child.render(screen_width - 4, screen_height - 4)
+            origin_x = int(child.get("x", 2))
+            origin_y = int(child.get("y", 2))
+            _blit(canvas, child_canvas, origin_x, origin_y)
+
+        return ["".join(row) for row in canvas]
+
+
+@dataclass
+class Button(ScreenComponent):
+    type: str = "button"
+
+    def __post_init__(self) -> None:
+        defaults = {
+            "text": "Button",
+            "width": 14,
+            "height": 3,
+            "enabled": True,
+            "x": 0,
+            "y": 0,
+        }
+        for key, value in defaults.items():
+            self.properties.setdefault(key, value)
+
+    def render(self, width: int, height: int) -> List[str]:
+        w = max(3, int(self.get("width", 14)))
+        h = max(3, int(self.get("height", 3)))
+        text = str(self.get("text", "Button"))[: w - 2]
+        enabled = bool(self.get("enabled", True))
+        border = ("┌", "┐", "└", "┘", "─", "│") if enabled else ("+", "+", "+", "+", "-", "|")
+
+        lines = [border[0] + border[4] * (w - 2) + border[1]]
+        lines.append(border[5] + text.center(w - 2) + border[5])
+        lines.append(border[2] + border[4] * (w - 2) + border[3])
+        while len(lines) < h:
+            lines.append(" " * w)
+        return lines
+
+
+@dataclass
+class TextBox(ScreenComponent):
+    type: str = "textbox"
+
+    def __post_init__(self) -> None:
+        defaults = {
+            "text": "",
+            "placeholder": "",
+            "width": 20,
+            "height": 3,
+            "x": 0,
+            "y": 0,
+        }
+        for key, value in defaults.items():
+            self.properties.setdefault(key, value)
+
+    def render(self, width: int, height: int) -> List[str]:
+        w = max(4, int(self.get("width", 20)))
+        h = max(3, int(self.get("height", 3)))
+        text = str(self.get("text", "")) or str(self.get("placeholder", ""))
+        if len(text) > w - 4:
+            text = f"{text[: w - 7]}..."
+
+        lines = ["┌" + "─" * (w - 2) + "┐"]
+        lines.append("│ " + text.ljust(w - 4) + " │")
+        lines.append("└" + "─" * (w - 2) + "┘")
+        while len(lines) < h:
+            lines.append(" " * w)
+        return lines
+
+
+@dataclass
+class Label(ScreenComponent):
+    type: str = "label"
+
+    def __post_init__(self) -> None:
+        self.properties.setdefault("text", "")
+        self.properties.setdefault("x", 0)
+        self.properties.setdefault("y", 0)
+
+    def render(self, width: int, height: int) -> List[str]:
+        return [str(self.get("text", ""))]
+
+
+class ScreenRegistry:
+    def __init__(self) -> None:
+        self._screens: Dict[str, Screen] = {}
+        self._components: Dict[str, ScreenComponent] = {}
+
+    # ------------------------------------------------------------------
+    def register_screen(self, screen: Screen) -> None:
+        self._screens[screen.name] = screen
+
+    def register_component(self, component: ScreenComponent) -> None:
+        self._components[component.name] = component
+
+    def get_screen(self, name: str) -> Screen:
+        if name not in self._screens:
+            raise KeyError(f"screen '{name}' not defined")
+        return self._screens[name]
+
+    def get_component(self, name: str) -> ScreenComponent:
+        if name not in self._components:
+            raise KeyError(f"component '{name}' not defined")
+        return self._components[name]
+
+    def clone_screen(self, name: str) -> Screen:
+        return self.get_screen(name).clone()
+
+    def list_screens(self) -> Iterable[str]:
+        return list(self._screens.keys())
+
+    def list_components(self) -> Iterable[str]:
+        return list(self._components.keys())
+
+    def snapshot(self) -> Dict[str, Screen]:
+        return dict(self._screens)
+
+    def component_snapshot(self) -> Dict[str, ScreenComponent]:
+        return dict(self._components)
+
+
+# Internal helpers ------------------------------------------------------
+
+def _draw_border(canvas: List[List[str]]) -> None:
+    width = len(canvas[0])
+    height = len(canvas)
+    canvas[0][0] = "╭"
+    canvas[0][width - 1] = "╮"
+    canvas[height - 1][0] = "╰"
+    canvas[height - 1][width - 1] = "╯"
+    for x in range(1, width - 1):
+        canvas[0][x] = "─"
+        canvas[height - 1][x] = "─"
+    for y in range(1, height - 1):
+        canvas[y][0] = "│"
+        canvas[y][width - 1] = "│"
+
+
+def _draw_title(canvas: List[List[str]], title: str) -> None:
+    width = len(canvas[0])
+    title = f" {title} "
+    title = title if len(title) < width - 2 else title[: width - 5] + "..."
+    offset = max(1, (width - len(title)) // 2)
+    for i, ch in enumerate(title):
+        canvas[0][offset + i] = ch
+
+
+def _blit(canvas: List[List[str]], child: List[str], x: int, y: int) -> None:
+    for row, line in enumerate(child):
+        for col, ch in enumerate(line):
+            target_y = y + row
+            target_x = x + col
+            if 0 <= target_y < len(canvas) and 0 <= target_x < len(canvas[0]) and ch != " ":
+                canvas[target_y][target_x] = ch

package/src/zexus/renderer/main_renderer.py

@@ -0,0 +1,66 @@
+"""High-level renderer facade used by the backend."""
+from __future__ import annotations
+
+from typing import Dict
+
+from .layout import Button, Label, Screen, ScreenComponent, ScreenRegistry, TextBox
+from .painter import AsciiPainter
+
+
+_COMPONENT_TYPES: Dict[str, type[ScreenComponent]] = {
+    "button": Button,
+    "textbox": TextBox,
+    "label": Label,
+    "screen": Screen,
+}
+
+
+class ZexusScreenRenderer:
+    def __init__(self, registry: ScreenRegistry | None = None) -> None:
+        self.registry = registry or ScreenRegistry()
+        self.painter = AsciiPainter()
+        self._install_default_components()
+
+    def _install_default_components(self) -> None:
+        if "primary_button" not in self.registry.list_components():
+            self.define_component("primary_button", "button", text="Submit", color="blue")
+        if "secondary_button" not in self.registry.list_components():
+            self.define_component("secondary_button", "button", text="Cancel", color="gray")
+
+    # ------------------------------------------------------------------
+    def define_screen(self, name: str, **properties) -> Screen:
+        screen = Screen(name)
+        if properties:
+            screen.properties.update(properties)
+        self.registry.register_screen(screen)
+        return screen
+
+    def define_component(self, name: str, component_type: str | None = None, **properties) -> ScreenComponent:
+        if component_type is None:
+            component_type = str(properties.pop("type", "label"))
+        if component_type not in _COMPONENT_TYPES:
+            raise ValueError(f"unknown component type '{component_type}'")
+        component = _COMPONENT_TYPES[component_type](name)
+        if properties:
+            component.properties.update(properties)
+        self.registry.register_component(component)
+        return component
+
+    def add_to_screen(self, screen_name: str, component_name: str, **overrides) -> None:
+        screen = self.registry.get_screen(screen_name)
+        component = self.registry.get_component(component_name)
+        clone = component.clone()
+        clone.properties.update(overrides)
+        screen.add_child(clone)
+
+    def render_screen(self, screen_name: str, **overrides) -> str:
+        screen = self.registry.clone_screen(screen_name)
+        screen.properties.update(overrides)
+
+        width = int(screen.get("width", 80))
+        height = int(screen.get("height", 24))
+        self.painter.init_screen(width, height)
+
+        rendered_lines = screen.render(width, height)
+        self.painter.draw_lines(rendered_lines, 0, 0)
+        return self.painter.render()

package/src/zexus/renderer/painter.py

@@ -0,0 +1,30 @@
+"""ASCII painter used by ``main_renderer``."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+
+@dataclass
+class AsciiPainter:
+    width: int = 0
+    height: int = 0
+    buffer: List[List[str]] = field(default_factory=list)
+
+    def init_screen(self, width: int, height: int) -> None:
+        self.width = width
+        self.height = height
+        self.buffer = [[" " for _ in range(width)] for _ in range(height)]
+
+    def draw_lines(self, lines: List[str], x: int, y: int) -> None:
+        for row, line in enumerate(lines):
+            target_y = y + row
+            if not (0 <= target_y < self.height):
+                continue
+            for col, char in enumerate(line):
+                target_x = x + col
+                if 0 <= target_x < self.width and char != " ":
+                    self.buffer[target_y][target_x] = char
+
+    def render(self) -> str:
+        return "\n".join("".join(row) for row in self.buffer)