hexastack-ui 0.4.0__tar.gz

hexastack_ui-0.4.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: hexastack-ui
+Version: 0.4.0
+Summary: Reactive UI and DevTools presentation adapters for Hexastack
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+License-Expression: Apache-2.0
+Requires-Dist: hexastack-core
+Requires-Dist: hexastack-cqrs
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: hexastack-ui[nicegui,textual] ; extra == 'all'
+Requires-Dist: hexastack-ui[nicegui] ; extra == 'devtools'
+Requires-Dist: fastapi>=0.141.1 ; extra == 'fastapi'
+Requires-Dist: fastapi>=0.141.1 ; extra == 'nicegui'
+Requires-Dist: nicegui>=2.0.0 ; extra == 'nicegui'
+Requires-Dist: textual>=0.70.0 ; extra == 'textual'
+Requires-Python: >=3.13
+Provides-Extra: all
+Provides-Extra: devtools
+Provides-Extra: fastapi
+Provides-Extra: nicegui
+Provides-Extra: textual
+Description-Content-Type: text/markdown
+
+# hexastack-ui
+
+Reactive UI presentation adapters and turnkey DevTools dashboard for Hexastack.
+
+## Overview
+
+`hexastack-ui` provides reactive UI integration for Hexastack architectures:
+- **NiceGUI Web Adapter**: `@ui_page`, `mount_ui_app`, `dispatch_command`, `dispatch_query`.
+- **Interactive DevTools Console**: `mount_devtools_dashboard` inspecting CQRS registries, feature flags, and DI containers.
+- **Pluggable Architecture**: Modular ports for expanding to Textual (TUI) and other frontend engines.
+
+## Installation
+
+```bash
+# With NiceGUI web engine
+pip install hexastack-ui[nicegui]
+
+# Or via the umbrella Hexastack distribution
+pip install hexastack[ui]
+```

hexastack_ui-0.4.0/README.md

@@ -0,0 +1,20 @@
+# hexastack-ui
+
+Reactive UI presentation adapters and turnkey DevTools dashboard for Hexastack.
+
+## Overview
+
+`hexastack-ui` provides reactive UI integration for Hexastack architectures:
+- **NiceGUI Web Adapter**: `@ui_page`, `mount_ui_app`, `dispatch_command`, `dispatch_query`.
+- **Interactive DevTools Console**: `mount_devtools_dashboard` inspecting CQRS registries, feature flags, and DI containers.
+- **Pluggable Architecture**: Modular ports for expanding to Textual (TUI) and other frontend engines.
+
+## Installation
+
+```bash
+# With NiceGUI web engine
+pip install hexastack-ui[nicegui]
+
+# Or via the umbrella Hexastack distribution
+pip install hexastack[ui]
+```

