ovui-widgets-app 0.2.0__py3-none-any.whl

ovui_widgets/app/__init__.py

@@ -0,0 +1,53 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: LicenseRef-NvidiaProprietary
+#
+# NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
+# property and proprietary rights in and to this material, related
+# documentation and any modifications thereto. Any use, reproduction,
+# disclosure or distribution of this material and related documentation
+# without an express license agreement from NVIDIA CORPORATION or
+# its affiliates is strictly prohibited.
+
+"""OvGear: Kit-free 3D application built on standalone omni.ui.
+
+Top-level imports are lazy so that ``import ovui_widgets.app`` does not pull in
+``omni.ui`` (or anything that imports it). This is required by the
+headless entrypoint (``python -m ovui_widgets.app.headless``), which must set
+``OMNIUI_HEADLESS=1`` and ``OMNIUI_BACKEND=vulkan`` *before* the ovui
+platform is initialised. Eagerly importing :class:`Application` here
+would defeat that ordering, because Python imports the package
+``ovui_widgets.app`` (and runs this file) before executing ``headless.py``.
+"""
+
+from ovui_widgets.common.version import package_version as _package_version
+
+__version__ = _package_version("ovui-widgets-app")
+
+__all__ = [
+    "AppWindowContribution",
+    "AppWindowHandle",
+    "AppWindowRegistry",
+    "Application",
+    "ContentBrowserWindow",
+    "ErrorReporter",
+    "StatusBar",
+]
+
+
+def __getattr__(name):
+    if name == "Application":
+        from ovui_widgets.app.application import Application
+        return Application
+    if name in {"AppWindowContribution", "AppWindowHandle", "AppWindowRegistry"}:
+        from ovui_widgets.app import window_hooks
+        return getattr(window_hooks, name)
+    if name == "ContentBrowserWindow":
+        from ovui_widgets.content import ContentBrowserWindow
+        return ContentBrowserWindow
+    if name == "ErrorReporter":
+        from ovui_widgets.common.error_reporter import ErrorReporter
+        return ErrorReporter
+    if name == "StatusBar":
+        from ovui_widgets.app.status_bar import StatusBar
+        return StatusBar
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

ovui_widgets/app/__main__.py

@@ -0,0 +1,83 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: LicenseRef-NvidiaProprietary
+#
+# NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
+# property and proprietary rights in and to this material, related
+# documentation and any modifications thereto. Any use, reproduction,
+# disclosure or distribution of this material and related documentation
+# without an express license agreement from NVIDIA CORPORATION or
+# its affiliates is strictly prohibited.
+
+import argparse
+import sys
+from typing import List, Optional
+
+
+async def _main_async() -> None:
+    """Cooperative entry point for embedding OvGear in an existing asyncio loop.
+
+    Callers are responsible for the synchronous bootstrap (write_split_ini,
+    ui.init, style setup) before awaiting this coroutine. For a standalone
+    launch use :func:`main`, which delegates to :meth:`Application.run`.
+    """
+    from ovui_widgets.app.application import Application
+
+    app = Application()
+    app._running = True
+    try:
+        await app.run_async()
+    finally:
+        app._running = False
+
+
+def _parse_args(argv: Optional[List[str]] = None) -> argparse.Namespace:
+    from ovui_widgets.app.cli_settings import extract_setting_overrides
+
+    parser = argparse.ArgumentParser(
+        description="OvGear — standalone 3D USD viewer",
+        epilog=(
+            "Settings overrides: any --/path/to/key=value argument sets the "
+            "corresponding dotted setting at launch (e.g. --/ui/theme=light "
+            "sets ui.theme). Overrides take precedence over persisted settings."
+        ),
+    )
+    parser.add_argument(
+        "usd_file",
+        nargs="?",
+        default=None,
+        help="Optional path to a USD file (.usd/.usda/.usdc/.usdz) to open on startup.",
+    )
+    if argv is None:
+        argv = sys.argv[1:]
+    try:
+        overrides, remaining = extract_setting_overrides(list(argv))
+    except ValueError as exc:
+        parser.error(str(exc))
+    args = parser.parse_args(remaining)
+    args.settings_overrides = overrides
+    return args
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    """Launch OvGear. Used by both `python -m ovui_widgets.app` and the `ovui-widgets` console script."""
+    args = _parse_args(argv if argv is not None else sys.argv[1:])
+    from ovui_widgets.app.native_runtime_bootstrap import (
+        install_preconstructed_renderer,
+        preconstruct_selected_native_renderer,
+    )
+
+    bootstrap = preconstruct_selected_native_renderer()
+    from ovui_widgets.app.application import Application
+
+    app = Application(settings_overrides=args.settings_overrides)
+    install_preconstructed_renderer(app, bootstrap)
+    app.run(usd_path=args.usd_file)
+
+
+def main_sync() -> None:
+    """Console script entry point declared in pyproject.toml. Delegates to main()."""
+    main()
+
+
+if __name__ == "__main__":
+    main()

