ren-ui-python 0.1.0__py3-none-any.whl

ren_ui/__init__.py

@@ -0,0 +1,11 @@
+"""Native Haiku UI. Importing and composing widgets works on any host."""
+
+from .app import Application, Event
+from .resources import asset_path
+from .widgets import Button, CheckBox, Column, Image, Label, Row, Slider, TextArea, TextInput, Window
+
+__version__ = "0.1.0"
+__all__ = [
+    "Application", "Event", "Image", "asset_path", "Window", "Column", "Row", "Label", "Button",
+    "TextInput", "TextArea", "CheckBox", "Slider",
+]

ren_ui/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

ren_ui/_native.py

@@ -0,0 +1,70 @@
+"""Versioned ctypes boundary. CDLL releases the GIL before looper locks."""
+from __future__ import annotations
+
+import ctypes as C
+import os
+from pathlib import Path
+import sys
+
+
+class NativeError(RuntimeError):
+    pass
+
+
+CALLBACK = C.CFUNCTYPE(None, C.c_int64, C.c_int64, C.c_char_p, C.c_char_p, C.c_int)
+
+
+def utf8(value: str) -> bytes:
+    if not isinstance(value, str) or "\0" in value:
+        raise ValueError("Expected a string without NUL characters")
+    return value.encode("utf-8")
+
+
+class Native:
+    def __init__(self):
+        if not sys.platform.startswith("haiku"):
+            raise NativeError("Native UI requires Haiku OS. Use 'ren doctor' to check your environment.")
+        location = os.environ.get("REN_UI_LIBRARY")
+        path = Path(location) if location else Path(__file__).with_name("libren_ui.so")
+        if not path.is_file():
+            raise NativeError("Native bridge not found. Run 'ren native' or launch with 'ren run'.")
+        try:
+            self.lib = C.CDLL(str(path.resolve()))
+        except OSError as exc:
+            raise NativeError(f"Cannot load {path}: {exc}") from exc
+        self.lib.ren_abi.restype = C.c_int
+        self.lib.ren_abi.argtypes = []
+        if self.lib.ren_abi() != 5:
+            raise NativeError("Native bridge ABI mismatch; rebuild with 'ren native'.")
+        i, q, p, s, f = C.c_int, C.c_int64, C.c_void_p, C.c_char_p, C.c_float
+        signatures = {
+            "abi": (i, []), "error": (s, []),
+            "app_create": (p, [s, CALLBACK]), "app_run": (i, [p]),
+            "app_quit": (i, [p]), "app_destroy": (i, [p]),
+            "window_create": (q, [p, s, f, f, i]),
+            "window_show": (i, [p, q]), "window_close": (i, [p, q]),
+            "window_close_reply": (i, [p, q, i]),
+            "window_title": (i, [p, q, s]),
+            "view_create": (q, [p, q, q, s, s, s, f, f]),
+            "image_source": (i, [p, q, q, s]),
+            "button_icon": (i, [p, q, q, s, i]),
+            "view_set_text": (i, [p, q, q, s]),
+            "view_text": (s, [p, q, q]),
+            "view_set_value": (i, [p, q, q, i]), "view_value": (i, [p, q, q, C.POINTER(i)]),
+            "view_enabled": (i, [p, q, q, i]),
+            "view_invoke": (i, [p, q, q]),
+            "alert": (i, [s, s]), "clipboard_set": (i, [s]),
+            "confirm": (i, [s, s, s, s]),
+            "clipboard_get": (s, []), "launch": (i, [s]),
+            "directory": (s, [i]), "file_panel": (s, [i, s, s, s]),
+        }
+        for name, (result, arguments) in signatures.items():
+            function = getattr(self.lib, "ren_" + name)
+            function.restype, function.argtypes = result, arguments
+
+    def call(self, name, *args):
+        result = getattr(self.lib, "ren_" + name)(*args)
+        error = self.lib.ren_error()
+        if error:
+            raise NativeError(error.decode("utf-8", errors="replace"))
+        return result