hexastack_ui-0.4.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "hexastack-ui"
+version = "0.4.0"
+description = "Reactive UI and DevTools presentation adapters for Hexastack"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+    "hexastack-cqrs",
+    "pydantic>=2.10.0",
+]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.141.1"]
+nicegui = [
+    "fastapi>=0.141.1",
+    "nicegui>=2.0.0",
+]
+devtools = ["hexastack-ui[nicegui]"]
+textual = ["textual>=0.70.0"]
+all = ["hexastack-ui[nicegui,textual]"]
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.hexastack-core]
+workspace = true
+
+[tool.uv.sources.hexastack-cqrs]
+workspace = true
+
+[tool.importlinter]
+root_packages = ["hexastack_ui"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_ui"]
+layers = [
+    "infra",
+    "adapters",
+    "ports",
+    "domain",
+]

hexastack_ui-0.4.0/pyproject.toml.orig

@@ -0,0 +1,55 @@
+[project]
+name = "hexastack-ui"
+version = "0.4.0"
+description = "Reactive UI and DevTools presentation adapters for Hexastack"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-core",
+    "hexastack-cqrs",
+    "pydantic>=2.10.0",
+]
+
+[project.optional-dependencies]
+fastapi = [
+    "fastapi>=0.141.1",
+]
+nicegui = [
+    "fastapi>=0.141.1",
+    "nicegui>=2.0.0",
+]
+devtools = [
+    "hexastack-ui[nicegui]",
+]
+textual = [
+    "textual>=0.70.0",
+]
+all = [
+    "hexastack-ui[nicegui,textual]",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+hexastack-core = { workspace = true }
+hexastack-cqrs = { workspace = true }
+
+[tool.importlinter]
+root_packages = ["hexastack_ui"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_ui"]
+layers = [
+    "infra",
+    "adapters",
+    "ports",
+    "domain",
+]

hexastack_ui-0.4.0/src/hexastack_ui/__init__.py

@@ -0,0 +1,35 @@
+"""Hexastack UI - Reactive UI Presentation Adapters and DevTools Dashboard."""
+
+from hexastack_ui.adapters import (
+    check_nicegui_installed,
+    dispatch_command,
+    dispatch_query,
+    mount_devtools_dashboard,
+    mount_ui_app,
+    ui_page,
+)
+from hexastack_ui.domain import (
+    CQRSMessageSummary,
+    DevToolsDashboardState,
+    FeatureFlagSummary,
+    ServiceBindingSummary,
+)
+from hexastack_ui.ports import (
+    DevToolsPresenterPort,
+    UIPresenterPort,
+)
+
+__all__ = [
+    "check_nicegui_installed",
+    "CQRSMessageSummary",
+    "DevToolsDashboardState",
+    "DevToolsPresenterPort",
+    "dispatch_command",
+    "dispatch_query",
+    "FeatureFlagSummary",
+    "mount_devtools_dashboard",
+    "mount_ui_app",
+    "ServiceBindingSummary",
+    "ui_page",
+    "UIPresenterPort",
+]

hexastack_ui-0.4.0/src/hexastack_ui/adapters/__init__.py

@@ -0,0 +1,19 @@
+"""UI presentation adapters for Hexastack."""
+
+from hexastack_ui.adapters.nicegui import (
+    check_nicegui_installed,
+    dispatch_command,
+    dispatch_query,
+    mount_devtools_dashboard,
+    mount_ui_app,
+    ui_page,
+)
+
+__all__ = [
+    "check_nicegui_installed",
+    "dispatch_command",
+    "dispatch_query",
+    "mount_devtools_dashboard",
+    "mount_ui_app",
+    "ui_page",
+]

hexastack_ui-0.4.0/src/hexastack_ui/adapters/nicegui/__init__.py

@@ -0,0 +1,21 @@
+"""NiceGUI reactive presentation adapter and DevTools dashboard."""
+
+from hexastack_ui.adapters.nicegui.devtools import mount_devtools_dashboard
+from hexastack_ui.adapters.nicegui.dispatch import (
+    dispatch_command,
+    dispatch_query,
+)
+from hexastack_ui.adapters.nicegui.page import (
+    check_nicegui_installed,
+    mount_ui_app,
+    ui_page,
+)
+
+__all__ = [
+    "check_nicegui_installed",
+    "dispatch_command",
+    "dispatch_query",
+    "mount_devtools_dashboard",
+    "mount_ui_app",
+    "ui_page",
+]

hexastack_ui-0.4.0/src/hexastack_ui/adapters/nicegui/devtools.py

@@ -0,0 +1,384 @@
+"""Turnkey DevTools diagnostic dashboard built on NiceGUI.
+
+Notes/Architectural Intent:
+    Renders an interactive inspector for CQRS registries, command bus middlewares,
+    feature flag state, and DI container service bindings.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from rodi import Container
+
+from hexastack_cqrs.infra.pipeline import ExecutionPipeline
+from hexastack_ui.adapters.nicegui.page import check_nicegui_installed, mount_ui_app
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+__all__ = [
+    "mount_devtools_dashboard",
+]
+
+_STATIC_DIR = Path(__file__).parent / "static"
+
+
+def _render_cqrs_messages(container: Container) -> None:
+    """Render table of registered CQRS message contracts."""
+    from nicegui import ui
+
+    from hexastack_cqrs.infra.registries.command import CommandRegistry
+    from hexastack_cqrs.infra.registries.query import QueryRegistry
+
+    ui.label("Registered CQRS Commands & Queries").classes("hx-section-heading")
+
+    cmd_reg = (
+        container.resolve(CommandRegistry) if CommandRegistry in container else None
+    )
+    qry_reg = container.resolve(QueryRegistry) if QueryRegistry in container else None
+
+    commands_list = (
+        [
+            {"type": "Command", "name": getattr(k, "__name__", str(k))}
+            for k in cmd_reg.all.values()
+        ]
+        if cmd_reg
+        else []
+    )
+    queries_list = (
+        [
+            {"type": "Query", "name": getattr(k, "__name__", str(k))}
+            for k in qry_reg.all.values()
+        ]
+        if qry_reg
+        else []
+    )
+    cqrs_rows = commands_list + queries_list
+
+    if cqrs_rows:
+        ui.table(
+            columns=[
+                {
+                    "name": "type",
+                    "label": "Message Type",
+                    "field": "type",
+                    "sortable": True,
+                },
+                {
+                    "name": "name",
+                    "label": "Class Name",
+                    "field": "name",
+                    "sortable": True,
+                },
+            ],
+            rows=cqrs_rows,
+            row_key="name",
+        ).classes("w-full mb-6")
+    else:
+        ui.label("No CQRS messages registered in container.").classes("hx-empty-label")
+
+
+def _render_middleware_chain(middlewares: list[Any]) -> None:
+    """Render visual chain of active command bus middlewares."""
+    from nicegui import ui
+
+    ui.label("Command Bus Middleware Pipeline").classes("hx-section-heading")
+    if middlewares:
+        with (
+            ui.card().classes("hx-card"),
+            ui.row().classes("items-center flex-wrap gap-2"),
+        ):
+            for idx, mw in enumerate(middlewares, 1):
+                mw_name = type(mw).__name__
+                ui.chip(
+                    f"{idx}. {mw_name}",
+                    icon="security" if "Auth" in mw_name else "filter_alt",
+                    color="blue-9",
+                    text_color="white",
+                ).classes("font-medium")
+                if idx < len(middlewares):
+                    ui.icon("arrow_forward", size="sm")
+            ui.icon("arrow_forward", size="sm")
+            ui.chip(
+                "Handler Execution",
+                icon="play_circle",
+                color="green-9",
+                text_color="white",
+            ).classes("font-bold")
+    else:
+        ui.label("No active middlewares attached to CommandBus.").classes(
+            "hx-empty-label"
+        )
+
+
+async def _dispatch_ping(
+    ping_value: str,
+    container: Container,
+    pipeline: ExecutionPipeline | None,
+    middlewares: list[Any],
+    log_output: Any,
+) -> None:
+    """Execute ping dispatch across pipeline and log output."""
+    log_output.push(f"➡️ [DISPATCH] PingDemoCommand(message='{ping_value}')")
+    for mw in middlewares:
+        log_output.push(
+            f"   ↳ [MIDDLEWARE] Intercepting through {type(mw).__name__}..."
+        )
+
+    try:
+        active_pipeline = pipeline
+        if active_pipeline is None and ExecutionPipeline in container:
+            active_pipeline = container.resolve(ExecutionPipeline)
+
+        if active_pipeline is not None:
+            cmd_cls = None
+            from hexastack_cqrs.infra.registries.command import (
+                CommandRegistry,
+            )
+
+            if CommandRegistry in container:
+                creg = container.resolve(CommandRegistry)
+                for name, cls in creg.all.items():
+                    if "ping" in name.lower():
+                        cmd_cls = cls
+                        break
+
+            if cmd_cls is not None:
+                cmd_instance = cmd_cls.model_validate({"message": ping_value})
+                res = active_pipeline.execute(cmd_instance)
+                log_output.push(f"✅ [SUCCESS] Result: {res}")
+            else:
+                res = active_pipeline.execute_by_name(
+                    "PingDemoCommand", {"message": ping_value}
+                )
+                log_output.push(f"✅ [SUCCESS] Result: {res}")
+        else:
+            log_output.push(
+                "⚠️ [WARNING] ExecutionPipeline instance not directly bound."
+            )
+    except Exception as exc:
+        log_output.push(f"❌ [ERROR] Execution failed: {exc}")
+
+
+def _render_live_runner(
+    container: Container,
+    pipeline: ExecutionPipeline | None,
+    middlewares: list[Any],
+) -> None:
+    """Render interactive test runner card for ping command dispatch."""
+    from nicegui import ui
+
+    ui.label("Interactive Pipeline Execution").classes("hx-section-heading")
+    with ui.card().classes("hx-card"):
+        ui.label("Dispatch PingDemoCommand across the middleware pipeline:").classes(
+            "hx-subtext"
+        )
+        with ui.row().classes("items-center gap-3 w-full"):
+            ping_input = ui.input(
+                label="Message Payload", value="Hello from Hexastack DevTools!"
+            ).classes("flex-grow")
+            log_output = ui.log(max_lines=10).classes("hx-log-console")
+
+            async def _run_ping() -> None:
+                await _dispatch_ping(
+                    str(ping_input.value),
+                    container,
+                    pipeline,
+                    middlewares,
+                    log_output,
+                )
+
+            ui.button(
+                "Dispatch Ping Command", on_click=_run_ping, icon="send", color="blue-9"
+            ).classes("text-white font-medium shadow-sm")
+
+
+def _render_cqrs_tab(
+    container: Container, pipeline: ExecutionPipeline | None = None
+) -> None:
+    """Render the CQRS tab panel showing registered messages, middleware pipeline, and live runner."""
+    from hexastack_cqrs.ports.buses import CommandBusPort
+
+    _render_cqrs_messages(container)
+    cmd_bus = container.resolve(CommandBusPort) if CommandBusPort in container else None
+    middlewares = getattr(cmd_bus, "_middleware", []) if cmd_bus else []
+    _render_middleware_chain(middlewares)
+    _render_live_runner(container, pipeline, middlewares)
+
+
+def _render_flags_tab(container: Container) -> None:
+    """Render the feature flags tab panel showing active flags."""
+    from nicegui import ui
+
+    from hexastack_core.ports.feature_flags import FeatureFlagPort
+
+    ui.label("Active Feature Flags").classes("hx-section-heading")
+    flags_adapter = (
+        container.resolve(FeatureFlagPort) if FeatureFlagPort in container else None
+    )
+
+    get_all_fn = getattr(flags_adapter, "get_all_flags", None)
+    if callable(get_all_fn):
+        flags_data: dict[str, Any] = get_all_fn()
+        if flags_data:
+            flag_rows = [{"flag": k, "enabled": str(v)} for k, v in flags_data.items()]
+            ui.table(
+                columns=[
+                    {
+                        "name": "flag",
+                        "label": "Flag Key",
+                        "field": "flag",
+                        "sortable": True,
+                    },
+                    {
+                        "name": "enabled",
+                        "label": "Status",
+                        "field": "enabled",
+                        "sortable": True,
+                    },
+                ],
+                rows=flag_rows,
+                row_key="flag",
+                pagination={"rowsPerPage": 10},
+            ).classes("w-full")
+        else:
+            ui.label("No feature flags currently configured in provider.").classes(
+                "hx-empty-label"
+            )
+    else:
+        ui.label(
+            "Feature flag provider not available or does not support listing."
+        ).classes("hx-empty-label")
+
+
+def _render_container_tab(container: Container) -> None:
+    """Render the DI container tab panel showing registered services."""
+    from nicegui import ui
+
+    ui.label("Dependency Injection Services").classes("hx-section-heading")
+
+    service_map = getattr(container, "_map", {})
+    services: list[dict[str, str]] = []
+
+    for cls, resolver in service_map.items():
+        service_name = getattr(cls, "__qualname__", getattr(cls, "__name__", str(cls)))
+        module_name = getattr(cls, "__module__", "")
+        resolver_desc = str(resolver).strip("<>")
+
+        services.append(
+            {
+                "service": service_name,
+                "module": module_name,
+                "resolver": resolver_desc,
+            }
+        )
+
+    services.sort(key=lambda s: s["service"])
+
+    if services:
+        ui.table(
+            columns=[
+                {
+                    "name": "service",
+                    "label": "Registered Port / Service",
+                    "field": "service",
+                    "sortable": True,
+                },
+                {
+                    "name": "module",
+                    "label": "Module",
+                    "field": "module",
+                    "sortable": True,
+                },
+                {
+                    "name": "resolver",
+                    "label": "Binding / Lifetime",
+                    "field": "resolver",
+                    "sortable": True,
+                },
+            ],
+            rows=services,
+            row_key="service",
+            pagination={"rowsPerPage": 10},
+        ).classes("w-full")
+    else:
+        ui.label("No direct services found in container introspection.").classes(
+            "hx-empty-label"
+        )
+
+
+def _render_devtools_content(
+    container: Container,
+    pipeline: ExecutionPipeline | None,
+    title: str,
+) -> None:
+    """Render the full DevTools dashboard UI components."""
+    from nicegui import ui
+
+    ui.add_head_html(
+        '<link rel="stylesheet" type="text/css" href="/_hexastack/ui/static/devtools.css">'
+    )
+
+    with ui.header().classes("hx-header"):
+        with ui.row().classes("hx-header-title"):
+            ui.icon("layers", size="md").classes("text-blue-400")
+            ui.label(title).classes("hx-header-text")
+        ui.badge("v0.3.0", color="blue-10").classes("text-xs font-semibold text-white")
+
+    with ui.tabs().classes("w-full bg-slate-100 dark:bg-slate-800") as tabs:
+        tab_cqrs = ui.tab("CQRS Registry", icon="bolt")
+        tab_flags = ui.tab("Feature Flags", icon="toggle_on")
+        tab_container = ui.tab("DI Container", icon="hub")
+
+    with ui.tab_panels(tabs, value=tab_cqrs).classes("w-full p-6"):
+        with ui.tab_panel(tab_cqrs):
+            _render_cqrs_tab(container, pipeline=pipeline)
+
+        with ui.tab_panel(tab_flags):
+            _render_flags_tab(container)
+
+        with ui.tab_panel(tab_container):
+            _render_container_tab(container)
+
+
+def mount_devtools_dashboard(
+    app: FastAPI,
+    container: Container,
+    pipeline: ExecutionPipeline | None = None,
+    *,
+    path: str = "/_devtools",
+    title: str = "Hexastack DevTools",
+) -> None:
+    """Mount the default Hexastack interactive DevTools dashboard on FastAPI.
+
+    Args:
+        app: Target FastAPI application.
+        container: Application rodi.Container instance.
+        pipeline: Optional ExecutionPipeline instance.
+        path: URL path where the dashboard is mounted (default '/_devtools').
+        title: Dashboard page title.
+
+    Returns:
+        None.
+
+    Raises:
+        MissingDependencyError: If NiceGUI is not installed.
+
+    Notes/Architectural Intent:
+        Renders a rich developer console inspecting CQRS buses, feature flags,
+        and DI container services built entirely using the NiceGUI primitives.
+    """
+    check_nicegui_installed()
+    from nicegui import app as nicegui_app
+    from nicegui import ui
+
+    if _STATIC_DIR.is_dir():
+        nicegui_app.add_static_files("/_hexastack/ui/static", str(_STATIC_DIR))
+
+    mount_ui_app(app, title=title)
+
+    @ui.page(path, title=title)
+    def devtools_page():
+        _render_devtools_content(container, pipeline, title)

hexastack_ui-0.4.0/src/hexastack_ui/adapters/nicegui/dispatch.py

@@ -0,0 +1,66 @@
+"""CQRS dispatch helpers for NiceGUI reactive event handlers.
+
+Notes/Architectural Intent:
+    Allows NiceGUI buttons, form submissions, and reactive event loops to invoke
+    ExecutionPipeline commands and queries synchronously or asynchronously.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from hexastack_core.domain import Command, Query
+    from hexastack_cqrs.infra.pipeline import ExecutionPipeline
+
+__all__ = [
+    "dispatch_command",
+    "dispatch_query",
+]
+
+
+async def dispatch_command(pipeline: ExecutionPipeline, command: Command) -> Any:
+    """Dispatch a CQRS command from a NiceGUI interactive event handler.
+
+    Args:
+        pipeline: ExecutionPipeline instance.
+        command: Command instance to execute.
+
+    Returns:
+        Result returned by command execution.
+
+    Raises:
+        Exception: Propagates any handler or middleware execution errors.
+
+    Notes/Architectural Intent:
+        Executes a command through the standard ExecutionPipeline,
+        transparently awaiting async handler returns or returning synchronous values.
+    """
+    result = pipeline.execute(command)
+    if inspect.isawaitable(result):
+        return await result
+    return result
+
+
+async def dispatch_query(pipeline: ExecutionPipeline, query: Query) -> Any:
+    """Dispatch a CQRS query from a NiceGUI interactive event handler or data loader.
+
+    Args:
+        pipeline: ExecutionPipeline instance.
+        query: Query instance to execute.
+
+    Returns:
+        Result returned by query execution.
+
+    Raises:
+        Exception: Propagates any query handler execution errors.
+
+    Notes/Architectural Intent:
+        Executes a query through the standard ExecutionPipeline,
+        transparently awaiting async handler returns or returning synchronous values.
+    """
+    result = pipeline.execute(query)
+    if inspect.isawaitable(result):
+        return await result
+    return result

hexastack_ui-0.4.0/src/hexastack_ui/adapters/nicegui/page.py

@@ -0,0 +1,116 @@
+"""NiceGUI reactive page and mounting primitives.
+
+Notes/Architectural Intent:
+    Provides decorators and mounting functions for integrating NiceGUI with FastAPI/Starlette.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from hexastack_core.domain.exceptions import MissingDependencyError
+
+__all__ = [
+    "check_nicegui_installed",
+    "mount_ui_app",
+    "ui_page",
+]
+
+
+def check_nicegui_installed() -> None:
+    """Verify NiceGUI is available in runtime environment.
+
+    Raises:
+        MissingDependencyError: If NiceGUI is not installed.
+
+    Notes/Architectural Intent:
+        Enables lazy import error reporting with installation hints.
+    """
+    try:
+        import nicegui  # noqa: F401
+    except ImportError as e:
+        raise MissingDependencyError(
+            "NiceGUI is required for hexastack-ui NiceGUI support. "
+            "Install with 'pip install hexastack-ui[nicegui]' or 'pip install nicegui'."
+        ) from e
+
+
+def ui_page(
+    path: str,
+    *,
+    title: str | None = None,
+    viewport: str | None = None,
+    favicon: str | None = None,
+    dark: bool | None = None,
+    response_timeout: float = 3.0,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Declarative decorator registering a NiceGUI reactive UI page.
+
+    Args:
+        path: URL path for the page (e.g. '/dashboard', '/users').
+        title: Optional browser tab title.
+        viewport: Optional viewport meta tag string.
+        favicon: Optional favicon path or URL.
+        dark: Optional dark mode setting (True/False/None).
+        response_timeout: Maximum seconds to wait for client connection response.
+
+    Returns:
+        Decorated page function.
+
+    Raises:
+        MissingDependencyError: If NiceGUI is not installed.
+
+    Notes/Architectural Intent:
+        Wraps `nicegui.ui.page` while cleanly decoupling application modules from
+        direct NiceGUI hard dependency at module import time.
+    """
+    check_nicegui_installed()
+    from nicegui import ui
+
+    return ui.page(
+        path,
+        title=title,
+        viewport=viewport,
+        favicon=favicon,
+        dark=dark,
+        response_timeout=response_timeout,
+    )
+
+
+def mount_ui_app(
+    app: Any,
+    *,
+    title: str = "Hexastack UI",
+    viewport: str = "width=device-width, initial-scale=1",
+    favicon: str | None = None,
+    dark: bool | None = None,
+) -> None:
+    """Mount NiceGUI reactive engine onto an existing FastAPI/Starlette application instance.
+
+    Args:
+        app: Target FastAPI or Starlette application.
+        title: Application default page title.
+        viewport: Viewport meta tag.
+        favicon: Optional favicon.
+        dark: Dark mode preference.
+
+    Returns:
+        None.
+
+    Raises:
+        MissingDependencyError: If NiceGUI is not installed.
+
+    Notes/Architectural Intent:
+        Integrates NiceGUI's Socket.IO and static assets into the host server lifecycle.
+    """
+    check_nicegui_installed()
+    from nicegui import ui
+
+    ui.run_with(
+        app,
+        title=title,
+        viewport=viewport,
+        favicon=favicon,
+        dark=dark,
+    )

hexastack_ui-0.4.0/src/hexastack_ui/adapters/nicegui/static/devtools.css

@@ -0,0 +1,85 @@
+/* Hexastack DevTools Dashboard Stylesheet */
+
+:root {
+	--hx-primary: #1e40af;
+	--hx-secondary: #065f46;
+	--hx-accent: #5b21b6;
+	--hx-dark-bg: #0f172a;
+	--hx-card-bg: #f8fafc;
+	--hx-card-dark-bg: #0f172a;
+	--hx-log-bg: #020617;
+	--hx-log-text: #34d399;
+}
+
+.hx-header {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	background-color: var(--hx-dark-bg);
+	color: #ffffff;
+	padding: 0.75rem 1.5rem;
+}
+
+.hx-header-title {
+	display: flex;
+	align-items: center;
+	gap: 0.75rem;
+}
+
+.hx-header-text {
+	font-size: 1.25rem;
+	font-weight: 700;
+	letter-spacing: -0.025em;
+}
+
+.hx-card {
+	width: 100%;
+	background-color: var(--hx-card-bg);
+	border: 1px solid #e2e8f0;
+	padding: 1rem;
+	margin-bottom: 1.5rem;
+	border-radius: 0.5rem;
+}
+
+.body--dark .hx-card {
+	background-color: var(--hx-card-dark-bg);
+	border-color: #334155;
+}
+
+.hx-log-console {
+	width: 100%;
+	height: 8rem;
+	background-color: var(--hx-log-bg);
+	color: var(--hx-log-text);
+	padding: 0.5rem;
+	font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+	font-size: 0.75rem;
+	border-radius: 0.375rem;
+	border: 1px solid #1e293b;
+}
+
+.hx-section-heading {
+	font-size: 1.125rem;
+	font-weight: 600;
+	margin-bottom: 1rem;
+}
+
+.hx-subtext {
+	font-size: 0.875rem;
+	color: #64748b;
+	margin-bottom: 0.75rem;
+}
+
+.body--dark .hx-subtext {
+	color: #94a3b8;
+}
+
+.hx-empty-label {
+	color: #64748b;
+	font-style: italic;
+	margin-bottom: 1.5rem;
+}
+
+.body--dark .hx-empty-label {
+	color: #94a3b8;
+}

hexastack_ui-0.4.0/src/hexastack_ui/domain/__init__.py

@@ -0,0 +1,15 @@
+"""Domain entities and value objects for Hexastack UI."""
+
+from hexastack_ui.domain.models import (
+    CQRSMessageSummary,
+    DevToolsDashboardState,
+    FeatureFlagSummary,
+    ServiceBindingSummary,
+)
+
+__all__ = [
+    "CQRSMessageSummary",
+    "DevToolsDashboardState",
+    "FeatureFlagSummary",
+    "ServiceBindingSummary",
+]

hexastack_ui-0.4.0/src/hexastack_ui/domain/models.py

@@ -0,0 +1,95 @@
+"""Domain models for UI presentations and DevTools state.
+
+Notes/Architectural Intent:
+    Pure domain representations of diagnostic records, CQRS messages,
+    service bindings, and UI dashboard state independent of any UI framework.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = [
+    "CQRSMessageSummary",
+    "DevToolsDashboardState",
+    "FeatureFlagSummary",
+    "ServiceBindingSummary",
+]
+
+
+class CQRSMessageSummary(BaseModel):
+    """Summary of a registered CQRS Command or Query contract.
+
+    Notes/Architectural Intent:
+        Represents message metadata for visual exploration across developer dashboards.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(
+        description="Canonical class or registration name of the CQRS message"
+    )
+    message_type: str = Field(description="Type of message ('Command' or 'Query')")
+    module: str = Field(
+        default="", description="Originating module of the message definition"
+    )
+
+
+class FeatureFlagSummary(BaseModel):
+    """Summary of an active feature flag and its current state.
+
+    Notes/Architectural Intent:
+        Encapsulates feature flag key/value status for dashboard toggling and inspection.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    key: str = Field(description="Unique identifier key of the feature flag")
+    enabled: bool = Field(description="Boolean enabled status of the flag")
+    description: str = Field(
+        default="", description="Optional human-readable description"
+    )
+
+
+class ServiceBindingSummary(BaseModel):
+    """Summary of a dependency injection service registration.
+
+    Notes/Architectural Intent:
+        Represents service lifetime, interface, and concrete implementation binding metadata.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    service: str = Field(description="Service interface or class name")
+    module: str = Field(
+        default="", description="Module path where the service is defined"
+    )
+    resolver: str = Field(
+        default="", description="Binding description or lifetime resolution strategy"
+    )
+
+
+class DevToolsDashboardState(BaseModel):
+    """Aggregated snapshot of Hexastack runtime state for DevTools inspection.
+
+    Notes/Architectural Intent:
+        Immutable aggregate containing all diagnostic summaries for UI rendering.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    commands: list[CQRSMessageSummary] = Field(
+        default_factory=list, description="Registered commands"
+    )
+    queries: list[CQRSMessageSummary] = Field(
+        default_factory=list, description="Registered queries"
+    )
+    flags: list[FeatureFlagSummary] = Field(
+        default_factory=list, description="Active feature flags"
+    )
+    services: list[ServiceBindingSummary] = Field(
+        default_factory=list, description="Registered DI services"
+    )
+    middlewares: list[str] = Field(
+        default_factory=list, description="Active middleware pipeline names"
+    )

hexastack_ui-0.4.0/src/hexastack_ui/infra/__init__.py

@@ -0,0 +1,7 @@
+"""Infrastructure layer for Hexastack UI."""
+
+from hexastack_ui.infra.bootstrap import UIBootstrapper
+
+__all__ = [
+    "UIBootstrapper",
+]

hexastack_ui-0.4.0/src/hexastack_ui/infra/bootstrap.py

@@ -0,0 +1,35 @@
+"""Infrastructure bootstrapping and DI configuration for UI adapters.
+
+Notes/Architectural Intent:
+    Provides automatic registration of UI presentation adapters into rodi.Container.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rodi import Container
+
+__all__ = [
+    "UIBootstrapper",
+]
+
+
+class UIBootstrapper:
+    """Bootstrapper for Hexastack UI presentation components."""
+
+    @classmethod
+    def bootstrap(cls, container: Container, **kwargs: Any) -> None:
+        """Register UI adapters and ports into the DI container.
+
+        Args:
+            container: Application rodi.Container instance.
+            **kwargs: Extra bootstrap arguments.
+
+        Returns:
+            None.
+
+        Notes/Architectural Intent:
+            Ensures UI presenters and state providers can be resolved cleanly across services.
+        """
+        # Future presenter registrations can be bound here

hexastack_ui-0.4.0/src/hexastack_ui/ports/__init__.py

@@ -0,0 +1,11 @@
+"""Ports and interface contracts for Hexastack UI."""
+
+from hexastack_ui.ports.presenter import (
+    DevToolsPresenterPort,
+    UIPresenterPort,
+)
+
+__all__ = [
+    "DevToolsPresenterPort",
+    "UIPresenterPort",
+]

hexastack_ui-0.4.0/src/hexastack_ui/ports/presenter.py

@@ -0,0 +1,65 @@
+"""Abstract presentation ports for Hexastack UI integrations.
+
+Notes/Architectural Intent:
+    Defines UI framework-agnostic interfaces for rendering developer consoles,
+    mounting web/TUI application lifecycles, and collecting diagnostic state.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from hexastack_ui.domain.models import DevToolsDashboardState
+
+__all__ = [
+    "DevToolsPresenterPort",
+    "UIPresenterPort",
+]
+
+
+class UIPresenterPort(ABC):
+    """Abstract port for mounting and lifecycle management of UI presentation engines."""
+
+    @abstractmethod
+    def mount(self, target_app: Any, **kwargs: Any) -> None:
+        """Mount UI presentation engine onto a host server or execution runtime.
+
+        Args:
+            target_app: Target application or server instance.
+            **kwargs: Additional framework-specific configuration options.
+
+        Returns:
+            None.
+
+        Raises:
+            Exception: If mounting fails.
+
+        Notes/Architectural Intent:
+            Enables generic mounting logic across HTTP servers (FastAPI/Starlette) or TUI runtimes.
+        """
+
+
+class DevToolsPresenterPort(ABC):
+    """Abstract port for rendering interactive DevTools diagnostic dashboards."""
+
+    @abstractmethod
+    def render_dashboard(
+        self, state: DevToolsDashboardState, target_app: Any, **kwargs: Any
+    ) -> None:
+        """Render diagnostic dashboard given a snapshot of the runtime state.
+
+        Args:
+            state: Current aggregated runtime state.
+            target_app: Host application instance.
+            **kwargs: Additional presentation parameters.
+
+        Returns:
+            None.
+
+        Raises:
+            Exception: If dashboard rendering fails.
+
+        Notes/Architectural Intent:
+            Decouples dashboard visualization (NiceGUI, Textual) from state extraction.
+        """