CreativePython 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

CreativePython/GuiRenderer.py

@@ -0,0 +1,3222 @@
+#######################################################################################
+# GuiRenderer.py    Version 1.0    12-Mar-2026
+# Taj Ballinger, Bill Manaris
+#######################################################################################
+#
+# GuiRenderer runs in the child process and owns the Qt event loop.
+# It receives commands from GuiHandler via a Pipe, renders them with Qt,
+# and sends back responses and events.
+#
+# This file is never imported by gui.py — only by the child process via the lazy
+# import inside GuiHandler._launchRenderer().  Qt can therefore be
+# imported normally at the top of this file without affecting the main interpreter.
+#
+# Mirror objects
+# --------------
+# Each gui.py class that creates Qt objects has a mirror class here
+# (e.g. Display -> DisplayMirror, Rectangle -> RectangleMirror).  Mirror objects are
+# instantiated by 'create' commands and registered in GuiRenderer._objectRegistry
+# under their objectId.  Subsequent commands are dispatched to the mirror by objectId.
+#
+# Base classes
+# ------------
+# _DrawableMirror  — position, size, rotation, hit-testing, visibility, tooltip
+# _GraphicsMirror  — color, fill, thickness  (extends _DrawableMirror)
+# Each concrete shape class extends _GraphicsMirror and may override _setSize.
+#
+# Command dispatch
+# ----------------
+# Each mirror class builds a _commandHandlers dict in __init__, mapping action
+# names to handler methods.  Handlers always take (args, responseId) so the
+# dispatcher (handleCommand) stays uniform.  Because Python resolves 'self.method'
+# through the MRO at the time the dict is built, subclass overrides (e.g.
+# RectangleMirror._setSize) are picked up automatically without extra wiring.
+#
+# Event handling
+# --------------
+# GuiHandler.registerEvent() stores a callback locally and sends a 'registerEvent'
+# command here.  GuiRenderer stores the (objectId, eventType) pair in
+# _registeredEvents.  The _GuiEventDispatcher (Phase 7) checks _registeredEvents
+# before relaying any Qt event across the pipe, so only user-registered events
+# generate inter-process traffic.
+#
+# See GuiHandler.py for the full protocol description.
+#
+
+import PySide6.QtWidgets       as QtWidgets
+import PySide6.QtCore          as QtCore
+import PySide6.QtGui           as QtGui
+
+from CreativePython.GuiHandler import _createCommand, _createResponse, _createEvent
+
+# Arc style constants — must match gui.py's PIE, OPEN, CHORD values.
+# Defined here to avoid importing gui.py in the child process.
+_PIE   = 0
+_OPEN  = 1
+_CHORD = 2
+
+
+#######################################################################################
+# GuiRenderer
+#######################################################################################
+
+class GuiRenderer:
+   """
+   Owns the Qt event loop and all Qt objects in the child process.
+   Receives commands from GuiHandler via a Pipe, renders them, and sends
+   back responses and events.
+
+   Command routing
+   ---------------
+   'create' commands instantiate a new mirror object (e.g. DisplayMirror, RectangleMirror)
+   and register it in _objectRegistry under the objectId in the command's 'target'
+   field.  All subsequent commands for that object are routed to it by objectId.
+   Built-in actions ('ping', 'shutdown', 'registerEvent') are handled directly.
+   Unknown targets and unknown actions are silently ignored.
+   """
+
+   def __init__(self, childConn):
+      """
+      Creates the QApplication and initializes all registries.
+      """
+      self.connection = childConn
+
+      # QApplication must be created first; it owns the Qt event loop.
+      self._app = QtWidgets.QApplication([])
+
+      # Do not quit when the last window is closed.  The default behaviour
+      # (quitOnLastWindowClosed = True) would exit the child process the
+      # moment the user closes a Display, breaking the IPC pipe and making
+      # it impossible to open new Displays without restarting Python.
+      # The child only exits when the parent sends a 'shutdown' command or
+      # kills the process directly.
+      self._app.setQuitOnLastWindowClosed(False)
+
+      # Qt installs a SIGTERM handler that drains the event queue before
+      # exiting (graceful shutdown).  When the parent kills this process,
+      # we want immediate exit — override Qt's handler after QApplication
+      # is constructed so ours takes precedence.
+      import signal, os as _os
+      signal.signal(signal.SIGTERM, lambda sig, frame: _os._exit(0))
+
+      # maps objectId (int) -> mirror object (e.g. DisplayMirror, RectangleMirror)
+      self._objectRegistry = {}
+
+      # set of (objectId, eventType) pairs registered by the parent process.
+      # _GuiEventDispatcher (Phase 7) checks this before sending events across the pipe.
+      self._registeredEvents = set()
+
+   def run(self):
+      """
+      Starts the pipe-polling timer and enters Qt's event loop.
+      The QTimer fires _pollPipe() every 8ms (~120 Hz), draining any pending
+      commands without blocking the Qt event loop between frames.
+      """
+      self._timer = QtCore.QTimer()
+      self._timer.timeout.connect(self._pollPipe)
+      self._timer.start(8)
+      self._app.exec()
+
+   _polling = False  # reentrancy guard
+
+   # # ── Option A: no batching (drain entire queue before rendering) ─────────
+   # def _pollPipe(self):
+   #    """
+   #    Drains all pending commands before returning to Qt's event loop.
+   #    """
+   #    while self.connection.poll():
+   #       message     = self.connection.recv()
+   #       keepRunning = self._routeCommand(message)
+   #       if not keepRunning:
+   #          break
+
+   # ── Option B: fixed batch (let Qt render every N commands) ──────────────
+   _BATCH_SIZE = 10
+   
+   def _pollPipe(self):
+      """
+      Drains pending commands, letting Qt process events every _BATCH_SIZE
+      commands so the display updates incrementally during large batches.
+      """
+      if self._polling:
+         return   # processEvents() fired the timer again — skip
+      self._polling = True
+      try:
+         count = 0
+         while self.connection.poll():
+            message     = self.connection.recv()
+            keepRunning = self._routeCommand(message)
+            if not keepRunning:
+               break
+            count += 1
+            if count % self._BATCH_SIZE == 0:
+               self._app.processEvents()
+      finally:
+         self._polling = False
+
+   # # ── Option C: adaptive batch (scales with scene complexity) ─────────────
+   # _BATCH_MIN = 10    # batch size when scene is empty
+   # _BATCH_MAX = 1000  # batch size ceiling
+   # _BATCH_PER = 25    # add this many to the batch per 1000 objects in scene
+
+   # def _pollPipe(self):
+   #    """
+   #    Drains pending commands, letting Qt process events at adaptive
+   #    intervals.  Small scenes get frequent updates (responsive feel);
+   #    large scenes batch more commands between repaints (less overhead
+   #    from increasingly expensive repaints).
+   #    """
+   #    if self._polling:
+   #       return   # processEvents() fired the timer again — skip
+   #    self._polling = True
+   #    try:
+   #       objectCount = len(self._objectRegistry)
+   #       batchSize   = min(self._BATCH_MAX,
+   #                         self._BATCH_MIN + objectCount * self._BATCH_PER)
+   #       count = 0
+   #       while self.connection.poll():
+   #          message     = self.connection.recv()
+   #          keepRunning = self._routeCommand(message)
+   #          if not keepRunning:
+   #             break
+   #          count += 1
+   #          if count % batchSize == 0:
+   #             self._app.processEvents()
+   #    finally:
+   #       self._polling = False
+
+   def _routeCommand(self, commandDict):
+      """
+      Routes an incoming command to the appropriate handler.
+      Returns False if the renderer should shut down, True otherwise.
+      """
+      action     = commandDict.get('action')
+      target     = commandDict.get('target')
+      args       = commandDict.get('args', {})
+      responseId = commandDict.get('responseId')
+
+      # ── Built-in actions ──────────────────────────────────────────────────
+      if action == 'shutdown':
+         self._handleShutdown()
+         return False
+
+      elif action == 'ping':
+         response = _createResponse(responseId, ['pong'])
+         self.connection.send(response)
+
+      elif action == 'registerEvent':
+         objectId  = args.get('objectId')
+         eventType = args.get('eventType')
+         self._registeredEvents.add((objectId, eventType))
+
+      elif action == 'unregisterEvent':
+         objectId  = args.get('objectId')
+         eventType = args.get('eventType')
+         self._registeredEvents.discard((objectId, eventType))
+
+      elif action == 'getBatchSize':
+         response = _createResponse(responseId, [self._BATCH_SIZE])
+         self.connection.send(response)
+
+      elif action == 'setBatchSize':
+         self._BATCH_SIZE = int(args.get('batchSize', self._BATCH_SIZE))
+
+      elif action == 'fireTestEvent':
+         eventType   = args.get('eventType', 'testEvent')
+         eventTarget = args.get('target', 0)
+         eventArgs   = args.get('eventArgs', {})
+         self.sendEvent(eventType, eventTarget, eventArgs)
+
+      elif action == 'colorDialog':
+         import sys, subprocess
+         initial = args.get('initial', [0, 0, 0, 255])
+         r, g, b, a = initial
+
+         if sys.platform == 'darwin':
+            # On macOS, showing any dialog (native or Qt) while a Qt window is
+            # on screen triggers Metal blit-shader compilation in Qt's window
+            # backing store.  On Apple Silicon (AGXMetalG15X_M1) this compilation
+            # aborts at the GPU driver level (SIGABRT), killing the child process.
+            #
+            # Fix: run the color picker as a completely separate process via
+            # osascript.  It has its own Metal context and no interaction with
+            # Qt's rendering pipeline.  AppleScript returns 16-bit components
+            # (0-65535); we rescale to 8-bit (0-255).
+            r16 = int(r / 255 * 65535 + 0.5)
+            g16 = int(g / 255 * 65535 + 0.5)
+            b16 = int(b / 255 * 65535 + 0.5)
+            script = f'choose color default color {{{r16}, {g16}, {b16}}}'
+            proc = subprocess.run(['osascript', '-e', script],
+                                  capture_output=True, text=True)
+            if proc.returncode == 0:
+               parts  = proc.stdout.strip().strip('{}').split(', ')
+               result = [int(int(p) / 65535 * 255 + 0.5) for p in parts]
+            else:
+               result = [r, g, b]   # user cancelled
+         else:
+            # On Windows and Linux, QColorDialog works without issue.
+            initialColor = QtGui.QColor(r, g, b, a)
+            chosen = QtWidgets.QColorDialog.getColor(initialColor)
+            if chosen.isValid():
+               result = [chosen.red(), chosen.green(), chosen.blue()]
+            else:
+               result = [r, g, b]   # user cancelled
+         response = _createResponse(responseId, result)
+         self.connection.send(response)
+
+      # ── Object creation ───────────────────────────────────────────────────
+      elif action == 'create':
+         objectType = args.get('type')
+         objectId   = target   # objectId is pre-assigned by the parent process
+
+         if objectType == 'Display':
+            mirror = DisplayMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'Rectangle':
+            mirror = RectangleMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'Oval':
+            mirror = OvalMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'Arc':
+            mirror = ArcMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'Polyline':
+            mirror = PolylineMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'Line':
+            mirror = LineMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'Polygon':
+            mirror = PolygonMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'Icon':
+            mirror = IconMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'Label':
+            mirror = LabelMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'Group':
+            mirror = GroupMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'Button':
+            mirror = ButtonMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'CheckBox':
+            mirror = CheckBoxMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'Slider':
+            mirror = SliderMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'DropDownList':
+            mirror = DropDownListMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'TextField':
+            mirror = TextFieldMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'TextArea':
+            mirror = TextAreaMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+         elif objectType == 'Menu':
+            mirror = MenuMirror(objectId, args, self)
+            self._objectRegistry[objectId] = mirror
+
+      # ── Mirror object actions ─────────────────────────────────────────────
+      else:
+         mirrorObject = self._objectRegistry.get(target)
+         if mirrorObject is not None:
+            mirrorObject.handleCommand(action, args, responseId)
+         # unknown targets are silently ignored
+
+      return True
+
+   def sendResponse(self, responseId, values=None):
+      """Sends a response back to the parent process."""
+      response = _createResponse(responseId, values)
+      self.connection.send(response)
+
+   def sendEvent(self, eventType, objectId, args=None):
+      """Sends an event to the parent process."""
+      event = _createEvent(eventType, objectId, args)
+      self.connection.send(event)
+
+   def _handleShutdown(self):
+      """Stops the polling timer and quits the Qt event loop."""
+      self._timer.stop()
+      self._app.quit()
+
+
+#######################################################################################
+# Qt helper classes
+#######################################################################################
+
+class QtDisplay(QtWidgets.QMainWindow):
+   """
+   QMainWindow subclass used by DisplayMirror.
+   Overrides closeEvent so DisplayMirror can send a 'displayClose' event to the
+   parent process when the user closes the window.
+   """
+
+   def __init__(self, owner):
+      super().__init__()
+      self._owner = owner   # the DisplayMirror that owns this window
+
+   def closeEvent(self, event):
+      self._owner.onWindowClose()
+      event.accept()
+
+
+#######################################################################################
+# _GuiEventDispatcher  —  Qt event filter for mouse/keyboard events
+#######################################################################################
+
+class _GuiEventDispatcher(QtCore.QObject):
+   """
+   Intercepts Qt mouse and keyboard events on a DisplayMirror's view/viewport,
+   performs hit testing against the display's _itemList, and sends matching
+   events across the pipe to GuiHandler for callback delivery.
+
+   One instance per DisplayMirror, installed as an event filter on _view (keys)
+   and _view.viewport() (mouse).
+   """
+
+   _CLICK_THRESHOLD = 5   # max pixel movement for mouseDown+mouseUp to count as a click
+
+   def __init__(self, displayMirror):
+      super().__init__()
+      self._display       = displayMirror
+      self._guiRenderer   = displayMirror._guiRenderer
+      self._draggingItems = []      # list of objectIds being dragged (set on mouseDown)
+      self._lastMouseDown = None    # (x, y) at last mouseDown
+      self._lastMouseMove = None    # (x, y) at last mouseMove
+      self._itemsUnderMouse = set() # set of objectIds currently under mouse
+
+      # install as event filter on viewport (mouse events) and view (key events)
+      displayMirror._view.viewport().installEventFilter(self)
+      displayMirror._view.installEventFilter(self)
+
+      # map Qt event types to handler methods
+      self._mouseHandlers = {
+         QtCore.QEvent.Type.MouseButtonPress:   self._handleMousePress,
+         QtCore.QEvent.Type.MouseButtonRelease: self._handleMouseRelease,
+         QtCore.QEvent.Type.MouseMove:          self._handleMouseMove,
+         QtCore.QEvent.Type.Enter:              self._handleMouseEnter,
+         QtCore.QEvent.Type.Leave:              self._handleMouseLeave,
+      }
+      self._keyHandlers = {
+         QtCore.QEvent.Type.KeyPress:   self._handleKeyPress,
+         QtCore.QEvent.Type.KeyRelease: self._handleKeyRelease,
+      }
+
+   # ── eventFilter (Qt override) ─────────────────────────────────────────────
+
+   def eventFilter(self, obj, qEvent):
+      """
+      Qt event filter callback.  Routes mouse events from the viewport and
+      key events from the view to the appropriate handler.
+      """
+      try:
+         if obj is self._display._view.viewport():
+            handler = self._mouseHandlers.get(qEvent.type())
+            if handler is not None:
+               x, y = self._extractMouseCoords(qEvent)
+               return handler(x, y)
+
+         elif obj is self._display._view:
+            handler = self._keyHandlers.get(qEvent.type())
+            if handler is not None:
+               if not qEvent.isAutoRepeat():
+                  key  = qEvent.key()
+                  char = qEvent.text() if qEvent.text() else ""
+                  return handler(key, char)
+      except RuntimeError:
+         pass   # C++ object deleted during shutdown
+
+      return False
+
+   def _extractMouseCoords(self, qEvent):
+      """Extracts integer (x, y) coordinates from a QMouseEvent."""
+      if hasattr(qEvent, 'position') and callable(qEvent.position):
+         return int(qEvent.position().x()), int(qEvent.position().y())
+      elif self._lastMouseMove is not None:
+         return self._lastMouseMove
+      else:
+         return 0, 0
+
+   # ── Hit testing ────────────────────────────────────────────────────────────
+
+   def _allHittableItems(self, itemList=None):
+      """
+      Recursively walks a display's _itemList, descending into GroupMirrors.
+      Yields items in front-to-back order.
+      For Groups, yields children first, then the Group itself.
+      """
+      if itemList is None:
+         itemList = self._display._itemList
+      for item in itemList:
+         if item._isControl:
+            continue
+         if isinstance(item, GroupMirror):
+            # yield children first (they are in front of the group)
+            yield from self._allHittableItems(item._itemList)
+            # then yield the group itself
+            yield item
+         else:
+            yield item
+
+   def _hitTestCascade(self, eventType, x, y):
+      """
+      Returns an ordered list of objectIds to notify (deepest child first,
+      then ancestor Groups).  Only includes items registered for eventType.
+      """
+      point   = QtCore.QPointF(x, y)
+      targets = []
+      for item in self._allHittableItems():
+         localPoint = item._qObject.mapFromScene(point)
+         if item._qObject.contains(localPoint):
+            if (item.objectId, eventType) in self._guiRenderer._registeredEvents:
+               targets.append(item.objectId)
+      return targets
+
+   def _sendIfRegistered(self, eventType, objectId, args):
+      """Sends an event across the pipe if (objectId, eventType) is registered."""
+      if (objectId, eventType) in self._guiRenderer._registeredEvents:
+         self._guiRenderer.sendEvent(eventType, objectId, args)
+
+   # ── Mouse handlers ─────────────────────────────────────────────────────────
+
+   def _handleMousePress(self, x, y):
+      self._lastMouseDown = (x, y)
+      args = [x, y]
+
+      # find all items registered for mouseDrag (for future drag events)
+      self._draggingItems = self._hitTestCascade('mouseDrag', x, y)
+
+      # mouseDown: hit test and deliver to all matching items + Display
+      targets = self._hitTestCascade('mouseDown', x, y)
+      for targetId in targets:
+         self._sendIfRegistered('mouseDown', targetId, args)
+      self._sendIfRegistered('mouseDown', self._display.objectId, args)
+      return False
+
+   def _handleMouseRelease(self, x, y):
+      args = [x, y]
+
+      # check if this is a click (mouse moved less than threshold)
+      isClick = False
+      if self._lastMouseDown is not None:
+         dx = abs(x - self._lastMouseDown[0])
+         dy = abs(y - self._lastMouseDown[1])
+         if dx <= self._CLICK_THRESHOLD and dy <= self._CLICK_THRESHOLD:
+            isClick = True
+
+      self._lastMouseDown = None
+      self._draggingItems = []
+
+      # mouseUp: hit test and deliver
+      targets = self._hitTestCascade('mouseUp', x, y)
+      for targetId in targets:
+         self._sendIfRegistered('mouseUp', targetId, args)
+      self._sendIfRegistered('mouseUp', self._display.objectId, args)
+
+      # mouseClick: only if movement was under threshold
+      if isClick:
+         clickTargets = self._hitTestCascade('mouseClick', x, y)
+         for targetId in clickTargets:
+            self._sendIfRegistered('mouseClick', targetId, args)
+         self._sendIfRegistered('mouseClick', self._display.objectId, args)
+
+      return False
+
+   def _handleMouseMove(self, x, y):
+      self._lastMouseMove = (x, y)
+      args = [x, y]
+
+      if self._lastMouseDown is None:
+         # mouseMove (button up): hit test all matching items
+         targets = self._hitTestCascade('mouseMove', x, y)
+         for targetId in targets:
+            self._sendIfRegistered('mouseMove', targetId, args)
+         self._sendIfRegistered('mouseMove', self._display.objectId, args)
+      else:
+         # mouseDrag (button down): deliver to all drag items from mouseDown
+         for targetId in self._draggingItems:
+            self._sendIfRegistered('mouseDrag', targetId, args)
+         self._sendIfRegistered('mouseDrag', self._display.objectId, args)
+
+      # mouseEnter/Exit: only iterate if any item is registered for these events
+      self._updateEnterExit(x, y)
+
+      return False
+
+   def _updateEnterExit(self, x, y):
+      """Tracks which items are under the mouse and sends enter/exit events."""
+      # optimization: skip if no items are registered for enter or exit
+      hasEnterExit = False
+      for item in self._allHittableItems():
+         oid = item.objectId
+         if ((oid, 'mouseEnter') in self._guiRenderer._registeredEvents or
+             (oid, 'mouseExit')  in self._guiRenderer._registeredEvents):
+            hasEnterExit = True
+            break
+      if not hasEnterExit:
+         return
+
+      # determine which items are under the mouse now
+      point = QtCore.QPointF(x, y)
+      itemsNow = set()
+      for item in self._allHittableItems():
+         localPoint = item._qObject.mapFromScene(point)
+         if item._qObject.contains(localPoint):
+            itemsNow.add(item.objectId)
+
+      entered = itemsNow - self._itemsUnderMouse
+      exited  = self._itemsUnderMouse - itemsNow
+      self._itemsUnderMouse = itemsNow
+
+      args = [x, y]
+      for objectId in entered:
+         self._sendIfRegistered('mouseEnter', objectId, args)
+      for objectId in exited:
+         self._sendIfRegistered('mouseExit', objectId, args)
+
+   def _handleMouseEnter(self, x, y):
+      """Mouse entered the Display viewport — deliver mouseEnter to the Display."""
+      self._sendIfRegistered('mouseEnter', self._display.objectId, [x, y])
+      return False
+
+   def _handleMouseLeave(self, x, y):
+      """Mouse left the Display viewport — deliver mouseExit to the Display."""
+      self._sendIfRegistered('mouseExit', self._display.objectId, [x, y])
+      return False
+
+   # ── Key handlers ───────────────────────────────────────────────────────────
+
+   def _handleKeyPress(self, key, char):
+      """Delivers keyDown to ALL registered items (including grouped) + Display, then keyType."""
+      registered = self._guiRenderer._registeredEvents
+
+      # keyDown: deliver to all registered items
+      for item in self._allHittableItems():
+         if (item.objectId, 'keyDown') in registered:
+            self._guiRenderer.sendEvent('keyDown', item.objectId, [key])
+      self._sendIfRegistered('keyDown', self._display.objectId, [key])
+
+      # keyType: deliver to all registered items (char, not key code)
+      if char:
+         for item in self._allHittableItems():
+            if (item.objectId, 'keyType') in registered:
+               self._guiRenderer.sendEvent('keyType', item.objectId, [char])
+         self._sendIfRegistered('keyType', self._display.objectId, [char])
+
+      return False
+
+   def _handleKeyRelease(self, key, char):
+      """Delivers keyUp to ALL registered items (including grouped) + Display."""
+      registered = self._guiRenderer._registeredEvents
+
+      for item in self._allHittableItems():
+         if (item.objectId, 'keyUp') in registered:
+            self._guiRenderer.sendEvent('keyUp', item.objectId, [key])
+      self._sendIfRegistered('keyUp', self._display.objectId, [key])
+
+      return False
+
+
+#######################################################################################
+# DisplayMirror  —  mirror of gui.py's Display
+#######################################################################################
+
+class DisplayMirror:
+   """
+   Mirror of gui.py's Display class.  Owns all Qt objects for one display window.
+
+   Created by GuiRenderer when it receives a 'create' command with type='Display'.
+   All subsequent operations arrive as commands routed through handleCommand().
+
+   add / addOrder / remove
+   -----------------------
+   Items on a Display are tracked in _itemList (front = top z-order).  Qt z-order
+   is maintained as a float _qZValue on each mirror object so that insertions only
+   require averaging two neighbours rather than renumbering the entire list.
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      """
+      Creates the Qt window, scene, view, and OpenGL viewport for one Display.
+      """
+      self.objectId     = objectId
+      self._guiRenderer = guiRenderer
+      self._itemList    = []
+      self._toolTipText = None
+      self._showCoords  = False
+
+      title  = args.get('title',  '')
+      width  = args.get('width',  600)
+      height = args.get('height', 400)
+      x      = args.get('x',     0)
+      y      = args.get('y',     50)
+      color  = args.get('color', [255, 255, 255, 255])
+
+      self._window = QtDisplay(self)
+      self._window.setWindowTitle(title)
+      self._window.setGeometry(x, y, width, height)
+      self._window.setFixedSize(width, height)
+      contextPolicy = QtCore.Qt.ContextMenuPolicy.CustomContextMenu
+      self._window.setContextMenuPolicy(contextPolicy)
+      self._window.show()
+
+      # Qt 6's default software rasterizer (raster engine) is sufficient for
+      # 2D educational graphics and works consistently across all platforms.
+      # QOpenGLWidget was previously used here for hardware acceleration, but
+      # on macOS its OpenGL→Metal bridge conflicted with native AppKit dialogs
+      # (NSColorPicker, etc.) that also use Metal, causing the GPU shader
+      # compiler to abort (SIGABRT in AGXMetal).  Removing it eliminates that
+      # crash, simplifies the code, and gives identical behavior on every OS.
+      # The OS window manager still handles GPU compositing of the final window.
+      self._scene   = QtWidgets.QGraphicsScene(0, 0, width, height)
+      self._view    = QtWidgets.QGraphicsView(self._scene)
+      self._window.setCentralWidget(self._view)
+
+      noIndex       = QtWidgets.QGraphicsScene.ItemIndexMethod.NoIndex
+      minimalUpdate = QtWidgets.QGraphicsView.ViewportUpdateMode.MinimalViewportUpdate
+      hoverTracking = QtCore.Qt.WidgetAttribute.WA_Hover
+      mouseTracking = QtCore.Qt.WidgetAttribute.WA_MouseTracking
+      scrollOff     = QtCore.Qt.ScrollBarPolicy.ScrollBarAlwaysOff
+      antiAlias     = QtGui.QPainter.RenderHint.Antialiasing
+      smoothPixmap  = QtGui.QPainter.RenderHint.SmoothPixmapTransform
+      textAntiAlias = QtGui.QPainter.RenderHint.TextAntialiasing
+
+      self._scene.setItemIndexMethod(noIndex)
+      self._view.setViewportUpdateMode(minimalUpdate)
+      self._view.setAttribute(hoverTracking,  True)
+      self._view.setAttribute(mouseTracking,  True)
+      self._view.setHorizontalScrollBarPolicy(scrollOff)
+      self._view.setVerticalScrollBarPolicy(scrollOff)
+      self._view.setRenderHint(antiAlias,     True)
+      self._view.setRenderHint(smoothPixmap,  True)
+      self._view.setRenderHint(textAntiAlias, True)
+
+      r, g, b, a = color
+      qColor      = QtGui.QColor(r, g, b, a)
+      brush       = QtGui.QBrush(qColor)
+      self._scene.setBackgroundBrush(brush)
+      self._view.setBackgroundBrush(brush)
+
+      # Persistent draw layer — a transparent pixmap that one-time draw calls paint onto.
+      # Sits at z = -1e9, permanently below all instantiated objects (which start at z=1.0
+      # and decrease).  Never added to _itemList, so it is invisible to hit-testing,
+      # removeAll, and z-order management.
+      self._drawPixmap = QtGui.QPixmap(width, height)
+      self._drawPixmap.fill(QtCore.Qt.GlobalColor.transparent)
+      self._drawLayer  = QtWidgets.QGraphicsPixmapItem(self._drawPixmap)
+      self._drawLayer.setZValue(-1e9)
+      self._scene.addItem(self._drawLayer)
+
+      self._commandHandlers = {
+         'show':                 self._show,
+         'hide':                 self._hide,
+         'close':                self._close,
+         'add':                  self._add,
+         'addOrder':             self._addOrder,
+         'remove':               self._remove,
+         'removeAll':            self._removeAll,
+         'move':                 self._move,
+         'getOrder':             self._getOrder,
+         'setOrder':             self._setOrder,
+         'getColor':             self._getColor,
+         'setColor':             self._setColor,
+         'getTitle':             self._getTitle,
+         'setTitle':             self._setTitle,
+         'getWidth':             self._getWidth,
+         'getHeight':            self._getHeight,
+         'getSize':              self._getSize,
+         'setSize':              self._setSize,
+         'getPosition':          self._getPosition,
+         'setPosition':          self._setPosition,
+         'setToolTipText':       self._setToolTipText,
+         'showMouseCoordinates': self._showMouseCoordinates,
+         'hideMouseCoordinates': self._hideMouseCoordinates,
+         'addMenu':              self._addMenu,
+         'addPopupMenu':         self._addPopupMenu,
+         'write':                self._write,
+         'draw':                 self._draw,
+         'clearDrawing':         self._clearDrawing,
+      }
+
+      self._drawHandlers = {
+         'rectangle': self._drawRectangle,
+         'oval':      self._drawOval,
+         'circle':    self._drawOval,
+         'point':     self._drawOval,
+         'arc':       self._drawArc,
+         'line':      self._drawLine,
+         'polyline':  self._drawPolyline,
+         'polygon':   self._drawPolygon,
+         'icon':      self._drawIcon,
+         'label':     self._drawLabel,
+      }
+
+      self._popupMenu = None
+      self._window.customContextMenuRequested.connect(self._onContextMenuRequested)
+
+      self._eventDispatcher = _GuiEventDispatcher(self)
+
+   def handleCommand(self, action, args, responseId):
+      handler = self._commandHandlers.get(action)
+      if handler is not None:
+         handler(args, responseId)
+
+   # ── Window visibility ──────────────────────────────────────────────────────
+
+   def _show(self, args, responseId):
+      self._window.show()
+
+   def _hide(self, args, responseId):
+      self._window.hide()
+
+   def _close(self, args, responseId):
+      self._window.close()
+
+   # ── Item management ────────────────────────────────────────────────────────
+
+   def _add(self, args, responseId):
+      """Adds an item at the top of the z-order (order = 0)."""
+      itemId       = args.get('itemId')
+      x            = args.get('x')
+      y            = args.get('y')
+      addOrderArgs = {'itemId': itemId, 'order': 0, 'x': x, 'y': y}
+      self._addOrder(addOrderArgs, responseId=None)
+
+   def _addOrder(self, args, responseId):
+      """Adds an item at the specified z-order position."""
+      itemId = args.get('itemId')
+      order  = args.get('order', 0)
+      x      = args.get('x')
+      y      = args.get('y')
+
+      item = self._guiRenderer._objectRegistry.get(itemId)
+      if item is None:
+         return
+
+      if item in self._itemList:
+         self._itemList.remove(item)
+         self._scene.removeItem(item._qObject)
+
+      order = max(0, min(len(self._itemList), order))
+      self._itemList.insert(order, item)
+
+      if order == 0:
+         qZValue = 1.0
+         if len(self._itemList) > 1:
+            neighbor = self._itemList[1]
+            qZValue  = neighbor._qZValue + 1.0
+
+      elif order >= len(self._itemList) - 1:
+         qZValue = 0.0
+         if len(self._itemList) > 1:
+            neighbor = self._itemList[-2]
+            qZValue  = neighbor._qZValue - 1.0
+
+      else:
+         frontNeighbor = self._itemList[order - 1]
+         backNeighbor  = self._itemList[order + 1]
+         qZValue       = (frontNeighbor._qZValue + backNeighbor._qZValue) / 2.0
+
+      item._qZValue = qZValue
+      if item._isControl:
+         item._qObject.setParent(self._window)  # attach QWidget to window
+         item._qObject.show()
+      else:
+         item._qObject.setZValue(qZValue)
+         self._scene.addItem(item._qObject)      # attach QGraphicsItem to scene
+         cacheMode = QtWidgets.QGraphicsItem.CacheMode.DeviceCoordinateCache
+         item._qObject.setCacheMode(cacheMode)
+
+      posArgs = {}
+      if x is not None:
+         posArgs['x'] = x
+      if y is not None:
+         posArgs['y'] = y
+      if posArgs:
+         item._setPosition(posArgs, responseId=None)
+
+   def _remove(self, args, responseId):
+      itemId = args.get('itemId')
+      item = self._guiRenderer._objectRegistry.get(itemId)
+      if item is not None and item in self._itemList:
+         self._itemList.remove(item)
+         if item._isControl:
+            item._qObject.setParent(None)     # detach QWidget from window
+            item._qObject.hide()
+         else:
+            self._scene.removeItem(item._qObject)
+
+   def _removeAll(self, args, responseId):
+      self._view.setUpdatesEnabled(False)
+      for item in list(self._itemList):
+         if item._isControl:
+            item._qObject.setParent(None)
+            item._qObject.hide()
+         else:
+            self._scene.removeItem(item._qObject)
+      self._itemList.clear()
+      self._view.setUpdatesEnabled(True)
+      self._view.viewport().update()
+
+   def _move(self, args, responseId):
+      itemId = args.get('itemId')
+      x      = args.get('x')
+      y      = args.get('y')
+      item = self._guiRenderer._objectRegistry.get(itemId)
+      if item is not None and item in self._itemList:
+         item._setPosition({'x': x, 'y': y}, responseId=None)
+
+   def _getOrder(self, args, responseId):
+      itemId = args.get('itemId')
+      order  = None
+      for i, item in enumerate(self._itemList):
+         if item.objectId == itemId:
+            order = i
+            break
+      self._guiRenderer.sendResponse(responseId, [order])
+
+   def _setOrder(self, args, responseId):
+      itemId       = args.get('itemId')
+      order        = args.get('order', 0)
+      addOrderArgs = {'itemId': itemId, 'order': order, 'x': None, 'y': None}
+      self._addOrder(addOrderArgs, responseId=None)
+
+   # ── Color ──────────────────────────────────────────────────────────────────
+
+   def _getColor(self, args, responseId):
+      qColor = self._scene.backgroundBrush().color()
+      r      = qColor.red()
+      g      = qColor.green()
+      b      = qColor.blue()
+      a      = qColor.alpha()
+      self._guiRenderer.sendResponse(responseId, [r, g, b, a])
+
+   def _setColor(self, args, responseId):
+      color      = args.get('color', [255, 255, 255, 255])
+      r, g, b, a = color
+      qColor     = QtGui.QColor(r, g, b, a)
+      brush      = QtGui.QBrush(qColor)
+      self._scene.setBackgroundBrush(brush)
+      self._view.setBackgroundBrush(brush)
+
+   # ── Title ──────────────────────────────────────────────────────────────────
+
+   def _getTitle(self, args, responseId):
+      title = self._window.windowTitle()
+      self._guiRenderer.sendResponse(responseId, [title])
+
+   def _setTitle(self, args, responseId):
+      title = args.get('title', '')
+      self._window.setWindowTitle(title)
+
+   # ── Size ───────────────────────────────────────────────────────────────────
+
+   def _getWidth(self, args, responseId):
+      self._guiRenderer.sendResponse(responseId, [int(self._scene.width())])
+
+   def _getHeight(self, args, responseId):
+      self._guiRenderer.sendResponse(responseId, [int(self._scene.height())])
+
+   def _getSize(self, args, responseId):
+      width  = int(self._scene.width())
+      height = int(self._scene.height())
+      self._guiRenderer.sendResponse(responseId, [width, height])
+
+   def _setSize(self, args, responseId):
+      width  = args.get('width',  600)
+      height = args.get('height', 400)
+      if width > 0 and height > 0:
+         pos = self._window.pos()
+         self._scene.setSceneRect(0, 0, width, height)
+         self._window.setFixedSize(width, height)
+         self._window.move(pos)
+
+         # Recreate the draw layer at the new dimensions.  The old drawing is cleared
+         # because scaling painted geometry would distort it.
+         self._drawPixmap = QtGui.QPixmap(width, height)
+         self._drawPixmap.fill(QtCore.Qt.GlobalColor.transparent)
+         self._drawLayer.setPixmap(self._drawPixmap)
+
+   # ── Position ───────────────────────────────────────────────────────────────
+
+   def _getPosition(self, args, responseId):
+      x = int(self._window.x())
+      y = int(self._window.y())
+      self._guiRenderer.sendResponse(responseId, [x, y])
+
+   def _setPosition(self, args, responseId):
+      x      = int(args.get('x', 0))
+      y      = int(args.get('y', 0))
+      width  = int(self._scene.width())
+      height = int(self._scene.height())
+      self._window.setGeometry(x, y, width, height)
+
+   # ── Tooltip ────────────────────────────────────────────────────────────────
+
+   def _setToolTipText(self, args, responseId):
+      text              = args.get('text')
+      self._toolTipText = text
+      self._view.setToolTip(text)
+
+   def _showMouseCoordinates(self, args, responseId):
+      self._showCoords = True
+      self._view.setToolTip(None)
+
+   def _hideMouseCoordinates(self, args, responseId):
+      self._showCoords = False
+      self._view.setToolTip(self._toolTipText)
+
+   # ── Menu ───────────────────────────────────────────────────────────────────
+
+   def _addMenu(self, args, responseId):
+      menuId = args.get('menuId')
+      menu   = self._guiRenderer._objectRegistry.get(menuId)
+      if menu is not None:
+         self._window.menuBar().addMenu(menu._qMenu)
+
+   def _addPopupMenu(self, args, responseId):
+      menuId = args.get('menuId')
+      menu   = self._guiRenderer._objectRegistry.get(menuId)
+      if menu is not None:
+         self._popupMenu = menu._qMenu
+
+   def _onContextMenuRequested(self, pos):
+      if self._popupMenu is not None:
+         globalPos = self._window.mapToGlobal(pos)
+         self._popupMenu.exec(globalPos)
+
+   # ── Draw layer ─────────────────────────────────────────────────────────────
+
+   def _draw(self, args, responseId):
+      """Dispatches a one-time draw command to the appropriate shape painter."""
+      shape   = args.get('shape')
+      handler = self._drawHandlers.get(shape)
+      if handler is not None:
+         handler(args)
+
+   def _clearDrawing(self, args, responseId):
+      """Clears all one-time drawn content from the draw layer."""
+      self._drawPixmap.fill(QtCore.Qt.GlobalColor.transparent)
+      self._drawLayer.setPixmap(self._drawPixmap)
+
+   def _openDrawPainter(self):
+      """Opens an antialiased QPainter on the draw pixmap and returns it."""
+      painter = QtGui.QPainter(self._drawPixmap)
+      painter.setRenderHint(QtGui.QPainter.RenderHint.Antialiasing)
+      painter.setRenderHint(QtGui.QPainter.RenderHint.SmoothPixmapTransform)
+      return painter
+
+   def _closeDrawPainter(self, painter):
+      """Ends the painter and pushes the updated pixmap to the draw layer."""
+      painter.end()
+      self._drawLayer.setPixmap(self._drawPixmap)
+
+   def _makeDrawPen(self, color, thickness):
+      """Returns a QPen for the given [r,g,b,a] color and line thickness."""
+      r, g, b, a = color
+      pen = QtGui.QPen(QtGui.QColor(r, g, b, a))
+      pen.setWidth(thickness)
+      return pen
+
+   def _makeDrawBrush(self, color, fill):
+      """Returns a filled QBrush if fill is True, otherwise NoBrush."""
+      if fill:
+         r, g, b, a = color
+         return QtGui.QBrush(QtGui.QColor(r, g, b, a))
+      return QtGui.QBrush(QtCore.Qt.BrushStyle.NoBrush)
+
+   def _drawOval(self, args):
+      """
+      Paints an ellipse (or circle) onto the draw layer.
+      Used by both 'oval' and 'circle' draw commands.
+
+      Args:
+        x, y          — top-left corner of the bounding box
+        width, height — bounding box dimensions
+        color         — [r, g, b, a]
+        fill          — bool
+        thickness     — int (line width)
+        rotation      — degrees (CCW visual)
+      """
+      x         = args.get('x',         0)
+      y         = args.get('y',         0)
+      width     = args.get('width',     10)
+      height    = args.get('height',    10)
+      color     = args.get('color',     [0, 0, 0, 255])
+      fill      = args.get('fill',      False)
+      thickness = args.get('thickness', 1)
+      rotation  = args.get('rotation',  0)
+
+      painter = self._openDrawPainter()
+      painter.setPen(self._makeDrawPen(color, thickness))
+      painter.setBrush(self._makeDrawBrush(color, fill))
+
+      if rotation != 0:
+         cx = x + width  / 2
+         cy = y + height / 2
+         painter.translate(cx, cy)
+         painter.rotate(-rotation)   # Qt rotates CW; CP rotation is CCW visual
+         painter.drawEllipse(QtCore.QRectF(-width / 2, -height / 2, width, height))
+      else:
+         painter.drawEllipse(QtCore.QRectF(x, y, width, height))
+
+      self._closeDrawPainter(painter)
+
+   def _drawRectangle(self, args):
+      """
+      Paints a rectangle onto the draw layer.
+
+      Args:
+        x, y          — top-left corner of the bounding box
+        width, height — bounding box dimensions
+        color         — [r, g, b, a]
+        fill          — bool
+        thickness     — int (line width)
+        rotation      — degrees (CCW visual)
+      """
+      x         = args.get('x',         0)
+      y         = args.get('y',         0)
+      width     = args.get('width',     10)
+      height    = args.get('height',    10)
+      color     = args.get('color',     [0, 0, 0, 255])
+      fill      = args.get('fill',      False)
+      thickness = args.get('thickness', 1)
+      rotation  = args.get('rotation',  0)
+
+      painter = self._openDrawPainter()
+      painter.setPen(self._makeDrawPen(color, thickness))
+      painter.setBrush(self._makeDrawBrush(color, fill))
+
+      if rotation != 0:
+         cx = x + width  / 2
+         cy = y + height / 2
+         painter.translate(cx, cy)
+         painter.rotate(-rotation)
+         painter.drawRect(QtCore.QRectF(-width / 2, -height / 2, width, height))
+      else:
+         painter.drawRect(QtCore.QRectF(x, y, width, height))
+
+      self._closeDrawPainter(painter)
+
+   def _drawArc(self, args):
+      """
+      Paints an arc (open, pie, or chord) onto the draw layer.
+      Uses the same QPainterPath construction as ArcMirror.
+
+      Args:
+        x, y          — top-left corner of the bounding box
+        width, height — bounding box dimensions
+        startAngle    — degrees
+        endAngle      — degrees
+        style         — 0 (PIE), 1 (OPEN), 2 (CHORD)
+        color         — [r, g, b, a]
+        fill          — bool
+        thickness     — int (line width)
+        rotation      — degrees (CCW visual)
+      """
+      x          = args.get('x',          0)
+      y          = args.get('y',          0)
+      width      = args.get('width',      100)
+      height     = args.get('height',     100)
+      startAngle = args.get('startAngle', 180)
+      endAngle   = args.get('endAngle',   360)
+      style      = args.get('style',      _OPEN)
+      color      = args.get('color',      [0, 0, 0, 255])
+      fill       = args.get('fill',       False)
+      thickness  = args.get('thickness',  1)
+      rotation   = args.get('rotation',   0)
+
+      arcWidth = -(endAngle - startAngle)   # Qt sweeps CW for positive span
+
+      path = QtGui.QPainterPath()
+      path.arcMoveTo(0, 0, width, height, startAngle)
+      path.arcTo(0, 0, width, height, startAngle, arcWidth)
+      if style == _PIE:
+         path.lineTo(width / 2, height / 2)
+         path.closeSubpath()
+      elif style == _CHORD:
+         path.closeSubpath()
+
+      painter = self._openDrawPainter()
+      painter.setPen(self._makeDrawPen(color, thickness))
+      painter.setBrush(self._makeDrawBrush(color, fill))
+
+      if rotation != 0:
+         cx = x + width  / 2
+         cy = y + height / 2
+         painter.translate(cx, cy)
+         painter.rotate(-rotation)
+         painter.translate(-width / 2, -height / 2)
+      else:
+         painter.translate(x, y)
+
+      painter.drawPath(path)
+      self._closeDrawPainter(painter)
+
+   def _drawLine(self, args):
+      """
+      Paints a line segment onto the draw layer.
+      Rotation is applied around the line's midpoint.
+
+      Args:
+        x1, y1, x2, y2 — endpoint coordinates (scene space)
+        color           — [r, g, b, a]
+        thickness       — int (line width)
+        rotation        — degrees (CCW visual)
+      """
+      x1        = args.get('x1',        0)
+      y1        = args.get('y1',        0)
+      x2        = args.get('x2',        100)
+      y2        = args.get('y2',        100)
+      color     = args.get('color',     [0, 0, 0, 255])
+      thickness = args.get('thickness', 1)
+      rotation  = args.get('rotation',  0)
+
+      painter = self._openDrawPainter()
+      painter.setPen(self._makeDrawPen(color, thickness))
+
+      if rotation != 0:
+         mx = (x1 + x2) / 2
+         my = (y1 + y2) / 2
+         painter.translate(mx, my)
+         painter.rotate(-rotation)
+         painter.translate(-mx, -my)
+
+      painter.drawLine(QtCore.QPointF(x1, y1), QtCore.QPointF(x2, y2))
+      self._closeDrawPainter(painter)
+
+   def _drawPolyline(self, args):
+      """
+      Paints an open polyline onto the draw layer.
+      Rotation is applied around the bounding box center.
+
+      Args:
+        xPoints   — list of x coordinates (scene space)
+        yPoints   — list of y coordinates (scene space)
+        color     — [r, g, b, a]
+        thickness — int (line width)
+        rotation  — degrees (CCW visual)
+      """
+      xPoints   = args.get('xPoints',   [0, 100])
+      yPoints   = args.get('yPoints',   [0, 100])
+      color     = args.get('color',     [0, 0, 0, 255])
+      thickness = args.get('thickness', 1)
+      rotation  = args.get('rotation',  0)
+
+      points  = [QtCore.QPointF(x, y) for x, y in zip(xPoints, yPoints)]
+      polygon = QtGui.QPolygonF(points)
+
+      painter = self._openDrawPainter()
+      painter.setPen(self._makeDrawPen(color, thickness))
+      painter.setBrush(QtCore.Qt.BrushStyle.NoBrush)
+
+      if rotation != 0:
+         cx = (min(xPoints) + max(xPoints)) / 2
+         cy = (min(yPoints) + max(yPoints)) / 2
+         painter.translate(cx, cy)
+         painter.rotate(-rotation)
+         painter.translate(-cx, -cy)
+
+      painter.drawPolyline(polygon)
+      self._closeDrawPainter(painter)
+
+   def _drawPolygon(self, args):
+      """
+      Paints a closed polygon onto the draw layer.
+      Rotation is applied around the bounding box center.
+
+      Args:
+        xPoints   — list of x coordinates (scene space)
+        yPoints   — list of y coordinates (scene space)
+        color     — [r, g, b, a]
+        fill      — bool
+        thickness — int (line width)
+        rotation  — degrees (CCW visual)
+      """
+      xPoints   = args.get('xPoints',   [0, 100, 50])
+      yPoints   = args.get('yPoints',   [0,   0, 100])
+      color     = args.get('color',     [0, 0, 0, 255])
+      fill      = args.get('fill',      False)
+      thickness = args.get('thickness', 1)
+      rotation  = args.get('rotation',  0)
+
+      points  = [QtCore.QPointF(x, y) for x, y in zip(xPoints, yPoints)]
+      polygon = QtGui.QPolygonF(points)
+
+      painter = self._openDrawPainter()
+      painter.setPen(self._makeDrawPen(color, thickness))
+      painter.setBrush(self._makeDrawBrush(color, fill))
+
+      if rotation != 0:
+         cx = (min(xPoints) + max(xPoints)) / 2
+         cy = (min(yPoints) + max(yPoints)) / 2
+         painter.translate(cx, cy)
+         painter.rotate(-rotation)
+         painter.translate(-cx, -cy)
+
+      painter.drawPolygon(polygon)
+      self._closeDrawPainter(painter)
+
+   def _drawIcon(self, args):
+      """
+      Paints an image file onto the draw layer.
+
+      Args:
+        filename      — path to the image file
+        x, y          — top-left position in scene space
+        width, height — target dimensions (None = use pixmap's native size)
+        rotation      — degrees (CCW visual)
+      """
+      filename = args.get('filename', '')
+      x        = args.get('x',        0)
+      y        = args.get('y',        0)
+      width    = args.get('width')
+      height   = args.get('height')
+      rotation = args.get('rotation', 0)
+
+      pixmap = QtGui.QPixmap(filename)
+      if pixmap.isNull():
+         return
+
+      if width is None and height is None:
+         width  = pixmap.width()
+         height = pixmap.height()
+      elif width is None:
+         width  = int(pixmap.width() * (height / pixmap.height()))
+      elif height is None:
+         height = int(pixmap.height() * (width / pixmap.width()))
+
+      pixmap = pixmap.scaled(int(width), int(height),
+                             QtCore.Qt.AspectRatioMode.IgnoreAspectRatio,
+                             QtCore.Qt.TransformationMode.SmoothTransformation)
+
+      painter = self._openDrawPainter()
+
+      if rotation != 0:
+         cx = x + width  / 2
+         cy = y + height / 2
+         painter.translate(cx, cy)
+         painter.rotate(-rotation)
+         painter.drawPixmap(QtCore.QPointF(-width / 2, -height / 2), pixmap)
+      else:
+         painter.drawPixmap(QtCore.QPointF(x, y), pixmap)
+
+      self._closeDrawPainter(painter)
+
+   def _drawLabel(self, args):
+      """
+      Paints a text string onto the draw layer.
+      Text is positioned with its top-left at (x, y), matching Label's placement.
+
+      Args:
+        text  — string
+        x, y  — top-left of the text in scene space
+        color — [r, g, b, a]
+        font  — None, or [name, [weight, italic], size]
+      """
+      text  = str(args.get('text',  ''))
+      x     = args.get('x',     0)
+      y     = args.get('y',     0)
+      color = args.get('color', [0, 0, 0, 255])
+      font  = args.get('font')
+
+      painter = self._openDrawPainter()
+
+      r, g, b, a = color
+      painter.setPen(QtGui.QColor(r, g, b, a))
+
+      if font is not None:
+         name, style, size = font
+         weight, italic    = style
+         qFont = QtGui.QFont(name, size)
+         qFont.setWeight(QtGui.QFont.Weight(weight))
+         qFont.setItalic(italic)
+         painter.setFont(qFont)
+
+      # QRectF positions top-left at (x, y), matching Label's setPos behavior
+      painter.drawText(
+         QtCore.QRectF(x, y, self._drawPixmap.width(), self._drawPixmap.height()),
+         QtCore.Qt.AlignmentFlag.AlignLeft | QtCore.Qt.TextFlag.TextSingleLine,
+         text)
+
+      self._closeDrawPainter(painter)
+
+   # ── Write ──────────────────────────────────────────────────────────────────
+
+   def _write(self, args, responseId):
+      """
+      Renders the scene to a QPixmap and saves it to a file.
+      Optional width/height args resize the output; omitting one preserves aspect ratio.
+      Sends [success (bool), resolvedPath (str)] back to the parent process.
+      """
+      import os
+      filename = args.get('filename', 'display.png')
+      width    = args.get('width')
+      height   = args.get('height')
+
+      sceneRect = self._scene.sceneRect()
+      pixmap    = QtGui.QPixmap(int(sceneRect.width()), int(sceneRect.height()))
+      pixmap.fill(QtCore.Qt.GlobalColor.transparent)
+      painter   = QtGui.QPainter(pixmap)
+      painter.setRenderHint(QtGui.QPainter.RenderHint.Antialiasing)
+      painter.setRenderHint(QtGui.QPainter.RenderHint.SmoothPixmapTransform)
+      self._scene.render(painter)
+      painter.end()
+
+      if width is not None or height is not None:
+         origW  = pixmap.width()
+         origH  = pixmap.height()
+         width  = int(origW * (height / origH)) if width  is None else int(width)
+         height = int(origH * (width  / origW)) if height is None else int(height)
+         pixmap = pixmap.scaled(width, height,
+                                QtCore.Qt.AspectRatioMode.IgnoreAspectRatio,
+                                QtCore.Qt.TransformationMode.SmoothTransformation)
+
+      success      = pixmap.save(filename)
+      resolvedPath = os.path.abspath(filename)
+      self._guiRenderer.sendResponse(responseId, [success, resolvedPath])
+
+   # ── Close event ────────────────────────────────────────────────────────────
+
+   def onWindowClose(self):
+      isRegistered = (self.objectId, 'displayClose') in self._guiRenderer._registeredEvents
+      if isRegistered:
+         self._guiRenderer.sendEvent('displayClose', self.objectId, {})
+
+
+#######################################################################################
+# _DrawableMirror  —  base mirror for all drawable items
+#######################################################################################
+
+class _DrawableMirror:
+   """
+   Base class for all mirror objects that can be placed on a Display.
+   Provides position, size, rotation, hit-testing, visibility, and tooltip command handlers.
+
+   Concrete classes (e.g. RectangleMirror) must:
+     1. Call super().__init__(objectId, guiRenderer) first.
+     2. Create self._qObject (the underlying QGraphicsItem).
+     3. Set self._localCornerX, _localCornerY, _width, _height from their constructor args.
+     4. Call self._qObject.setPos(x, y) to place the item.
+     5. Override _setSize if their QGraphicsItem needs shape-specific resizing.
+
+   Because Python resolves 'self.method' through the MRO at the time the
+   _commandHandlers dict is built, any override of _setSize in a subclass is
+   automatically used without needing to re-register the handler.
+   """
+
+   _isControl = False   # Controls override this to True
+
+   def __init__(self, objectId, guiRenderer):
+      self.objectId      = objectId
+      self._guiRenderer  = guiRenderer
+      self._qObject      = None     # set by concrete class constructor
+      self._qZValue      = 0.0      # assigned by DisplayMirror._addOrder
+
+      # cached object values, used as fallbacks
+      self._localCornerX = 0
+      self._localCornerY = 0
+      self._width        = 0
+      self._height       = 0
+      self._rotation     = 0
+      self._toolTipText  = None
+
+      # GuiRenderer only handles commands that alter an object visually, or
+      # that rely on hit testing.  The true state is contained in the real gui.py object.
+      self._commandHandlers = {
+         'setPosition':      self.setPosition,
+         'getSize':          self.getSize,
+         'setSize':          self.setSize,
+         'setRotation':      self.setRotation,
+         'contains':         self.contains,
+         'intersects':       self.intersects,
+         'encloses':         self.encloses,
+         'setToolTipText':   self.setToolTipText,
+         'show':             self.show,
+         'hide':             self.hide,
+      }
+
+   def handleCommand(self, action, args, responseId):
+      """
+      Dispatches an incoming command to the appropriate handler method.
+      Unknown actions are silently ignored.
+      """
+      handler = self._commandHandlers.get(action)
+      if handler is not None:
+         handler(args, responseId)
+
+   # ── Position ───────────────────────────────────────────────────────────────
+
+   def setPosition(self, args, responseId):
+      """
+      Set the item's local (x, y) coordinates.
+      """
+      x = args.get('x', self._localCornerX)
+      y = args.get('y', self._localCornerY)
+
+      # update Qt item
+      self._qObject.setPos(x, y)
+
+      # store cached position
+      self._localCornerX = x
+      self._localCornerY = y
+
+   # ── Size ───────────────────────────────────────────────────────────────────
+
+   def getSize(self, args, responseId):
+      """
+      Returns [width, height] for this item.  Used by Icon and Label to
+      resolve dimensions after creation, since pixel data lives in Qt.
+      """
+      self._guiRenderer.sendResponse(responseId, [self._width, self._height])
+
+   def setSize(self, args, responseId):
+      """
+      Base size handler — updates _width/_height only.
+      Concrete classes override this to also update their QGraphicsItem geometry.
+      """
+      self._width  = args.get('width',  self._width)
+      self._height = args.get('height', self._height)
+
+   # ── Rotation ───────────────────────────────────────────────────────────────
+
+   def setRotation(self, args, responseId):
+      """
+      Applies rotation to the Qt object.
+      We always rotate around the center of the shape.
+      """
+      rotation = args.get('rotation', self._rotation)
+      centerX  = (self._width  / 2)
+      centerY  = (self._height / 2)
+
+      # update internal rotation
+      self._rotation = rotation
+
+      # update Qt scene
+      qtDegree = -rotation % 360   # CP increases CCW; Qt increases CW
+      self._qObject.setTransformOriginPoint(centerX, centerY)
+      self._qObject.prepareGeometryChange()
+      self._qObject.setRotation(qtDegree)
+
+   # ── Hit testing ────────────────────────────────────────────────────────────
+
+   def contains(self, args, responseId):
+      """Returns True if the point (x, y) is inside this item."""
+      x           = args.get('x', 0)
+      y           = args.get('y', 0)
+      globalPoint = QtCore.QPointF(x, y)
+      localPoint  = self._qObject.mapFromScene(globalPoint)
+      result      = self._qObject.contains(localPoint)
+      self._guiRenderer.sendResponse(responseId, [result])
+
+   def intersects(self, args, responseId):
+      """Returns True if this item intersects another item."""
+      otherObjectId = args.get('otherObjectId')
+      otherMirror   = self._guiRenderer._objectRegistry.get(otherObjectId)
+      result        = False
+
+      if otherMirror is not None:
+         pathA  = self._qObject.mapToScene(self._qObject.shape())
+         pathB  = otherMirror._qObject.mapToScene(otherMirror._qObject.shape())
+         result = pathA.intersects(pathB)
+
+      self._guiRenderer.sendResponse(responseId, [result])
+
+   def encloses(self, args, responseId):
+      """Returns True if this item fully encloses another item."""
+      otherObjectId = args.get('otherObjectId')
+      otherMirror   = self._guiRenderer._objectRegistry.get(otherObjectId)
+      result        = False
+
+      if otherMirror is not None:
+         pathA  = self._qObject.mapToScene(self._qObject.shape())
+         pathB  = otherMirror._qObject.mapToScene(otherMirror._qObject.shape())
+         result = pathA.contains(pathB)
+
+      self._guiRenderer.sendResponse(responseId, [result])
+
+   # ── Visibility ─────────────────────────────────────────────────────────────
+
+   def show(self, args, responseId):
+      self._qObject.setVisible(True)
+
+   def hide(self, args, responseId):
+      self._qObject.setVisible(False)
+
+   # ── Tooltip ────────────────────────────────────────────────────────────────
+
+   def setToolTipText(self, args, responseId):
+      text              = args.get('text')
+      self._toolTipText = text
+      self._qObject.setToolTip(text)
+
+
+#######################################################################################
+# _GraphicsMirror  —  base mirror for shape primitives
+#######################################################################################
+
+class _GraphicsMirror(_DrawableMirror):
+   """
+   Extends _DrawableMirror with color, fill, and line-thickness support.
+   All concrete shape classes (RectangleMirror, OvalMirror, etc.) extend this.
+
+   Constructor extracts 'color', 'fill', and 'thickness' from the
+   args dict and stores them.  The concrete class is responsible for creating
+   _qObject and then calling _applyColor() and _applyThickness() to push the
+   initial values to Qt.
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, guiRenderer)
+
+      self._color     = args.get('color',     [0, 0, 0, 255])
+      self._fill      = args.get('fill',      False)
+      self._thickness = args.get('thickness', 1)
+
+      # add graphics-specific command handlers on top of drawable ones
+      self._commandHandlers.update({
+         'setColor':     self.setColor,
+         'setFill':      self.setFill,
+         'setThickness': self.setThickness,
+      })
+
+   def _applyColor(self):
+      """
+      Pushes self._color to the QPen outline and, if filled, to the QBrush fill.
+      Must be called after self._qObject is created.
+      """
+      r, g, b, a = self._color
+      qColor     = QtGui.QColor(r, g, b, a)
+
+      qPen = self._qObject.pen()
+      qPen.setColor(qColor)
+      self._qObject.setPen(qPen)
+
+      if self._fill:
+         qBrush = QtGui.QBrush(qColor)
+      else:
+         qBrush = QtGui.QBrush(QtGui.QColor(0, 0, 0, 0))   # fully transparent
+      self._qObject.setBrush(qBrush)
+
+   def _applyThickness(self):
+      """
+      Pushes self._thickness to the QPen line width.
+      Must be called after self._qObject is created.
+      """
+      qPen = self._qObject.pen()
+      qPen.setWidth(self._thickness)
+      self._qObject.setPen(qPen)
+
+   # ── Color ──────────────────────────────────────────────────────────────────
+
+   def setColor(self, args, responseId):
+      self._color = args.get('color', [0, 0, 0, 255])
+      self._applyColor()
+
+   # ── Fill ───────────────────────────────────────────────────────────────────
+
+   def setFill(self, args, responseId):
+      self._fill = bool(args.get('fill', False))
+      self._applyColor()   # brush depends on fill state, so re-apply color
+
+   # ── Thickness ──────────────────────────────────────────────────────────────
+
+   def setThickness(self, args, responseId):
+      self._thickness = int(args.get('thickness', 1))
+      self._applyThickness()
+
+
+#######################################################################################
+# RectangleMirror  —  mirror of gui.py's Rectangle
+#######################################################################################
+
+class RectangleMirror(_GraphicsMirror):
+   """
+   Mirror of gui.py's Rectangle.  Backed by a QGraphicsRectItem.
+
+   Constructor args expected in the 'args' dict:
+     x, y          — pre-rotation top-left corner (pre-processed by gui.py)
+     width, height — dimensions
+     color         — [r, g, b, a]
+     fill          — bool
+     thickness     — int (line width)
+     rotation      — degrees (CCW visual, 0 = no rotation)
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, args, guiRenderer)
+
+      rotation = args.get('rotation', 0)
+
+      self._localCornerX = args.get('x',      0)
+      self._localCornerY = args.get('y',      0)
+      self._width        = args.get('width',  100)
+      self._height       = args.get('height', 100)
+
+      # create the backing Qt item
+      self._qObject = QtWidgets.QGraphicsRectItem(0, 0, self._width, self._height)
+
+      # push initial values to Qt
+      self._qObject.setPos(self._localCornerX, self._localCornerY)
+      self._applyColor()
+      self._applyThickness()
+
+      if rotation != 0:
+         self.setRotation({'rotation': rotation}, responseId=None)
+
+   def setSize(self, args, responseId):
+      """
+      Overrides _DrawableMirror.setSize to also update the QRectF geometry.
+      Called automatically via MRO when 'setSize' commands arrive.
+      """
+      width  = args.get('width',  self._width)
+      height = args.get('height', self._height)
+      if width > 0 and height > 0:
+         rect = QtCore.QRectF(0, 0, width, height)
+         self._qObject.prepareGeometryChange()   # invalidate Qt hit box
+         self._qObject.setRect(rect)
+         self._width  = width
+         self._height = height
+
+
+#######################################################################################
+# OvalMirror  —  mirror of gui.py's Oval
+#######################################################################################
+
+class OvalMirror(_GraphicsMirror):
+   """
+   Mirror of gui.py's Oval.  Backed by a QGraphicsEllipseItem.
+   Also used by Circle and Point (their differences are resolved on the gui.py side).
+
+   Constructor args expected in the 'args' dict:
+     x, y          — pre-rotation top-left corner (pre-processed by gui.py)
+     width, height — dimensions
+     color         — [r, g, b, a]
+     fill          — bool
+     thickness     — int (line width)
+     rotation      — degrees (CCW visual, 0 = no rotation)
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, args, guiRenderer)
+
+      rotation = args.get('rotation', 0)
+
+      self._localCornerX = args.get('x',      0)
+      self._localCornerY = args.get('y',      0)
+      self._width        = args.get('width',  100)
+      self._height       = args.get('height', 100)
+
+      # create the backing Qt item
+      self._qObject = QtWidgets.QGraphicsEllipseItem(0, 0, self._width, self._height)
+
+      # push initial values to Qt
+      self._qObject.setPos(self._localCornerX, self._localCornerY)
+      self._applyColor()
+      self._applyThickness()
+
+      if rotation != 0:
+         self.setRotation({'rotation': rotation}, responseId=None)
+
+   def setSize(self, args, responseId):
+      """
+      Overrides _DrawableMirror.setSize to also update the QRectF geometry.
+      """
+      width  = args.get('width',  self._width)
+      height = args.get('height', self._height)
+      if width > 0 and height > 0:
+         rect = QtCore.QRectF(0, 0, width, height)
+         self._qObject.prepareGeometryChange()   # invalidate Qt hit box
+         self._qObject.setRect(rect)
+         self._width  = width
+         self._height = height
+
+
+#######################################################################################
+# ArcMirror  —  mirror of gui.py's Arc
+#######################################################################################
+
+class ArcMirror(_GraphicsMirror):
+   """
+   Mirror of gui.py's Arc.  Backed by a QGraphicsPathItem.
+   Also used by ArcCircle (its differences are resolved on the gui.py side).
+
+   Constructor args expected in the 'args' dict:
+     x, y          — pre-rotation top-left corner (pre-processed by gui.py)
+     width, height — dimensions
+     startAngle    — degrees
+     endAngle      — degrees
+     style         — 0 (PIE), 1 (OPEN), or 2 (CHORD)
+     color         — [r, g, b, a]
+     fill          — bool
+     thickness     — int (line width)
+     rotation      — degrees (CCW visual, 0 = no rotation)
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, args, guiRenderer)
+
+      rotation = args.get('rotation', 0)
+
+      self._localCornerX = args.get('x',      0)
+      self._localCornerY = args.get('y',      0)
+      self._width        = args.get('width',  100)
+      self._height       = args.get('height', 100)
+
+      self._startAngle = args.get('startAngle', 180)
+      self._endAngle   = args.get('endAngle',   360)
+      self._style      = args.get('style',      _OPEN)
+      self._arcWidth   = -(self._endAngle - self._startAngle)  # Qt angles are opposite
+
+      self._commandHandlers.update({
+         'setArcWidth': self._setArcWidth,
+      })
+
+      # build the arc path
+      path = self._buildPath(self._width, self._height)
+      self._qObject = QtWidgets.QGraphicsPathItem(path)
+
+      # push initial values to Qt
+      self._qObject.setPos(self._localCornerX, self._localCornerY)
+      self._applyColor()
+      self._applyThickness()
+
+      if rotation != 0:
+         self.setRotation({'rotation': rotation}, responseId=None)
+
+   def _buildPath(self, width, height):
+      """
+      Builds a QPainterPath for the arc at the given dimensions.
+      """
+      path = QtGui.QPainterPath()
+      path.arcMoveTo(0, 0, width, height, self._startAngle)
+      path.arcTo(0, 0, width, height, self._startAngle, self._arcWidth)
+
+      if self._style == _PIE:
+         centerX = width  / 2
+         centerY = height / 2
+         path.lineTo(centerX, centerY)
+         path.closeSubpath()
+      elif self._style == _CHORD:
+         path.closeSubpath()
+
+      return path
+
+   def setSize(self, args, responseId):
+      """
+      Overrides _DrawableMirror.setSize.
+      Prefers scaling via QTransform; falls back to rebuilding the path
+      if either current dimension is 0.
+      """
+      width  = args.get('width',  self._width)
+      height = args.get('height', self._height)
+      if width > 0 and height > 0:
+
+         if self._width != 0 and self._height != 0:
+            scaleX    = width  / self._width
+            scaleY    = height / self._height
+            oldPath   = self._qObject.path()
+            oldRect   = oldPath.boundingRect()
+            transform = QtGui.QTransform()
+            transform.translate(-oldRect.x(), -oldRect.y())
+            transform.scale(scaleX, scaleY)
+            transform.translate(oldRect.x(), oldRect.y())
+            path = transform.map(oldPath)
+         else:
+            path = self._buildPath(width, height)
+
+         self._qObject.prepareGeometryChange()
+         self._qObject.setPath(path)
+         self._width  = width
+         self._height = height
+
+   def _setArcWidth(self, args, responseId):
+      """
+      Changes the arc's sweep angle and rebuilds the path.
+      'arcWidth' uses Qt's sign convention: negative values sweep clockwise.
+      """
+      self._arcWidth = args.get('arcWidth', self._arcWidth)
+      path = self._buildPath(self._width, self._height)
+      self._qObject.prepareGeometryChange()
+      self._qObject.setPath(path)
+
+
+#######################################################################################
+# LineMirror  —  mirror of gui.py's Line
+#######################################################################################
+
+class LineMirror(_GraphicsMirror):
+   """
+   Mirror of gui.py's Line.  Backed by a QGraphicsLineItem.
+
+   Separated from PolylineMirror because QGraphicsLineItem is simpler and faster
+   than QGraphicsPathItem for a two-point line.  It also has a direct setLine() API
+   which makes setLength support trivial.
+
+   QGraphicsLineItem has no brush, so _applyColor is overridden to skip setBrush().
+
+   Constructor args expected in the 'args' dict:
+     x, y          — pre-rotation top-left corner (pre-processed by gui.py)
+     width, height — dimensions
+     xPoints       — [x1, x2] endpoint x-coords, relative to the corner (pre-processed by gui.py)
+     yPoints       — [y1, y2] endpoint y-coords, relative to the corner (pre-processed by gui.py)
+     color         — [r, g, b, a]
+     thickness     — int (line width)
+     rotation      — degrees (CCW visual, 0 = no rotation)
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, args, guiRenderer)
+
+      rotation = args.get('rotation', 0)
+
+      self._localCornerX = args.get('x',      0)
+      self._localCornerY = args.get('y',      0)
+      self._width        = args.get('width',  100)
+      self._height       = args.get('height', 100)
+
+      self._xPoints = args.get('xPoints', [0, self._width])
+      self._yPoints = args.get('yPoints', [0, self._height])
+
+      # store original size (for rebuilding flattened geometry)
+      self._originalWidth  = self._width
+      self._originalHeight = self._height
+
+      innerX1, innerX2 = self._xPoints
+      innerY1, innerY2 = self._yPoints
+
+      # create the backing Qt item
+      self._qObject = QtWidgets.QGraphicsLineItem(innerX1, innerY1, innerX2, innerY2)
+
+      # push initial values to Qt
+      self._qObject.setPos(self._localCornerX, self._localCornerY)
+      self._applyColor()
+      self._applyThickness()
+
+      # add Line-specific command handler
+      self._commandHandlers['setLine'] = self._setLine
+
+      if rotation != 0:
+         self.setRotation({'rotation': rotation}, responseId=None)
+
+   def _applyColor(self):
+      """
+      Overrides _GraphicsMirror._applyColor.
+      QGraphicsLineItem has no brush, so we only set the pen color.
+      """
+      r, g, b, a = self._color
+      qColor = QtGui.QColor(r, g, b, a)
+      qPen   = self._qObject.pen()
+      qPen.setColor(qColor)
+      self._qObject.setPen(qPen)
+
+   def _setLine(self, args, responseId):
+      """
+      Sets the line's endpoints directly.  Used by gui.py's setLength().
+      Takes global coordinates x1, y1, x2, y2 — recalculates corner position
+      and local endpoints.
+      """
+      x1 = args.get('x1', 0)
+      y1 = args.get('y1', 0)
+      x2 = args.get('x2', 0)
+      y2 = args.get('y2', 0)
+
+      self._localCornerX = min(x1, x2)
+      self._localCornerY = min(y1, y2)
+      self._width        = abs(x2 - x1)
+      self._height       = abs(y2 - y1)
+
+      innerX1 = x1 - self._localCornerX
+      innerY1 = y1 - self._localCornerY
+      innerX2 = x2 - self._localCornerX
+      innerY2 = y2 - self._localCornerY
+
+      self._xPoints = [innerX1, innerX2]
+      self._yPoints = [innerY1, innerY2]
+
+      self._qObject.prepareGeometryChange()
+      self._qObject.setLine(innerX1, innerY1, innerX2, innerY2)
+      self.setPosition({'x': self._localCornerX, 'y': self._localCornerY}, responseId=None)
+
+   def setSize(self, args, responseId):
+      """
+      Overrides _DrawableMirror.setSize.
+      Scales the line endpoints proportionally to the new dimensions.
+      """
+      self._width  = args.get('width',  self._width)
+      self._height = args.get('height', self._height)
+
+      # rebuild from original points, scaled to new dimensions
+      scaleX = 0 if (self._originalWidth  == 0) else (self._width  / self._originalWidth)
+      scaleY = 0 if (self._originalHeight == 0) else (self._height / self._originalHeight)
+      scaledX = [x * scaleX for x in self._xPoints]
+      scaledY = [y * scaleY for y in self._yPoints]
+
+      self._qObject.prepareGeometryChange()
+      self._qObject.setLine(scaledX[0], scaledY[0], scaledX[1], scaledY[1])
+
+
+#######################################################################################
+# PolylineMirror  —  mirror of gui.py's Polyline
+#######################################################################################
+
+class PolylineMirror(_GraphicsMirror):
+   """
+   Mirror of gui.py's Polyline.  Backed by a QGraphicsPathItem.
+
+   Constructor args expected in the 'args' dict:
+     x, y          — pre-rotation top-left corner (pre-processed by gui.py)
+     width, height — dimensions
+     xPoints       — x-coordinates relative to the corner (pre-processed by gui.py)
+     yPoints       — y-coordinates relative to the corner (pre-processed by gui.py)
+     color         — [r, g, b, a]
+     thickness     — int (line width)
+     rotation      — degrees (CCW visual, 0 = no rotation)
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, args, guiRenderer)
+
+      rotation = args.get('rotation', 0)
+
+      self._localCornerX = args.get('x',      0)
+      self._localCornerY = args.get('y',      0)
+      self._width        = args.get('width',  100)
+      self._height       = args.get('height', 100)
+
+      self._xPoints = args.get('xPoints', [0, 100])
+      self._yPoints = args.get('yPoints', [0, 100])
+
+      # store original size (for rebuilding flattened geometry)
+      self._originalWidth  = self._width
+      self._originalHeight = self._height
+
+      # build initial path
+      path = self._buildPath(self._xPoints, self._yPoints)
+      self._qObject = QtWidgets.QGraphicsPathItem(path)
+
+      # push initial values to Qt
+      self._qObject.setPos(self._localCornerX, self._localCornerY)
+      self._applyColor()
+      self._applyThickness()
+
+      if rotation != 0:
+         self.setRotation({'rotation': rotation}, responseId=None)
+
+   def _buildPath(self, xPoints, yPoints):
+      """
+      Builds a QPainterPath from local coordinate lists.
+      """
+      path = QtGui.QPainterPath()
+      path.moveTo(xPoints[0], yPoints[0])
+      for i in range(1, len(xPoints)):
+         path.lineTo(xPoints[i], yPoints[i])
+      return path
+
+   def setSize(self, args, responseId):
+      """
+      Overrides _DrawableMirror.setSize.
+      Prefers scaling via QTransform; falls back to rebuilding the path
+      from original points if either current dimension is 0.
+      """
+      width  = args.get('width',  self._width)
+      height = args.get('height', self._height)
+
+      if self._width != 0 and self._height != 0:
+         scaleX    = width  / self._width
+         scaleY    = height / self._height
+         oldPath   = self._qObject.path()
+         oldRect   = oldPath.boundingRect()
+         transform = QtGui.QTransform()
+         transform.translate(-oldRect.x(), -oldRect.y())
+         transform.scale(scaleX, scaleY)
+         transform.translate(oldRect.x(), oldRect.y())
+         path = transform.map(oldPath)
+      else:
+         # rebuild from original points, scaled to new dimensions
+         scaleX = 0 if (self._originalWidth  == 0) else (width  / self._originalWidth)
+         scaleY = 0 if (self._originalHeight == 0) else (height / self._originalHeight)
+         scaledX = [x * scaleX for x in self._xPoints]
+         scaledY = [y * scaleY for y in self._yPoints]
+         path = self._buildPath(scaledX, scaledY)
+
+      self._qObject.prepareGeometryChange()
+      self._qObject.setPath(path)
+      self._width  = width
+      self._height = height
+
+
+#######################################################################################
+# PolygonMirror  —  mirror of gui.py's Polygon
+#######################################################################################
+
+class PolygonMirror(_GraphicsMirror):
+   """
+   Mirror of gui.py's Polygon.  Backed by a QGraphicsPolygonItem.
+
+   Constructor args expected in the 'args' dict:
+     x, y          — pre-rotation top-left corner (pre-processed by gui.py)
+     width, height — dimensions
+     xPoints       — x-coordinates relative to the corner (pre-processed by gui.py)
+     yPoints       — y-coordinates relative to the corner (pre-processed by gui.py)
+     color         — [r, g, b, a]
+     fill          — bool
+     thickness     — int (line width)
+     rotation      — degrees (CCW visual, 0 = no rotation)
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, args, guiRenderer)
+
+      rotation = args.get('rotation', 0)
+
+      self._localCornerX = args.get('x',      0)
+      self._localCornerY = args.get('y',      0)
+      self._width        = args.get('width',  100)
+      self._height       = args.get('height', 100)
+
+      self._xPoints = args.get('xPoints', [0, 100, 50])
+      self._yPoints = args.get('yPoints', [0,   0, 100])
+
+      # store original size (for rebuilding flattened geometry)
+      self._originalWidth  = self._width
+      self._originalHeight = self._height
+
+      # build initial polygon
+      polygon = self._buildPolygon(self._xPoints, self._yPoints)
+      self._qObject = QtWidgets.QGraphicsPolygonItem(polygon)
+
+      # push initial values to Qt
+      self._qObject.setPos(self._localCornerX, self._localCornerY)
+      self._applyColor()
+      self._applyThickness()
+
+      if rotation != 0:
+         self.setRotation({"rotation": rotation}, responseId=None)
+
+   def _buildPolygon(self, xPoints, yPoints):
+      """
+      Builds a QPolygonF from local coordinate lists.
+      """
+      polygon = QtGui.QPolygonF()
+      for i in range(len(xPoints)):
+         polygon.append(QtCore.QPointF(xPoints[i], yPoints[i]))
+      return polygon
+
+   def setSize(self, args, responseId):
+      """
+      Overrides _DrawableMirror.setSize.
+      Prefers scaling via QTransform; falls back to rebuilding the polygon
+      from original points if either current dimension is 0.
+      """
+      width  = args.get("width",  self._width)
+      height = args.get("height", self._height)
+
+      if self._width != 0 and self._height != 0:
+         scaleX     = width  / self._width
+         scaleY     = height / self._height
+         oldPolygon = self._qObject.polygon()
+         oldRect    = oldPolygon.boundingRect()
+         transform  = QtGui.QTransform()
+         transform.translate(-oldRect.x(), -oldRect.y())
+         transform.scale(scaleX, scaleY)
+         transform.translate(oldRect.x(), oldRect.y())
+         polygon = transform.map(oldPolygon)
+      else:
+         # rebuild from original points, scaled to new dimensions
+         scaleX  = 0 if (self._originalWidth  == 0) else (width  / self._originalWidth)
+         scaleY  = 0 if (self._originalHeight == 0) else (height / self._originalHeight)
+         scaledX = [x * scaleX for x in self._xPoints]
+         scaledY = [y * scaleY for y in self._yPoints]
+         polygon = self._buildPolygon(scaledX, scaledY)
+
+      self._qObject.prepareGeometryChange()
+      self._qObject.setPolygon(polygon)
+      self._width  = width
+      self._height = height
+
+
+#######################################################################################
+# IconMirror  —  mirror of gui.py's Icon
+#######################################################################################
+
+class IconMirror(_GraphicsMirror):
+   """
+   Mirror of gui.py's Icon.  Backed by a QGraphicsPixmapItem.
+
+   Unlike other mirrors, Icon does most of its work on the Qt side because pixel
+   operations must happen where the QPixmap lives.  This means IconMirror has
+   getters (getPixel, getPixels) that send responses back through the pipe.
+
+   Extends _GraphicsMirror for rotation support, but overrides _applyColor and
+   _applyThickness as no-ops because QGraphicsPixmapItem has no pen or brush.
+
+   Constructor args expected in the 'args' dict:
+     filename   — path to image file (str)
+     width      — optional target width (int or None)
+     height     — optional target height (int or None)
+     rotation   — degrees (CCW)
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, args, guiRenderer)
+
+      filename = args.get('filename', '')
+      width    = args.get('width')
+      height   = args.get('height')
+      rotation = args.get('rotation')
+
+      # build pixmap
+      pixmap = QtGui.QPixmap(filename)
+
+      if pixmap.isNull():
+         # file failed to load — create blank pixmap
+         if width is None:
+            width = 600
+         if height is None:
+            height = 400
+         pixmap = QtGui.QPixmap(width, height)
+
+      # resolve width/height from pixmap if not specified
+      if width is None and height is None:
+         width  = pixmap.width()
+         height = pixmap.height()
+      elif width is None:
+         width = int(pixmap.width() * (height / pixmap.height()))
+      elif height is None:
+         height = int(pixmap.height() * (width / pixmap.width()))
+
+      scaledPixmap = pixmap.scaled(width, height)
+
+      self._qObject = QtWidgets.QGraphicsPixmapItem(scaledPixmap)
+      self._pixmap  = pixmap   # original (unscaled) pixmap for quality rescaling
+
+      # initialize geometry state
+      self._localCornerX = 0
+      self._localCornerY = 0
+      self._width        = width
+      self._height       = height
+
+      if rotation != 0:
+         self.setRotation({'rotation': rotation}, responseId=None)
+
+      # add Icon-specific command handlers
+      self._commandHandlers.update({
+         'crop':      self.crop,
+         'getPixel':  self.getPixel,
+         'setPixel':  self.setPixel,
+         'getPixels': self.getPixels,
+         'setPixels': self.setPixels,
+         'write':     self.write,
+      })
+
+   def _applyColor(self):
+      """No-op — QGraphicsPixmapItem has no pen or brush."""
+      pass
+
+   def _applyThickness(self):
+      """No-op — QGraphicsPixmapItem has no pen or brush."""
+      pass
+
+   # ── Size ───────────────────────────────────────────────────────────────────
+
+   def setSize(self, args, responseId):
+      """
+      Rescales the pixmap from the original for quality.
+      """
+      width  = args.get('width',  self._width)
+      height = args.get('height', self._height)
+      if width > 0 and height > 0:
+         scaledPixmap = self._pixmap.scaled(int(width), int(height))
+         self._qObject.prepareGeometryChange()
+         self._qObject.setPixmap(scaledPixmap)
+         self._width  = int(width)
+         self._height = int(height)
+
+   # ── Crop ───────────────────────────────────────────────────────────────────
+
+   def crop(self, args, responseId):
+      """
+      Crops the original pixmap, then rescales to the cropped dimensions.
+      """
+      x      = args.get('x', 0)
+      y      = args.get('y', 0)
+      width  = args.get('width',  self._width)
+      height = args.get('height', self._height)
+
+      self._pixmap = self._pixmap.copy(x, y, width, height)
+      scaledPixmap = self._pixmap.scaled(width, height)
+      self._qObject.setPixmap(scaledPixmap)
+      self._width  = width
+      self._height = height
+
+   # ── Pixel getters / setters ────────────────────────────────────────────────
+
+   def getPixel(self, args, responseId):
+      """
+      Returns [r, g, b] for the pixel at (column, row) on the original pixmap.
+      """
+      column = args.get('column', 0)
+      row    = args.get('row', 0)
+      image  = self._pixmap.toImage()
+      color  = image.pixelColor(column, row)
+      self._guiRenderer.sendResponse(responseId, [color.red(), color.green(), color.blue()])
+
+   def setPixel(self, args, responseId):
+      """
+      Sets the pixel at (column, row) to [r, g, b] on the original pixmap,
+      then rescales to current display dimensions.
+      """
+      column    = args.get('column', 0)
+      row       = args.get('row', 0)
+      color     = args.get('color', [0, 0, 0])
+      r, g, b   = color
+      qtColor   = QtGui.QColor(r, g, b, 255)
+
+      image = self._pixmap.toImage()
+      image.setPixelColor(column, row, qtColor)
+      self._pixmap = QtGui.QPixmap(image)
+
+      scaledPixmap = self._pixmap.scaled(self._width, self._height)
+      self._qObject.setPixmap(scaledPixmap)
+
+   def getPixels(self, args, responseId):
+      """
+      Returns all pixels as a 2D list of [r, g, b] values from the original pixmap.
+      """
+      image  = self._pixmap.toImage()
+      image  = image.convertToFormat(QtGui.QImage.Format.Format_RGBA8888)
+      width  = image.width()
+      height = image.height()
+
+      pixels = []
+      for row in range(height):
+         rowPixels = []
+         for col in range(width):
+            color = image.pixelColor(col, row)
+            rowPixels.append([color.red(), color.green(), color.blue()])
+         pixels.append(rowPixels)
+
+      self._guiRenderer.sendResponse(responseId, pixels)
+
+   def setPixels(self, args, responseId):
+      """
+      Sets all pixels from a 2D list of [r, g, b] values.
+      Rebuilds the pixmap and rescales to current display dimensions.
+      """
+      pixels = args.get('pixels', [])
+      if not pixels:
+         return
+
+      height = len(pixels)
+      width  = len(pixels[0])
+
+      image = QtGui.QImage(width, height, QtGui.QImage.Format.Format_RGBA8888)
+      for row in range(height):
+         for col in range(width):
+            rgb = pixels[row][col]
+            r, g, b = rgb[0], rgb[1], rgb[2]
+            image.setPixelColor(col, row, QtGui.QColor(r, g, b, 255))
+
+      self._pixmap = QtGui.QPixmap(image)
+      scaledPixmap = self._pixmap.scaled(self._width, self._height)
+      self._qObject.setPixmap(scaledPixmap)
+
+   # ── Write ──────────────────────────────────────────────────────────────────
+
+   def write(self, args, responseId):
+      """
+      Saves the icon's original pixmap to a file.
+      Optional width/height args resize the output; omitting one preserves aspect ratio.
+      Sends [success (bool), resolvedPath (str)] back to the parent process.
+      """
+      import os
+      filename = args.get('filename', 'icon.png')
+      width    = args.get('width')
+      height   = args.get('height')
+
+      pixmap = self._pixmap
+
+      if width is not None or height is not None:
+         origW  = pixmap.width()
+         origH  = pixmap.height()
+         width  = int(origW * (height / origH)) if width  is None else int(width)
+         height = int(origH * (width  / origW)) if height is None else int(height)
+         pixmap = pixmap.scaled(width, height,
+                                QtCore.Qt.AspectRatioMode.IgnoreAspectRatio,
+                                QtCore.Qt.TransformationMode.SmoothTransformation)
+
+      success      = pixmap.save(filename)
+      resolvedPath = os.path.abspath(filename)
+      self._guiRenderer.sendResponse(responseId, [success, resolvedPath])
+
+
+#######################################################################################
+# LabelMirror  —  mirror of gui.py's Label
+#######################################################################################
+
+class LabelMirror(_GraphicsMirror):
+   """
+   Mirror of gui.py's Label.  Backed by a QGraphicsItemGroup containing
+   a QGraphicsTextItem (foreground text) and a QGraphicsRectItem (background).
+
+   Overrides _applyColor (text color), _applyThickness (background pen), and
+   _setFill (background visibility) because Label's Qt structure differs from
+   simple shape items.
+
+   Constructor args expected in the 'args' dict:
+     text             — string
+     alignment        — int (Qt.AlignmentFlag value: 1=Left, 132=Center, 2=Right)
+     textColor        — [r, g, b, a]
+     backgroundColor  — [r, g, b, a]
+     font             — None or [name, [weight, italic], size]
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, args, guiRenderer)
+
+      text            = str(args.get('text', ''))
+      alignment       = args.get('alignment', 1)   # 1 = AlignLeft
+      textColor       = args.get('textColor', [0, 0, 0, 255])
+      backgroundColor = args.get('backgroundColor', [0, 0, 0, 0])
+      font            = args.get('font')
+
+      self._color           = textColor
+      self._backgroundColor = backgroundColor
+
+      # create foreground text
+      self._qTextObject = QtWidgets.QGraphicsTextItem(text)
+      r, g, b, a = textColor
+      self._qTextObject.setDefaultTextColor(QtGui.QColor(r, g, b, a))
+
+      # create background rectangle (matches text bounds)
+      self._qBackgroundObject = QtWidgets.QGraphicsRectItem(
+         self._qTextObject.boundingRect()
+      )
+      r, g, b, a = backgroundColor
+      self._qBackgroundObject.setBrush(QtGui.QColor(r, g, b, a))
+      self._qBackgroundObject.setPen(QtCore.Qt.PenStyle.NoPen)
+
+      # create graphics container (group is the main _qObject)
+      self._qObject = QtWidgets.QGraphicsItemGroup()
+      self._qObject.addToGroup(self._qBackgroundObject)
+      self._qObject.addToGroup(self._qTextObject)
+
+      # initialize geometry from text bounds
+      bounds       = self._qTextObject.boundingRect()
+      self._localCornerX = 0
+      self._localCornerY = 0
+      self._width  = int(bounds.width())
+      self._height = int(bounds.height())
+
+      # apply alignment
+      self._setAlignmentValue(alignment)
+
+      # apply font if provided
+      if font is not None:
+         self._applyFont(font)
+
+      # push initial position
+      self._qObject.setPos(0, 0)
+
+      # add Label-specific command handlers
+      self._commandHandlers.update({
+         'setText':            self.setText,
+         'setBackgroundColor': self.setBackgroundColor,
+         'setAlignment':       self.setAlignment,
+         'setFont':            self.setFont,
+      })
+
+   # ── Overrides ──────────────────────────────────────────────────────────────
+
+   def _applyColor(self):
+      """Sets the text color (not pen/brush — Labels use setDefaultTextColor)."""
+      r, g, b, a = self._color
+      self._qTextObject.setDefaultTextColor(QtGui.QColor(r, g, b, a))
+
+   def _applyThickness(self):
+      """Sets the background rectangle's pen width."""
+      qPen = self._qBackgroundObject.pen()
+      qPen.setWidth(self._thickness)
+      self._qBackgroundObject.setPen(qPen)
+
+   def setFill(self, args, responseId):
+      """Controls background visibility.  When unfilled, background is transparent."""
+      self._fill = bool(args.get('fill', False))
+      if self._fill:
+         r, g, b, a = self._backgroundColor
+         qColor = QtGui.QColor(r, g, b, a)
+      else:
+         qColor = QtGui.QColor(0, 0, 0, 0)
+      self._qBackgroundObject.setBrush(QtGui.QBrush(qColor))
+
+   # ── Text ───────────────────────────────────────────────────────────────────
+
+   def setText(self, args, responseId):
+      """Sets the label's text and updates the background rect to match."""
+      text = str(args.get('text', ''))
+      self._qTextObject.setPlainText(text)
+      self._updateBackground()
+
+   def _updateBackground(self):
+      """Resizes the background rect to match the current text bounds."""
+      bounds = self._qTextObject.boundingRect()
+      self._qBackgroundObject.setRect(bounds)
+      self._width  = int(bounds.width())
+      self._height = int(bounds.height())
+
+   # ── Background color ──────────────────────────────────────────────────────
+
+   def setBackgroundColor(self, args, responseId):
+      """Sets the background rectangle's fill color."""
+      self._backgroundColor = args.get('color', [0, 0, 0, 0])
+      r, g, b, a = self._backgroundColor
+      self._qBackgroundObject.setBrush(QtGui.QColor(r, g, b, a))
+
+   # ── Alignment ──────────────────────────────────────────────────────────────
+
+   def setAlignment(self, args, responseId):
+      """Sets text alignment from an integer Qt.AlignmentFlag value."""
+      alignment = args.get('alignment', 1)
+      self._setAlignmentValue(alignment)
+
+   def _setAlignmentValue(self, alignment):
+      """Applies alignment to the text item's document."""
+      qtFlag      = QtCore.Qt.AlignmentFlag(alignment)
+      document    = self._qTextObject.document()
+      textOption  = document.defaultTextOption()
+      textOption.setAlignment(qtFlag)
+      document.setDefaultTextOption(textOption)
+
+   # ── Font ───────────────────────────────────────────────────────────────────
+
+   def setFont(self, args, responseId):
+      """Sets the text font from [name, [weight, italic], size]."""
+      font = args.get('font')
+      if font is not None:
+         self._applyFont(font)
+         self._updateBackground()
+
+   def _applyFont(self, font):
+      """Constructs a QFont and applies it to the text item."""
+      name, style, size = font
+      weight, italic    = style
+      qFont = QtGui.QFont(name, size)
+      qFont.setWeight(QtGui.QFont.Weight(weight))
+      qFont.setItalic(italic)
+      self._qTextObject.setFont(qFont)
+
+
+#######################################################################################
+# GroupMirror  —  mirror of gui.py's Group
+#######################################################################################
+
+class GroupMirror(_DrawableMirror):
+   """
+   Mirror of gui.py's Group.  Backed by a QGraphicsItemGroup.
+
+   Groups contain other drawable mirrors as children.  Adding a child attaches
+   its _qObject to this group's QGraphicsItemGroup; removing detaches it.
+
+   Group extends _DrawableMirror (not _GraphicsMirror) because gui.py's Group
+   inherits from _Drawable, not _Graphics — it has no color, fill, or thickness.
+
+   Constructor args expected in the 'args' dict:
+     (none — children are added via addChild / addChildOrder commands)
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, guiRenderer)
+
+      self._qObject  = QtWidgets.QGraphicsItemGroup()
+      self._itemList = []
+
+      # initialize geometry
+      self._localCornerX = 0
+      self._localCornerY = 0
+      self._width        = 0
+      self._height       = 0
+
+      self._qObject.setPos(0, 0)
+
+      # add Group-specific command handlers
+      self._commandHandlers.update({
+         'addChild':      self.addChild,
+         'addChildOrder': self.addChildOrder,
+         'removeChild':   self.removeChild,
+         'getOrder':      self.getOrder,
+         'setOrder':      self.setOrder,
+      })
+
+   # ── Child management ───────────────────────────────────────────────────────
+
+   def addChild(self, args, responseId):
+      """Adds a child at the top of the z-order (order = 0)."""
+      itemId          = args.get('itemId')
+      addChildArgs    = {'itemId': itemId, 'order': 0}
+      self.addChildOrder(addChildArgs, responseId=None)
+
+   def addChildOrder(self, args, responseId):
+      """Adds a child at the specified z-order position."""
+      itemId = args.get('itemId')
+      order  = args.get('order', 0)
+
+      item = self._guiRenderer._objectRegistry.get(itemId)
+      if item is None:
+         return
+
+      # remove from this group if already present
+      if item in self._itemList:
+         self._itemList.remove(item)
+         self._qObject.removeFromGroup(item._qObject)
+
+      # clamp order and insert
+      order = max(0, min(len(self._itemList), order))
+      self._itemList.insert(order, item)
+
+      # calculate z-value (same algorithm as DisplayMirror)
+      if order == 0:
+         qZValue = 1.0
+         if len(self._itemList) > 1:
+            neighbor = self._itemList[1]
+            qZValue  = neighbor._qZValue + 1.0
+
+      elif order >= len(self._itemList) - 1:
+         qZValue = 0.0
+         if len(self._itemList) > 1:
+            neighbor = self._itemList[-2]
+            qZValue  = neighbor._qZValue - 1.0
+
+      else:
+         frontNeighbor = self._itemList[order - 1]
+         backNeighbor  = self._itemList[order + 1]
+         qZValue       = (frontNeighbor._qZValue + backNeighbor._qZValue) / 2.0
+
+      item._qZValue = qZValue
+      item._qObject.setZValue(qZValue)
+      self._qObject.addToGroup(item._qObject)
+
+      cacheMode = QtWidgets.QGraphicsItem.CacheMode.DeviceCoordinateCache
+      item._qObject.setCacheMode(cacheMode)
+
+   def removeChild(self, args, responseId):
+      """Removes a child from the group."""
+      itemId = args.get('itemId')
+      item   = self._guiRenderer._objectRegistry.get(itemId)
+      if item is not None and item in self._itemList:
+         self._itemList.remove(item)
+         self._qObject.removeFromGroup(item._qObject)
+
+   def getOrder(self, args, responseId):
+      """Returns the order of a child in the group."""
+      itemId = args.get('itemId')
+      order  = None
+      for i, item in enumerate(self._itemList):
+         if item.objectId == itemId:
+            order = i
+            break
+      self._guiRenderer.sendResponse(responseId, [order])
+
+   def setOrder(self, args, responseId):
+      """Changes a child's z-order by removing and re-adding at the new position."""
+      itemId         = args.get('itemId')
+      order          = args.get('order', 0)
+      addChildArgs   = {'itemId': itemId, 'order': order}
+      self.addChildOrder(addChildArgs, responseId=None)
+
+
+#######################################################################################
+# _ControlMirror  —  base mirror for all Control widgets
+#######################################################################################
+
+class _ControlMirror:
+   """
+   Base class for all Control mirror objects (QWidgets, not QGraphicsItems).
+   Parallel to _DrawableMirror but uses QWidget APIs: .move() for position,
+   .setFixedSize() for dimensions, and stylesheets for color.
+
+   Controls have no hit-testing (contains/intersects/encloses) because QWidgets
+   handle their own input directly.
+
+   Concrete classes must:
+     1. Call super().__init__(objectId, args, guiRenderer) first.
+     2. Create self._qObject (the underlying QWidget).
+   """
+
+   _isControl = True   # tells DisplayMirror to use setParent/show instead of scene.addItem
+
+   def __init__(self, objectId, args, guiRenderer):
+      self.objectId      = objectId
+      self._guiRenderer  = guiRenderer
+      self._qObject      = None     # set by concrete class constructor
+      self._qZValue      = 0.0      # assigned by DisplayMirror._addOrder
+      self._localCornerX = 0
+      self._localCornerY = 0
+      self._width        = 0
+      self._height       = 0
+      self._toolTipText  = None
+
+      self._commandHandlers = {
+         'setPosition':    self.setPosition,
+         'getSize':        self.getSize,
+         'setSize':        self.setSize,
+         'setToolTipText': self.setToolTipText,
+      }
+
+   def handleCommand(self, action, args, responseId):
+      """Dispatches an incoming command to the appropriate handler method."""
+      handler = self._commandHandlers.get(action)
+      if handler is not None:
+         handler(args, responseId)
+
+   # ── Position ───────────────────────────────────────────────────────────────
+
+   def setPosition(self, args, responseId):
+      x = int(args.get('x', self._localCornerX))
+      y = int(args.get('y', self._localCornerY))
+      self._localCornerX = x
+      self._localCornerY = y 
+      self._qObject.move(x, y)
+
+   # ── Size ───────────────────────────────────────────────────────────────────
+
+   def getSize(self, args, responseId):
+      self._guiRenderer.sendResponse(responseId, [self._width, self._height])
+
+   def setSize(self, args, responseId):
+      width  = int(args.get('width',  self._width))
+      height = int(args.get('height', self._height))
+      if width > 0 and height > 0:
+         self._qObject.setFixedSize(width, height)
+         self._width  = width
+         self._height = height
+
+   # ── Tooltip ────────────────────────────────────────────────────────────────
+
+   def setToolTipText(self, args, responseId):
+      text              = args.get('text')
+      self._toolTipText = text
+      self._qObject.setToolTip(text)
+
+   # ── Event helper ───────────────────────────────────────────────────────────
+
+   def _forwardEvent(self, eventType, eventArgs=None):
+      """
+      Checks if the event is registered, and if so, sends it to the parent process.
+      Connected to Qt signals in the concrete class constructor.
+      """
+      isRegistered = (self.objectId, eventType) in self._guiRenderer._registeredEvents
+      if isRegistered:
+         self._guiRenderer.sendEvent(eventType, self.objectId, eventArgs or {})
+
+
+#######################################################################################
+# ButtonMirror  —  mirror of gui.py's Button
+#######################################################################################
+
+class ButtonMirror(_ControlMirror):
+   """
+   Mirror of gui.py's Button.  Backed by a QPushButton.
+
+   Constructor args expected in the 'args' dict:
+     text   — string
+     color  — [r, g, b, a]
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, args, guiRenderer)
+
+      text  = args.get('text', '')
+      color = args.get('color', [211, 211, 211, 255])   # LIGHT_GRAY default
+
+      self._qObject = QtWidgets.QPushButton()
+      self._qObject.setText(text)
+      self._qObject.adjustSize()
+      self._width  = self._qObject.width()
+      self._height = self._qObject.height()
+
+      self._applyColor(color)
+
+      # wire Qt signal → event forwarding
+      self._qObject.clicked.connect(lambda: self._forwardEvent('clicked'))
+
+      self._commandHandlers.update({
+         'setText':  self.setText,
+         'getText':  self.getText,
+         'setColor': self.setColor,
+      })
+
+   def _applyColor(self, color):
+      r, g, b, a = color
+      dr = max(0, int(r * 0.9))
+      dg = max(0, int(g * 0.9))
+      db = max(0, int(b * 0.9))
+      self._qObject.setStyleSheet(
+         f"QPushButton {{ background-color: rgba({r},{g},{b},{a}); color: black; }}"
+         f"QPushButton::pressed {{ background-color: rgba({dr},{dg},{db},{a}); }}"
+      )
+
+   def setColor(self, args, responseId):
+      color = args.get('color', [211, 211, 211, 255])
+      self._applyColor(color)
+
+   def setText(self, args, responseId):
+      text = args.get('text', '')
+      self._qObject.setText(text)
+      self._qObject.adjustSize()
+      self._width  = self._qObject.width()
+      self._height = self._qObject.height()
+
+   def getText(self, args, responseId):
+      self._guiRenderer.sendResponse(responseId, [self._qObject.text()])
+
+
+#######################################################################################
+# CheckBoxMirror  —  mirror of gui.py's CheckBox
+#######################################################################################
+
+class CheckBoxMirror(_ControlMirror):
+   """
+   Mirror of gui.py's CheckBox.  Backed by a QCheckBox.
+
+   Constructor args expected in the 'args' dict:
+     text   — string
+     color  — [r, g, b, a]
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, args, guiRenderer)
+
+      text  = args.get('text', '')
+      color = args.get('color', [0, 0, 0, 0])   # CLEAR default
+
+      self._qObject = QtWidgets.QCheckBox(text)
+      self._qObject.adjustSize()
+      self._width  = self._qObject.width()
+      self._height = self._qObject.height()
+
+      self._applyColor(color)
+
+      self._qObject.stateChanged.connect(
+         lambda state: self._forwardEvent('stateChanged', {'checked': state != 0})
+      )
+
+      self._commandHandlers.update({
+         'setText':    self.setText,
+         'getText':    self.getText,
+         'setColor':   self.setColor,
+         'isChecked':  self.isChecked,
+         'check':      self.check,
+         'uncheck':    self.uncheck,
+      })
+
+   def _applyColor(self, color):
+      r, g, b, a = color
+      self._qObject.setStyleSheet(
+         f"QCheckBox {{ background-color: rgba({r},{g},{b},{a}); color: black; }}"
+      )
+
+   def setColor(self, args, responseId):
+      color = args.get('color', [0, 0, 0, 0])
+      self._applyColor(color)
+
+   def setText(self, args, responseId):
+      text = args.get('text', '')
+      self._qObject.setText(text)
+      self._qObject.adjustSize()
+      self._width  = self._qObject.width()
+      self._height = self._qObject.height()
+
+   def getText(self, args, responseId):
+      self._guiRenderer.sendResponse(responseId, [self._qObject.text()])
+
+   def isChecked(self, args, responseId):
+      self._guiRenderer.sendResponse(responseId, [self._qObject.isChecked()])
+
+   def check(self, args, responseId):
+      self._qObject.setChecked(True)
+
+   def uncheck(self, args, responseId):
+      self._qObject.setChecked(False)
+
+
+#######################################################################################
+# SliderMirror  —  mirror of gui.py's Slider
+#######################################################################################
+
+class SliderMirror(_ControlMirror):
+   """
+   Mirror of gui.py's Slider.  Backed by a QSlider.
+
+   Constructor args expected in the 'args' dict:
+     orientation  — int (1 = Horizontal, 2 = Vertical; matches Qt.Orientation values)
+     minValue     — int
+     maxValue     — int
+     startValue   — int
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, args, guiRenderer)
+
+      orientation = args.get('orientation', 1)   # 1 = Horizontal
+      minValue    = args.get('minValue', 0)
+      maxValue    = args.get('maxValue', 100)
+      startValue  = args.get('startValue')
+
+      if startValue is None:
+         startValue = int((minValue + maxValue) / 2)
+
+      qtOrientation = QtCore.Qt.Orientation(orientation)
+      self._qObject = QtWidgets.QSlider(qtOrientation)
+      self._qObject.setRange(minValue, maxValue)
+      self._qObject.setValue(startValue)
+      self._qObject.adjustSize()
+      self._width  = self._qObject.width()
+      self._height = self._qObject.height()
+
+      # wire Qt signal → event forwarding
+      self._qObject.valueChanged.connect(
+         lambda value: self._forwardEvent('valueChanged', {'value': value})
+      )
+
+      self._commandHandlers.update({
+         'setValue':  self._setValue,
+         'getValue':  self._getValue,
+      })
+
+   def _setValue(self, args, responseId):
+      value = args.get('value', 0)
+      self._qObject.setValue(value)
+
+   def _getValue(self, args, responseId):
+      self._guiRenderer.sendResponse(responseId, [self._qObject.value()])
+
+
+#######################################################################################
+# DropDownListMirror  —  mirror of gui.py's DropDownList
+#######################################################################################
+
+class DropDownListMirror(_ControlMirror):
+   """
+   Mirror of gui.py's DropDownList.  Backed by a QComboBox.
+
+   Constructor args expected in the 'args' dict:
+     items  — list of strings
+     color  — [r, g, b, a]
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, args, guiRenderer)
+
+      items = args.get('items', [])
+      color = args.get('color', [211, 211, 211, 255])   # LIGHT_GRAY default
+
+      self._qObject = QtWidgets.QComboBox()
+      self._qObject.addItems(items)
+      self._qObject.adjustSize()
+      self._width  = self._qObject.width()
+      self._height = self._qObject.height()
+
+      self._applyColor(color)
+
+      # wire Qt signal → event forwarding (sends selected index)
+      self._qObject.activated.connect(
+         lambda index: self._forwardEvent('activated', {'index': index})
+      )
+
+      self._commandHandlers.update({
+         'setColor': self._setColor,
+      })
+
+   def _applyColor(self, color):
+      r, g, b, a = color
+      self._qObject.setStyleSheet(
+         f"QComboBox {{ background-color: rgba({r},{g},{b},{a}); color: black; }}"
+         f"QComboBox QAbstractItemView {{ background-color: rgba({r},{g},{b},{a}); color: black; }}"
+      )
+
+   def _setColor(self, args, responseId):
+      color = args.get('color', [211, 211, 211, 255])
+      self._applyColor(color)
+
+
+#######################################################################################
+# TextFieldMirror  —  mirror of gui.py's TextField
+#######################################################################################
+
+class TextFieldMirror(_ControlMirror):
+   """
+   Mirror of gui.py's TextField.  Backed by a QLineEdit.
+
+   Constructor args expected in the 'args' dict:
+     text    — string
+     width   — int (pre-computed by gui.py from columns + font metrics)
+     height  — int (pre-computed by gui.py)
+     color   — [r, g, b, a]
+     font    — None or [name, [weight, italic], size]
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, args, guiRenderer)
+
+      text   = args.get('text', '')
+      width  = args.get('width')
+      height = args.get('height')
+      color  = args.get('color', [255, 255, 255, 255])   # WHITE default
+      font   = args.get('font')
+
+      self._qObject = QtWidgets.QLineEdit(str(text))
+
+      if font is not None:
+         self._applyFont(font)
+
+      columns = args.get('columns')
+
+      if width is not None and height is not None:
+         self._qObject.setFixedSize(width, height)
+         self._width  = width
+         self._height = height
+      elif columns is not None:
+         fm       = QtGui.QFontMetrics(self._qObject.font())
+         charW    = fm.horizontalAdvance('M')
+         charH    = fm.lineSpacing()
+         margins  = self._qObject.textMargins()
+         hMargin  = margins.left() + margins.right()
+         vMargin  = margins.top()  + margins.bottom()
+         frameOpt = QtWidgets.QStyleOptionFrame()
+         self._qObject.initStyleOption(frameOpt)
+         frame    = self._qObject.style().pixelMetric(
+            QtWidgets.QStyle.PixelMetric.PM_DefaultFrameWidth, frameOpt, self._qObject
+         )
+         w = (charW * columns) + hMargin + (2 * frame)
+         h = charH + vMargin + (2 * frame)
+         self._qObject.setFixedSize(w, h)
+         self._width  = w
+         self._height = h
+      else:
+         self._qObject.adjustSize()
+         self._width  = self._qObject.width()
+         self._height = self._qObject.height()
+
+      self._applyColor(color)
+
+      # wire Qt signal → event forwarding
+      self._qObject.returnPressed.connect(
+         lambda: self._forwardEvent('returnPressed', {'text': self._qObject.text()})
+      )
+
+      self._commandHandlers.update({
+         'setText':  self._setText,
+         'getText':  self._getText,
+         'setColor': self._setColor,
+         'setFont':  self._setFont,
+      })
+
+   def _applyColor(self, color):
+      r, g, b, a = color
+      self._qObject.setStyleSheet(
+         f"QLineEdit {{ background-color: rgba({r},{g},{b},{a}); color: black; }}"
+      )
+
+   def _setColor(self, args, responseId):
+      color = args.get('color', [255, 255, 255, 255])
+      self._applyColor(color)
+
+   def _setText(self, args, responseId):
+      text = args.get('text', '')
+      self._qObject.setText(text)
+
+   def _getText(self, args, responseId):
+      self._guiRenderer.sendResponse(responseId, [self._qObject.text()])
+
+   def _applyFont(self, font):
+      name, style, size = font
+      weight, italic    = style
+      qFont = QtGui.QFont(name, size)
+      qFont.setWeight(QtGui.QFont.Weight(weight))
+      qFont.setItalic(italic)
+      self._qObject.setFont(qFont)
+
+   def _setFont(self, args, responseId):
+      font = args.get('font')
+      if font is not None:
+         self._applyFont(font)
+
+
+#######################################################################################
+# TextAreaMirror  —  mirror of gui.py's TextArea
+#######################################################################################
+
+class TextAreaMirror(_ControlMirror):
+   """
+   Mirror of gui.py's TextArea.  Backed by a QTextEdit.
+
+   Constructor args expected in the 'args' dict:
+     text    — string
+     width   — int (pre-computed by gui.py from columns/rows + font metrics)
+     height  — int (pre-computed by gui.py)
+     color   — [r, g, b, a]
+     font    — None or [name, [weight, italic], size]
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      super().__init__(objectId, args, guiRenderer)
+
+      text   = args.get('text', '')
+      width  = args.get('width')
+      height = args.get('height')
+      color  = args.get('color', [255, 255, 255, 255])   # WHITE default
+      font   = args.get('font')
+
+      columns = args.get('columns')
+      rows    = args.get('rows')
+
+      self._qObject = QtWidgets.QTextEdit(str(text))
+
+      if font is not None:
+         self._applyFont(font)
+
+      if width is not None and height is not None:
+         self._qObject.setFixedSize(width, height)
+         self._width  = width
+         self._height = height
+      elif columns is not None or rows is not None:
+         fm = QtGui.QFontMetrics(self._qObject.font())
+         w  = fm.horizontalAdvance('M') * (columns or 8)
+         h  = fm.lineSpacing()          * (rows    or 5)
+         self._qObject.setFixedSize(w, h)
+         self._width  = w
+         self._height = h
+      else:
+         self._qObject.adjustSize()
+         self._width  = self._qObject.width()
+         self._height = self._qObject.height()
+
+      self._applyColor(color)
+
+      self._commandHandlers.update({
+         'setText':  self._setText,
+         'getText':  self._getText,
+         'setColor': self._setColor,
+         'setFont':  self._setFont,
+      })
+
+   def _applyColor(self, color):
+      r, g, b, a = color
+      self._qObject.setStyleSheet(
+         f"QTextEdit {{ background-color: rgba({r},{g},{b},{a}); color: black; }}"
+      )
+
+   def _setColor(self, args, responseId):
+      color = args.get('color', [255, 255, 255, 255])
+      self._applyColor(color)
+
+   def _setText(self, args, responseId):
+      text = args.get('text', '')
+      self._qObject.setText(text)
+
+   def _getText(self, args, responseId):
+      self._guiRenderer.sendResponse(responseId, [self._qObject.toPlainText()])
+
+   def _applyFont(self, font):
+      name, style, size = font
+      weight, italic    = style
+      qFont = QtGui.QFont(name, size)
+      qFont.setWeight(QtGui.QFont.Weight(weight))
+      qFont.setItalic(italic)
+      self._qObject.setFont(qFont)
+
+   def _setFont(self, args, responseId):
+      font = args.get('font')
+      if font is not None:
+         self._applyFont(font)
+
+#######################################################################################
+# MenuMirror  —  mirror of gui.py's Menu
+#######################################################################################
+
+class MenuMirror:
+   """
+   Mirror of gui.py's Menu class.  Backed by a QMenu.
+
+   Menus are not placed on a Display via add() — they are attached to a
+   Display's menu bar (addMenu command) or used as a right-click context menu
+   (addPopupMenu command).
+
+   Constructor args expected in the 'args' dict:
+     title — string
+
+   Item callbacks are routed back to gui.py via a single 'itemTriggered' event
+   carrying {'itemIndex': int}.  gui.py maps the index to the per-item callback.
+   """
+
+   def __init__(self, objectId, args, guiRenderer):
+      self.objectId     = objectId
+      self._guiRenderer = guiRenderer
+
+      title       = args.get('title', '')
+      self._qMenu = QtWidgets.QMenu(title)
+
+      self._commandHandlers = {
+         'addItem':      self._addItem,
+         'addSeparator': self._addSeparator,
+         'addSubmenu':   self._addSubmenu,
+         'enable':       self._enable,
+         'disable':      self._disable,
+      }
+
+   def handleCommand(self, action, args, responseId):
+      handler = self._commandHandlers.get(action)
+      if handler is not None:
+         handler(args, responseId)
+
+   def _addItem(self, args, responseId):
+      text      = args.get('text', '')
+      itemIndex = args.get('itemIndex', 0)
+      qAction   = QtGui.QAction(text, self._qMenu)
+      qAction.triggered.connect(
+         lambda checked=False, idx=itemIndex: self._onItemTriggered(idx)
+      )
+      self._qMenu.addAction(qAction)
+
+   def _onItemTriggered(self, itemIndex):
+      isRegistered = (self.objectId, 'itemTriggered') in self._guiRenderer._registeredEvents
+      if isRegistered:
+         self._guiRenderer.sendEvent('itemTriggered', self.objectId, {'itemIndex': itemIndex})
+
+   def _addSeparator(self, args, responseId):
+      self._qMenu.addSeparator()
+
+   def _addSubmenu(self, args, responseId):
+      submenuId = args.get('submenuId')
+      submenu   = self._guiRenderer._objectRegistry.get(submenuId)
+      if submenu is not None:
+         self._qMenu.addMenu(submenu._qMenu)
+
+   def _enable(self, args, responseId):
+      self._qMenu.setEnabled(True)
+
+   def _disable(self, args, responseId):
+      self._qMenu.setEnabled(False)