ren_ui/app.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import queue
+import re
+import threading
+import traceback
+from typing import Callable
+
+from ._native import CALLBACK, Native, utf8
+
+
+@dataclass(frozen=True)
+class Event:
+    """A snapshot of a native control event; callbacks receive one Event."""
+    source: object
+    kind: str
+    text: str = ""
+    value: int = 0
+
+
+class Application:
+    """One BApplication per process, created and run on the main thread.
+
+    User callbacks execute serially on a Python dispatcher thread. Native
+    callbacks only enqueue snapshots, never run user code under a looper lock.
+    """
+    _current: Application | None = None
+
+    def __init__(self, signature: str):
+        if not re.fullmatch(r"application/[A-Za-z0-9][A-Za-z0-9.+_-]*", signature):
+            raise ValueError("signature must be an application MIME type")
+        self.signature = signature
+        self._native = None
+        self._handle = None
+        self._windows = {}
+        self._queue = queue.Queue()
+        self._running = False
+        self._closed = False
+        self._dispatcher = None
+
+    def _check_ui_thread(self):
+        expected = self._dispatcher if self._running else threading.main_thread()
+        if threading.current_thread() is not expected:
+            raise RuntimeError("Use app.call_soon() to access UI from another thread")
+
+    def _ensure_native(self):
+        self._check_ui_thread()
+        if self._closed:
+            raise RuntimeError("Application has already closed")
+        if self._native is None:
+            if threading.current_thread() is not threading.main_thread():
+                raise RuntimeError("Create the first window on the main thread")
+            if Application._current is not None:
+                raise RuntimeError("Only one Application may be active")
+            native = Native()
+            self._callback = CALLBACK(self._enqueue)
+            self._handle = native.call("app_create", utf8(self.signature), self._callback)
+            self._native = native
+            Application._current = self
+        return self._native
+
+    def _enqueue(self, window, view, kind, text, value):
+        self._queue.put((window, view, kind.decode(), text.decode("utf-8", "replace"), value))
+
+    def _dispatch(self):
+        while True:
+            item = self._queue.get()
+            if item is None:
+                return
+            try:
+                if callable(item):
+                    item()
+                    continue
+                window_id, view_id, kind, text, value = item
+                if kind == "quit_requested":
+                    for window in list(self._windows.values()):
+                        window.close()
+                    continue
+                window = self._windows.get(window_id)
+                if window is None:
+                    continue
+                if kind == "closed":
+                    if window._closed:
+                        continue
+                    window._closed = True
+                    if window.on_close:
+                        window.on_close(Event(window, kind))
+                    continue
+                if window._closed or window._closing:
+                    continue
+                if kind == "close_requested":
+                    window._decide_close(Event(window, kind))
+                    continue
+                widget = window._widgets.get(view_id)
+                if widget is not None and widget.on_change:
+                    widget.on_change(Event(widget, kind, text, value))
+            except Exception:
+                # A failing handler must not kill the dispatcher or the app.
+                traceback.print_exc()
+
+    def call_soon(self, callback: Callable[[], None]):
+        if self._closed:
+            raise RuntimeError("Application has already closed")
+        if not callable(callback):
+            raise TypeError("callback must be callable")
+        self._queue.put(callback)
+
+    def run(self):
+        if threading.current_thread() is not threading.main_thread():
+            raise RuntimeError("Application.run() must run on the main thread")
+        if self._running:
+            raise RuntimeError("Application is already running")
+        native = self._ensure_native()
+        if not self._windows:
+            raise RuntimeError("Show at least one window before run()")
+        worker = threading.Thread(target=self._dispatch, name="ren-ui-events")
+        self._dispatcher = worker
+        self._running = True
+        worker.start()
+        try:
+            native.call("app_run", self._handle)
+        finally:
+            self._queue.put(None)
+            worker.join()
+            self._running = False
+            self.close()
+
+    def quit(self):
+        self._check_ui_thread()
+        if self._native and not self._closed:
+            self._native.call("app_quit", self._handle)
+
+    def close(self):
+        """Release native resources after run, or after a setup failure."""
+        if self._running:
+            raise RuntimeError("Use quit() while the application is running")
+        if threading.current_thread() is not threading.main_thread():
+            raise RuntimeError("Application.close() must run on the main thread")
+        if self._native and not self._closed:
+            self._native.call("app_destroy", self._handle)
+            self._handle = None
+            Application._current = None
+        self._closed = True
+        for window in self._windows.values():
+            window._closed = True
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