ovui_widgets/app/_input_bridge.py

@@ -0,0 +1,288 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: LicenseRef-NvidiaProprietary
+#
+# NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
+# property and proprietary rights in and to this material, related
+# documentation and any modifications thereto. Any use, reproduction,
+# disclosure or distribution of this material and related documentation
+# without an express license agreement from NVIDIA CORPORATION or
+# its affiliates is strictly prohibited.
+
+"""Tier 3 livestream input bridge — SDK callback ↔ ovgear main loop.
+
+The ovstream SDK delivers input events on a worker thread; ovgear's
+ImGui IO must be written on the main loop thread before
+``ui.next_frame()``. ``RemoteInputBridge`` is the lock-protected
+hand-off:
+
+* ``MouseEventType.MOVE`` events coalesce into a single atomic
+  ``(x, y)`` — only the most recent cursor position survives until
+  the next drain.
+* Button presses, wheel ticks, keyboard events and unicode text
+  strings append to a deque.
+* Consecutive wheel events with the same modifier mask accumulate
+  their deltas, so a fast scroll spinning out 30 ticks in one frame
+  collapses to a single injected scroll.
+
+Coordinates arrive in streamed-frame pixel space — no scaling. The SDK
+clamps inclusively to its announced extents
+(``input_handler.cpp:119–120``), so ``x == width`` is reachable. The
+bridge accepts that range and clamps it to the ovui-indexable range
+``[0, width-1] × [0, height-1]``. The first out-of-range coord raises
+a one-time WARN; subsequent out-of-range traffic is silent so a
+mis-sized client cannot flood the log.
+
+This module is the **skeleton** (issue #34, Step 3.2). The pre-tick
+drain loop (Step 3.3), mouse-button enum mapping (Step 3.4), modifier
+disconnect cleanup (Step 3.5), and ``Server`` callback wiring (Step
+3.6) layer on top of this state object.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections import deque
+from typing import Deque, List, Tuple, Union
+
+from ovstream import KeyboardEvent, KeyState, MouseEvent, MouseEventType
+
+_LOG = logging.getLogger("ovui_widgets.app.input_bridge")
+
+# NVST key codes that count as "modifier keys" for disconnect cleanup
+# (KeyDefs.h:138–155). Caps Lock and Num Lock are deliberately omitted:
+# they are toggle keys, not held modifiers, so synthesising a release
+# on disconnect would falsely tell ovui the user just released CapsLock
+# even when they are still toggling it.
+#
+# Tracking the actual key codes (not an aggregate ``modifiers`` bitmask)
+# is the source-of-truth fix for the Codex Step 3.5 NOT-GOOD finding:
+# the runtime ovstream WebRTC handler at
+# ``kit-livestream/sdk/src/webrtc/input_handler.cpp:205–224`` collapses
+# RSHIFT / RCONTROL / RALT into the *generic* ``kModShift / kModControl
+# / kModAlt`` bits and reuses bits ``0x0010`` and ``0x0020`` for
+# CapsLock / NumLock. The aggregate ``modifiers`` mask therefore tells
+# us *something* is held but not which side; only the per-event
+# ``key_code`` is side-aware.
+_MODIFIER_NVST_KEY_CODES = frozenset({
+    0x0301,  # NVST_KEY_SHIFT
+    0x0302,  # NVST_KEY_LSHIFT
+    0x0303,  # NVST_KEY_RSHIFT
+    0x0304,  # NVST_KEY_CONTROL
+    0x0305,  # NVST_KEY_LCONTROL
+    0x0306,  # NVST_KEY_RCONTROL
+    0x0307,  # NVST_KEY_ALT
+    0x0308,  # NVST_KEY_LALT
+    0x0309,  # NVST_KEY_RALT
+    0x0310,  # NVST_KEY_META
+    0x0311,  # NVST_KEY_LMETA
+    0x0312,  # NVST_KEY_RMETA
+})
+
+# Discrete events the bridge accepts in its deque. KeyboardEvent and
+# MouseEvent are stored verbatim; unicode-text callbacks land as plain
+# ``str`` so the drain can dispatch with ``isinstance``.
+BridgeEvent = Union[KeyboardEvent, MouseEvent, str]
+
+
+class RemoteInputBridge:
+    """Lock-protected SDK→main-loop event buffer."""
+
+    def __init__(self, width: int, height: int) -> None:
+        if width <= 0 or height <= 0:
+            raise ValueError(
+                f"extents must be positive, got width={width} height={height}"
+            )
+        self._lock = threading.Lock()
+        self._width: int = int(width)
+        self._height: int = int(height)
+        self._mouse_xy: Tuple[int, int] = (0, 0)
+        self._mouse_modifier_mask: int = 0
+        self._mouse_modifier_dirty: bool = False
+        self._events: Deque[BridgeEvent] = deque()
+        # Press-ordered list of NVST modifier key codes that the SDK
+        # delivered DOWN events for and has not yet delivered matching
+        # UP events for. The disconnect-cleanup path reads this so the
+        # synthesised releases use the **same** key code (and therefore
+        # the same ImGui side) the client originally pressed.
+        self._held_modifier_keys: List[int] = []
+        # Cached aggregate ``modifiers`` mask from the last keyboard
+        # event. Kept for diagnostics only — Codex's Step 3.5 review
+        # established that this mask is not side-aware on the runtime
+        # ovstream WebRTC path, so cleanup reads the held-keys list
+        # above instead.
+        self._last_modifier_mask: int = 0
+        self._out_of_range_warned: bool = False
+
+    # ------------------------------------------------------------------
+    # Configuration
+    # ------------------------------------------------------------------
+
+    def set_extents(self, width: int, height: int) -> None:
+        """Update the clamp window (e.g. on resolution change)."""
+        if width <= 0 or height <= 0:
+            return
+        with self._lock:
+            self._width = int(width)
+            self._height = int(height)
+
+    # ------------------------------------------------------------------
+    # SDK-side callbacks (run on the ovstream worker thread)
+    # ------------------------------------------------------------------
+
+    def on_mouse_event(self, event: MouseEvent) -> None:
+        mouse_modifier_mask = int(event.modifiers)
+        if event.type == MouseEventType.BUTTON and event.button_state == KeyState.UP:
+            mouse_modifier_mask = 0
+        if event.type == MouseEventType.MOVE:
+            x, y = self._clamp(event.x, event.y)
+            with self._lock:
+                self._mouse_xy = (x, y)
+                self._set_mouse_modifier_mask_unlocked(mouse_modifier_mask)
+            return
+
+        if event.type == MouseEventType.WHEEL:
+            with self._lock:
+                self._set_mouse_modifier_mask_unlocked(mouse_modifier_mask)
+                tail = self._events[-1] if self._events else None
+                if (
+                    isinstance(tail, MouseEvent)
+                    and tail.type == MouseEventType.WHEEL
+                    and tail.modifiers == event.modifiers
+                ):
+                    tail.data += event.data
+                    tail.data2 += event.data2
+                    tail.scroll_x += event.scroll_x
+                    tail.scroll_y += event.scroll_y
+                    return
+                self._events.append(event)
+            return
+
+        # MouseEventType.BUTTON
+        with self._lock:
+            self._set_mouse_modifier_mask_unlocked(mouse_modifier_mask)
+            self._events.append(event)
+
+    def on_keyboard_event(self, event: KeyboardEvent) -> None:
+        # Steady-state: the SDK delivers each modifier press/release as
+        # an ordinary KeyboardEvent (``InputHandler.cpp:230–249``), so
+        # the bridge appends it verbatim. The held-keys list and the
+        # diagnostic mask are tracked **only** to support disconnect
+        # cleanup — no diff-and-emit synthesis in the steady-state
+        # path (Codex finding 10b).
+        key_code = int(event.key_code)
+        with self._lock:
+            self._events.append(event)
+            self._last_modifier_mask = int(event.modifiers)
+            if key_code in _MODIFIER_NVST_KEY_CODES:
+                if event.key_state == KeyState.DOWN:
+                    if key_code not in self._held_modifier_keys:
+                        self._held_modifier_keys.append(key_code)
+                else:
+                    # KeyState.UP — drop the key from the held list if
+                    # present. ``list.remove`` raises ValueError if the
+                    # item is missing; guard so a stray UP without a
+                    # matching DOWN does not crash the worker thread.
+                    try:
+                        self._held_modifier_keys.remove(key_code)
+                    except ValueError:
+                        pass
+
+    def on_unicode(self, text: str) -> None:
+        if not text:
+            return
+        with self._lock:
+            self._events.append(text)
+
+    def on_connection(self, connected: bool) -> None:
+        """Handle a connection state change from the ovstream ``Server``.
+
+        On disconnect, every modifier the SDK delivered a DOWN event
+        for (and has not yet delivered a matching UP event for) is
+        converted into a synthetic ``KeyState.UP``
+        :class:`KeyboardEvent` and appended to the deque. The drain
+        dispatches those releases through the same
+        :func:`_input_drain.drain_bridge_into_ui` path as ordinary
+        keyboard events, so ovui sees a release for every modifier the
+        remote client was holding when the link dropped — preventing a
+        sticky Shift / Ctrl / Alt / Super state.
+
+        The synthesised release uses the **same NVST key code** the
+        client pressed, so right-side modifiers release right-side
+        ImGui keys (Codex Step 3.5 NOT-GOOD fix). Aggregate
+        ``modifiers`` mask bits are not consulted because the runtime
+        ovstream WebRTC path collapses RSHIFT/RCONTROL/RALT into the
+        generic Shift/Control/Alt bits and reuses bits 0x0010/0x0020
+        for CapsLock/NumLock.
+
+        Idempotent: clearing the held list at the end means a second
+        ``on_connection(False)`` finds it empty and is a no-op.
+        """
+        if connected:
+            return
+        with self._lock:
+            for nvst_key in self._held_modifier_keys:
+                self._events.append(
+                    KeyboardEvent(
+                        key_code=nvst_key,
+                        scan_code=0,
+                        modifiers=0,
+                        key_state=KeyState.UP,
+                    )
+                )
+            self._held_modifier_keys.clear()
+            self._last_modifier_mask = 0
+
+    # ------------------------------------------------------------------
+    # Main-loop side
+    # ------------------------------------------------------------------
+
+    def drain(self) -> Tuple[Tuple[int, int], List[BridgeEvent]]:
+        """Snapshot the current cursor + queued events, clearing the deque."""
+        with self._lock:
+            xy = self._mouse_xy
+            events = list(self._events)
+            self._events.clear()
+        return xy, events
+
+    def mouse_modifier_mask(self) -> int:
+        """Return the latest mouse-event modifier mask."""
+        with self._lock:
+            return self._mouse_modifier_mask
+
+    def consume_mouse_modifier_state(self) -> Tuple[int, bool]:
+        """Return ``(mask, changed)`` and clear the changed flag."""
+        with self._lock:
+            mask = self._mouse_modifier_mask
+            changed = self._mouse_modifier_dirty
+            self._mouse_modifier_dirty = False
+        return mask, changed
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _set_mouse_modifier_mask_unlocked(self, mask: int) -> None:
+        mask = int(mask)
+        if mask != self._mouse_modifier_mask:
+            self._mouse_modifier_mask = mask
+            self._mouse_modifier_dirty = True
+
+    def _clamp(self, x: int, y: int) -> Tuple[int, int]:
+        with self._lock:
+            w = self._width
+            h = self._height
+        out_of_range = x < 0 or y < 0 or x > (w - 1) or y > (h - 1)
+        clamped_x = min(max(int(x), 0), w - 1)
+        clamped_y = min(max(int(y), 0), h - 1)
+        if out_of_range:
+            with self._lock:
+                fire_warn = not self._out_of_range_warned
+                self._out_of_range_warned = True
+            if fire_warn:
+                _LOG.warning(
+                    "coord out of range (%d,%d) for extents %dx%d; "
+                    "clamping to (%d,%d). Subsequent out-of-range events will be silent.",
+                    x, y, w, h, clamped_x, clamped_y,
+                )
+        return clamped_x, clamped_y

ovui_widgets/app/_input_drain.py

@@ -0,0 +1,232 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: LicenseRef-NvidiaProprietary
+#
+# NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
+# property and proprietary rights in and to this material, related
+# documentation and any modifications thereto. Any use, reproduction,
+# disclosure or distribution of this material and related documentation
+# without an express license agreement from NVIDIA CORPORATION or
+# its affiliates is strictly prohibited.
+
+"""Tier 3 input bridge → ovui native input dispatcher.
+
+The :class:`ovui_widgets.app._input_bridge.RemoteInputBridge` accumulates events
+on the ovstream worker thread; this module is the main-loop side that
+translates them into ``omni.ui._ui._inject_*`` calls.
+
+Critical ordering: the dispatcher must run **before**
+``await ui.next_frame()`` so the injected events land in *that* tick's
+ImGui IO. ovui's ``HeadlessVulkanPlatform.cpp`` runs
+``applyInjectedInput()`` at line 485, immediately before
+``ImGui::NewFrame()`` at line 487; an event injected after the
+``next_frame`` await would not be seen until the *next* tick.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from ovstream import KeyboardEvent, KeyState, MouseEvent, MouseEventType
+
+from ovui_widgets.app._input_bridge import RemoteInputBridge
+from ovui_widgets.app._input_keymap import nvst_to_imgui_key
+
+# ImGui's explicit modifier-key slots. These are inside
+# ImGuiKey_NamedKey_BEGIN..END, so the existing standalone _inject_key_event
+# binding accepts them without needing a native API change.
+_IMGUI_KEY_RESERVED_MOD_CTRL = 663
+_IMGUI_KEY_RESERVED_MOD_SHIFT = 664
+_IMGUI_KEY_RESERVED_MOD_ALT = 665
+_IMGUI_KEY_RESERVED_MOD_SUPER = 666
+
+_NVST_MOD_SHIFT = 0x0001
+_NVST_MOD_CTRL = 0x0002
+_NVST_MOD_ALT = 0x0004
+_NVST_MOD_SUPER = 0x0008
+
+# ovstream's ``MouseButton`` enum and ImGui's ``ImGuiMouseButton_`` enum
+# disagree on the order of the middle and right buttons:
+#
+#   ovstream (NONE=0, LEFT=1, MIDDLE=2, RIGHT=3, EXTRA1=4, EXTRA2=5)
+#   ImGui    (Left=0, Right=1, Middle=2, …)                 — imgui.h:2042–2047
+#
+# ovui's ``injectMouseButton(int button, bool pressed)`` passes the int
+# straight to ``io.AddMouseButtonEvent`` (StandaloneInit.cpp:330–336),
+# so the integer fed in IS the ImGui button index. Use an explicit
+# table — a subtract-one shortcut would silently swap MIDDLE and RIGHT.
+_NVST_TO_IMGUI_BUTTON: dict[int, int] = {
+    1: 0,   # MouseButton.LEFT   → ImGuiMouseButton_Left   (0)
+    3: 1,   # MouseButton.RIGHT  → ImGuiMouseButton_Right  (1)
+    2: 2,   # MouseButton.MIDDLE → ImGuiMouseButton_Middle (2)
+    4: 3,   # MouseButton.EXTRA1 → 3
+    5: 4,   # MouseButton.EXTRA2 → 4
+}
+
+
+def _nvst_printable_char(key_code: int, modifiers: int) -> str:
+    """Return the printable character for *key_code* under *modifiers*, or ''.
+
+    The NVST SDK delivers keyboard events as physical key codes only; ImGui's
+    InputText widgets additionally require ``io.AddInputCharactersUTF8`` to
+    insert a glyph into the edit buffer.  This function synthesises that
+    character for the printable ASCII subset of the NVST code space:
+
+        0x20        → space
+        0x30–0x39   → digits 0–9 (identical to ASCII code points)
+        0x41–0x5A   → letter keys A–Z (NVST always uses uppercase VK codes)
+
+    Shift state is bit 0 of *modifiers* (``kModShift``, KeyDefs.h).
+    CapsLock state is bit 4 (``kModCapsLock``).  Letters are uppercase when
+    Shift XOR CapsLock is set, matching standard keyboard behaviour.
+
+    Control (bit 1, ``kModControl``) and Alt (bit 2, ``kModAlt``) suppress
+    character synthesis — Ctrl+key and Alt+key combos are accelerators, not
+    text input.
+    """
+    if modifiers & 0x0006:  # kModControl | kModAlt
+        return ''
+    if key_code == 0x0020:
+        return ' '
+    if 0x0030 <= key_code <= 0x0039:
+        return chr(key_code)
+    if 0x0041 <= key_code <= 0x005A:
+        shift = bool(modifiers & 0x0001)
+        caps  = bool(modifiers & 0x0010)
+        return chr(key_code) if (shift ^ caps) else chr(key_code + 32)
+    return ''
+
+
+def _inject_imgui_modifier_state(ui_native: Any, modifiers: int) -> None:
+    """Submit ImGui's aggregate modifier state from an NVST modifier mask.
+
+    The livestream SDK may report Alt/Ctrl/Shift/Super on mouse events even
+    when it does not deliver separate keyboard events. Scene gestures compare
+    against ImGui's aggregate modifier slots (``io.KeyAlt`` etc.), so injecting
+    only the physical key is not enough for Alt+LMB camera navigation.
+    """
+    mask = int(modifiers)
+    ui_native._inject_key_event(
+        _IMGUI_KEY_RESERVED_MOD_CTRL,
+        bool(mask & _NVST_MOD_CTRL),
+    )
+    ui_native._inject_key_event(
+        _IMGUI_KEY_RESERVED_MOD_SHIFT,
+        bool(mask & _NVST_MOD_SHIFT),
+    )
+    ui_native._inject_key_event(
+        _IMGUI_KEY_RESERVED_MOD_ALT,
+        bool(mask & _NVST_MOD_ALT),
+    )
+    ui_native._inject_key_event(
+        _IMGUI_KEY_RESERVED_MOD_SUPER,
+        bool(mask & _NVST_MOD_SUPER),
+    )
+
+
+def _mouse_scroll_delta(event: MouseEvent) -> tuple[float, float]:
+    """Return the wheel delta, preferring modern ovstream float fields."""
+    scroll_x = float(getattr(event, "scroll_x", 0.0) or 0.0)
+    scroll_y = float(getattr(event, "scroll_y", 0.0) or 0.0)
+    if scroll_x != 0.0 or scroll_y != 0.0:
+        return scroll_x, scroll_y
+    return float(event.data), float(event.data2)
+
+
+def drain_bridge_into_ui(
+    bridge: RemoteInputBridge,
+    ui_native: Any,
+    *,
+    on_left_click: Optional[Callable[[int, int], None]] = None,
+    on_char: Optional[Callable[[str], None]] = None,
+) -> None:
+    """Drain *bridge* and inject every event into *ui_native*.
+
+    *ui_native* is the ``omni.ui._ui`` C-binding submodule (or any
+    object exposing the same ``_inject_*`` surface — a mock works for
+    tests).
+
+    Mouse-position injection is unconditional: the latest cursor
+    coordinates always go in first so subsequent button/wheel events
+    fire at the up-to-date hover target. Discrete events are dispatched
+    in the order they were enqueued.
+
+    The function never raises on bridge contents — unmappable keys
+    (``ImGuiKey_None``), the ``MouseButton.NONE`` button, and out-of-
+    range button indices are silently dropped rather than fed into the
+    ImGui IO.
+
+    *on_left_click*, if provided, is called with the current ``(x, y)``
+    stream coordinates whenever a left-button DOWN event is drained.  The
+    application uses this to synthesise widget focus for widgets (such as
+    the Stage Browser filter bar) whose ``set_mouse_pressed_fn`` callbacks
+    do not fire from ImGui IO injection alone.  The callback runs before
+    ``ui.next_frame()``, so any programmatic focus changes it makes land
+    in the same tick.
+
+    *on_char*, if provided, is called with each printable ASCII character
+    synthesised from a key-down event (via :func:`_nvst_printable_char`).
+    The application uses this to route typed characters to widget models
+    (e.g. the Stage Browser filter) that require direct model updates
+    because ``io.AddInputCharactersUTF8`` alone is insufficient when the
+    target widget hasn't captured ImGui keyboard focus.
+    """
+    (mouse_x, mouse_y), events = bridge.drain()
+    if hasattr(bridge, "consume_mouse_modifier_state"):
+        mouse_modifiers, modifiers_changed = bridge.consume_mouse_modifier_state()
+        if modifiers_changed:
+            _inject_imgui_modifier_state(ui_native, mouse_modifiers)
+    elif hasattr(bridge, "mouse_modifier_mask"):
+        mouse_modifiers = bridge.mouse_modifier_mask()
+        if mouse_modifiers:
+            _inject_imgui_modifier_state(ui_native, mouse_modifiers)
+    ui_native._inject_mouse_move(int(mouse_x), int(mouse_y))
+
+    for event in events:
+        if isinstance(event, MouseEvent):
+            if event.modifiers:
+                _inject_imgui_modifier_state(ui_native, int(event.modifiers))
+            if event.type == MouseEventType.BUTTON:
+                imgui_button = _NVST_TO_IMGUI_BUTTON.get(int(event.data))
+                # ``MouseButton.NONE`` (0) and any future SDK addition
+                # outside the table drop silently — feeding an
+                # unrecognised index into ovui would corrupt
+                # ``MouseDown[]`` (the inject helper takes the int
+                # verbatim and indexes a fixed-size array).
+                if imgui_button is not None:
+                    ui_native._inject_mouse_button(
+                        imgui_button,
+                        event.button_state == KeyState.DOWN,
+                    )
+                    if (imgui_button == 0
+                            and event.button_state == KeyState.DOWN
+                            and on_left_click is not None):
+                        on_left_click(int(mouse_x), int(mouse_y))
+                    if event.button_state == KeyState.UP and event.modifiers:
+                        _inject_imgui_modifier_state(ui_native, 0)
+                continue
+            if event.type == MouseEventType.WHEEL:
+                ui_native._inject_mouse_scroll(*_mouse_scroll_delta(event))
+                continue
+            # MouseEventType.MOVE never reaches the deque (it coalesces
+            # into the atomic position read above). Defensive: skip
+            # silently rather than raise if the bridge ever changes.
+            continue
+
+        if isinstance(event, KeyboardEvent):
+            imgui_key = nvst_to_imgui_key(int(event.key_code))
+            if imgui_key != 0:
+                ui_native._inject_key_event(
+                    imgui_key,
+                    event.key_state == KeyState.DOWN,
+                )
+            if event.key_state == KeyState.DOWN:
+                ch = _nvst_printable_char(int(event.key_code), int(event.modifiers))
+                if ch:
+                    ui_native._inject_text_input(ch)
+                    if on_char is not None:
+                        on_char(ch)
+            continue
+
+        if isinstance(event, str):
+            ui_native._inject_text_input(event)
+            continue