minilibx-python 0.1.0__py3-none-any.whl

minilibx_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: minilibx-python
+Version: 0.1.0
+Summary: Python wrapper for MiniLibX — the 42 school graphics library
+License: MIT
+Project-URL: Homepage, https://github.com/yourname/pymlx
+Project-URL: Repository, https://github.com/yourname/pymlx
+Keywords: minilibx,42school,graphics,x11
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# pymlx
+
+A Python wrapper for [MiniLibX](https://github.com/42Paris/minilibx-linux) — the simple X11 graphics library used at 42 school.
+
+Lets you open windows, draw shapes, and handle keyboard/mouse events in pure Python.
+
+```python
+from pymlx import Mlx, Color
+
+with Mlx() as mlx:
+    win = mlx.new_window(800, 600, "Hello pymlx")
+    img = mlx.new_image(800, 600)
+
+    img.draw_circle(400, 300, 100, Color.RED)
+    img.draw_rect(50, 50, 200, 100, Color.BLUE)
+    img.draw_line(0, 0, 800, 600, Color.WHITE)
+
+    win.put_image(img)
+    win.on_close(mlx.loop_end)
+    win.on_key(lambda key: mlx.loop_end() if key == 65307 else None)
+
+    mlx.loop()
+```
+
+## Requirements
+
+- Linux with X11
+- Python 3.10+
+- `gcc`, `make`
+- `libX11-dev`, `libXext-dev`
+
+```bash
+sudo apt install gcc make libx11-dev libxext-dev
+```
+
+## Installation
+
+```bash
+git clone https://github.com/yourname/pymlx.git
+cd pymlx
+
+# Build the C wrapper
+make -C src/pymlx MLX_DIR=src/pymlx/lib/minilibx-linux
+
+# Install the package
+pip install -e .
+```
+
+## API
+
+### `Mlx`
+
+Main context. Use as a context manager.
+
+```python
+mlx = Mlx()
+mlx.new_window(width, height, title) -> Window
+mlx.new_image(width, height)         -> Image
+mlx.destroy_image(image)
+mlx.on_loop(callback)   # callback() called every frame
+mlx.loop()              # start event loop (blocking)
+mlx.loop_end()          # stop event loop
+mlx.destroy()
+```
+
+### `Window`
+
+```python
+win.put_image(image, x=0, y=0)           # blit image onto window
+win.pixel_put(x, y, color)               # direct pixel (slow)
+win.string_put(x, y, color, text)        # draw text
+
+win.on_key(callback)      # callback(keycode: int)
+win.on_mouse(callback)    # callback(button, x, y)
+win.on_close(callback)    # called on window close
+win.on_event(event, mask, callback)      # raw X11 event
+
+win.mouse_hide()
+win.mouse_show()
+win.mouse_pos() -> (x, y)
+win.mouse_move(x, y)
+win.destroy()
+```
+
+### `Image`
+
+All drawing methods write directly into the pixel buffer — fast enough for real-time rendering.
+
+```python
+# Pixels
+img.pixel_put(x, y, color)
+img.pixel_get(x, y) -> int
+img.clear(color)
+
+# Rectangles
+img.draw_rect(x, y, w, h, color)
+img.draw_rect_outline(x, y, w, h, color, thickness=1)
+
+# Lines
+img.draw_line(x0, y0, x1, y1, color)
+img.draw_line_thick(x0, y0, x1, y1, color, thickness=2)
+
+# Circles
+img.draw_circle(cx, cy, radius, color)
+img.draw_circle_outline(cx, cy, radius, color, thickness=1)
+
+# Triangles
+img.draw_triangle(x0, y0, x1, y1, x2, y2, color)
+img.draw_triangle_outline(x0, y0, x1, y1, x2, y2, color)
+
+# Gradients
+img.draw_gradient_h(x, y, w, h, color_left, color_right)
+img.draw_gradient_v(x, y, w, h, color_top, color_bottom)
+
+# Polygon outline
+img.draw_polygon([(x, y), ...], color)
+
+# Flood fill
+img.flood_fill(x, y, color)
+```
+
+### `Color`
+
+```python
+Color.BLACK, Color.WHITE, Color.RED, Color.GREEN
+Color.BLUE, Color.YELLOW, Color.CYAN, Color.MAGENTA
+Color.GRAY, Color.ORANGE, Color.PINK
+
+Color.rgb(r, g, b)        -> int   # 0–255 each
+Color.to_rgb(color)       -> (r, g, b)
+Color.lerp(c1, c2, t)     -> int   # t in [0.0, 1.0]
+```
+
+### `X11Event`
+
+```python
+X11Event.KEY_PRESS      # 2
+X11Event.KEY_RELEASE    # 3
+X11Event.BUTTON_PRESS   # 4
+X11Event.BUTTON_RELEASE # 5
+X11Event.MOTION_NOTIFY  # 6
+X11Event.DESTROY_NOTIFY # 17
+```
+
+## Example — animated gradient
+
+```python
+from pymlx import Mlx, Color
+
+W, H = 800, 600
+frame = 0
+
+with Mlx() as mlx:
+    win = mlx.new_window(W, H, "Gradient")
+    img = mlx.new_image(W, H)
+
+    def render():
+        global frame
+        t = (frame % 256) / 255
+        img.draw_gradient_h(0, 0, W, H,
+                            Color.lerp(Color.BLUE, Color.RED, t),
+                            Color.lerp(Color.RED, Color.BLUE, t))
+        win.put_image(img)
+        frame += 1
+
+    win.on_close(mlx.loop_end)
+    win.on_key(lambda k: mlx.loop_end() if k == 65307 else None)
+    mlx.on_loop(render)
+    mlx.loop()
+```
+
+## License
+
+MIT

minilibx_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+pymlx/__init__.py,sha256=fMafE7KmlVWkiPB3ngoh_G-P_pW6sOFEWQrkep2yCSs,113
+pymlx/core.py,sha256=HTylN7jOviBCWM-Zi32thuBuvXnYWEcDWaz19dliqbw,22942
+pymlx/lib/libmlx_wrapper.so,sha256=zTvHOhV_6Ay9pCU4L2_s9QkLLGxUzNi7J5AgR4uCa9w,39008
+minilibx_python-0.1.0.dist-info/METADATA,sha256=dCBOmT3Mod1jLIBOoplwSZTWeUgjQ4OVP4aU37MWtTk,4479
+minilibx_python-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+minilibx_python-0.1.0.dist-info/top_level.txt,sha256=q73JJdYIdIW82JnQHmMqAq3oZ2gy8VDsSjGoCpG_S0A,6
+minilibx_python-0.1.0.dist-info/RECORD,,

minilibx_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

minilibx_python-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pymlx

pymlx/__init__.py

@@ -0,0 +1,3 @@
+from .core import Mlx, Window, Image, Color, X11Event
+
+__all__ = ["Mlx", "Window", "Image", "Color", "X11Event"]

pymlx/core.py

@@ -0,0 +1,502 @@
+"""
+core.py — Python ctypes wrapper around libmlx_wrapper.so
+"""
+
+import ctypes
+import math
+from pathlib import Path
+
+# ─── Load shared library ──────────────────────────────────────────────────────
+_LIB_PATH = Path(__file__).parent / "lib" / "libmlx_wrapper.so"
+try:
+    _lib = ctypes.CDLL(str(_LIB_PATH))
+except OSError as e:
+    raise RuntimeError(
+        f"Cannot load libmlx_wrapper.so: {e}\n"
+        "Run `make` in the wrapper directory first."
+    )
+
+# ─── C struct: t_img_info ─────────────────────────────────────────────────────
+class _ImgInfo(ctypes.Structure):
+    _fields_ = [
+        ("img",            ctypes.c_void_p),
+        ("addr",           ctypes.c_char_p),
+        ("bits_per_pixel", ctypes.c_int),
+        ("line_length",    ctypes.c_int),
+        ("endian",         ctypes.c_int),
+    ]
+
+# ─── Callback types ───────────────────────────────────────────────────────────
+KeyCb     = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_int, ctypes.c_void_p)
+MouseCb   = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_int,
+                              ctypes.c_int, ctypes.c_int, ctypes.c_void_p)
+LoopCb    = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_void_p)
+GenericCb = ctypes.CFUNCTYPE(ctypes.c_int)
+
+# ─── Prototypes ───────────────────────────────────────────────────────────────
+def _proto(name, restype, *argtypes):
+    fn = getattr(_lib, name)
+    fn.restype  = restype
+    fn.argtypes = list(argtypes)
+    return fn
+
+_mlx_init             = _proto("wrap_mlx_init",               ctypes.c_void_p)
+_mlx_new_window       = _proto("wrap_mlx_new_window",         ctypes.c_void_p,
+                                ctypes.c_void_p, ctypes.c_int, ctypes.c_int,
+                                ctypes.c_char_p)
+_mlx_destroy_window   = _proto("wrap_mlx_destroy_window",     None,
+                                ctypes.c_void_p, ctypes.c_void_p)
+_mlx_destroy_display  = _proto("wrap_mlx_destroy_display",    None,
+                                ctypes.c_void_p)
+_mlx_new_image        = _proto("wrap_mlx_new_image",          _ImgInfo,
+                                ctypes.c_void_p, ctypes.c_int, ctypes.c_int)
+_mlx_destroy_image    = _proto("wrap_mlx_destroy_image",      None,
+                                ctypes.c_void_p, ctypes.c_void_p)
+_mlx_put_image_to_win = _proto("wrap_mlx_put_image_to_window", None,
+                                ctypes.c_void_p, ctypes.c_void_p,
+                                ctypes.c_void_p, ctypes.c_int, ctypes.c_int)
+_img_pixel_put        = _proto("wrap_img_pixel_put",          None,
+                                ctypes.POINTER(_ImgInfo),
+                                ctypes.c_int, ctypes.c_int, ctypes.c_int)
+_img_pixel_get        = _proto("wrap_img_pixel_get",          ctypes.c_int,
+                                ctypes.POINTER(_ImgInfo),
+                                ctypes.c_int, ctypes.c_int)
+_img_clear            = _proto("wrap_img_clear",              None,
+                                ctypes.POINTER(_ImgInfo), ctypes.c_int)
+_mlx_pixel_put        = _proto("wrap_mlx_pixel_put",          None,
+                                ctypes.c_void_p, ctypes.c_void_p,
+                                ctypes.c_int, ctypes.c_int, ctypes.c_int)
+_mlx_string_put       = _proto("wrap_mlx_string_put",         None,
+                                ctypes.c_void_p, ctypes.c_void_p,
+                                ctypes.c_int, ctypes.c_int, ctypes.c_int,
+                                ctypes.c_char_p)
+_mlx_key_hook         = _proto("wrap_mlx_key_hook",           None,
+                                ctypes.c_void_p, KeyCb, ctypes.c_void_p)
+_mlx_mouse_hook       = _proto("wrap_mlx_mouse_hook",         None,
+                                ctypes.c_void_p, MouseCb, ctypes.c_void_p)
+_mlx_hook             = _proto("wrap_mlx_hook",               None,
+                                ctypes.c_void_p, ctypes.c_int, ctypes.c_int,
+                                GenericCb, ctypes.c_void_p)
+_mlx_loop_hook        = _proto("wrap_mlx_loop_hook",          None,
+                                ctypes.c_void_p, LoopCb, ctypes.c_void_p)
+_mlx_loop             = _proto("wrap_mlx_loop",               None,
+                                ctypes.c_void_p)
+_mlx_loop_end         = _proto("wrap_mlx_loop_end",           None,
+                                ctypes.c_void_p)
+_mlx_mouse_hide       = _proto("wrap_mlx_mouse_hide",         ctypes.c_int,
+                                ctypes.c_void_p, ctypes.c_void_p)
+_mlx_mouse_show       = _proto("wrap_mlx_mouse_show",         ctypes.c_int,
+                                ctypes.c_void_p, ctypes.c_void_p)
+_mlx_mouse_get_pos    = _proto("wrap_mlx_mouse_get_pos",      ctypes.c_int,
+                                ctypes.c_void_p, ctypes.c_void_p,
+                                ctypes.POINTER(ctypes.c_int),
+                                ctypes.POINTER(ctypes.c_int))
+_mlx_mouse_move       = _proto("wrap_mlx_mouse_move",         ctypes.c_int,
+                                ctypes.c_void_p, ctypes.c_void_p,
+                                ctypes.c_int, ctypes.c_int)
+
+
+# ─── Color ────────────────────────────────────────────────────────────────────
+class Color:
+    """Color constants and helpers (0x00RRGGBB)."""
+    BLACK   = 0x000000
+    WHITE   = 0xFFFFFF
+    RED     = 0xFF0000
+    GREEN   = 0x00FF00
+    BLUE    = 0x0000FF
+    YELLOW  = 0xFFFF00
+    CYAN    = 0x00FFFF
+    MAGENTA = 0xFF00FF
+    GRAY    = 0x808080
+    ORANGE  = 0xFF8000
+    PINK    = 0xFF69B4
+
+    @staticmethod
+    def rgb(r: int, g: int, b: int) -> int:
+        """Create color from R, G, B components (0–255 each)."""
+        return ((r & 0xFF) << 16) | ((g & 0xFF) << 8) | (b & 0xFF)
+
+    @staticmethod
+    def to_rgb(color: int) -> tuple[int, int, int]:
+        """Split color int into (r, g, b) tuple."""
+        return ((color >> 16) & 0xFF, (color >> 8) & 0xFF, color & 0xFF)
+
+    @staticmethod
+    def lerp(c1: int, c2: int, t: float) -> int:
+        """Linear interpolation between two colors. t in [0.0, 1.0]."""
+        r1, g1, b1 = Color.to_rgb(c1)
+        r2, g2, b2 = Color.to_rgb(c2)
+        return Color.rgb(
+            int(r1 + (r2 - r1) * t),
+            int(g1 + (g2 - g1) * t),
+            int(b1 + (b2 - b1) * t),
+        )
+
+
+# ─── X11 Event codes ──────────────────────────────────────────────────────────
+class X11Event:
+    """Common X11 event codes for mlx_hook."""
+    KEY_PRESS      = 2
+    KEY_RELEASE    = 3
+    BUTTON_PRESS   = 4
+    BUTTON_RELEASE = 5
+    MOTION_NOTIFY  = 6
+    DESTROY_NOTIFY = 17
+
+
+# ─── Image ────────────────────────────────────────────────────────────────────
+class Image:
+    """
+    MLX image with direct pixel buffer access and drawing primitives.
+
+    All drawing methods write directly into the pixel buffer —
+    no X11 roundtrip, so they are fast enough for real-time rendering.
+    Call window.put_image(img) to display the result.
+    """
+
+    def __init__(self, info: _ImgInfo, width: int, height: int):
+        self._info  = info
+        self._pinfo = ctypes.pointer(info)
+        self.width  = width
+        self.height = height
+
+    @property
+    def handle(self) -> ctypes.c_void_p:
+        return self._info.img
+
+    # ── Low-level ─────────────────────────────────────────────────────────────
+
+    def pixel_put(self, x: int, y: int, color: int) -> None:
+        """Write a single pixel. Out-of-bounds coords are silently ignored."""
+        if 0 <= x < self.width and 0 <= y < self.height:
+            _img_pixel_put(self._pinfo, x, y, color)
+
+    def pixel_get(self, x: int, y: int) -> int:
+        """Read a single pixel color."""
+        if 0 <= x < self.width and 0 <= y < self.height:
+            return _img_pixel_get(self._pinfo, x, y)
+        return 0
+
+    def clear(self, color: int = Color.BLACK) -> None:
+        """Fill the entire image with one color."""
+        _img_clear(self._pinfo, color)
+
+    # ── Rectangles ────────────────────────────────────────────────────────────
+
+    def draw_rect(self, x: int, y: int, w: int, h: int, color: int) -> None:
+        """Draw a filled rectangle."""
+        x0 = max(x, 0);          y0 = max(y, 0)
+        x1 = min(x + w, self.width)
+        y1 = min(y + h, self.height)
+        for py in range(y0, y1):
+            for px in range(x0, x1):
+                _img_pixel_put(self._pinfo, px, py, color)
+
+    def draw_rect_outline(self, x: int, y: int, w: int, h: int,
+                          color: int, thickness: int = 1) -> None:
+        """Draw a rectangle outline (not filled)."""
+        for t in range(thickness):
+            self.draw_line(x + t,         y + t,         x + w - t,     y + t,         color)
+            self.draw_line(x + w - t,     y + t,         x + w - t,     y + h - t,     color)
+            self.draw_line(x + w - t,     y + h - t,     x + t,         y + h - t,     color)
+            self.draw_line(x + t,         y + h - t,     x + t,         y + t,         color)
+
+    # ── Lines ─────────────────────────────────────────────────────────────────
+
+    def draw_line(self, x0: int, y0: int, x1: int, y1: int,
+                  color: int) -> None:
+        """Draw a line using Bresenham's algorithm."""
+        dx = abs(x1 - x0);  sx = 1 if x0 < x1 else -1
+        dy = -abs(y1 - y0); sy = 1 if y0 < y1 else -1
+        err = dx + dy
+        while True:
+            self.pixel_put(x0, y0, color)
+            if x0 == x1 and y0 == y1:
+                break
+            e2 = 2 * err
+            if e2 >= dy:
+                if x0 == x1:
+                    break
+                err += dy
+                x0  += sx
+            if e2 <= dx:
+                if y0 == y1:
+                    break
+                err += dx
+                y0  += sy
+
+    def draw_line_thick(self, x0: int, y0: int, x1: int, y1: int,
+                        color: int, thickness: int = 2) -> None:
+        """Draw a thick line by drawing multiple offset lines."""
+        half = thickness // 2
+        dx = x1 - x0; dy = y1 - y0
+        length = math.hypot(dx, dy)
+        if length == 0:
+            self.draw_rect(x0 - half, y0 - half, thickness, thickness, color)
+            return
+        nx = -dy / length  # normal vector
+        ny =  dx / length
+        for i in range(-half, half + 1):
+            ox = round(nx * i); oy = round(ny * i)
+            self.draw_line(x0 + ox, y0 + oy, x1 + ox, y1 + oy, color)
+
+    # ── Circles ───────────────────────────────────────────────────────────────
+
+    def draw_circle(self, cx: int, cy: int, radius: int,
+                    color: int) -> None:
+        """Draw a filled circle using midpoint algorithm."""
+        for y in range(-radius, radius + 1):
+            x_max = int(math.sqrt(radius * radius - y * y))
+            for x in range(-x_max, x_max + 1):
+                self.pixel_put(cx + x, cy + y, color)
+
+    def draw_circle_outline(self, cx: int, cy: int, radius: int,
+                            color: int, thickness: int = 1) -> None:
+        """Draw a circle outline."""
+        for r in range(radius, radius - thickness, -1):
+            if r < 0:
+                break
+            x = 0; y = r; d = 1 - r
+            while x <= y:
+                for px, py in [
+                    (cx+x, cy+y), (cx-x, cy+y), (cx+x, cy-y), (cx-x, cy-y),
+                    (cx+y, cy+x), (cx-y, cy+x), (cx+y, cy-x), (cx-y, cy-x),
+                ]:
+                    self.pixel_put(px, py, color)
+                x += 1
+                if d < 0:
+                    d += 2 * x + 1
+                else:
+                    y -= 1; d += 2 * (x - y) + 1
+
+    # ── Triangles ─────────────────────────────────────────────────────────────
+
+    def draw_triangle(self, x0: int, y0: int, x1: int, y1: int,
+                      x2: int, y2: int, color: int) -> None:
+        """Draw a filled triangle."""
+        # Sort by y
+        pts = sorted([(x0, y0), (x1, y1), (x2, y2)], key=lambda p: p[1])
+        (ax, ay), (bx, by), (cx, cy) = pts
+
+        def scanline(y_start, y_end, xa, xb, x_long_start, dx_long, dx_short):
+            xl = x_long_start
+            xs = xa
+            for y in range(y_start, y_end):
+                left  = min(round(xl), round(xs))
+                right = max(round(xl), round(xs))
+                for x in range(left, right + 1):
+                    self.pixel_put(x, y, color)
+                xl += dx_long
+                xs += dx_short
+
+        total_h = cy - ay or 1
+        # Top half
+        if by != ay:
+            dx_long  = (cx - ax) / total_h
+            dx_short = (bx - ax) / (by - ay)
+            scanline(ay, by, ax, ax, ax, dx_long, dx_short)
+        # Bottom half
+        if cy != by:
+            dx_long  = (cx - ax) / total_h
+            dx_short = (cx - bx) / (cy - by)
+            x_long_at_b = ax + (cx - ax) * (by - ay) / total_h
+            scanline(by, cy, bx, x_long_at_b, x_long_at_b, dx_long, dx_short)
+
+    def draw_triangle_outline(self, x0: int, y0: int, x1: int, y1: int,
+                              x2: int, y2: int, color: int) -> None:
+        """Draw a triangle outline."""
+        self.draw_line(x0, y0, x1, y1, color)
+        self.draw_line(x1, y1, x2, y2, color)
+        self.draw_line(x2, y2, x0, y0, color)
+
+    # ── Gradients ─────────────────────────────────────────────────────────────
+
+    def draw_gradient_h(self, x: int, y: int, w: int, h: int,
+                        color_left: int, color_right: int) -> None:
+        """Horizontal gradient rectangle."""
+        for px in range(w):
+            t = px / (w - 1) if w > 1 else 0
+            c = Color.lerp(color_left, color_right, t)
+            for py in range(h):
+                self.pixel_put(x + px, y + py, c)
+
+    def draw_gradient_v(self, x: int, y: int, w: int, h: int,
+                        color_top: int, color_bottom: int) -> None:
+        """Vertical gradient rectangle."""
+        for py in range(h):
+            t = py / (h - 1) if h > 1 else 0
+            c = Color.lerp(color_top, color_bottom, t)
+            for px in range(w):
+                self.pixel_put(x + px, y + py, c)
+
+    # ── Polygon ───────────────────────────────────────────────────────────────
+
+    def draw_polygon(self, points: list[tuple[int, int]],
+                     color: int) -> None:
+        """Draw a polygon outline from a list of (x, y) points."""
+        n = len(points)
+        if n < 2:
+            return
+        for i in range(n):
+            x0, y0 = points[i]
+            x1, y1 = points[(i + 1) % n]
+            self.draw_line(x0, y0, x1, y1, color)
+
+    # ── Flood fill ────────────────────────────────────────────────────────────
+
+    def flood_fill(self, x: int, y: int, color: int) -> None:
+        """
+        Flood fill starting at (x, y).
+        Replaces all connected pixels of the same color with the new color.
+        Uses an iterative stack to avoid Python recursion limit.
+        """
+        if not (0 <= x < self.width and 0 <= y < self.height):
+            return
+        target = self.pixel_get(x, y)
+        if target == color:
+            return
+        stack = [(x, y)]
+        while stack:
+            px, py = stack.pop()
+            if not (0 <= px < self.width and 0 <= py < self.height):
+                continue
+            if self.pixel_get(px, py) != target:
+                continue
+            self.pixel_put(px, py, color)
+            stack.extend([(px+1, py), (px-1, py), (px, py+1), (px, py-1)])
+
+
+# ─── Window ───────────────────────────────────────────────────────────────────
+class Window:
+    """An MLX window."""
+
+    def __init__(self, mlx_ptr, win_ptr, width: int, height: int):
+        self._mlx       = mlx_ptr
+        self._win       = win_ptr
+        self.width      = width
+        self.height     = height
+        self._callbacks: list = []
+
+    def pixel_put(self, x: int, y: int, color: int) -> None:
+        """Direct pixel write. Slow — prefer Image + put_image for animation."""
+        _mlx_pixel_put(self._mlx, self._win, x, y, color)
+
+    def string_put(self, x: int, y: int, color: int, text: str) -> None:
+        """Draw text directly on the window using the built-in mlx font."""
+        _mlx_string_put(self._mlx, self._win, x, y, color, text.encode())
+
+    def put_image(self, image: Image, x: int = 0, y: int = 0) -> None:
+        """Blit an Image onto the window at position (x, y)."""
+        _mlx_put_image_to_win(self._mlx, self._win, image.handle, x, y)
+
+    # ── Hooks ─────────────────────────────────────────────────────────────────
+
+    def on_key(self, callback) -> None:
+        """Register key press handler: callback(keycode: int) -> None."""
+        def _cb(keycode, _param):
+            callback(keycode)
+            return 0
+        c_cb = KeyCb(_cb)
+        self._callbacks.append(c_cb)
+        _mlx_key_hook(self._win, c_cb, None)
+
+    def on_mouse(self, callback) -> None:
+        """Register mouse button handler: callback(button, x, y) -> None."""
+        def _cb(button, x, y, _param):
+            callback(button, x, y)
+            return 0
+        c_cb = MouseCb(_cb)
+        self._callbacks.append(c_cb)
+        _mlx_mouse_hook(self._win, c_cb, None)
+
+    def on_event(self, event: int, mask: int, callback) -> None:
+        """Register a generic X11 event hook: callback() -> None."""
+        def _cb():
+            callback()
+            return 0
+        c_cb = GenericCb(_cb)
+        self._callbacks.append(c_cb)
+        _mlx_hook(self._win, event, mask, c_cb, None)
+
+    def on_close(self, callback) -> None:
+        """Called when the window close button is pressed."""
+        self.on_event(X11Event.DESTROY_NOTIFY, 0, callback)
+
+    # ── Mouse control ─────────────────────────────────────────────────────────
+
+    def mouse_hide(self) -> None:
+        _mlx_mouse_hide(self._mlx, self._win)
+
+    def mouse_show(self) -> None:
+        _mlx_mouse_show(self._mlx, self._win)
+
+    def mouse_pos(self) -> tuple[int, int]:
+        x, y = ctypes.c_int(), ctypes.c_int()
+        _mlx_mouse_get_pos(self._mlx, self._win,
+                           ctypes.byref(x), ctypes.byref(y))
+        return x.value, y.value
+
+    def mouse_move(self, x: int, y: int) -> None:
+        _mlx_mouse_move(self._mlx, self._win, x, y)
+
+    def destroy(self) -> None:
+        _mlx_destroy_window(self._mlx, self._win)
+
+
+# ─── Mlx ──────────────────────────────────────────────────────────────────────
+class Mlx:
+    """
+    Main MiniLibX context. Use as a context manager for automatic cleanup:
+
+        with Mlx() as mlx:
+            win = mlx.new_window(800, 600, "Title")
+            ...
+            mlx.loop()
+    """
+
+    def __init__(self):
+        self._ptr = _mlx_init()
+        if not self._ptr:
+            raise RuntimeError("mlx_init() failed — is DISPLAY set?")
+        self._callbacks: list = []
+
+    def new_window(self, width: int, height: int, title: str) -> Window:
+        ptr = _mlx_new_window(self._ptr, width, height, title.encode())
+        if not ptr:
+            raise RuntimeError(f"mlx_new_window() failed for '{title}'")
+        return Window(self._ptr, ptr, width, height)
+
+    def new_image(self, width: int, height: int) -> Image:
+        info = _mlx_new_image(self._ptr, width, height)
+        if not info.img:
+            raise RuntimeError("mlx_new_image() failed")
+        return Image(info, width, height)
+
+    def destroy_image(self, image: Image) -> None:
+        _mlx_destroy_image(self._ptr, image.handle)
+
+    def on_loop(self, callback) -> None:
+        """Register a per-frame callback: callback() -> None."""
+        def _cb(_param):
+            callback()
+            return 0
+        c_cb = LoopCb(_cb)
+        self._callbacks.append(c_cb)
+        _mlx_loop_hook(self._ptr, c_cb, None)
+
+    def loop(self) -> None:
+        """Start the event loop (blocking)."""
+        _mlx_loop(self._ptr)
+
+    def loop_end(self) -> None:
+        """Stop the event loop."""
+        _mlx_loop_end(self._ptr)
+
+    def destroy(self) -> None:
+        _mlx_destroy_display(self._ptr)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.destroy()