ren_ui/build.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import platform
+import shlex
+import shutil
+import struct
+import subprocess
+import sys
+import sysconfig
+import tempfile
+
+from .project import Project, ProjectError, package_info, quote
+
+NATIVE = Path(__file__).with_name("native")
+ARCHITECTURES = {3: "x86", 62: "x86_64", 183: "arm64", 243: "riscv64"}
+
+
+def require_haiku():
+    if not sys.platform.startswith("haiku"):
+        raise ProjectError("This command requires Haiku OS and its development tools; use 'ren stage' to inspect sources on this host.")
+
+
+def command(arguments, **kwargs):
+    try:
+        subprocess.run([str(arg) for arg in arguments], check=True, **kwargs)
+    except FileNotFoundError as exc:
+        raise ProjectError(f"Required tool not found: {arguments[0]}. Run 'ren doctor'.") from exc
+    except subprocess.CalledProcessError as exc:
+        raise ProjectError(f"Command failed ({exc.returncode}): {shlex.join(map(str, arguments))}") from exc
+
+
+def secondary_architecture() -> str:
+    """'x86' when this Python belongs to a secondary architecture (32-bit hybrid Haiku), else ''."""
+    libdir = Path(sysconfig.get_config_var("LIBDIR") or "")
+    return libdir.name if libdir.parent.name == "lib" else ""
+
+
+def primary_architecture() -> str:
+    """The architecture pkgman installs for, e.g. x86_gcc2 on a 32-bit hybrid system."""
+    try:
+        result = subprocess.run(["getarch", "-p"], check=True, capture_output=True, text=True)
+    except (OSError, subprocess.CalledProcessError) as exc:
+        raise ProjectError("Cannot determine the primary architecture with 'getarch -p'") from exc
+    return result.stdout.strip()
+
+
+def compiler():
+    # A hybrid system's default c++ is GCC 2; the bridge must match this Python's architecture.
+    secondary = secondary_architecture()
+    arguments = shlex.split(os.environ.get("CXX", f"c++-{secondary}" if secondary else "c++"))
+    if not arguments:
+        raise ProjectError("CXX must name a C++17 compiler")
+    return arguments
+
+
+def native_link_flags():
+    # AArch64 linkers can default to 64 KiB pages. Haiku's runtime_loader
+    # rejects the resulting segment gaps with "Could not map image: Bad data".
+    if platform.machine().lower() in {"arm64", "aarch64"}:
+        return ["-Wl,-z,max-page-size=4096"]
+    return []
+
+
+def compile_native(output: Path):
+    require_haiku()
+    output = output.resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    # Build atomically: never destroy the previous library on compiler failure.
+    with tempfile.TemporaryDirectory(prefix="ren-native-", dir=output.parent) as temporary:
+        library = Path(temporary) / "libren_ui.so"
+        command([*compiler(), "-std=c++17", "-O2", "-Wall", "-Wextra", "-Wno-multichar",
+                 "-fPIC", "-shared", NATIVE / "bridge.cpp", "-o", library, "-lbe", "-ltranslation", "-ltracker",
+                 *native_link_flags()])
+        elf_architecture(library)
+        os.replace(library, output)
+    return output
+
+
+def elf_architecture(path: Path) -> str:
+    with path.open("rb") as file:
+        header = file.read(20)
+    if len(header) != 20 or header[:4] != b"\x7fELF" or header[4] not in (1, 2) or header[5] not in (1, 2):
+        raise ProjectError(f"Not an ELF binary: {path}")
+    machine = struct.unpack("<H" if header[5] == 1 else ">H", header[18:20])[0]
+    if machine not in ARCHITECTURES:
+        raise ProjectError(f"Unsupported ELF machine: {machine}")
+    return ARCHITECTURES[machine]
+
+
+def python_requirement(library: str, secondary: str = "") -> str:
+    """The package-system name of a libpython, e.g. lib:libpython3.12 or lib:libpython3.12_x86."""
+    return "lib:" + library.split(".so")[0] + (f"_{secondary}" if secondary else "")
+
+
+def stage(project: Project, destination: Path, *, architecture="x86_64", python_package=None, secondary=""):
+    """Write a reviewable source staging tree, not an installable package."""
+    if destination.exists() or destination.is_symlink():
+        raise ProjectError(f"Stage destination already exists: {destination}")
+    sources = project.source_files()
+    resolved = destination.resolve()
+    for item in project.include:
+        source = project.safe_path(item)
+        if source.is_dir() and resolved.is_relative_to(source):
+            raise ProjectError("Stage destination cannot be inside an included source directory")
+    destination.mkdir(parents=True)
+    payload = destination / "data" / project.name
+    app = payload / "app"
+    app.mkdir(parents=True)
+    for relative, source in sources.items():
+        target = app / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(source, target)
+    runtime = payload / "runtime" / "ren_ui"
+    runtime.mkdir(parents=True)
+    for source in Path(__file__).parent.glob("*.py"):
+        # Runtime users do not need packaging/CLI source or a compiler.
+        if source.name not in {"cli.py", "build.py", "project.py", "__main__.py"}:
+            shutil.copyfile(source, runtime / source.name)
+    licenses = destination / "data" / "licenses"
+    licenses.mkdir(parents=True, exist_ok=True)
+    # Namespace license files: different apps' MIT notices have different authors.
+    shutil.copyfile(project.safe_path(project.license_file), licenses / f"{project.name}_{project.license}")
+    # Preserve the bundled framework's license separately from the app's license.
+    (payload / "REN_UI_LICENSE").write_text(FRAMEWORK_LICENSE, encoding="utf-8")
+    if python_package is None:
+        python_package = python_requirement(f"libpython{sys.version_info.major}.{sys.version_info.minor}.so", secondary)
+    (destination / ".PackageInfo").write_text(
+        package_info(project, architecture, python_package, secondary), encoding="utf-8")
+    return destination
+
+
+def application_resources(project: Project) -> str:
+    source = f"resource app_signature {quote(project.signature)};\n"
+    if project.icon is not None and Path(project.icon).suffix.lower() == ".hvif":
+        data = project.icon_bytes()
+        # Hex literals avoid filesystem-dependent imports and RDEF injection.
+        chunks = "\n".join('    $"' + data[i:i + 32].hex() + '"' for i in range(0, len(data), 32))
+        source += "resource(101, \"BEOS:ICON\") #'VICN' array {\n" + chunks + "\n};\n"
+    return source
+
+
+def build(project: Project, output: Path, *, force=False) -> Path:
+    require_haiku()
+    for tool in [*compiler()[:1], "package", "rc", "xres", "resattr", "mimeset"]:
+        if not shutil.which(tool):
+            raise ProjectError(f"Required tool not found: {tool}. Run 'ren doctor'.")
+    if sys.version_info < (3, 11):
+        raise ProjectError("Python 3.11 or newer is required")
+    python_name = f"python{sys.version_info.major}.{sys.version_info.minor}"
+    if not shutil.which(python_name):
+        raise ProjectError(f"Packaged runtime interpreter not found: {python_name}")
+    # INSTSONAME is the name installed in the library path; the unversioned
+    # LDLIBRARY link only exists under develop/lib, where dlopen() does not look.
+    python_library = sysconfig.get_config_var("INSTSONAME") or sysconfig.get_config_var("LDLIBRARY")
+    if not isinstance(python_library, str) or ".so" not in python_library:
+        raise ProjectError("The packaged launcher requires a shared Python runtime (libpython*.so)")
+    python_library = Path(python_library).name
+    secondary = secondary_architecture()
+    output = output.resolve()
+    output.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="ren-build-") as directory:
+        work = Path(directory)
+        library = compile_native(work / "libren_ui.so")
+        architecture = elf_architecture(library)
+        # Secondary-architecture binaries ship in a package of the primary architecture.
+        package_architecture = primary_architecture() if secondary else architecture
+        target = output / f"{project.name}-{project.package_version}-{package_architecture}.hpkg"
+        if target.exists() and not force:
+            raise ProjectError(f"Package already exists: {target}; pass --force to replace it")
+        root = stage(project, work / "stage", architecture=package_architecture,
+                     python_package=python_requirement(python_library, secondary), secondary=secondary)
+        shutil.copyfile(library, root / "data" / project.name / "runtime" / "ren_ui" / "libren_ui.so")
+        launcher = root / "apps" / project.name
+        launcher.parent.mkdir(parents=True)
+        command([*compiler(), "-std=c++17", "-O2", NATIVE / "launcher.cpp", "-o", launcher, "-lbe",
+                 *native_link_flags(),
+                 f"-DREN_APP_NAME={quote(project.name)}", f"-DREN_ENTRY={quote(project.entry)}",
+                 f"-DREN_PYTHON={quote(python_name)}", f"-DREN_PYTHON_LIBRARY={quote(python_library)}"])
+        if elf_architecture(launcher) != architecture:
+            raise ProjectError("Launcher and bridge architectures differ")
+        resource = work / "app.rdef"
+        resource.write_text(application_resources(project), encoding="utf-8")
+        command(["rc", "-o", work / "app.rsrc", resource])
+        # Preserve the ELF while embedding resources as well as BFS attributes.
+        command(["xres", "-o", launcher, work / "app.rsrc"])
+        command(["resattr", "-o", launcher, work / "app.rsrc"])
+        if project.icon is not None and Path(project.icon).suffix.lower() == ".png":
+            icon_tool = work / "ren-icon"
+            command([*compiler(), "-std=c++17", "-O2", NATIVE / "icon.cpp", "-o", icon_tool,
+                     "-lbe", "-ltranslation", *native_link_flags()])
+            command([icon_tool, root / "data" / project.name / "app" / project.icon, launcher])
+        command(["mimeset", "-f", launcher])
+        link = root / "data" / "deskbar" / "menu" / "Applications" / project.title
+        # title is metadata elsewhere, but here it must be a single filename.
+        link.parent.mkdir(parents=True, exist_ok=True)
+        link.symlink_to(f"../../../../apps/{project.name}")
+        # package create recursively includes the staged payload; -b would omit it.
+        # Output must be outside the input tree, per Haiku's package tool.
+        artifact = work / target.name
+        command(["package", "create", "-C", root, artifact])
+        if not artifact.is_file() or artifact.stat().st_size < 4:
+            raise ProjectError("package create did not produce an HPKG")
+        with artifact.open("rb") as file:
+            if file.read(4) != b"hpkg":
+                raise ProjectError("package create output is not an HPKG")
+        # Rename on the destination filesystem; a failed copy cannot leave a partial HPKG.
+        with tempfile.TemporaryDirectory(prefix=".ren-output-", dir=output) as temporary:
+            staged_output = Path(temporary) / target.name
+            shutil.copyfile(artifact, staged_output)
+            os.replace(staged_output, target)
+    return target
+
+
+def doctor() -> tuple[str, bool]:
+    host = sys.platform.startswith("haiku")
+    rows = [f"Host: {platform.system()} ({platform.machine()})", f"Python: {platform.python_version()}"]
+    ready = host
+    for tool in [*compiler()[:1], "package", "rc", "xres", "resattr", "mimeset"]:
+        found = shutil.which(tool)
+        rows.append(f"{tool}: {found or 'missing'}")
+        ready &= found is not None
+    shared = sysconfig.get_config_var("LDLIBRARY") or ""
+    rows.append(f"Python shared runtime: {shared or 'missing'}")
+    ready &= ".so" in shared
+    interpreter = f"python{sys.version_info.major}.{sys.version_info.minor}"
+    found = shutil.which(interpreter)
+    rows.append(f"{interpreter}: {found or 'missing'}")
+    ready &= found is not None
+    rows.append("Native build: ready" if ready else "Native build: requires Haiku, a modern C++17 compiler, and Haiku packaging tools")
+    return "\n".join(rows), ready
+
+
+FRAMEWORK_LICENSE = """MIT License
+
+Copyright (c) 2026 ren-ui-python contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""

ren_ui/cli.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+
+from . import __version__
+from .build import FRAMEWORK_LICENSE, build, compile_native, doctor, require_haiku, stage
+from .project import Project, ProjectError
+
+
+def init_project(directory: Path, name=None):
+    name = name or directory.resolve().name.replace("-", "_").lower()
+    if not re.fullmatch(r"[a-z][a-z0-9_]*", name):
+        raise ProjectError("Choose a name containing only lowercase letters, digits, and underscores")
+    if directory.exists() and (not directory.is_dir() or any(directory.iterdir())):
+        raise ProjectError(f"Destination must be empty: {directory}")
+    directory.mkdir(parents=True, exist_ok=True)
+    signature = f"application/x-vnd.ren-{name}"
+    title = name.replace("_", " ").title()
+    manifest = f'''[app]
+name = {json.dumps(name)}
+title = {json.dumps(title)}
+version = "0.1.0"
+revision = 1
+signature = {json.dumps(signature)}
+summary = "A native Haiku application built with Python"
+description = "My first ren-ui-python application"
+author = "Your Name"
+license = "MIT"
+license-file = "LICENSE"
+entry = "main.py"
+
+[build]
+include = ["main.py"]
+requires = []
+'''
+    source = f'''from ren_ui import Application, Event, Window, Column, Row, Label, TextInput, Button
+
+
+def main():
+    with Application({signature!r}) as app:
+        greeting = Label("Welcome to Haiku!")
+        name = TextInput(label="Name:")
+
+        greet_button = Button("Say hello")
+        quit_button = Button("Quit")
+
+        @greet_button.onclick
+        def greet(event: Event):
+            greeting.text = f"Hello, {{name.text or 'Haiku'}}!"
+
+        @quit_button.onclick
+        def quit_app(event: Event):
+            app.quit()
+
+        Window(app, {title!r}, Column(
+            greeting,
+            name,
+            Row(greet_button, quit_button, padding=0),
+        )).show()
+        app.run()
+
+
+if __name__ == "__main__":
+    main()
+'''
+    (directory / "ren.toml").write_text(manifest, encoding="utf-8")
+    (directory / "main.py").write_text(source, encoding="utf-8")
+    (directory / "LICENSE").write_text(FRAMEWORK_LICENSE.replace(
+        "2026 ren-ui-python contributors", "2026 Your Name"), encoding="utf-8")
+    (directory / ".gitignore").write_text(".ren-build/\ndist/\n__pycache__/\n*.pyc\n", encoding="utf-8")
+    return directory
+
+
+def parser():
+    result = argparse.ArgumentParser(prog="ren", description="Python native Haiku apps and HPKG builds")
+    result.add_argument("--version", action="version", version=__version__)
+    sub = result.add_subparsers(dest="command", required=True)
+    init = sub.add_parser("init", help="create an application in an empty directory")
+    init.add_argument("directory", type=Path)
+    init.add_argument("--name")
+    sub.add_parser("doctor", help="check native runtime and build prerequisites")
+    native = sub.add_parser("native", help="compile the native bridge on Haiku")
+    native.add_argument("--output", type=Path, default=Path(".ren-build/libren_ui.so"))
+    for name, help_text in (("run", "build the bridge and run an app on Haiku"),
+                            ("build", "build a complete HPKG on Haiku"),
+                            ("stage", "prepare sources and PackageInfo for inspection; no native binaries"),
+                            ("check", "validate manifest, source paths and Python syntax")):
+        child = sub.add_parser(name, help=help_text)
+        child.add_argument("project", nargs="?", type=Path, default=Path.cwd())
+        if name == "build":
+            child.add_argument("--output", type=Path, help="artifact directory (default: PROJECT/dist)")
+            child.add_argument("--force", action="store_true", help="replace an existing HPKG")
+        if name == "stage":
+            child.add_argument("--output", type=Path, help="new staging directory (default: PROJECT/.ren-build/stage)")
+            child.add_argument("--arch", choices=("x86", "x86_64", "arm64", "riscv64"), default="x86_64")
+        if name == "run":
+            child.add_argument("args", nargs=argparse.REMAINDER, help="arguments passed to the app")
+    return result
+
+
+def check_sources(project):
+    files = project.source_files()
+    for relative, path in files.items():
+        if path.suffix == ".py":
+            try:
+                compile(path.read_bytes(), relative, "exec")
+            except (SyntaxError, ValueError) as exc:
+                raise ProjectError(f"Invalid Python source in {relative}: {exc}") from exc
+    return len(files)
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    try:
+        if args.command == "init":
+            path = init_project(args.directory, args.name)
+            print(f"Created {path}\nNext: ren check {path}\nOn Haiku: ren run {path} / ren build {path}")
+        elif args.command == "doctor":
+            report, ready = doctor()
+            print(report)
+            return 0 if ready else 1
+        elif args.command == "native":
+            path = compile_native(args.output)
+            print(f"Built {path}\nUse 'ren run' or set REN_UI_LIBRARY to this absolute path.")
+        else:
+            project = Project.load(args.project)
+            count = check_sources(project)
+            if args.command == "check":
+                print(f"Valid: {project.name} {project.package_version} ({count} source files)")
+            elif args.command == "stage":
+                path = stage(project, args.output or project.root / ".ren-build" / "stage", architecture=args.arch)
+                print(f"Staged sources: {path}\nThis is an inspection tree, not a complete package. Use 'ren build' on Haiku.")
+            elif args.command == "build":
+                print(build(project, args.output or project.root / "dist", force=args.force))
+            elif args.command == "run":
+                require_haiku()
+                library = compile_native(project.root / ".ren-build" / "libren_ui.so")
+                env = os.environ.copy()
+                env["REN_UI_LIBRARY"] = str(library)
+                env["REN_UI_ASSET_ROOT"] = str(project.root)
+                env["PYTHONPATH"] = os.pathsep.join(filter(None, [str(Path(__file__).parent.parent), str(project.root), env.get("PYTHONPATH")]))
+                arguments = args.args[1:] if args.args[:1] == ["--"] else args.args
+                return subprocess.run([sys.executable, "-B", str(project.root / project.entry), *arguments], cwd=project.root, env=env).returncode
+        return 0
+    except (ProjectError, OSError) as exc:
+        print(f"ren: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130