Dui

dui

Declarative UI packages for deux (.dui).

Load SVG + YAML packages and use them as touchscreen cards or physical keys without writing any Python rendering code.

Examples:

::

from deux import DuiCard, DuiKey

# Resolve by name — uses the built-in DUI repository
card = DuiCard("DashboardCard")
key  = DuiKey("IconKey")
key.set("label", "Power")

@card.on("toggle_play_pause")
async def handle():
    ...

# Add a custom search path for your own packages
from deux import add_dui_path
add_dui_path("~/my-dui-packages")

VALID_CATEGORIES module-attribute

VALID_CATEGORIES = frozenset({'media', 'productivity', 'system', 'gaming', 'social', 'development', 'utilities', 'streaming', 'home-automation', 'communication'})

Controlled vocabulary for the category manifest field.

SpinnerAnimator

Drive frame-by-frame spinner animation on an asyncio event loop.

The animator cycles through pre-rendered frames at a fixed interval, pushing each frame to the device via the provided push_fn.

Parameters:

Name	Type	Description	Default
frames	list[bytes]	List of encoded image bytes (one per frame).	required
interval_ms	int	Milliseconds between frame updates.	required
push_fn	PushFn	Async callable (frame_bytes) -> None that sends a frame to the hardware.	required

Source code in src/deux/dui/animator.py

class SpinnerAnimator:
    """Drive frame-by-frame spinner animation on an asyncio event loop.

    The animator cycles through pre-rendered frames at a fixed interval,
    pushing each frame to the device via the provided *push_fn*.

    Parameters
    ----------
    frames
        List of encoded image bytes (one per frame).
    interval_ms
        Milliseconds between frame updates.
    push_fn
        Async callable ``(frame_bytes) -> None`` that sends a frame
        to the hardware.
    """

    def __init__(
        self,
        frames: list[bytes],
        interval_ms: int,
        push_fn: PushFn,
    ) -> None:
        if not frames:
            raise ValueError("frames must not be empty")
        self._frames = frames
        self._interval = interval_ms / 1000.0
        self._push_fn = push_fn
        self._task: asyncio.Task[None] | None = None
        self._running = False

    @property
    def is_running(self) -> bool:
        """Whether the animation is currently playing."""
        return self._running

    async def start(self) -> None:
        """Begin the animation loop.

        If already running, this is a no-op.
        """
        if self._running:
            return
        self._running = True
        self._task = asyncio.create_task(self._loop(), name="deux-spinner")

    async def stop(self) -> None:
        """Stop the animation loop.

        Cancels the running task and waits for it to finish.
        """
        if not self._running:
            return
        self._running = False
        if self._task is not None and not self._task.done():
            self._task.cancel()
            with suppress(asyncio.CancelledError):
                await self._task
            self._task = None

    async def _loop(self) -> None:
        """Cycle through frames at the configured interval.

        The loop terminates silently if a frame push raises
        :class:`DeviceUnavailable`, since further pushes cannot
        succeed until the device reconnects and the spinner is
        restarted by application code.  Other exceptions are
        logged per frame so a transient hiccup does not kill
        the animation.
        """
        idx = 0
        n = len(self._frames)
        try:
            while self._running:
                frame = self._frames[idx % n]
                try:
                    await self._push_fn(frame)
                except DeviceUnavailable as exc:
                    logger.debug(
                        "Spinner stopping: device unavailable (%s)", exc
                    )
                    self._running = False
                    break
                except Exception:
                    logger.exception("Error pushing spinner frame")
                idx += 1
                await asyncio.sleep(self._interval)
        except asyncio.CancelledError:
            pass

is_running property

is_running: bool

Whether the animation is currently playing.

start async

start() -> None

Begin the animation loop.

If already running, this is a no-op.

Source code in src/deux/dui/animator.py

async def start(self) -> None:
    """Begin the animation loop.

    If already running, this is a no-op.
    """
    if self._running:
        return
    self._running = True
    self._task = asyncio.create_task(self._loop(), name="deux-spinner")

stop async

stop() -> None

Stop the animation loop.

Cancels the running task and waits for it to finish.

Source code in src/deux/dui/animator.py

async def stop(self) -> None:
    """Stop the animation loop.

    Cancels the running task and waits for it to finish.
    """
    if not self._running:
        return
    self._running = False
    if self._task is not None and not self._task.done():
        self._task.cancel()
        with suppress(asyncio.CancelledError):
            await self._task
        self._task = None

DuiCard

Bases: BindingMixin, Card

A touchscreen card whose layout and events are defined by a .dui package.

Instead of writing a Python class with imperative Pillow rendering, you describe the UI in an SVG layout and a YAML manifest. The card loads the package, lets you set binding values, and renders the SVG into a PIL Image for the Stream Deck touchscreen.

Examples:

::

from deux import DuiCard

# Resolve by name from the DUI repository
card = DuiCard("AudioCard")
card.set("artist", "Ash Walker")

@card.on("toggle_play_pause")
async def handle():
    ...

You can also pass a pre-loaded :class:~deux.dui.schema.PackageSpec directly::

from deux.dui import load_package, DuiCard

spec = load_package("./AudioCard.dui")
card = DuiCard(spec)

The card index is assigned automatically when you install the card on a screen with :meth:~deux.ui.screen.Screen.set_card.

Source code in src/deux/dui/card.py

class DuiCard(BindingMixin, Card):
    """A touchscreen card whose layout and events are defined by a .dui package.

    Instead of writing a Python class with imperative Pillow rendering,
    you describe the UI in an SVG layout and a YAML manifest.  The card
    loads the package, lets you set binding values, and renders the SVG
    into a PIL Image for the Stream Deck touchscreen.

    Examples
    --------
    ::

        from deux import DuiCard

        # Resolve by name from the DUI repository
        card = DuiCard("AudioCard")
        card.set("artist", "Ash Walker")

        @card.on("toggle_play_pause")
        async def handle():
            ...

    You can also pass a pre-loaded :class:`~deux.dui.schema.PackageSpec`
    directly::

        from deux.dui import load_package, DuiCard

        spec = load_package("./AudioCard.dui")
        card = DuiCard(spec)

    The card index is assigned automatically when you install the card
    on a screen with :meth:`~deux.ui.screen.Screen.set_card`.
    """

    def __init__(self, spec: PackageSpec | str) -> None:
        """Construct a DUI-backed touchscreen card.

        Parameters
        ----------
        spec : PackageSpec or str
            Either a pre-validated
            :class:`~deux.dui.schema.PackageSpec`, or a package name
            (for example ``"DashboardCard"``) to resolve from the DUI
            repository.  String resolution is deferred to
            :func:`~deux.dui.repository.resolve_dui` at call time so
            tests that monkeypatch that symbol behave correctly.

        Raises
        ------
        deux.dui.repository.PackageError
            If *spec* is a string and no matching package is found in
            any registered search path.

        Notes
        -----
        Construction performs no rendering and no device I/O.  The
        underlying :class:`~deux.dui.svg_renderer.SvgRenderer` and
        :class:`~deux.dui.events.EventMap` are built eagerly from
        *spec*; binding values, push callbacks, and background tiles
        are configured later via the corresponding setters.
        """
        if isinstance(spec, str):
            # Inline import: keeps the lookup go through repository.resolve_dui
            # at call time so monkeypatching that symbol in tests works.
            from .repository import resolve_dui  # noqa: PLC0415

            spec = resolve_dui(spec)
        super().__init__()
        self._spec = spec
        self._renderer = SvgRenderer(spec)
        self._events = EventMap(spec.events, spec.regions)
        self._subscriptions: list[tuple[AsyncEvent, AsyncHandler]] = []
        self._busy = False
        self._animator: SpinnerAnimator | None = None
        self._spinner_frames: SpinnerFrames | None = None
        self._push_fn: PushFn | None = None
        self._panel_size: tuple[int, int] | None = None
        self._bg_tile: bytes | None = None
        self._bg_svg_root: ET.Element | None = None
        self._card_index: int | None = None

    @property
    def spec(self) -> PackageSpec:
        """The package specification backing this card."""
        return self._spec

    @property
    def is_busy(self) -> bool:
        """Whether a busy-guarded handler is currently executing."""
        return self._busy

    @property
    def is_animating(self) -> bool:
        """Whether a spinner animation is currently running."""
        return self._animator is not None and self._animator.is_running

    def set_push_fn(self, push_fn: PushFn, panel_size: tuple[int, int]) -> None:
        """Set the async function used to push animation frames to the device.

        This must be called before spinner animations can play.
        Typically set by :class:`~deux.runtime.deck.Deck`.

        Parameters
        ----------
        push_fn
            Async callable ``(frame_bytes) -> None``.
        panel_size
            ``(width, height)`` of the touchscreen panel this card occupies,
            used to size spinner frames.
        """
        self._push_fn = push_fn
        self._panel_size = panel_size

    def set_bg_tile(self, tile: bytes | None) -> None:
        """Set the background tile for compositing spinner frames.

        When a touchstrip background SVG is active, the corresponding
        pre-sliced tile (PNG bytes) is passed here so that spinner
        animations can composite each frame onto the background.

        Parameters
        ----------
        tile
            PNG-encoded background tile bytes, or ``None`` to clear.
        """
        self._bg_tile = tile

    def set_background_layer(
        self,
        bg_root: ET.Element,
        card_index: int,
        panel_width: int,
        panel_height: int,
    ) -> None:
        """Set a background SVG layer underneath the card content.

        The background SVG's ``viewBox`` is sliced to the region for
        *card_index* and composed as a layer beneath the card's own
        SVG.  The composed tree is cached so subsequent renders only
        need to apply bindings and rasterise.

        Parameters
        ----------
        bg_root : ET.Element
            The full-width background ``<svg>`` root element.
        card_index : int
            Zero-based panel index.
        panel_width : int
            Width of a single panel in pixels.
        panel_height : int
            Height of a single panel in pixels.
        """
        self._bg_svg_root = bg_root
        self._card_index = card_index
        self._renderer.set_base_layer(bg_root, card_index, panel_width, panel_height)
        self._renderer.set_target_size(panel_width, panel_height)

    def clear_background_layer(self) -> None:
        """Remove the background layer and revert to the card's own SVG."""
        self._bg_svg_root = None
        self._card_index = None
        self._renderer.clear_base_layer()

    def render_bytes(
        self,
        *,
        panel_width: int,
        panel_height: int,
        image_format: str = "JPEG",
        background: str = "black",
    ) -> bytes:
        """Render the card directly to encoded image bytes.

        Uses the SVG-native pipeline: background compositing happens
        at the SVG level (if a background layer is set), dimensions are
        set for vector scaling, and the output is rasterised directly
        to the requested format.

        Parameters
        ----------
        panel_width : int
            Target panel width in pixels.
        panel_height : int
            Target panel height in pixels.
        image_format : str, default="JPEG"
            Image encoding format (``"JPEG"`` or ``"BMP"``).
        background : str, default="black"
            Fallback background colour (used when no background SVG
            layer is set).

        Returns
        -------
        bytes
            Encoded image bytes ready to send to the device.
        """
        self._renderer.set_target_size(panel_width, panel_height)
        fmt = image_format.upper()
        out_fmt = "jpeg" if fmt == "JPEG" else "bmp"
        # Only inject a solid background if no SVG background layer is set.
        bg = background if self._bg_svg_root is None else None
        return self._renderer.render_bytes(
            output_format=out_fmt,
            background=bg,
        )

    def render_panel_bytes(
        self,
        *,
        metrics: RenderMetrics,
        card_index: int,
        bg_tile: bytes | None,
        background: str = "black",
        image_format: str = "JPEG",
    ) -> bytes:
        """Render the card to encoded image bytes using the SVG-native pipeline.

        Overrides the base :meth:`Card.render_panel_bytes` to use
        SVG-level background compositing and direct rasterisation,
        avoiding the legacy Pillow compositing path entirely.

        Parameters
        ----------
        metrics : RenderMetrics
            Device metrics (panel dimensions, etc.).
        card_index : int
            The zero-based position of this card on the touch strip.
        bg_tile : Image.Image or None
            Cropped background tile for this card's panel, or ``None``.
        background : str, default="black"
            Fallback background colour.
        image_format : str, default="JPEG"
            Image encoding format (``"JPEG"`` or ``"BMP"``).

        Returns
        -------
        bytes
            Encoded image bytes ready to send to the device.
        """
        panel_bytes = self.render_bytes(
            panel_width=metrics.panel_width,
            panel_height=metrics.panel_height,
            image_format=image_format,
            background=background,
        )

        self.mark_clean()

        return panel_bytes

    def set(self, name: str, value: Any) -> DuiCard:
        """Set a binding value.  Marks the card dirty if changed.

        Parameters
        ----------
        name
            Binding name as defined in the manifest.
        value
            New value (type depends on binding kind).

        Returns
        -------
        DuiCard
            self, for method chaining.

        Raises
        ------
        KeyError
            If *name* is not a known binding.
        """
        if self._renderer.set(name, value):
            self.mark_dirty()
        return self

    def set_many(self, **kwargs: Any) -> DuiCard:
        """Set multiple binding values at once.

        Returns
        -------
        DuiCard
            self, for method chaining.
        """
        if self._renderer.set_many(**kwargs):
            self.mark_dirty()
        return self

    def get(self, name: str) -> Any:
        """Get the current value of a binding.

        Raises
        ------
        KeyError
            If *name* is not a known binding.
        """
        return self._renderer.get(name)

    def collect_icon_names(self) -> builtins.set[str]:
        """Return all Iconify icon identifiers needed by this card.

        Returns
        -------
        set[str]
            A set of ``"prefix:icon"`` strings referenced by the card's
            bindings (defaults and current values).
        """
        return self._renderer.collect_icon_names()

    def set_rendering_context(self, ctx: RenderingContext | None) -> None:
        """Set the explicit rendering context for this card.

        Parameters
        ----------
        ctx : RenderingContext or None
            The rendering context to apply, or ``None`` to revert to
            module-level defaults.
        """
        self._renderer.set_rendering_context(ctx)

    def set_range(
        self, name: str, value: float, *, min_val: float = 0, max_val: float = 1
    ) -> DuiCard:
        """Set a range/slider binding using a domain-scale value.

        Normalises *value* from ``[min_val, max_val]`` to ``[0.0, 1.0]``
        and delegates to :meth:`set`.

        Parameters
        ----------
        name
            Binding name (must be a ``range`` or ``slider`` binding).
        value
            Value in domain units (e.g. 0–100 for a percentage).
        min_val
            Lower bound of the domain range.
        max_val
            Upper bound of the domain range.

        Returns
        -------
        DuiCard
            self, for method chaining.

        Raises
        ------
        KeyError
            If *name* is not a known binding.
        ValueError
            If *min_val* equals *max_val*.
        """
        if min_val == max_val:
            raise ValueError("min_val and max_val must not be equal")
        clamped = max(min_val, min(max_val, value))
        normalised = (clamped - min_val) / (max_val - min_val)
        return self.set(name, normalised)

    def adjust_range(
        self, name: str, delta: float, *, min_val: float = 0, max_val: float = 1
    ) -> float:
        """Adjust a range/slider binding by *delta* domain-scale units.

        Reads the current normalised value, denormalises it, adds *delta*,
        clamps, re-normalises, and calls :meth:`set`.

        Parameters
        ----------
        name
            Binding name (must be a ``range`` or ``slider`` binding).
        delta
            Amount to add in domain units (negative to decrease).
        min_val
            Lower bound of the domain range.
        max_val
            Upper bound of the domain range.

        Returns
        -------
        float
            The new value in domain units (clamped to
            ``[min_val, max_val]``), so callers can use it for display
            without back-computing.

        Raises
        ------
        KeyError
            If *name* is not a known binding.
        ValueError
            If *min_val* equals *max_val*.
        """
        if min_val == max_val:
            raise ValueError("min_val and max_val must not be equal")
        current_norm = float(self.get(name) or 0.0)
        current_domain = min_val + current_norm * (max_val - min_val)
        new_domain = max(min_val, min(max_val, current_domain + delta))
        normalised = (new_domain - min_val) / (max_val - min_val)
        self.set(name, normalised)
        return new_domain

    def get_range(
        self, name: str, *, min_val: float = 0, max_val: float = 1
    ) -> float:
        """Get a range/slider binding denormalised to domain units.

        Parameters
        ----------
        name
            Binding name.
        min_val
            Lower bound of the domain range.
        max_val
            Upper bound of the domain range.

        Returns
        -------
        float
            The current value in domain units.

        Raises
        ------
        KeyError
            If *name* is not a known binding.
        ValueError
            If *min_val* equals *max_val*.
        """
        if min_val == max_val:
            raise ValueError("min_val and max_val must not be equal")
        current_norm = float(self.get(name) or 0.0)
        return min_val + current_norm * (max_val - min_val)


    def render(self) -> Image.Image:
        """Render the SVG layout with current bindings to a PIL Image.

        Returns
        -------
        Image.Image
            A panel-sized RGB :class:`~PIL.Image.Image` (sized from the
            ``.dui`` SVG's intrinsic dimensions).
        """
        return self._renderer.render()

    async def prepare_assets(self) -> None:
        """No-op — .dui cards manage their own assets via the SVG."""

    def handle_encoder_turn(self, direction: int) -> None:
        """Route encoder turn through the event map."""
        handler = self._events.handle_encoder_turn(direction)
        if handler is not None:
            self.queue_pending_callback(handler, (direction,))

    def handle_encoder_press(self) -> None:
        """Route encoder press through the event map."""
        for handler in self._events.handle_encoder_press():
            self.queue_pending_callback(handler, ())

    def handle_encoder_release(self) -> None:
        """Route encoder release through the event map."""
        for handler in self._events.handle_encoder_release():
            self.queue_pending_callback(handler, ())

    async def dispatch_touch(self, event: TouchEvent) -> None:
        """Dispatch touch events through regions and the event map.

        Falls back to the base Card touch handlers (on_tap, etc.)
        if the event map doesn't handle the event.
        """
        handler = self._events.handle_touch(event.event_type, event.x, event.y)
        if handler is not None:
            await handler()
        else:
            await super().dispatch_touch(event)

    async def start_busy(self) -> None:
        """Enter the busy state and start the spinner animation.

        While busy, the card suppresses further ``start_busy()`` calls.
        The spinner keeps running until :meth:`finish_busy` is called.

        If no spinner is configured in the manifest the busy flag is
        still set (suppressing duplicate calls) but no animation plays.
        """
        if self._busy:
            return
        self._busy = True
        await self._start_spinner()

    async def finish_busy(self) -> None:
        """Stop the spinner and exit the busy state.

        Call this from your application code when the asynchronous
        work is truly complete (e.g. after receiving a state update
        from an external system).

        If the card is not currently busy this is a no-op.
        """
        if not self._busy:
            return
        await self._stop_spinner()
        self._busy = False
        self.mark_dirty()

    async def _start_spinner(self) -> None:
        """Start the spinner animation if configured."""
        if (
            self._spec.spinner is None
            or self._push_fn is None
            or self._panel_size is None
        ):
            return

        width, height = self._panel_size
        rendered_svg = self._renderer.render_svg()
        spinner_frames = SpinnerFrames(
            self._spec,
            width=width,
            height=height,
            rendered_svg=rendered_svg,
            bg_tile=self._bg_tile,
        )
        self._spinner_frames = spinner_frames

        self._animator = SpinnerAnimator(
            frames=await asyncio.to_thread(lambda: spinner_frames.frames),
            interval_ms=spinner_frames.interval_ms,
            push_fn=self._push_fn,
        )
        await self._animator.start()

    async def _stop_spinner(self) -> None:
        """Stop the spinner animation."""
        if self._animator is not None:
            await self._animator.stop()
            self._animator = None

    async def cleanup(self) -> None:
        """Cancel pending accumulators and release resources."""
        await self._events.cancel_accumulators()

spec property

spec: PackageSpec

The package specification backing this card.

is_busy property

is_busy: bool

Whether a busy-guarded handler is currently executing.

is_animating property

is_animating: bool

Whether a spinner animation is currently running.

__init__

__init__(spec: PackageSpec | str) -> None

Construct a DUI-backed touchscreen card.

Parameters:

Name	Type	Description	Default
spec	PackageSpec or str	Either a pre-validated :class:~deux.dui.schema.PackageSpec, or a package name (for example "DashboardCard") to resolve from the DUI repository. String resolution is deferred to :func:~deux.dui.repository.resolve_dui at call time so tests that monkeypatch that symbol behave correctly.	required

Raises:

Type	Description
PackageError	If spec is a string and no matching package is found in any registered search path.

Notes

Construction performs no rendering and no device I/O. The underlying :class:~deux.dui.svg_renderer.SvgRenderer and :class:~deux.dui.events.EventMap are built eagerly from spec; binding values, push callbacks, and background tiles are configured later via the corresponding setters.

Source code in src/deux/dui/card.py

def __init__(self, spec: PackageSpec | str) -> None:
    """Construct a DUI-backed touchscreen card.

    Parameters
    ----------
    spec : PackageSpec or str
        Either a pre-validated
        :class:`~deux.dui.schema.PackageSpec`, or a package name
        (for example ``"DashboardCard"``) to resolve from the DUI
        repository.  String resolution is deferred to
        :func:`~deux.dui.repository.resolve_dui` at call time so
        tests that monkeypatch that symbol behave correctly.

    Raises
    ------
    deux.dui.repository.PackageError
        If *spec* is a string and no matching package is found in
        any registered search path.

    Notes
    -----
    Construction performs no rendering and no device I/O.  The
    underlying :class:`~deux.dui.svg_renderer.SvgRenderer` and
    :class:`~deux.dui.events.EventMap` are built eagerly from
    *spec*; binding values, push callbacks, and background tiles
    are configured later via the corresponding setters.
    """
    if isinstance(spec, str):
        # Inline import: keeps the lookup go through repository.resolve_dui
        # at call time so monkeypatching that symbol in tests works.
        from .repository import resolve_dui  # noqa: PLC0415

        spec = resolve_dui(spec)
    super().__init__()
    self._spec = spec
    self._renderer = SvgRenderer(spec)
    self._events = EventMap(spec.events, spec.regions)
    self._subscriptions: list[tuple[AsyncEvent, AsyncHandler]] = []
    self._busy = False
    self._animator: SpinnerAnimator | None = None
    self._spinner_frames: SpinnerFrames | None = None
    self._push_fn: PushFn | None = None
    self._panel_size: tuple[int, int] | None = None
    self._bg_tile: bytes | None = None
    self._bg_svg_root: ET.Element | None = None
    self._card_index: int | None = None

set_push_fn

set_push_fn(push_fn: PushFn, panel_size: tuple[int, int]) -> None

Set the async function used to push animation frames to the device.

This must be called before spinner animations can play. Typically set by :class:~deux.runtime.deck.Deck.

Parameters:

Name	Type	Description	Default
push_fn	PushFn	Async callable (frame_bytes) -> None.	required
panel_size	tuple[int, int]	(width, height) of the touchscreen panel this card occupies, used to size spinner frames.	required

Source code in src/deux/dui/card.py

def set_push_fn(self, push_fn: PushFn, panel_size: tuple[int, int]) -> None:
    """Set the async function used to push animation frames to the device.

    This must be called before spinner animations can play.
    Typically set by :class:`~deux.runtime.deck.Deck`.

    Parameters
    ----------
    push_fn
        Async callable ``(frame_bytes) -> None``.
    panel_size
        ``(width, height)`` of the touchscreen panel this card occupies,
        used to size spinner frames.
    """
    self._push_fn = push_fn
    self._panel_size = panel_size

set_bg_tile

set_bg_tile(tile: bytes | None) -> None

Set the background tile for compositing spinner frames.

When a touchstrip background SVG is active, the corresponding pre-sliced tile (PNG bytes) is passed here so that spinner animations can composite each frame onto the background.

Parameters:

Name	Type	Description	Default
tile	bytes | None	PNG-encoded background tile bytes, or None to clear.	required

Source code in src/deux/dui/card.py

def set_bg_tile(self, tile: bytes | None) -> None:
    """Set the background tile for compositing spinner frames.

    When a touchstrip background SVG is active, the corresponding
    pre-sliced tile (PNG bytes) is passed here so that spinner
    animations can composite each frame onto the background.

    Parameters
    ----------
    tile
        PNG-encoded background tile bytes, or ``None`` to clear.
    """
    self._bg_tile = tile

set_background_layer

set_background_layer(bg_root: Element, card_index: int, panel_width: int, panel_height: int) -> None

Set a background SVG layer underneath the card content.

The background SVG's viewBox is sliced to the region for card_index and composed as a layer beneath the card's own SVG. The composed tree is cached so subsequent renders only need to apply bindings and rasterise.

Parameters:

Name	Type	Description	Default
bg_root	Element	The full-width background <svg> root element.	required
card_index	int	Zero-based panel index.	required
panel_width	int	Width of a single panel in pixels.	required
panel_height	int	Height of a single panel in pixels.	required

Source code in src/deux/dui/card.py

def set_background_layer(
    self,
    bg_root: ET.Element,
    card_index: int,
    panel_width: int,
    panel_height: int,
) -> None:
    """Set a background SVG layer underneath the card content.

    The background SVG's ``viewBox`` is sliced to the region for
    *card_index* and composed as a layer beneath the card's own
    SVG.  The composed tree is cached so subsequent renders only
    need to apply bindings and rasterise.

    Parameters
    ----------
    bg_root : ET.Element
        The full-width background ``<svg>`` root element.
    card_index : int
        Zero-based panel index.
    panel_width : int
        Width of a single panel in pixels.
    panel_height : int
        Height of a single panel in pixels.
    """
    self._bg_svg_root = bg_root
    self._card_index = card_index
    self._renderer.set_base_layer(bg_root, card_index, panel_width, panel_height)
    self._renderer.set_target_size(panel_width, panel_height)

clear_background_layer

clear_background_layer() -> None

Remove the background layer and revert to the card's own SVG.

Source code in src/deux/dui/card.py

def clear_background_layer(self) -> None:
    """Remove the background layer and revert to the card's own SVG."""
    self._bg_svg_root = None
    self._card_index = None
    self._renderer.clear_base_layer()

render_bytes

render_bytes(*, panel_width: int, panel_height: int, image_format: str = 'JPEG', background: str = 'black') -> bytes

Render the card directly to encoded image bytes.

Uses the SVG-native pipeline: background compositing happens at the SVG level (if a background layer is set), dimensions are set for vector scaling, and the output is rasterised directly to the requested format.

Parameters:

Name	Type	Description	Default
panel_width	int	Target panel width in pixels.	required
panel_height	int	Target panel height in pixels.	required
image_format	str	Image encoding format ("JPEG" or "BMP").	"JPEG"
background	str	Fallback background colour (used when no background SVG layer is set).	"black"

Returns:

Type	Description
bytes	Encoded image bytes ready to send to the device.

Source code in src/deux/dui/card.py

def render_bytes(
    self,
    *,
    panel_width: int,
    panel_height: int,
    image_format: str = "JPEG",
    background: str = "black",
) -> bytes:
    """Render the card directly to encoded image bytes.

    Uses the SVG-native pipeline: background compositing happens
    at the SVG level (if a background layer is set), dimensions are
    set for vector scaling, and the output is rasterised directly
    to the requested format.

    Parameters
    ----------
    panel_width : int
        Target panel width in pixels.
    panel_height : int
        Target panel height in pixels.
    image_format : str, default="JPEG"
        Image encoding format (``"JPEG"`` or ``"BMP"``).
    background : str, default="black"
        Fallback background colour (used when no background SVG
        layer is set).

    Returns
    -------
    bytes
        Encoded image bytes ready to send to the device.
    """
    self._renderer.set_target_size(panel_width, panel_height)
    fmt = image_format.upper()
    out_fmt = "jpeg" if fmt == "JPEG" else "bmp"
    # Only inject a solid background if no SVG background layer is set.
    bg = background if self._bg_svg_root is None else None
    return self._renderer.render_bytes(
        output_format=out_fmt,
        background=bg,
    )

render_panel_bytes

render_panel_bytes(*, metrics: RenderMetrics, card_index: int, bg_tile: bytes | None, background: str = 'black', image_format: str = 'JPEG') -> bytes

Render the card to encoded image bytes using the SVG-native pipeline.

Overrides the base :meth:Card.render_panel_bytes to use SVG-level background compositing and direct rasterisation, avoiding the legacy Pillow compositing path entirely.

Parameters:

Name	Type	Description	Default
metrics	RenderMetrics	Device metrics (panel dimensions, etc.).	required
card_index	int	The zero-based position of this card on the touch strip.	required
bg_tile	Image or None	Cropped background tile for this card's panel, or None.	required
background	str	Fallback background colour.	"black"
image_format	str	Image encoding format ("JPEG" or "BMP").	"JPEG"

Returns:

Type	Description
bytes	Encoded image bytes ready to send to the device.

Source code in src/deux/dui/card.py

def render_panel_bytes(
    self,
    *,
    metrics: RenderMetrics,
    card_index: int,
    bg_tile: bytes | None,
    background: str = "black",
    image_format: str = "JPEG",
) -> bytes:
    """Render the card to encoded image bytes using the SVG-native pipeline.

    Overrides the base :meth:`Card.render_panel_bytes` to use
    SVG-level background compositing and direct rasterisation,
    avoiding the legacy Pillow compositing path entirely.

    Parameters
    ----------
    metrics : RenderMetrics
        Device metrics (panel dimensions, etc.).
    card_index : int
        The zero-based position of this card on the touch strip.
    bg_tile : Image.Image or None
        Cropped background tile for this card's panel, or ``None``.
    background : str, default="black"
        Fallback background colour.
    image_format : str, default="JPEG"
        Image encoding format (``"JPEG"`` or ``"BMP"``).

    Returns
    -------
    bytes
        Encoded image bytes ready to send to the device.
    """
    panel_bytes = self.render_bytes(
        panel_width=metrics.panel_width,
        panel_height=metrics.panel_height,
        image_format=image_format,
        background=background,
    )

    self.mark_clean()

    return panel_bytes

set

set(name: str, value: Any) -> DuiCard

Set a binding value. Marks the card dirty if changed.

Parameters:

Name	Type	Description	Default
name	str	Binding name as defined in the manifest.	required
value	Any	New value (type depends on binding kind).	required

Returns:

Type	Description
DuiCard	self, for method chaining.

Raises:

Type	Description
KeyError	If name is not a known binding.

Source code in src/deux/dui/card.py

def set(self, name: str, value: Any) -> DuiCard:
    """Set a binding value.  Marks the card dirty if changed.

    Parameters
    ----------
    name
        Binding name as defined in the manifest.
    value
        New value (type depends on binding kind).

    Returns
    -------
    DuiCard
        self, for method chaining.

    Raises
    ------
    KeyError
        If *name* is not a known binding.
    """
    if self._renderer.set(name, value):
        self.mark_dirty()
    return self

set_many

set_many(**kwargs: Any) -> DuiCard

Set multiple binding values at once.

Returns:

Type	Description
DuiCard	self, for method chaining.

Source code in src/deux/dui/card.py

def set_many(self, **kwargs: Any) -> DuiCard:
    """Set multiple binding values at once.

    Returns
    -------
    DuiCard
        self, for method chaining.
    """
    if self._renderer.set_many(**kwargs):
        self.mark_dirty()
    return self

get

get(name: str) -> Any

Get the current value of a binding.

Raises:

Type	Description
KeyError	If name is not a known binding.

Source code in src/deux/dui/card.py

def get(self, name: str) -> Any:
    """Get the current value of a binding.

    Raises
    ------
    KeyError
        If *name* is not a known binding.
    """
    return self._renderer.get(name)

collect_icon_names

collect_icon_names() -> builtins.set[str]

Return all Iconify icon identifiers needed by this card.

Returns:

Type	Description
set[str]	A set of "prefix:icon" strings referenced by the card's bindings (defaults and current values).

Source code in src/deux/dui/card.py

def collect_icon_names(self) -> builtins.set[str]:
    """Return all Iconify icon identifiers needed by this card.

    Returns
    -------
    set[str]
        A set of ``"prefix:icon"`` strings referenced by the card's
        bindings (defaults and current values).
    """
    return self._renderer.collect_icon_names()

set_rendering_context

set_rendering_context(ctx: RenderingContext | None) -> None

Set the explicit rendering context for this card.

Parameters:

Name	Type	Description	Default
ctx	RenderingContext or None	The rendering context to apply, or None to revert to module-level defaults.	required

Source code in src/deux/dui/card.py

def set_rendering_context(self, ctx: RenderingContext | None) -> None:
    """Set the explicit rendering context for this card.

    Parameters
    ----------
    ctx : RenderingContext or None
        The rendering context to apply, or ``None`` to revert to
        module-level defaults.
    """
    self._renderer.set_rendering_context(ctx)

set_range

set_range(name: str, value: float, *, min_val: float = 0, max_val: float = 1) -> DuiCard

Set a range/slider binding using a domain-scale value.

Normalises value from [min_val, max_val] to [0.0, 1.0] and delegates to :meth:set.

Parameters:

Name	Type	Description	Default
name	str	Binding name (must be a range or slider binding).	required
value	float	Value in domain units (e.g. 0–100 for a percentage).	required
min_val	float	Lower bound of the domain range.	0
max_val	float	Upper bound of the domain range.	1

Returns:

Type	Description
DuiCard	self, for method chaining.

Raises:

Type	Description
KeyError	If name is not a known binding.
ValueError	If min_val equals max_val.

Source code in src/deux/dui/card.py

def set_range(
    self, name: str, value: float, *, min_val: float = 0, max_val: float = 1
) -> DuiCard:
    """Set a range/slider binding using a domain-scale value.

    Normalises *value* from ``[min_val, max_val]`` to ``[0.0, 1.0]``
    and delegates to :meth:`set`.

    Parameters
    ----------
    name
        Binding name (must be a ``range`` or ``slider`` binding).
    value
        Value in domain units (e.g. 0–100 for a percentage).
    min_val
        Lower bound of the domain range.
    max_val
        Upper bound of the domain range.

    Returns
    -------
    DuiCard
        self, for method chaining.

    Raises
    ------
    KeyError
        If *name* is not a known binding.
    ValueError
        If *min_val* equals *max_val*.
    """
    if min_val == max_val:
        raise ValueError("min_val and max_val must not be equal")
    clamped = max(min_val, min(max_val, value))
    normalised = (clamped - min_val) / (max_val - min_val)
    return self.set(name, normalised)

adjust_range

adjust_range(name: str, delta: float, *, min_val: float = 0, max_val: float = 1) -> float

Adjust a range/slider binding by delta domain-scale units.

Reads the current normalised value, denormalises it, adds delta, clamps, re-normalises, and calls :meth:set.

Parameters:

Name	Type	Description	Default
name	str	Binding name (must be a range or slider binding).	required
delta	float	Amount to add in domain units (negative to decrease).	required
min_val	float	Lower bound of the domain range.	0
max_val	float	Upper bound of the domain range.	1

Returns:

Type	Description
float	The new value in domain units (clamped to [min_val, max_val]), so callers can use it for display without back-computing.

Raises:

Type	Description
KeyError	If name is not a known binding.
ValueError	If min_val equals max_val.

Source code in src/deux/dui/card.py

def adjust_range(
    self, name: str, delta: float, *, min_val: float = 0, max_val: float = 1
) -> float:
    """Adjust a range/slider binding by *delta* domain-scale units.

    Reads the current normalised value, denormalises it, adds *delta*,
    clamps, re-normalises, and calls :meth:`set`.

    Parameters
    ----------
    name
        Binding name (must be a ``range`` or ``slider`` binding).
    delta
        Amount to add in domain units (negative to decrease).
    min_val
        Lower bound of the domain range.
    max_val
        Upper bound of the domain range.

    Returns
    -------
    float
        The new value in domain units (clamped to
        ``[min_val, max_val]``), so callers can use it for display
        without back-computing.

    Raises
    ------
    KeyError
        If *name* is not a known binding.
    ValueError
        If *min_val* equals *max_val*.
    """
    if min_val == max_val:
        raise ValueError("min_val and max_val must not be equal")
    current_norm = float(self.get(name) or 0.0)
    current_domain = min_val + current_norm * (max_val - min_val)
    new_domain = max(min_val, min(max_val, current_domain + delta))
    normalised = (new_domain - min_val) / (max_val - min_val)
    self.set(name, normalised)
    return new_domain

get_range

get_range(name: str, *, min_val: float = 0, max_val: float = 1) -> float

Get a range/slider binding denormalised to domain units.

Parameters:

Name	Type	Description	Default
name	str	Binding name.	required
min_val	float	Lower bound of the domain range.	0
max_val	float	Upper bound of the domain range.	1

Returns:

Type	Description
float	The current value in domain units.

Raises:

Type	Description
KeyError	If name is not a known binding.
ValueError	If min_val equals max_val.

Source code in src/deux/dui/card.py

def get_range(
    self, name: str, *, min_val: float = 0, max_val: float = 1
) -> float:
    """Get a range/slider binding denormalised to domain units.

    Parameters
    ----------
    name
        Binding name.
    min_val
        Lower bound of the domain range.
    max_val
        Upper bound of the domain range.

    Returns
    -------
    float
        The current value in domain units.

    Raises
    ------
    KeyError
        If *name* is not a known binding.
    ValueError
        If *min_val* equals *max_val*.
    """
    if min_val == max_val:
        raise ValueError("min_val and max_val must not be equal")
    current_norm = float(self.get(name) or 0.0)
    return min_val + current_norm * (max_val - min_val)

render

render() -> Image.Image

Render the SVG layout with current bindings to a PIL Image.

Returns:

Type	Description
Image	A panel-sized RGB :class:~PIL.Image.Image (sized from the .dui SVG's intrinsic dimensions).

Source code in src/deux/dui/card.py

def render(self) -> Image.Image:
    """Render the SVG layout with current bindings to a PIL Image.

    Returns
    -------
    Image.Image
        A panel-sized RGB :class:`~PIL.Image.Image` (sized from the
        ``.dui`` SVG's intrinsic dimensions).
    """
    return self._renderer.render()

prepare_assets async

prepare_assets() -> None

No-op — .dui cards manage their own assets via the SVG.

Source code in src/deux/dui/card.py

async def prepare_assets(self) -> None:
    """No-op — .dui cards manage their own assets via the SVG."""

handle_encoder_turn

handle_encoder_turn(direction: int) -> None

Route encoder turn through the event map.

Source code in src/deux/dui/card.py

def handle_encoder_turn(self, direction: int) -> None:
    """Route encoder turn through the event map."""
    handler = self._events.handle_encoder_turn(direction)
    if handler is not None:
        self.queue_pending_callback(handler, (direction,))

handle_encoder_press

handle_encoder_press() -> None

Route encoder press through the event map.

Source code in src/deux/dui/card.py

def handle_encoder_press(self) -> None:
    """Route encoder press through the event map."""
    for handler in self._events.handle_encoder_press():
        self.queue_pending_callback(handler, ())

handle_encoder_release

handle_encoder_release() -> None

Route encoder release through the event map.

Source code in src/deux/dui/card.py

def handle_encoder_release(self) -> None:
    """Route encoder release through the event map."""
    for handler in self._events.handle_encoder_release():
        self.queue_pending_callback(handler, ())

dispatch_touch async

dispatch_touch(event: TouchEvent) -> None

Dispatch touch events through regions and the event map.

Falls back to the base Card touch handlers (on_tap, etc.) if the event map doesn't handle the event.

Source code in src/deux/dui/card.py

async def dispatch_touch(self, event: TouchEvent) -> None:
    """Dispatch touch events through regions and the event map.

    Falls back to the base Card touch handlers (on_tap, etc.)
    if the event map doesn't handle the event.
    """
    handler = self._events.handle_touch(event.event_type, event.x, event.y)
    if handler is not None:
        await handler()
    else:
        await super().dispatch_touch(event)

start_busy async

start_busy() -> None

Enter the busy state and start the spinner animation.

While busy, the card suppresses further start_busy() calls. The spinner keeps running until :meth:finish_busy is called.

If no spinner is configured in the manifest the busy flag is still set (suppressing duplicate calls) but no animation plays.

Source code in src/deux/dui/card.py

async def start_busy(self) -> None:
    """Enter the busy state and start the spinner animation.

    While busy, the card suppresses further ``start_busy()`` calls.
    The spinner keeps running until :meth:`finish_busy` is called.

    If no spinner is configured in the manifest the busy flag is
    still set (suppressing duplicate calls) but no animation plays.
    """
    if self._busy:
        return
    self._busy = True
    await self._start_spinner()

finish_busy async

finish_busy() -> None

Stop the spinner and exit the busy state.

Call this from your application code when the asynchronous work is truly complete (e.g. after receiving a state update from an external system).

If the card is not currently busy this is a no-op.

Source code in src/deux/dui/card.py

async def finish_busy(self) -> None:
    """Stop the spinner and exit the busy state.

    Call this from your application code when the asynchronous
    work is truly complete (e.g. after receiving a state update
    from an external system).

    If the card is not currently busy this is a no-op.
    """
    if not self._busy:
        return
    await self._stop_spinner()
    self._busy = False
    self.mark_dirty()

cleanup async

cleanup() -> None

Cancel pending accumulators and release resources.

Source code in src/deux/dui/card.py

async def cleanup(self) -> None:
    """Cancel pending accumulators and release resources."""
    await self._events.cancel_accumulators()

EventMap

Map physical hardware events to named semantic events.

Handles simple mappings (encoder_press → semantic name) as well as compound gestures:

• encoder_press_release: fires only if the press duration is within max_duration_ms.
• encoder_hold / key_hold: starts a timer on press and fires the handler after hold_ms while the key/encoder is still held. Suppresses any press_release or release event for that press–release cycle.
• encoder_turn: fires turn events only while the encoder is not pressed. Turning while pressed never falls through to this mapping. Immediately after releasing a press cycle that included at least one turn, encoder_turn is suppressed for release_turn_grace_ms to debounce the spurious tick a finger often produces while lifting off the dial.
• encoder_press_turn: fires turn events only while the encoder is held down. When declared with a direction filter, mismatching turns while pressed are silent — there is no fallback to encoder_turn. Any turn while pressed cancels a pending encoder_hold regardless of whether a handler fires.
• Direction filtering: encoder_turn with direction: left only fires for counter-clockwise turns.

Parameters:

Name	Type	Description	Default
events	tuple[EventMapping, ...]	Event mappings from the package manifest.	required
regions	tuple[Region, ...]	Touch regions from the package manifest.	()
release_turn_grace_ms	int	Suppression window (in milliseconds) applied to plain encoder_turn events immediately after the encoder is released following a press cycle that included at least one turn. Defaults to :data:~deux.dui.schema.DEFAULT_RELEASE_TURN_GRACE_MS. Pass 0 to disable.	DEFAULT_RELEASE_TURN_GRACE_MS

Source code in src/deux/dui/event_map.py

class EventMap:
    """Map physical hardware events to named semantic events.

    Handles simple mappings (encoder_press → semantic name) as well as
    compound gestures:

    - ``encoder_press_release``: fires only if the press duration is
      within ``max_duration_ms``.
    - ``encoder_hold`` / ``key_hold``: starts a timer on press and fires
      the handler after ``hold_ms`` while the key/encoder is still held.
      Suppresses any ``press_release`` or ``release`` event for that
      press–release cycle.
    - ``encoder_turn``: fires turn events only while the encoder is
      **not** pressed.  Turning while pressed never falls through to
      this mapping.  Immediately after releasing a press cycle that
      included at least one turn, ``encoder_turn`` is suppressed for
      ``release_turn_grace_ms`` to debounce the spurious tick a finger
      often produces while lifting off the dial.
    - ``encoder_press_turn``: fires turn events only while the encoder
      is held down.  When declared with a direction filter, mismatching
      turns while pressed are silent — there is no fallback to
      ``encoder_turn``.  Any turn while pressed cancels a pending
      ``encoder_hold`` regardless of whether a handler fires.
    - Direction filtering: ``encoder_turn`` with ``direction: left``
      only fires for counter-clockwise turns.

    Parameters
    ----------
    events
        Event mappings from the package manifest.
    regions
        Touch regions from the package manifest.
    release_turn_grace_ms
        Suppression window (in milliseconds) applied to plain
        ``encoder_turn`` events immediately after the encoder is released
        following a press cycle that included at least one turn.  Defaults
        to :data:`~deux.dui.schema.DEFAULT_RELEASE_TURN_GRACE_MS`.  Pass
        ``0`` to disable.
    """

    def __init__(
        self,
        events: tuple[EventMapping, ...],
        regions: tuple[Region, ...] = (),
        release_turn_grace_ms: int = DEFAULT_RELEASE_TURN_GRACE_MS,
    ) -> None:
        self._mappings = events
        self._regions = regions
        self._handlers: dict[str, AsyncHandler] = {}

        self._press_time: float | None = None
        self._pressed = False

        self._hold_task: asyncio.Task[None] | None = None
        self._hold_fired = False

        self._press_had_turn = False
        self._release_turn_grace_s = max(0, release_turn_grace_ms) / 1000.0
        self._turn_suppressed_until = 0.0

        self._by_source: dict[str, list[EventMapping]] = {}
        for mapping in events:
            self._by_source.setdefault(mapping.source, []).append(mapping)

        self._accumulators: dict[str, DialAccumulator] = {}

    def on(self, event_name: str, handler: AsyncHandler) -> None:
        """Register a handler for a named semantic event.

        Parameters
        ----------
        event_name
            The semantic event name (as defined in the manifest).
        handler
            An async callable to invoke when the event fires.
            For accumulated events the handler signature must accept
            a single ``int`` argument (the net accumulated steps).

        Raises
        ------
        KeyError
            If *event_name* is not defined in the manifest.
        """
        known = {m.name for m in self._mappings}
        if event_name not in known:
            raise KeyError(
                f"Unknown event '{event_name}'. Defined events: {sorted(known)}"
            )

        mapping = next(m for m in self._mappings if m.name == event_name)
        if mapping.accumulate:
            kwargs: dict[str, Any] = {}
            if mapping.accumulate_delay is not None:
                kwargs["delay"] = mapping.accumulate_delay
            if mapping.accumulate_max_steps is not None:
                kwargs["max_steps"] = mapping.accumulate_max_steps
            self._accumulators[event_name] = DialAccumulator(handler, **kwargs)

        self._handlers[event_name] = handler

    @property
    def event_names(self) -> list[str]:
        """All semantic event names defined in this map."""
        return [m.name for m in self._mappings]

    def _start_hold_timer(self, source: str) -> None:
        """Start a hold timer for the first matching hold mapping.

        Parameters
        ----------
        source
            ``"key_hold"`` or ``"encoder_hold"``.
        """
        for mapping in self._by_source.get(source, []):
            handler = self._handlers.get(mapping.name)
            if handler is None:
                continue
            hold_ms = mapping.hold_ms
            if hold_ms is None:
                continue  # pragma: no cover — validated by loader
            self._hold_task = asyncio.create_task(
                self._hold_delay(hold_ms / 1000.0, handler),
                name="dui-hold-timer",
            )
            return

    async def _hold_delay(self, seconds: float, handler: AsyncHandler) -> None:
        """Sleep then fire the hold handler if still pressed.

        Detaches ``_hold_task`` before invoking the handler so that a
        subsequent encoder release does not cancel the in-flight handler
        via :meth:`_cancel_hold_timer`.
        """
        await asyncio.sleep(seconds)
        if self._pressed:
            self._hold_fired = True
            self._hold_task = None
            try:
                await handler()
            except Exception:
                logger.exception("Hold-timer handler raised an exception")

    def _cancel_hold_timer(self) -> None:
        """Cancel an in-progress hold timer if one is running."""
        if self._hold_task is not None:
            self._hold_task.cancel()
            self._hold_task = None

    async def cancel_accumulators(self) -> None:
        """Cancel all active dial accumulators and discard pending ticks."""
        for acc in self._accumulators.values():
            await acc.cancel()

    def handle_encoder_turn(self, direction: int) -> AsyncHandler | None:
        """Match an encoder turn to a semantic event.

        Parameters
        ----------
        direction
            Positive for clockwise, negative for counter-clockwise.

        Returns
        -------
        AsyncHandler or None
            The matched handler, or ``None`` if no mapping matched.
            For accumulated events this returns ``None`` because the
            tick is forwarded to the :class:`DialAccumulator` which
            schedules its own async flush.
        """
        if self._pressed:
            self._cancel_hold_timer()
            self._press_had_turn = True

            for mapping in self._by_source.get("encoder_press_turn", []):
                if self._direction_matches(mapping, direction):
                    acc = self._accumulators.get(mapping.name)
                    if acc is not None:
                        acc.tick(direction)
                        return None
                    h = self._handlers.get(mapping.name)
                    if h is not None:
                        return h
            return None

        if time.monotonic() < self._turn_suppressed_until:
            return None

        for mapping in self._by_source.get("encoder_turn", []):
            if self._direction_matches(mapping, direction):
                acc = self._accumulators.get(mapping.name)
                if acc is not None:
                    acc.tick(direction)
                    return None
                h = self._handlers.get(mapping.name)
                if h is not None:
                    return h

        return None

    def handle_encoder_press(self) -> list[AsyncHandler]:
        """Match an encoder press to semantic events.

        Records the press timestamp for gesture detection and starts
        a hold timer if an ``encoder_hold`` mapping exists.

        Returns
        -------
        list[AsyncHandler]
            A list of matched handlers (may be empty).
        """
        self._press_time = time.monotonic()
        self._pressed = True
        self._hold_fired = False
        self._press_had_turn = False

        self._start_hold_timer("encoder_hold")

        handlers: list[AsyncHandler] = []
        for mapping in self._by_source.get("encoder_press", []):
            handler = self._handlers.get(mapping.name)
            if handler is not None:
                handlers.append(handler)
        return handlers

    def handle_encoder_release(self) -> list[AsyncHandler]:
        """Match an encoder release to semantic events.

        Cancels any running hold timer.  The simple ``encoder_release``
        event always fires regardless of whether a hold fired.
        ``encoder_press_release`` is suppressed when a hold already
        fired for this press–release cycle (since the interaction was
        a hold, not a press-release gesture).

        If at least one turn occurred during the press cycle, opens a
        ``release_turn_grace_ms`` window during which subsequent plain
        ``encoder_turn`` events are ignored.

        Returns
        -------
        list[AsyncHandler]
            A list of matched handlers (may be empty).
        """
        self._pressed = False
        self._cancel_hold_timer()

        hold_fired = self._hold_fired
        self._hold_fired = False

        if self._press_had_turn and self._release_turn_grace_s > 0:
            self._turn_suppressed_until = (
                time.monotonic() + self._release_turn_grace_s
            )
        self._press_had_turn = False

        handlers: list[AsyncHandler] = []

        if not hold_fired and self._press_time is not None:
            elapsed_ms = (time.monotonic() - self._press_time) * 1000

            for mapping in self._by_source.get("encoder_press_release", []):
                max_ms = mapping.max_duration_ms
                if max_ms is None or elapsed_ms <= max_ms:
                    handler = self._handlers.get(mapping.name)
                    if handler is not None:
                        handlers.append(handler)

        self._press_time = None

        for mapping in self._by_source.get("encoder_release", []):
            handler = self._handlers.get(mapping.name)
            if handler is not None:
                handlers.append(handler)

        return handlers

    def handle_key_press(self) -> list[AsyncHandler]:
        """Match a key press to semantic events.

        Records the press timestamp and starts a hold timer if a
        ``key_hold`` mapping exists.

        Returns
        -------
        list[AsyncHandler]
            A list of matched handlers (may be empty).
        """
        self._press_time = time.monotonic()
        self._pressed = True
        self._hold_fired = False

        self._start_hold_timer("key_hold")

        handlers: list[AsyncHandler] = []
        for mapping in self._by_source.get("key_press", []):
            handler = self._handlers.get(mapping.name)
            if handler is not None:
                handlers.append(handler)
        return handlers

    def handle_key_release(self) -> list[AsyncHandler]:
        """Match a key release to semantic events.

        Cancels any running hold timer.  The simple ``key_release``
        event always fires regardless of whether a hold fired.
        ``key_press_release`` is suppressed when a hold already
        fired for this press–release cycle (since the interaction was
        a hold, not a press-release gesture).

        Returns
        -------
        list[AsyncHandler]
            A list of matched handlers (may be empty).
        """
        self._pressed = False
        self._cancel_hold_timer()

        hold_fired = self._hold_fired
        self._hold_fired = False

        handlers: list[AsyncHandler] = []

        if not hold_fired and self._press_time is not None:
            elapsed_ms = (time.monotonic() - self._press_time) * 1000

            for mapping in self._by_source.get("key_press_release", []):
                max_ms = mapping.max_duration_ms
                if max_ms is None or elapsed_ms <= max_ms:
                    handler = self._handlers.get(mapping.name)
                    if handler is not None:
                        handlers.append(handler)

        self._press_time = None

        for mapping in self._by_source.get("key_release", []):
            handler = self._handlers.get(mapping.name)
            if handler is not None:
                handlers.append(handler)

        return handlers

    def handle_touch(
        self, event_type: EventType, x: int, y: int
    ) -> AsyncHandler | None:
        """Match a touch event to a semantic event via regions.

        Parameters
        ----------
        event_type
            The touch event type (TOUCH_SHORT or TOUCH_LONG).
        x
            Touch x coordinate (relative to card origin).
        y
            Touch y coordinate (relative to card origin).

        Returns
        -------
        AsyncHandler or None
            The matched handler, or ``None`` if no region/mapping matched.
        """
        # Inline import: importing runtime.events triggers runtime.__init__
        # which loads runtime.deck and creates a cycle through dui.* modules.
        from ..runtime.events import EventType as ET_Enum  # noqa: PLC0415

        if event_type == ET_Enum.TOUCH_SHORT:
            touch_name = "tap"
        elif event_type == ET_Enum.TOUCH_LONG:
            touch_name = "long_press"
        else:
            return None

        for region in self._regions:
            if touch_name not in region.events:
                continue
            if (
                region.x <= x < region.x + region.width
                and region.y <= y < region.y + region.height
            ):
                for mapping in self._by_source.get(touch_name, []):
                    h = self._handlers.get(mapping.name)
                    if h is not None:
                        return h

        for mapping in self._by_source.get(touch_name, []):
            h = self._handlers.get(mapping.name)
            if h is not None:
                return h

        return None

    @staticmethod
    def _direction_matches(mapping: EventMapping, direction: int) -> bool:
        """Check if a turn direction matches the mapping's filter."""
        if mapping.direction is None:
            return True
        if mapping.direction == "left" and direction < 0:
            return True
        return mapping.direction == "right" and direction > 0

event_names property

event_names: list[str]

All semantic event names defined in this map.

on

on(event_name: str, handler: AsyncHandler) -> None

Register a handler for a named semantic event.

Parameters:

Name	Type	Description	Default
event_name	str	The semantic event name (as defined in the manifest).	required
handler	AsyncHandler	An async callable to invoke when the event fires. For accumulated events the handler signature must accept a single int argument (the net accumulated steps).	required

Raises:

Type	Description
KeyError	If event_name is not defined in the manifest.

Source code in src/deux/dui/event_map.py

def on(self, event_name: str, handler: AsyncHandler) -> None:
    """Register a handler for a named semantic event.

    Parameters
    ----------
    event_name
        The semantic event name (as defined in the manifest).
    handler
        An async callable to invoke when the event fires.
        For accumulated events the handler signature must accept
        a single ``int`` argument (the net accumulated steps).

    Raises
    ------
    KeyError
        If *event_name* is not defined in the manifest.
    """
    known = {m.name for m in self._mappings}
    if event_name not in known:
        raise KeyError(
            f"Unknown event '{event_name}'. Defined events: {sorted(known)}"
        )

    mapping = next(m for m in self._mappings if m.name == event_name)
    if mapping.accumulate:
        kwargs: dict[str, Any] = {}
        if mapping.accumulate_delay is not None:
            kwargs["delay"] = mapping.accumulate_delay
        if mapping.accumulate_max_steps is not None:
            kwargs["max_steps"] = mapping.accumulate_max_steps
        self._accumulators[event_name] = DialAccumulator(handler, **kwargs)

    self._handlers[event_name] = handler

cancel_accumulators async

cancel_accumulators() -> None

Cancel all active dial accumulators and discard pending ticks.

Source code in src/deux/dui/event_map.py

async def cancel_accumulators(self) -> None:
    """Cancel all active dial accumulators and discard pending ticks."""
    for acc in self._accumulators.values():
        await acc.cancel()

handle_encoder_turn

handle_encoder_turn(direction: int) -> AsyncHandler | None

Match an encoder turn to a semantic event.

Parameters:

Name	Type	Description	Default
direction	int	Positive for clockwise, negative for counter-clockwise.	required

Returns:

Type	Description
AsyncHandler or None	The matched handler, or None if no mapping matched. For accumulated events this returns None because the tick is forwarded to the :class:DialAccumulator which schedules its own async flush.

Source code in src/deux/dui/event_map.py

def handle_encoder_turn(self, direction: int) -> AsyncHandler | None:
    """Match an encoder turn to a semantic event.

    Parameters
    ----------
    direction
        Positive for clockwise, negative for counter-clockwise.

    Returns
    -------
    AsyncHandler or None
        The matched handler, or ``None`` if no mapping matched.
        For accumulated events this returns ``None`` because the
        tick is forwarded to the :class:`DialAccumulator` which
        schedules its own async flush.
    """
    if self._pressed:
        self._cancel_hold_timer()
        self._press_had_turn = True

        for mapping in self._by_source.get("encoder_press_turn", []):
            if self._direction_matches(mapping, direction):
                acc = self._accumulators.get(mapping.name)
                if acc is not None:
                    acc.tick(direction)
                    return None
                h = self._handlers.get(mapping.name)
                if h is not None:
                    return h
        return None

    if time.monotonic() < self._turn_suppressed_until:
        return None

    for mapping in self._by_source.get("encoder_turn", []):
        if self._direction_matches(mapping, direction):
            acc = self._accumulators.get(mapping.name)
            if acc is not None:
                acc.tick(direction)
                return None
            h = self._handlers.get(mapping.name)
            if h is not None:
                return h

    return None

handle_encoder_press

handle_encoder_press() -> list[AsyncHandler]

Match an encoder press to semantic events.

Records the press timestamp for gesture detection and starts a hold timer if an encoder_hold mapping exists.

Returns:

Type	Description
list[AsyncHandler]	A list of matched handlers (may be empty).

Source code in src/deux/dui/event_map.py

def handle_encoder_press(self) -> list[AsyncHandler]:
    """Match an encoder press to semantic events.

    Records the press timestamp for gesture detection and starts
    a hold timer if an ``encoder_hold`` mapping exists.

    Returns
    -------
    list[AsyncHandler]
        A list of matched handlers (may be empty).
    """
    self._press_time = time.monotonic()
    self._pressed = True
    self._hold_fired = False
    self._press_had_turn = False

    self._start_hold_timer("encoder_hold")

    handlers: list[AsyncHandler] = []
    for mapping in self._by_source.get("encoder_press", []):
        handler = self._handlers.get(mapping.name)
        if handler is not None:
            handlers.append(handler)
    return handlers

handle_encoder_release

handle_encoder_release() -> list[AsyncHandler]

Match an encoder release to semantic events.

Cancels any running hold timer. The simple encoder_release event always fires regardless of whether a hold fired. encoder_press_release is suppressed when a hold already fired for this press–release cycle (since the interaction was a hold, not a press-release gesture).

If at least one turn occurred during the press cycle, opens a release_turn_grace_ms window during which subsequent plain encoder_turn events are ignored.

Returns:

Type	Description
list[AsyncHandler]	A list of matched handlers (may be empty).

Source code in src/deux/dui/event_map.py

def handle_encoder_release(self) -> list[AsyncHandler]:
    """Match an encoder release to semantic events.

    Cancels any running hold timer.  The simple ``encoder_release``
    event always fires regardless of whether a hold fired.
    ``encoder_press_release`` is suppressed when a hold already
    fired for this press–release cycle (since the interaction was
    a hold, not a press-release gesture).

    If at least one turn occurred during the press cycle, opens a
    ``release_turn_grace_ms`` window during which subsequent plain
    ``encoder_turn`` events are ignored.

    Returns
    -------
    list[AsyncHandler]
        A list of matched handlers (may be empty).
    """
    self._pressed = False
    self._cancel_hold_timer()

    hold_fired = self._hold_fired
    self._hold_fired = False

    if self._press_had_turn and self._release_turn_grace_s > 0:
        self._turn_suppressed_until = (
            time.monotonic() + self._release_turn_grace_s
        )
    self._press_had_turn = False

    handlers: list[AsyncHandler] = []

    if not hold_fired and self._press_time is not None:
        elapsed_ms = (time.monotonic() - self._press_time) * 1000

        for mapping in self._by_source.get("encoder_press_release", []):
            max_ms = mapping.max_duration_ms
            if max_ms is None or elapsed_ms <= max_ms:
                handler = self._handlers.get(mapping.name)
                if handler is not None:
                    handlers.append(handler)

    self._press_time = None

    for mapping in self._by_source.get("encoder_release", []):
        handler = self._handlers.get(mapping.name)
        if handler is not None:
            handlers.append(handler)

    return handlers

handle_key_press

handle_key_press() -> list[AsyncHandler]

Match a key press to semantic events.

Records the press timestamp and starts a hold timer if a key_hold mapping exists.

Returns:

Type	Description
list[AsyncHandler]	A list of matched handlers (may be empty).

Source code in src/deux/dui/event_map.py

def handle_key_press(self) -> list[AsyncHandler]:
    """Match a key press to semantic events.

    Records the press timestamp and starts a hold timer if a
    ``key_hold`` mapping exists.

    Returns
    -------
    list[AsyncHandler]
        A list of matched handlers (may be empty).
    """
    self._press_time = time.monotonic()
    self._pressed = True
    self._hold_fired = False

    self._start_hold_timer("key_hold")

    handlers: list[AsyncHandler] = []
    for mapping in self._by_source.get("key_press", []):
        handler = self._handlers.get(mapping.name)
        if handler is not None:
            handlers.append(handler)
    return handlers

handle_key_release

handle_key_release() -> list[AsyncHandler]

Match a key release to semantic events.

Cancels any running hold timer. The simple key_release event always fires regardless of whether a hold fired. key_press_release is suppressed when a hold already fired for this press–release cycle (since the interaction was a hold, not a press-release gesture).

Returns:

Type	Description
list[AsyncHandler]	A list of matched handlers (may be empty).

Source code in src/deux/dui/event_map.py

def handle_key_release(self) -> list[AsyncHandler]:
    """Match a key release to semantic events.

    Cancels any running hold timer.  The simple ``key_release``
    event always fires regardless of whether a hold fired.
    ``key_press_release`` is suppressed when a hold already
    fired for this press–release cycle (since the interaction was
    a hold, not a press-release gesture).

    Returns
    -------
    list[AsyncHandler]
        A list of matched handlers (may be empty).
    """
    self._pressed = False
    self._cancel_hold_timer()

    hold_fired = self._hold_fired
    self._hold_fired = False

    handlers: list[AsyncHandler] = []

    if not hold_fired and self._press_time is not None:
        elapsed_ms = (time.monotonic() - self._press_time) * 1000

        for mapping in self._by_source.get("key_press_release", []):
            max_ms = mapping.max_duration_ms
            if max_ms is None or elapsed_ms <= max_ms:
                handler = self._handlers.get(mapping.name)
                if handler is not None:
                    handlers.append(handler)

    self._press_time = None

    for mapping in self._by_source.get("key_release", []):
        handler = self._handlers.get(mapping.name)
        if handler is not None:
            handlers.append(handler)

    return handlers

handle_touch

handle_touch(event_type: EventType, x: int, y: int) -> AsyncHandler | None

Match a touch event to a semantic event via regions.

Parameters:

Name	Type	Description	Default
event_type	EventType	The touch event type (TOUCH_SHORT or TOUCH_LONG).	required
x	int	Touch x coordinate (relative to card origin).	required
y	int	Touch y coordinate (relative to card origin).	required

Returns:

Type	Description
AsyncHandler or None	The matched handler, or None if no region/mapping matched.

Source code in src/deux/dui/event_map.py

def handle_touch(
    self, event_type: EventType, x: int, y: int
) -> AsyncHandler | None:
    """Match a touch event to a semantic event via regions.

    Parameters
    ----------
    event_type
        The touch event type (TOUCH_SHORT or TOUCH_LONG).
    x
        Touch x coordinate (relative to card origin).
    y
        Touch y coordinate (relative to card origin).

    Returns
    -------
    AsyncHandler or None
        The matched handler, or ``None`` if no region/mapping matched.
    """
    # Inline import: importing runtime.events triggers runtime.__init__
    # which loads runtime.deck and creates a cycle through dui.* modules.
    from ..runtime.events import EventType as ET_Enum  # noqa: PLC0415

    if event_type == ET_Enum.TOUCH_SHORT:
        touch_name = "tap"
    elif event_type == ET_Enum.TOUCH_LONG:
        touch_name = "long_press"
    else:
        return None

    for region in self._regions:
        if touch_name not in region.events:
            continue
        if (
            region.x <= x < region.x + region.width
            and region.y <= y < region.y + region.height
        ):
            for mapping in self._by_source.get(touch_name, []):
                h = self._handlers.get(mapping.name)
                if h is not None:
                    return h

    for mapping in self._by_source.get(touch_name, []):
        h = self._handlers.get(mapping.name)
        if h is not None:
            return h

    return None

IconifyError

Bases: DeuxError

Raised when an Iconify icon cannot be resolved.

Source code in src/deux/dui/iconify.py

class IconifyError(DeuxError):
    """Raised when an Iconify icon cannot be resolved."""

DuiKey

Bases: BindingMixin, KeySlot

A physical key whose layout and events are defined by a .dui package.

DuiKey extends :class:~deux.ui.controls.key_slot.KeySlot so that it is accepted wherever a KeySlot is expected. It replaces the icon + label rendering with SVG-based rendering from a .dui package.

Examples:

::

from deux import DuiKey

# Resolve by name from the DUI repository
key = DuiKey("IconKey")
key.set("label", "Shutdown")

@key.on("activate")
async def handle():
    ...

You can also pass a pre-loaded :class:~deux.dui.schema.PackageSpec directly::

from deux.dui import load_package, DuiKey

spec = load_package("./PowerKey.dui")
key = DuiKey(spec)

The key index is assigned automatically when you install the key on a screen with :meth:~deux.ui.screen.Screen.set_key.

Parameters:

Name	Type	Description	Default
spec	PackageSpec or str	A validated :class:~deux.dui.schema.PackageSpec, or a package name (e.g. "IconKey") to resolve from the DUI repository.	required

Source code in src/deux/dui/key.py

class DuiKey(BindingMixin, KeySlot):
    """A physical key whose layout and events are defined by a .dui package.

    ``DuiKey`` extends :class:`~deux.ui.controls.key_slot.KeySlot`
    so that it is accepted wherever a ``KeySlot`` is expected.  It
    replaces the icon + label rendering with SVG-based rendering from
    a ``.dui`` package.

    Examples
    --------
    ::

        from deux import DuiKey

        # Resolve by name from the DUI repository
        key = DuiKey("IconKey")
        key.set("label", "Shutdown")

        @key.on("activate")
        async def handle():
            ...

    You can also pass a pre-loaded :class:`~deux.dui.schema.PackageSpec`
    directly::

        from deux.dui import load_package, DuiKey

        spec = load_package("./PowerKey.dui")
        key = DuiKey(spec)

    The key index is assigned automatically when you install the key
    on a screen with :meth:`~deux.ui.screen.Screen.set_key`.

    Parameters
    ----------
    spec : PackageSpec or str
        A validated :class:`~deux.dui.schema.PackageSpec`, or a
        package name (e.g. ``"IconKey"``) to resolve from the DUI
        repository.
    """

    def __init__(self, spec: PackageSpec | str) -> None:
        if isinstance(spec, str):
            # Inline import: keeps the lookup go through repository.resolve_dui
            # at call time so monkeypatching that symbol in tests works.
            from .repository import resolve_dui  # noqa: PLC0415

            spec = resolve_dui(spec)
        super().__init__()
        self._spec = spec
        self._renderer = SvgRenderer(spec)
        self._events = EventMap(spec.events)
        self._subscriptions: list[tuple[AsyncEvent, AsyncHandler]] = []
        self._dirty = True
        self._busy = False
        self._animator: SpinnerAnimator | None = None
        self._spinner_frames: SpinnerFrames | None = None
        self._push_fn: PushFn | None = None
        self._key_size: tuple[int, int] | None = None

    @property
    def spec(self) -> PackageSpec:
        """The package specification backing this key."""
        return self._spec

    @property
    def is_busy(self) -> bool:
        """Whether a busy-guarded handler is currently executing."""
        return self._busy

    @property
    def is_animating(self) -> bool:
        """Whether a spinner animation is currently running."""
        return self._animator is not None and self._animator.is_running

    def set_push_fn(self, push_fn: PushFn, key_size: tuple[int, int]) -> None:
        """Set the async function used to push animation frames to the device.

        Parameters
        ----------
        push_fn
            Async callable ``(frame_bytes) -> None``.
        key_size
            ``(width, height)`` of the device's key — used to size
            spinner frames.
        """
        self._push_fn = push_fn
        self._key_size = key_size

    def set(self, name: str, value: Any) -> DuiKey:
        """Set a binding value.  Marks the key dirty if changed.

        Parameters
        ----------
        name
            Binding name as defined in the manifest.
        value
            New value (type depends on binding kind).

        Returns
        -------
        DuiKey
            self, for method chaining.

        Raises
        ------
        KeyError
            If *name* is not a known binding.
        """
        if self._renderer.set(name, value):
            self._dirty = True
        return self

    def set_many(self, **kwargs: Any) -> DuiKey:
        """Set multiple binding values at once.

        Returns
        -------
        DuiKey
            self, for method chaining.
        """
        if self._renderer.set_many(**kwargs):
            self._dirty = True
        return self

    def get(self, name: str) -> Any:
        """Get the current value of a binding.

        Raises
        ------
        KeyError
            If *name* is not a known binding.
        """
        return self._renderer.get(name)

    def collect_icon_names(self) -> builtins.set[str]:
        """Return all Iconify icon identifiers needed by this key.

        Returns
        -------
        set[str]
            A set of ``"prefix:icon"`` strings referenced by the key's
            bindings (defaults and current values).
        """
        return self._renderer.collect_icon_names()

    def set_rendering_context(self, ctx: RenderingContext | None) -> None:
        """Set the explicit rendering context for this key.

        Parameters
        ----------
        ctx : RenderingContext or None
            The rendering context to apply, or ``None`` to revert to
            module-level defaults.
        """
        self._renderer.set_rendering_context(ctx)

    def set_range(
        self, name: str, value: float, *, min_val: float = 0, max_val: float = 1
    ) -> DuiKey:
        """Set a range/slider binding using a domain-scale value.

        Normalises *value* from ``[min_val, max_val]`` to ``[0.0, 1.0]``
        and delegates to :meth:`set`.

        Parameters
        ----------
        name
            Binding name (must be a ``range`` or ``slider`` binding).
        value
            Value in domain units (e.g. 0–100 for a percentage).
        min_val
            Lower bound of the domain range.
        max_val
            Upper bound of the domain range.

        Returns
        -------
        DuiKey
            self, for method chaining.

        Raises
        ------
        KeyError
            If *name* is not a known binding.
        ValueError
            If *min_val* equals *max_val*.
        """
        if min_val == max_val:
            raise ValueError("min_val and max_val must not be equal")
        clamped = max(min_val, min(max_val, value))
        normalised = (clamped - min_val) / (max_val - min_val)
        return self.set(name, normalised)

    def adjust_range(
        self, name: str, delta: float, *, min_val: float = 0, max_val: float = 1
    ) -> float:
        """Adjust a range/slider binding by *delta* domain-scale units.

        Reads the current normalised value, denormalises it, adds *delta*,
        clamps, re-normalises, and calls :meth:`set`.

        Parameters
        ----------
        name
            Binding name (must be a ``range`` or ``slider`` binding).
        delta
            Amount to add in domain units (negative to decrease).
        min_val
            Lower bound of the domain range.
        max_val
            Upper bound of the domain range.

        Returns
        -------
        float
            The new value in domain units (clamped to
            ``[min_val, max_val]``), so callers can use it for display
            without back-computing.

        Raises
        ------
        KeyError
            If *name* is not a known binding.
        ValueError
            If *min_val* equals *max_val*.
        """
        if min_val == max_val:
            raise ValueError("min_val and max_val must not be equal")
        current_norm = float(self.get(name) or 0.0)
        current_domain = min_val + current_norm * (max_val - min_val)
        new_domain = max(min_val, min(max_val, current_domain + delta))
        normalised = (new_domain - min_val) / (max_val - min_val)
        self.set(name, normalised)
        return new_domain

    def get_range(
        self, name: str, *, min_val: float = 0, max_val: float = 1
    ) -> float:
        """Get a range/slider binding denormalised to domain units.

        Parameters
        ----------
        name
            Binding name.
        min_val
            Lower bound of the domain range.
        max_val
            Upper bound of the domain range.

        Returns
        -------
        float
            The current value in domain units.

        Raises
        ------
        KeyError
            If *name* is not a known binding.
        ValueError
            If *min_val* equals *max_val*.
        """
        if min_val == max_val:
            raise ValueError("min_val and max_val must not be equal")
        current_norm = float(self.get(name) or 0.0)
        return min_val + current_norm * (max_val - min_val)

    def render_image(
        self,
        key_size: tuple[int, int],
        image_format: str = "JPEG",
    ) -> bytes:
        """Render the SVG layout to image bytes for the key.

        Uses the SVG-native pipeline: the SVG is rasterised at
        *key_size* directly (vector scaling via ``viewBox``) with a
        black background injected at the SVG level.  No Pillow resize
        or compositing is needed.

        Falls back to the legacy Pillow path for BMP format.

        Parameters
        ----------
        key_size
            Target key dimensions ``(width, height)`` in pixels.
        image_format
            Image encoding format (``"JPEG"`` or ``"BMP"``).

        Returns
        -------
        bytes
            Encoded image bytes.
        """
        self._renderer.set_target_size(*key_size)
        fmt = image_format.upper()
        out_fmt = "jpeg" if fmt == "JPEG" else "bmp"
        return self._renderer.render_bytes(
            output_format=out_fmt,
            background="black",
        )

    async def _dispatch_event(self, pressed: bool) -> None:
        """Dispatch a key press/release through the event map.

        All matching handlers (simple and compound) are called.
        Falls back to the base KeySlot handlers if the event map
        returns no matches.
        """
        handlers = (
            self._events.handle_key_press()
            if pressed
            else self._events.handle_key_release()
        )

        if handlers:
            for handler in handlers:
                await handler()
        else:
            await super()._dispatch_event(pressed)

    async def start_busy(self) -> None:
        """Enter the busy state and start the spinner animation.

        While busy, the key suppresses further ``start_busy()`` calls.
        The spinner keeps running until :meth:`finish_busy` is called.

        If no spinner is configured in the manifest the busy flag is
        still set (suppressing duplicate calls) but no animation plays.
        """
        if self._busy:
            return
        self._busy = True
        await self._start_spinner()

    async def finish_busy(self) -> None:
        """Stop the spinner and exit the busy state.

        Call this from your application code when the asynchronous
        work is truly complete (e.g. after receiving a state update
        from an external system).

        If the key is not currently busy this is a no-op.
        """
        if not self._busy:
            return
        await self._stop_spinner()
        self._busy = False
        self._dirty = True

    async def _start_spinner(self) -> None:
        """Start the spinner animation if configured."""
        if (
            self._spec.spinner is None
            or self._push_fn is None
            or self._key_size is None
        ):
            return

        width, height = self._key_size
        rendered_svg = self._renderer.render_svg()
        spinner_frames = SpinnerFrames(
            self._spec,
            width=width,
            height=height,
            rendered_svg=rendered_svg,
        )
        self._spinner_frames = spinner_frames

        self._animator = SpinnerAnimator(
            frames=await asyncio.to_thread(lambda: spinner_frames.frames),
            interval_ms=spinner_frames.interval_ms,
            push_fn=self._push_fn,
        )
        await self._animator.start()

    async def _stop_spinner(self) -> None:
        """Stop the spinner animation."""
        if self._animator is not None:
            await self._animator.stop()
            self._animator = None

spec property

spec: PackageSpec

The package specification backing this key.

is_busy property

is_busy: bool

Whether a busy-guarded handler is currently executing.

is_animating property

is_animating: bool

Whether a spinner animation is currently running.

set_push_fn

set_push_fn(push_fn: PushFn, key_size: tuple[int, int]) -> None

Set the async function used to push animation frames to the device.

Parameters:

Name	Type	Description	Default
push_fn	PushFn	Async callable (frame_bytes) -> None.	required
key_size	tuple[int, int]	(width, height) of the device's key — used to size spinner frames.	required

Source code in src/deux/dui/key.py

def set_push_fn(self, push_fn: PushFn, key_size: tuple[int, int]) -> None:
    """Set the async function used to push animation frames to the device.

    Parameters
    ----------
    push_fn
        Async callable ``(frame_bytes) -> None``.
    key_size
        ``(width, height)`` of the device's key — used to size
        spinner frames.
    """
    self._push_fn = push_fn
    self._key_size = key_size

set

set(name: str, value: Any) -> DuiKey

Set a binding value. Marks the key dirty if changed.

Parameters:

Name	Type	Description	Default
name	str	Binding name as defined in the manifest.	required
value	Any	New value (type depends on binding kind).	required

Returns:

Type	Description
DuiKey	self, for method chaining.

Raises:

Type	Description
KeyError	If name is not a known binding.

Source code in src/deux/dui/key.py

def set(self, name: str, value: Any) -> DuiKey:
    """Set a binding value.  Marks the key dirty if changed.

    Parameters
    ----------
    name
        Binding name as defined in the manifest.
    value
        New value (type depends on binding kind).

    Returns
    -------
    DuiKey
        self, for method chaining.

    Raises
    ------
    KeyError
        If *name* is not a known binding.
    """
    if self._renderer.set(name, value):
        self._dirty = True
    return self

set_many

set_many(**kwargs: Any) -> DuiKey

Set multiple binding values at once.

Returns:

Type	Description
DuiKey	self, for method chaining.

Source code in src/deux/dui/key.py

def set_many(self, **kwargs: Any) -> DuiKey:
    """Set multiple binding values at once.

    Returns
    -------
    DuiKey
        self, for method chaining.
    """
    if self._renderer.set_many(**kwargs):
        self._dirty = True
    return self

get

get(name: str) -> Any

Get the current value of a binding.

Raises:

Type	Description
KeyError	If name is not a known binding.

Source code in src/deux/dui/key.py

def get(self, name: str) -> Any:
    """Get the current value of a binding.

    Raises
    ------
    KeyError
        If *name* is not a known binding.
    """
    return self._renderer.get(name)

collect_icon_names

collect_icon_names() -> builtins.set[str]

Return all Iconify icon identifiers needed by this key.

Returns:

Type	Description
set[str]	A set of "prefix:icon" strings referenced by the key's bindings (defaults and current values).

Source code in src/deux/dui/key.py

def collect_icon_names(self) -> builtins.set[str]:
    """Return all Iconify icon identifiers needed by this key.

    Returns
    -------
    set[str]
        A set of ``"prefix:icon"`` strings referenced by the key's
        bindings (defaults and current values).
    """
    return self._renderer.collect_icon_names()

set_rendering_context

set_rendering_context(ctx: RenderingContext | None) -> None

Set the explicit rendering context for this key.

Parameters:

Name	Type	Description	Default
ctx	RenderingContext or None	The rendering context to apply, or None to revert to module-level defaults.	required

Source code in src/deux/dui/key.py

def set_rendering_context(self, ctx: RenderingContext | None) -> None:
    """Set the explicit rendering context for this key.

    Parameters
    ----------
    ctx : RenderingContext or None
        The rendering context to apply, or ``None`` to revert to
        module-level defaults.
    """
    self._renderer.set_rendering_context(ctx)

set_range

set_range(name: str, value: float, *, min_val: float = 0, max_val: float = 1) -> DuiKey

Set a range/slider binding using a domain-scale value.

Normalises value from [min_val, max_val] to [0.0, 1.0] and delegates to :meth:set.

Parameters:

Name	Type	Description	Default
name	str	Binding name (must be a range or slider binding).	required
value	float	Value in domain units (e.g. 0–100 for a percentage).	required
min_val	float	Lower bound of the domain range.	0
max_val	float	Upper bound of the domain range.	1

Returns:

Type	Description
DuiKey	self, for method chaining.

Raises:

Type	Description
KeyError	If name is not a known binding.
ValueError	If min_val equals max_val.

Source code in src/deux/dui/key.py

def set_range(
    self, name: str, value: float, *, min_val: float = 0, max_val: float = 1
) -> DuiKey:
    """Set a range/slider binding using a domain-scale value.

    Normalises *value* from ``[min_val, max_val]`` to ``[0.0, 1.0]``
    and delegates to :meth:`set`.

    Parameters
    ----------
    name
        Binding name (must be a ``range`` or ``slider`` binding).
    value
        Value in domain units (e.g. 0–100 for a percentage).
    min_val
        Lower bound of the domain range.
    max_val
        Upper bound of the domain range.

    Returns
    -------
    DuiKey
        self, for method chaining.

    Raises
    ------
    KeyError
        If *name* is not a known binding.
    ValueError
        If *min_val* equals *max_val*.
    """
    if min_val == max_val:
        raise ValueError("min_val and max_val must not be equal")
    clamped = max(min_val, min(max_val, value))
    normalised = (clamped - min_val) / (max_val - min_val)
    return self.set(name, normalised)

adjust_range

adjust_range(name: str, delta: float, *, min_val: float = 0, max_val: float = 1) -> float

Adjust a range/slider binding by delta domain-scale units.

Reads the current normalised value, denormalises it, adds delta, clamps, re-normalises, and calls :meth:set.

Parameters:

Name	Type	Description	Default
name	str	Binding name (must be a range or slider binding).	required
delta	float	Amount to add in domain units (negative to decrease).	required
min_val	float	Lower bound of the domain range.	0
max_val	float	Upper bound of the domain range.	1

Returns:

Type	Description
float	The new value in domain units (clamped to [min_val, max_val]), so callers can use it for display without back-computing.

Raises:

Type	Description
KeyError	If name is not a known binding.
ValueError	If min_val equals max_val.

Source code in src/deux/dui/key.py

def adjust_range(
    self, name: str, delta: float, *, min_val: float = 0, max_val: float = 1
) -> float:
    """Adjust a range/slider binding by *delta* domain-scale units.

    Reads the current normalised value, denormalises it, adds *delta*,
    clamps, re-normalises, and calls :meth:`set`.

    Parameters
    ----------
    name
        Binding name (must be a ``range`` or ``slider`` binding).
    delta
        Amount to add in domain units (negative to decrease).
    min_val
        Lower bound of the domain range.
    max_val
        Upper bound of the domain range.

    Returns
    -------
    float
        The new value in domain units (clamped to
        ``[min_val, max_val]``), so callers can use it for display
        without back-computing.

    Raises
    ------
    KeyError
        If *name* is not a known binding.
    ValueError
        If *min_val* equals *max_val*.
    """
    if min_val == max_val:
        raise ValueError("min_val and max_val must not be equal")
    current_norm = float(self.get(name) or 0.0)
    current_domain = min_val + current_norm * (max_val - min_val)
    new_domain = max(min_val, min(max_val, current_domain + delta))
    normalised = (new_domain - min_val) / (max_val - min_val)
    self.set(name, normalised)
    return new_domain

get_range

get_range(name: str, *, min_val: float = 0, max_val: float = 1) -> float

Get a range/slider binding denormalised to domain units.

Parameters:

Name	Type	Description	Default
name	str	Binding name.	required
min_val	float	Lower bound of the domain range.	0
max_val	float	Upper bound of the domain range.	1

Returns:

Type	Description
float	The current value in domain units.

Raises:

Type	Description
KeyError	If name is not a known binding.
ValueError	If min_val equals max_val.

Source code in src/deux/dui/key.py

def get_range(
    self, name: str, *, min_val: float = 0, max_val: float = 1
) -> float:
    """Get a range/slider binding denormalised to domain units.

    Parameters
    ----------
    name
        Binding name.
    min_val
        Lower bound of the domain range.
    max_val
        Upper bound of the domain range.

    Returns
    -------
    float
        The current value in domain units.

    Raises
    ------
    KeyError
        If *name* is not a known binding.
    ValueError
        If *min_val* equals *max_val*.
    """
    if min_val == max_val:
        raise ValueError("min_val and max_val must not be equal")
    current_norm = float(self.get(name) or 0.0)
    return min_val + current_norm * (max_val - min_val)

render_image

render_image(key_size: tuple[int, int], image_format: str = 'JPEG') -> bytes

Render the SVG layout to image bytes for the key.

Uses the SVG-native pipeline: the SVG is rasterised at key_size directly (vector scaling via viewBox) with a black background injected at the SVG level. No Pillow resize or compositing is needed.

Falls back to the legacy Pillow path for BMP format.

Parameters:

Name	Type	Description	Default
key_size	tuple[int, int]	Target key dimensions (width, height) in pixels.	required
image_format	str	Image encoding format ("JPEG" or "BMP").	'JPEG'

Returns:

Type	Description
bytes	Encoded image bytes.

Source code in src/deux/dui/key.py

def render_image(
    self,
    key_size: tuple[int, int],
    image_format: str = "JPEG",
) -> bytes:
    """Render the SVG layout to image bytes for the key.

    Uses the SVG-native pipeline: the SVG is rasterised at
    *key_size* directly (vector scaling via ``viewBox``) with a
    black background injected at the SVG level.  No Pillow resize
    or compositing is needed.

    Falls back to the legacy Pillow path for BMP format.

    Parameters
    ----------
    key_size
        Target key dimensions ``(width, height)`` in pixels.
    image_format
        Image encoding format (``"JPEG"`` or ``"BMP"``).

    Returns
    -------
    bytes
        Encoded image bytes.
    """
    self._renderer.set_target_size(*key_size)
    fmt = image_format.upper()
    out_fmt = "jpeg" if fmt == "JPEG" else "bmp"
    return self._renderer.render_bytes(
        output_format=out_fmt,
        background="black",
    )

start_busy async

start_busy() -> None

Enter the busy state and start the spinner animation.

While busy, the key suppresses further start_busy() calls. The spinner keeps running until :meth:finish_busy is called.

If no spinner is configured in the manifest the busy flag is still set (suppressing duplicate calls) but no animation plays.

Source code in src/deux/dui/key.py

async def start_busy(self) -> None:
    """Enter the busy state and start the spinner animation.

    While busy, the key suppresses further ``start_busy()`` calls.
    The spinner keeps running until :meth:`finish_busy` is called.

    If no spinner is configured in the manifest the busy flag is
    still set (suppressing duplicate calls) but no animation plays.
    """
    if self._busy:
        return
    self._busy = True
    await self._start_spinner()

finish_busy async

finish_busy() -> None

Stop the spinner and exit the busy state.

Call this from your application code when the asynchronous work is truly complete (e.g. after receiving a state update from an external system).

If the key is not currently busy this is a no-op.

Source code in src/deux/dui/key.py

async def finish_busy(self) -> None:
    """Stop the spinner and exit the busy state.

    Call this from your application code when the asynchronous
    work is truly complete (e.g. after receiving a state update
    from an external system).

    If the key is not currently busy this is a no-op.
    """
    if not self._busy:
        return
    await self._stop_spinner()
    self._busy = False
    self._dirty = True

PackageError

Bases: DeuxError

Raised when a .dui package is invalid or cannot be loaded.

Source code in src/deux/dui/loader.py

class PackageError(DeuxError):
    """Raised when a .dui package is invalid or cannot be loaded."""

DuiRepository

Registry of .dui package search paths with in-memory caching.

Directories are searched in priority order — the most recently added path wins when two directories contain a package with the same name. The bundled packages directory is always present as the lowest-priority source and cannot be removed.

Parameters:

Name	Type	Description	Default
include_bundled	bool	Whether to include the bundled packages directory. Set to False only in tests that need a completely empty repo.	True

Examples:

::

repo = DuiRepository()
repo.add_path("/home/user/my-packages")
spec = repo.resolve("IconKey")

Source code in src/deux/dui/repository.py

class DuiRepository:
    """Registry of .dui package search paths with in-memory caching.

    Directories are searched in *priority order* — the most recently
    added path wins when two directories contain a package with the
    same name.  The bundled packages directory is always present as
    the lowest-priority source and cannot be removed.

    Parameters
    ----------
    include_bundled : bool, default=True
        Whether to include the bundled packages directory.  Set to
        ``False`` only in tests that need a completely empty repo.

    Examples
    --------
    ::

        repo = DuiRepository()
        repo.add_path("/home/user/my-packages")
        spec = repo.resolve("IconKey")
    """

    def __init__(self, *, include_bundled: bool = True) -> None:
        self._paths: list[Path] = []
        self._cache: dict[str, PackageSpec] = {}
        self._include_bundled = include_bundled

    # ── Path management ───────────────────────────────────────────────

    def add_path(self, path: str | Path) -> None:
        """Register a directory as a DUI package source.

        The directory is inserted at the *highest* priority position.
        If it is already registered it is moved to the top.  The
        in-memory cache is cleared so that subsequent :meth:`resolve`
        calls pick up any overrides.

        Parameters
        ----------
        path : str or Path
            Directory containing ``.dui`` package subdirectories.

        Raises
        ------
        PackageError
            If *path* does not exist or is not a directory.
        """
        resolved = Path(path).expanduser().resolve()
        if not resolved.is_dir():
            raise PackageError(f"DUI path is not a directory: {resolved}")

        # Move to top if already present, otherwise append
        if resolved in self._paths:
            self._paths.remove(resolved)
        self._paths.append(resolved)
        self._cache.clear()
        logger.info("Added DUI path: %s (priority %d)", resolved, len(self._paths))

    def remove_path(self, path: str | Path) -> None:
        """Unregister a directory.  Clears the cache.

        Parameters
        ----------
        path : str or Path
            Previously registered directory.

        Raises
        ------
        ValueError
            If *path* is not currently registered.
        """
        resolved = Path(path).expanduser().resolve()
        try:
            self._paths.remove(resolved)
        except ValueError:
            raise ValueError(f"Path not registered: {resolved}") from None
        self._cache.clear()
        logger.info("Removed DUI path: %s", resolved)

    def list_paths(self) -> list[Path]:
        """Return registered search paths in priority order (highest first).

        The bundled directory is included at the end when
        ``include_bundled`` is ``True``.

        Returns
        -------
        list[Path]
            Ordered list of directories.
        """
        # Reverse so that last-added (highest priority) comes first
        result = list(reversed(self._paths))
        if self._include_bundled and _BUNDLED_DIR.is_dir():
            result.append(_BUNDLED_DIR)
        return result

    # ── Resolution & caching ──────────────────────────────────────────

    def resolve(self, name: str) -> PackageSpec:
        """Look up a package by name and return a cached spec.

        Search order: user paths (most recently added first), then
        bundled packages.  The result is cached so that repeated calls
        with the same *name* return the identical :class:`PackageSpec`
        object without re-reading the filesystem.

        Parameters
        ----------
        name : str
            Package name **without** the ``.dui`` suffix
            (e.g. ``"IconKey"``, not ``"IconKey.dui"``).

        Returns
        -------
        PackageSpec
            A validated, frozen package specification.

        Raises
        ------
        PackageError
            If no package with that name exists in any registered path.
        """
        cached = self._cache.get(name)
        if cached is not None:
            return cached

        pkg_dir = self._find(name)
        if pkg_dir is None:
            paths_desc = ", ".join(str(p) for p in self.list_paths()) or "(none)"
            raise PackageError(
                f"DUI package '{name}' not found. "
                f"Searched paths: {paths_desc}"
            )

        spec = load_package(pkg_dir)
        self._cache[name] = spec
        logger.debug("Resolved DUI package '%s' from %s", name, pkg_dir)
        return spec

    def _find(self, name: str) -> Path | None:
        """Locate the directory for *name* across all search paths.

        Parameters
        ----------
        name : str
            Package name without the ``.dui`` suffix.

        Returns
        -------
        Path or None
            Absolute path to the ``.dui`` directory, or ``None`` if
            not found in any registered path.
        """
        dir_name = f"{name}.dui"

        # User paths in priority order (last-added first)
        for base in reversed(self._paths):
            candidate = base / dir_name
            if candidate.is_dir():
                return candidate

        # Bundled fallback
        if self._include_bundled and _BUNDLED_DIR.is_dir():
            candidate = _BUNDLED_DIR / dir_name
            if candidate.is_dir():
                return candidate

        return None

    # ── Cache management ──────────────────────────────────────────────

    def clear_cache(self) -> None:
        """Drop all cached :class:`PackageSpec` objects.

        Subsequent :meth:`resolve` calls will re-read packages from
        disk.
        """
        count = len(self._cache)
        self._cache.clear()
        if count:
            logger.debug("Cleared DUI package cache (%d entries)", count)

    def invalidate(self, name: str) -> None:
        """Remove a single package from the cache.

        Use this after editing a ``.dui`` package on disk to force
        :meth:`resolve` to reload it.

        Parameters
        ----------
        name : str
            Package name to invalidate.
        """
        removed = self._cache.pop(name, None)
        if removed is not None:
            logger.debug("Invalidated cached DUI package '%s'", name)

    # ── Introspection ─────────────────────────────────────────────────

    def list_packages(self) -> list[str]:
        """List all package names visible across all search paths.

        Packages are returned in alphabetical order.  If the same name
        exists in multiple paths only one entry is returned.

        Returns
        -------
        list[str]
            Sorted package names (without the ``.dui`` suffix).
        """
        names: set[str] = set()
        for base in self.list_paths():
            if base.is_dir():
                for entry in base.iterdir():
                    if entry.is_dir() and entry.suffix == ".dui":
                        names.add(entry.stem)
        return sorted(names)

    def __repr__(self) -> str:
        n_paths = len(self._paths) + (1 if self._include_bundled else 0)
        return (
            f"DuiRepository(paths={n_paths}, "
            f"cached={len(self._cache)}, "
            f"bundled={self._include_bundled})"
        )

add_path

add_path(path: str | Path) -> None

Register a directory as a DUI package source.

The directory is inserted at the highest priority position. If it is already registered it is moved to the top. The in-memory cache is cleared so that subsequent :meth:resolve calls pick up any overrides.

Parameters:

Name	Type	Description	Default
path	str or Path	Directory containing .dui package subdirectories.	required

Raises:

Type	Description
PackageError	If path does not exist or is not a directory.

Source code in src/deux/dui/repository.py

def add_path(self, path: str | Path) -> None:
    """Register a directory as a DUI package source.

    The directory is inserted at the *highest* priority position.
    If it is already registered it is moved to the top.  The
    in-memory cache is cleared so that subsequent :meth:`resolve`
    calls pick up any overrides.

    Parameters
    ----------
    path : str or Path
        Directory containing ``.dui`` package subdirectories.

    Raises
    ------
    PackageError
        If *path* does not exist or is not a directory.
    """
    resolved = Path(path).expanduser().resolve()
    if not resolved.is_dir():
        raise PackageError(f"DUI path is not a directory: {resolved}")

    # Move to top if already present, otherwise append
    if resolved in self._paths:
        self._paths.remove(resolved)
    self._paths.append(resolved)
    self._cache.clear()
    logger.info("Added DUI path: %s (priority %d)", resolved, len(self._paths))

remove_path

remove_path(path: str | Path) -> None

Unregister a directory. Clears the cache.

Parameters:

Name	Type	Description	Default
path	str or Path	Previously registered directory.	required

Raises:

Type	Description
ValueError	If path is not currently registered.

Source code in src/deux/dui/repository.py

def remove_path(self, path: str | Path) -> None:
    """Unregister a directory.  Clears the cache.

    Parameters
    ----------
    path : str or Path
        Previously registered directory.

    Raises
    ------
    ValueError
        If *path* is not currently registered.
    """
    resolved = Path(path).expanduser().resolve()
    try:
        self._paths.remove(resolved)
    except ValueError:
        raise ValueError(f"Path not registered: {resolved}") from None
    self._cache.clear()
    logger.info("Removed DUI path: %s", resolved)

list_paths

list_paths() -> list[Path]

Return registered search paths in priority order (highest first).

The bundled directory is included at the end when include_bundled is True.

Returns:

Type	Description
list[Path]	Ordered list of directories.

Source code in src/deux/dui/repository.py

def list_paths(self) -> list[Path]:
    """Return registered search paths in priority order (highest first).

    The bundled directory is included at the end when
    ``include_bundled`` is ``True``.

    Returns
    -------
    list[Path]
        Ordered list of directories.
    """
    # Reverse so that last-added (highest priority) comes first
    result = list(reversed(self._paths))
    if self._include_bundled and _BUNDLED_DIR.is_dir():
        result.append(_BUNDLED_DIR)
    return result

resolve

resolve(name: str) -> PackageSpec

Look up a package by name and return a cached spec.

Search order: user paths (most recently added first), then bundled packages. The result is cached so that repeated calls with the same name return the identical :class:PackageSpec object without re-reading the filesystem.

Parameters:

Name	Type	Description	Default
name	str	Package name without the .dui suffix (e.g. "IconKey", not "IconKey.dui").	required

Returns:

Type	Description
PackageSpec	A validated, frozen package specification.

Raises:

Type	Description
PackageError	If no package with that name exists in any registered path.

Source code in src/deux/dui/repository.py

def resolve(self, name: str) -> PackageSpec:
    """Look up a package by name and return a cached spec.

    Search order: user paths (most recently added first), then
    bundled packages.  The result is cached so that repeated calls
    with the same *name* return the identical :class:`PackageSpec`
    object without re-reading the filesystem.

    Parameters
    ----------
    name : str
        Package name **without** the ``.dui`` suffix
        (e.g. ``"IconKey"``, not ``"IconKey.dui"``).

    Returns
    -------
    PackageSpec
        A validated, frozen package specification.

    Raises
    ------
    PackageError
        If no package with that name exists in any registered path.
    """
    cached = self._cache.get(name)
    if cached is not None:
        return cached

    pkg_dir = self._find(name)
    if pkg_dir is None:
        paths_desc = ", ".join(str(p) for p in self.list_paths()) or "(none)"
        raise PackageError(
            f"DUI package '{name}' not found. "
            f"Searched paths: {paths_desc}"
        )

    spec = load_package(pkg_dir)
    self._cache[name] = spec
    logger.debug("Resolved DUI package '%s' from %s", name, pkg_dir)
    return spec

clear_cache

clear_cache() -> None

Drop all cached :class:PackageSpec objects.

Subsequent :meth:resolve calls will re-read packages from disk.

Source code in src/deux/dui/repository.py

def clear_cache(self) -> None:
    """Drop all cached :class:`PackageSpec` objects.

    Subsequent :meth:`resolve` calls will re-read packages from
    disk.
    """
    count = len(self._cache)
    self._cache.clear()
    if count:
        logger.debug("Cleared DUI package cache (%d entries)", count)

invalidate

invalidate(name: str) -> None

Remove a single package from the cache.

Use this after editing a .dui package on disk to force :meth:resolve to reload it.

Parameters:

Name	Type	Description	Default
name	str	Package name to invalidate.	required

Source code in src/deux/dui/repository.py

def invalidate(self, name: str) -> None:
    """Remove a single package from the cache.

    Use this after editing a ``.dui`` package on disk to force
    :meth:`resolve` to reload it.

    Parameters
    ----------
    name : str
        Package name to invalidate.
    """
    removed = self._cache.pop(name, None)
    if removed is not None:
        logger.debug("Invalidated cached DUI package '%s'", name)

list_packages

list_packages() -> list[str]

List all package names visible across all search paths.

Packages are returned in alphabetical order. If the same name exists in multiple paths only one entry is returned.

Returns:

Type	Description
list[str]	Sorted package names (without the .dui suffix).

Source code in src/deux/dui/repository.py

def list_packages(self) -> list[str]:
    """List all package names visible across all search paths.

    Packages are returned in alphabetical order.  If the same name
    exists in multiple paths only one entry is returned.

    Returns
    -------
    list[str]
        Sorted package names (without the ``.dui`` suffix).
    """
    names: set[str] = set()
    for base in self.list_paths():
        if base.is_dir():
            for entry in base.iterdir():
                if entry.is_dir() and entry.suffix == ".dui":
                    names.add(entry.stem)
    return sorted(names)

BindingType

Bases: Enum

Supported binding types for SVG node manipulation.

Source code in src/deux/dui/schema.py

class BindingType(Enum):
    """Supported binding types for SVG node manipulation."""

    TEXT = "text"
    IMAGE = "image"
    VISIBILITY = "visibility"
    COLOR = "color"
    RANGE = "range"
    SLIDER = "slider"
    TOGGLE = "toggle"
    ICONIFY = "iconify"
    LIST = "list"
    TRANSFORM = "transform"
    CSS_CLASS = "css_class"

ColorBinding dataclass

Bind a colour value to an SVG element's fill, stroke, or color.

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class ColorBinding:
    """Bind a colour value to an SVG element's fill, stroke, or color."""

    node: str
    attribute: str = "fill"
    default: str = "#ffffff"

    def __post_init__(self) -> None:
        if self.attribute not in _COLOR_ATTRIBUTES:
            msg = (
                f"Invalid color attribute {self.attribute!r}; "
                f"must be one of {sorted(_COLOR_ATTRIBUTES)}"
            )
            raise ValueError(msg)

    def default_value(self) -> Any:
        """Return the initial stored value for this binding."""
        return self.default

default_value

default_value() -> Any

Return the initial stored value for this binding.

Source code in src/deux/dui/schema.py

def default_value(self) -> Any:
    """Return the initial stored value for this binding."""
    return self.default

CssClassBinding dataclass

Bind a CSS class string to an SVG element's class attribute.

The binding replaces the entire class attribute value on the target node. Setting an empty string removes the attribute.

Parameters:

Name	Type	Description	Default
node	str	ID of the SVG element whose class attribute is controlled.	required
default	str	Initial class value applied when no explicit value has been set.	''

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class CssClassBinding:
    """Bind a CSS class string to an SVG element's ``class`` attribute.

    The binding replaces the entire ``class`` attribute value on the
    target node.  Setting an empty string removes the attribute.

    Parameters
    ----------
    node : str
        ID of the SVG element whose ``class`` attribute is controlled.
    default : str
        Initial class value applied when no explicit value has been set.
    """

    node: str
    default: str = ""

    def default_value(self) -> Any:
        """Return the initial stored value for this binding."""
        return self.default

default_value

default_value() -> Any

Return the initial stored value for this binding.

Source code in src/deux/dui/schema.py

def default_value(self) -> Any:
    """Return the initial stored value for this binding."""
    return self.default

EventMapping dataclass

Map a physical input to a named semantic event.

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class EventMapping:
    """Map a physical input to a named semantic event."""

    name: str
    source: str
    direction: str | None = None
    max_duration_ms: int | None = None
    hold_ms: int | None = None
    accumulate: bool = False
    accumulate_delay: float | None = None
    accumulate_max_steps: int | None = None

IconifyBinding dataclass

Load an Iconify icon by name and embed it into an SVG <g> element.

The icon name follows the Iconify convention <prefix>:<name> (for example line-md:home). Icons are fetched from https://api.iconify.design on first use and cached in-process.

The resolved icon SVG is inserted as children of the target <g> node, scaled to a size × size square. Setting the binding value to None or an empty string removes any previously embedded icon from the node.

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class IconifyBinding:
    """Load an Iconify icon by name and embed it into an SVG ``<g>`` element.

    The icon name follows the Iconify convention ``<prefix>:<name>`` (for
    example ``line-md:home``).  Icons are fetched from
    ``https://api.iconify.design`` on first use and cached in-process.

    The resolved icon SVG is inserted as children of the target ``<g>``
    node, scaled to a ``size`` × ``size`` square.  Setting the binding
    value to ``None`` or an empty string removes any previously embedded
    icon from the node.
    """

    node: str
    size: int
    default: str = ""

    def default_value(self) -> Any:
        """Return the initial stored value for this binding."""
        return self.default

default_value

default_value() -> Any

Return the initial stored value for this binding.

Source code in src/deux/dui/schema.py

def default_value(self) -> Any:
    """Return the initial stored value for this binding."""
    return self.default

ImageBinding dataclass

Bind a PIL Image to an SVG element's href.

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class ImageBinding:
    """Bind a PIL Image to an <image> SVG element's href."""

    node: str
    fit: ImageFit = ImageFit.COVER
    placeholder_node: str | None = None

    # ImageBinding has no default-displayable value; renderer treats every
    # assignment as a change (PIL Image equality is expensive/unreliable).
    force_dirty = True

    def default_value(self) -> Any:
        """Return the initial stored value for this binding."""
        return None

default_value

default_value() -> Any

Return the initial stored value for this binding.

Source code in src/deux/dui/schema.py

def default_value(self) -> Any:
    """Return the initial stored value for this binding."""
    return None

ImageFit

Bases: Enum

Image scaling strategy within the target node dimensions.

Source code in src/deux/dui/schema.py

class ImageFit(Enum):
    """Image scaling strategy within the target node dimensions."""

    COVER = "cover"
    CONTAIN = "contain"
    FILL = "fill"

OverflowMode

Bases: Enum

Text overflow handling strategy.

Source code in src/deux/dui/schema.py

class OverflowMode(Enum):
    """Text overflow handling strategy."""

    ELLIPSIS = "ellipsis"
    CLIP = "clip"

PackageSpec dataclass

Fully validated, immutable representation of a loaded .dui package.

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class PackageSpec:
    """Fully validated, immutable representation of a loaded .dui package."""

    name: str
    type: PackageType
    version: int
    svg_source: str
    bindings: dict[str, Binding] = field(default_factory=dict)
    events: tuple[EventMapping, ...] = ()
    regions: tuple[Region, ...] = ()
    assets: dict[str, bytes] = field(default_factory=dict)
    spinner: SpinnerSpec | None = None
    description: str | None = None
    author: str | None = None
    license: str | None = None
    tags: tuple[str, ...] = ()
    category: str | None = None
    url: str | None = None
    icon: str | None = None
    min_deux: str | None = None
    device: tuple[str, ...] = ()

PackageType

Bases: Enum

Hardware target for a .dui package.

Source code in src/deux/dui/schema.py

class PackageType(Enum):
    """Hardware target for a .dui package."""

    TOUCH_STRIP_CARD = "TouchStripCard"
    KEY = "Key"

RangeBinding dataclass

Scale an SVG element's width or height proportional to a 0–1 value.

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class RangeBinding:
    """Scale an SVG element's width or height proportional to a 0–1 value."""

    node: str
    default: float = 0.0
    direction: RangeDirection = RangeDirection.HORIZONTAL

    def default_value(self) -> Any:
        """Return the initial stored value for this binding."""
        return self.default

default_value

default_value() -> Any

Return the initial stored value for this binding.

Source code in src/deux/dui/schema.py

def default_value(self) -> Any:
    """Return the initial stored value for this binding."""
    return self.default

RangeDirection

Bases: Enum

Axis along which a range binding scales an SVG element.

Source code in src/deux/dui/schema.py

class RangeDirection(Enum):
    """Axis along which a range binding scales an SVG element."""

    HORIZONTAL = "horizontal"
    VERTICAL = "vertical"

Region dataclass

A touchscreen hit-test region for touch events.

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class Region:
    """A touchscreen hit-test region for touch events."""

    name: str
    x: int
    y: int
    width: int
    height: int
    events: tuple[str, ...] = ()

RotateTransform dataclass

Rotate an SVG element between two angles proportional to a 0–1 value.

The element is rotated by interpolating linearly between from_angle and to_angle based on the binding's current value.

Parameters:

Name	Type	Description	Default
from_angle	float	Rotation angle (degrees) when the value is 0.0.	0.0
to_angle	float	Rotation angle (degrees) when the value is 1.0.	360.0
origin	str	Rotation origin. "center" resolves to the element's bounding box center at render time. An explicit "x y" string sets a fixed origin in SVG user-space coordinates.	'center'

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class RotateTransform:
    """Rotate an SVG element between two angles proportional to a 0–1 value.

    The element is rotated by interpolating linearly between *from_angle*
    and *to_angle* based on the binding's current value.

    Parameters
    ----------
    from_angle : float
        Rotation angle (degrees) when the value is 0.0.
    to_angle : float
        Rotation angle (degrees) when the value is 1.0.
    origin : str
        Rotation origin.  ``"center"`` resolves to the element's bounding
        box center at render time.  An explicit ``"x y"`` string sets a
        fixed origin in SVG user-space coordinates.
    """

    from_angle: float = 0.0
    to_angle: float = 360.0
    origin: str = "center"

SliderBinding dataclass

Translate an SVG element between two positions proportional to a 0–1 value.

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class SliderBinding:
    """Translate an SVG element between two positions proportional to a 0–1 value."""

    node: str
    default: float = 0.0
    direction: RangeDirection = RangeDirection.HORIZONTAL
    min_pos: float = 0.0
    max_pos: float = 0.0

    def default_value(self) -> Any:
        """Return the initial stored value for this binding."""
        return self.default

default_value

default_value() -> Any

Return the initial stored value for this binding.

Source code in src/deux/dui/schema.py

def default_value(self) -> Any:
    """Return the initial stored value for this binding."""
    return self.default

SpinnerSpec dataclass

Configuration for a spinner animation.

The spinner is started and stopped explicitly by the application via :meth:~deux.dui.card.DuiCard.start_busy / :meth:~deux.dui.card.DuiCard.finish_busy (and the equivalent methods on :class:~deux.dui.key.DuiKey). It provides visual feedback by cycling pre-rendered animation frames on the key or card panel.

Parameters:

Name	Type	Description	Default
type	SpinnerType	Animation strategy: rotation (rotate an SVG node), pulse (fade opacity), or custom (user-provided frames).	required
node	str | None	SVG element ID to animate (required for rotation and pulse; ignored for custom).	None
frames	int	Number of frames per animation cycle.	DEFAULT_SPINNER_FRAMES
interval_ms	int	Milliseconds between frames.	DEFAULT_SPINNER_INTERVAL_MS
background_node	str | None	Optional SVG element ID shown behind the spinner during busy state. The node is made visible when the spinner is active and hidden at rest, but it is not animated (no rotation, pulse, or opacity changes are applied to it). Ignored for custom type spinners.	None

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class SpinnerSpec:
    """Configuration for a spinner animation.

    The spinner is started and stopped explicitly by the application
    via :meth:`~deux.dui.card.DuiCard.start_busy` /
    :meth:`~deux.dui.card.DuiCard.finish_busy` (and the equivalent
    methods on :class:`~deux.dui.key.DuiKey`).  It provides visual
    feedback by cycling pre-rendered animation frames on the key or
    card panel.

    Parameters
    ----------
    type
        Animation strategy: ``rotation`` (rotate an SVG node),
        ``pulse`` (fade opacity), or ``custom`` (user-provided frames).
    node
        SVG element ID to animate (required for ``rotation`` and
        ``pulse``; ignored for ``custom``).
    frames
        Number of frames per animation cycle.
    interval_ms
        Milliseconds between frames.
    background_node
        Optional SVG element ID shown behind the spinner during busy
        state.  The node is made visible when the spinner is active and
        hidden at rest, but it is **not** animated (no rotation, pulse,
        or opacity changes are applied to it).  Ignored for ``custom``
        type spinners.
    """

    type: SpinnerType
    node: str | None = None
    frames: int = DEFAULT_SPINNER_FRAMES
    interval_ms: int = DEFAULT_SPINNER_INTERVAL_MS
    background_node: str | None = None

SpinnerType

Bases: Enum

Animation strategy for the busy spinner.

Source code in src/deux/dui/schema.py

class SpinnerType(Enum):
    """Animation strategy for the busy spinner."""

    ROTATION = "rotation"
    PULSE = "pulse"
    CUSTOM = "custom"

TextBinding dataclass

Bind a value to a <text> SVG element's content.

When wrap is True the renderer word-wraps the text into multiple <tspan> lines that each fit within max_width pixels. Font metrics are auto-detected from the SVG <text> element. If the wrapped text exceeds max_height, the last visible line is truncated according to overflow.

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class TextBinding:
    """Bind a value to a ``<text>`` SVG element's content.

    When *wrap* is ``True`` the renderer word-wraps the text into
    multiple ``<tspan>`` lines that each fit within *max_width* pixels.
    Font metrics are auto-detected from the SVG ``<text>`` element.
    If the wrapped text exceeds *max_height*, the last visible line is
    truncated according to *overflow*.
    """

    node: str
    default: str = ""
    max_width: int | None = None
    overflow: OverflowMode = OverflowMode.ELLIPSIS
    wrap: bool = False
    max_height: int | None = None
    line_height: float | None = None

    def default_value(self) -> Any:
        """Return the initial stored value for this binding."""
        return self.default

default_value

default_value() -> Any

Return the initial stored value for this binding.

Source code in src/deux/dui/schema.py

def default_value(self) -> Any:
    """Return the initial stored value for this binding."""
    return self.default

ToggleBinding dataclass

Switch between two SVG elements based on a boolean value.

When the value is truthy, node_on is visible and node_off is hidden. When falsy, the opposite applies.

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class ToggleBinding:
    """Switch between two SVG elements based on a boolean value.

    When the value is truthy, ``node_on`` is visible and ``node_off``
    is hidden.  When falsy, the opposite applies.
    """

    node_on: str
    node_off: str
    default: bool = False

    def default_value(self) -> Any:
        """Return the initial stored value for this binding."""
        return self.default

default_value

default_value() -> Any

Return the initial stored value for this binding.

Source code in src/deux/dui/schema.py

def default_value(self) -> Any:
    """Return the initial stored value for this binding."""
    return self.default

TransformBinding dataclass

Apply one or more SVG transforms to a node proportional to a 0–1 value.

Each entry in transforms produces an SVG transform attribute fragment; multiple transforms are composed (space-separated) in order.

Parameters:

Name	Type	Description	Default
node	str	ID of the SVG element to transform.	required
default	float	Initial normalised value (0.0–1.0).	0.0
transforms	tuple[TransformSpec, ...]	Ordered sequence of transform specifications applied to the node.	()

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class TransformBinding:
    """Apply one or more SVG transforms to a node proportional to a 0–1 value.

    Each entry in *transforms* produces an SVG ``transform`` attribute
    fragment; multiple transforms are composed (space-separated) in order.

    Parameters
    ----------
    node : str
        ID of the SVG element to transform.
    default : float
        Initial normalised value (0.0–1.0).
    transforms : tuple[TransformSpec, ...]
        Ordered sequence of transform specifications applied to the node.
    """

    node: str
    default: float = 0.0
    transforms: tuple[TransformSpec, ...] = ()

    def default_value(self) -> Any:
        """Return the initial stored value for this binding."""
        return self.default

default_value

default_value() -> Any

Return the initial stored value for this binding.

Source code in src/deux/dui/schema.py

def default_value(self) -> Any:
    """Return the initial stored value for this binding."""
    return self.default

TransformKind

Bases: Enum

Supported transform operations for SVG nodes.

Source code in src/deux/dui/schema.py

class TransformKind(Enum):
    """Supported transform operations for SVG nodes."""

    ROTATE = "rotate"

VisibilityBinding dataclass

Toggle the display attribute of an SVG element.

Source code in src/deux/dui/schema.py

@dataclass(frozen=True, slots=True)
class VisibilityBinding:
    """Toggle the display attribute of an SVG element."""

    node: str
    default: bool = True

    def default_value(self) -> Any:
        """Return the initial stored value for this binding."""
        return self.default

default_value

default_value() -> Any

Return the initial stored value for this binding.

Source code in src/deux/dui/schema.py

def default_value(self) -> Any:
    """Return the initial stored value for this binding."""
    return self.default

SpinnerFrames

Pre-renders spinner animation frames from an SVG template.

Frames are generated lazily on first access and cached for the lifetime of the instance.

When a bg_tile is provided, each frame is composited onto the background tile before encoding so that transparent regions of the spinner reveal the touchstrip background underneath.

Parameters:

Name	Type	Description	Default
spec	PackageSpec	The package specification containing the SVG source and spinner config.	required
width	int	Target image width in pixels.	required
height	int	Target image height in pixels.	required
image_format	str	Encoding format ("JPEG" or "BMP").	'JPEG'
rendered_svg	str | None	Optional pre-rendered SVG source with bindings already applied.	None
bg_tile	bytes | Image | None	Optional RGB background tile to composite frames onto.	None

Source code in src/deux/dui/spinner.py

class SpinnerFrames:
    """Pre-renders spinner animation frames from an SVG template.

    Frames are generated lazily on first access and cached for the
    lifetime of the instance.

    When a *bg_tile* is provided, each frame is composited onto the
    background tile before encoding so that transparent regions of
    the spinner reveal the touchstrip background underneath.

    Parameters
    ----------
    spec
        The package specification containing the SVG source and spinner config.
    width
        Target image width in pixels.
    height
        Target image height in pixels.
    image_format
        Encoding format (``"JPEG"`` or ``"BMP"``).
    rendered_svg
        Optional pre-rendered SVG source with bindings already applied.
    bg_tile
        Optional RGB background tile to composite frames onto.
    """

    def __init__(
        self,
        spec: PackageSpec,
        width: int,
        height: int,
        image_format: str = "JPEG",
        rendered_svg: str | None = None,
        bg_tile: bytes | Image.Image | None = None,
    ) -> None:
        if spec.spinner is None:
            raise ValueError("PackageSpec has no spinner configuration")
        self._spec = spec
        self._spinner: SpinnerSpec = spec.spinner
        self._width = width
        self._height = height
        self._image_format = image_format
        self._rendered_svg = rendered_svg
        self._bg_tile = bg_tile
        self._cached_frames: list[bytes] | None = None

    @property
    def frame_count(self) -> int:
        """Number of frames in the animation cycle."""
        return self._spinner.frames

    @property
    def interval_ms(self) -> int:
        """Milliseconds between frames."""
        return self._spinner.interval_ms

    @property
    def frames(self) -> list[bytes]:
        """Encoded animation frames, generated on first access."""
        if self._cached_frames is None:
            self._cached_frames = self._generate()
        return self._cached_frames

    def _generate(self) -> list[bytes]:
        """Generate all animation frames."""
        if self._spinner.type == SpinnerType.ROTATION:
            return self._generate_rotation()
        if self._spinner.type == SpinnerType.PULSE:
            return self._generate_pulse()
        return self._generate_custom()

    def _generate_rotation(self) -> list[bytes]:
        """Generate frames by rotating the spinner node.

        Returns
        -------
        list[bytes]
            Encoded image frames, one per rotation step.
        """
        svg_source = self._rendered_svg or self._spec.svg_source
        base_root = safe_fromstring(svg_source)  # untrusted: .dui package
        node = self._spinner.node
        assert node is not None

        # Find the element to determine its centre of rotation
        elem = _find_element_by_id(base_root, node)
        if elem is None:
            logger.warning("Spinner node '%s' not found; returning blank frames", node)
            return self._blank_frames()

        cx, cy = self._element_centre(elem)
        step = 360.0 / self._spinner.frames

        frames: list[bytes] = []
        for i in range(self._spinner.frames):
            root = copy.deepcopy(base_root)
            el = _find_element_by_id(root, node)
            if el is not None:
                # Make the spinner node visible
                el.attrib.pop("display", None)
                angle = step * i
                existing = el.get("transform", "")
                rotation = f"rotate({angle:.1f},{cx:.1f},{cy:.1f})"
                el.set("transform", f"{existing} {rotation}".strip())

            self._show_background_node(root)
            frames.append(self._rasterise(root))
        return frames

    def _generate_pulse(self) -> list[bytes]:
        """Generate frames by pulsing opacity on the spinner node.

        Returns
        -------
        list[bytes]
            Encoded image frames with a triangle-wave opacity cycle.
        """
        svg_source = self._rendered_svg or self._spec.svg_source
        base_root = safe_fromstring(svg_source)  # untrusted: .dui package
        node = self._spinner.node
        assert node is not None

        n = self._spinner.frames
        frames: list[bytes] = []
        for i in range(n):
            root = copy.deepcopy(base_root)
            el = _find_element_by_id(root, node)
            if el is not None:
                el.attrib.pop("display", None)
                # Triangle wave: 0→1→0 over the cycle
                t = i / n
                opacity = 1.0 - 2.0 * abs(t - 0.5)
                opacity = max(0.2, min(1.0, 0.2 + 0.8 * opacity))
                el.set("opacity", f"{opacity:.2f}")

            self._show_background_node(root)
            frames.append(self._rasterise(root))
        return frames

    def _show_background_node(self, root: ET.Element) -> None:
        """Make the background node visible in the given SVG tree.

        If ``background_node`` is configured on the spinner spec, this
        removes ``display="none"`` from it so the background appears
        behind the animated spinner.  No transform or opacity changes
        are applied — the node is shown as-is.

        Parameters
        ----------
        root
            The parsed SVG element tree (will be mutated in place).
        """
        bg_id = self._spinner.background_node
        if bg_id is not None:
            bg_el = _find_element_by_id(root, bg_id)
            if bg_el is not None:
                bg_el.attrib.pop("display", None)

    def _generate_custom(self) -> list[bytes]:
        """Load custom frames from package assets.

        Looks for ``assets/spinner.gif`` first, then numbered PNGs in
        ``assets/spinner/``. Falls back to blank frames if neither is found.

        Returns
        -------
        list[bytes]
            Encoded image frames loaded from the package assets.
        """
        assets = self._spec.assets

        # Try animated GIF first
        if "spinner.gif" in assets:
            return self._load_gif_frames(assets["spinner.gif"])

        # Try numbered PNGs in spinner/ subdirectory
        frame_keys = sorted(k for k in assets if k.startswith("spinner/frame_"))
        if not frame_keys:
            logger.warning("No custom spinner frames found; returning blank frames")
            return self._blank_frames()

        frames: list[bytes] = []
        for key in frame_keys:
            frame_img: Image.Image = Image.open(io.BytesIO(assets[key]))
            if frame_img.size != (self._width, self._height):
                frame_img = frame_img.resize(
                    (self._width, self._height), Image.Resampling.LANCZOS
                )
            frames.append(self._composite_on_bg(frame_img.convert("RGBA")))
        return frames

    def _load_gif_frames(self, data: bytes) -> list[bytes]:
        """Extract and encode frames from an animated GIF.

        Parameters
        ----------
        data : bytes
            Raw GIF file bytes.

        Returns
        -------
        list[bytes]
            Encoded image frames; falls back to blank frames if the GIF
            contains no frames.
        """
        gif = Image.open(io.BytesIO(data))
        n_frames = getattr(gif, "n_frames", 1)

        frames: list[bytes] = []
        for i in range(n_frames):
            gif.seek(i)
            frame = gif.convert("RGBA")
            if frame.size != (self._width, self._height):
                frame = frame.resize(
                    (self._width, self._height), Image.Resampling.LANCZOS
                )
            frames.append(self._composite_on_bg(frame))

        if not frames:
            logger.warning("Animated GIF has no frames; returning blank frames")
            return self._blank_frames()
        return frames

    def _blank_frames(self) -> list[bytes]:
        """Return a list of blank encoded frames as fallback.

        When a background tile is set, blank frames show the background
        tile instead of solid black.

        Returns
        -------
        list[bytes]
            Blank or background-filled frames, one per configured spinner
            frame count.
        """
        if self._bg_tile is not None:
            data = self._encode_tile(self._bg_tile)
        else:
            data = self._encode_blank()
        return [data] * self._spinner.frames

    def _composite_on_bg(self, frame: Image.Image) -> bytes:
        """Composite a frame onto the background tile if available.

        Parameters
        ----------
        frame : Image.Image
            RGBA frame image.

        Returns
        -------
        bytes
            Encoded image bytes in the instance's configured format.
        """
        if self._bg_tile is not None:
            if isinstance(self._bg_tile, bytes):
                base = Image.open(io.BytesIO(self._bg_tile)).convert("RGBA")
            else:
                base = self._bg_tile.convert("RGBA")
            result = Image.alpha_composite(base, frame)
        else:
            result = frame

        return self._encode_pil(result)

    def _encode_pil(self, img: Image.Image) -> bytes:
        """Encode a PIL image in the configured format.

        Parameters
        ----------
        img
            A ``PIL.Image.Image`` instance.

        Returns
        -------
        bytes
            Encoded image bytes.
        """
        # Inline import: tests patch ``deux.render.key_renderer._encode_image_bytes``;
        # importing it lazily keeps that patching point effective.
        from ..render.key_renderer import _encode_image_bytes  # noqa: PLC0415

        return _encode_image_bytes(img, self._image_format)

    def _encode_tile(self, tile: bytes | Image.Image) -> bytes:
        """Re-encode a tile in the configured output format.

        Parameters
        ----------
        tile : bytes or Image.Image
            PNG-encoded tile bytes or a PIL Image.

        Returns
        -------
        bytes
            Image bytes in the configured format.
        """
        if isinstance(tile, bytes):
            img = Image.open(io.BytesIO(tile)).convert("RGB")
        else:
            img = tile.convert("RGB")
        return self._encode_pil(img)

    def _encode_blank(self) -> bytes:
        """Encode a solid black frame.

        Returns
        -------
        bytes
            Black frame in the configured format.
        """
        img = Image.new("RGB", (self._width, self._height), (0, 0, 0))
        return self._encode_pil(img)

    def _rasterise(self, root: ET.Element) -> bytes:
        """Rasterise an SVG element tree to encoded image bytes.

        Parameters
        ----------
        root : ET.Element
            The SVG document root to render.

        Returns
        -------
        bytes
            Image data encoded in the instance's configured format.
        """
        # Inline import: tests patch ``deux.render.svg_rasterize._svg_to_image``;
        # importing it lazily keeps that patching point effective.
        from ..render.svg_rasterize import _svg_to_image  # noqa: PLC0415

        svg_bytes = ET.tostring(root, encoding="unicode", xml_declaration=True)
        frame = _svg_to_image(
            svg_bytes.encode("utf-8"), self._width, self._height, mode="RGBA"
        )
        return self._composite_on_bg(frame)

    @staticmethod
    def _element_centre(elem: ET.Element) -> tuple[float, float]:
        """Compute the centre of an SVG element from its geometry attributes.

        Handles both rectangular elements (``x``, ``y``, ``width``, ``height``)
        and circle/ellipse elements (``cx``, ``cy``).

        Parameters
        ----------
        elem : ET.Element
            The SVG element to measure.

        Returns
        -------
        tuple[float, float]
            ``(cx, cy)`` centre coordinates.
        """
        x = float(elem.get("x", "0"))
        y = float(elem.get("y", "0"))
        w = float(elem.get("width", "0"))
        h = float(elem.get("height", "0"))

        # For circle/ellipse elements
        if w == 0 and h == 0:
            cx = float(elem.get("cx", str(x)))
            cy = float(elem.get("cy", str(y)))
            return cx, cy

        return x + w / 2, y + h / 2

frame_count property

frame_count: int

Number of frames in the animation cycle.

interval_ms property

interval_ms: int

Milliseconds between frames.

frames property

frames: list[bytes]

Encoded animation frames, generated on first access.

SvgRenderer

Render a .dui SVG layout with live data bindings.

The renderer holds a parsed copy of the SVG template. Each call to :meth:render clones the template, applies current binding values, inlines image assets, and rasterises to a PIL Image via CairoSVG.

Parameters:

Name	Type	Description	Default
spec	PackageSpec	The validated package specification.	required

Source code in src/deux/dui/svg_renderer.py

class SvgRenderer:
    """Render a .dui SVG layout with live data bindings.

    The renderer holds a parsed copy of the SVG template.  Each call
    to :meth:`render` clones the template, applies current binding
    values, inlines image assets, and rasterises to a PIL Image via
    CairoSVG.

    Parameters
    ----------
    spec
        The validated package specification.
    """

    def __init__(self, spec: PackageSpec) -> None:
        self._spec = spec
        self._values: dict[str, Any] = {}
        self._base_root: ET.Element = safe_fromstring(spec.svg_source)  # untrusted: .dui pkg
        self._original_root: ET.Element = copy.deepcopy(self._base_root)
        self._range_extents: dict[str, float] = {}
        self._target_width: int | None = None
        self._target_height: int | None = None
        self._rendering_ctx: RenderingContext | None = None
        # Per-render cache of the child→parent map for the currently rendered
        # tree.  Populated lazily by :meth:`_get_parent_map` during a render
        # pass and reset to ``None`` between renders so that mutations done by
        # bindings (e.g. wrapped-text ``<tspan>`` children) don't poison later
        # renders.  Caching it here keeps font-attribute resolution at O(N)
        # per render instead of O(N*M) for M text bindings.
        self._parent_map_root: ET.Element | None = None
        self._parent_map_cache: dict[ET.Element, ET.Element] | None = None

        # Register binding handlers as bound methods so subclasses can override
        # ``_apply_*`` and have the override take effect without re-registering.
        self._binding_handlers: dict[type[Binding], Callable[..., None]] = {
            TextBinding: lambda root, elem, name, binding, value: self._apply_text(
                root, elem, binding, value
            ),
            ImageBinding: lambda root, elem, name, binding, value: self._apply_image(
                root, elem, binding, value
            ),
            VisibilityBinding: lambda root, elem, name, binding, value: self._apply_visibility(
                elem, value
            ),
            ColorBinding: lambda root, elem, name, binding, value: self._apply_color(
                elem, binding, value
            ),
            RangeBinding: lambda root, elem, name, binding, value: self._apply_range(
                elem, name, binding, value
            ),
            SliderBinding: lambda root, elem, name, binding, value: self._apply_slider(
                elem, binding, value
            ),
            IconifyBinding: lambda root, elem, name, binding, value: self._apply_iconify(
                elem, binding, value
            ),
            ListBinding: lambda root, elem, name, binding, value: self._apply_list(
                root, elem, binding, value
            ),
            TransformBinding: lambda root, elem, name, binding, value: self._apply_transform(
                elem, binding, value
            ),
            CssClassBinding: lambda root, elem, name, binding, value: self._apply_css_class(
                elem, value
            ),
        }

        for name, binding in spec.bindings.items():
            self._values[name] = binding.default_value()

    def set(self, name: str, value: Any) -> bool:
        """Set a binding value.

        Parameters
        ----------
        name
            Binding name as defined in the manifest.
        value
            The new value.  Type depends on the binding:
            text → ``str``, image → ``PIL.Image.Image`` or ``bytes``,
            visibility → ``bool``, color → ``str``.

        Returns
        -------
        bool
            ``True`` if the value actually changed (triggers dirty flag).

        Raises
        ------
        KeyError
            If *name* is not a known binding.
        """
        if name not in self._spec.bindings:
            raise KeyError(
                f"Unknown binding '{name}'. Available: {sorted(self._spec.bindings)}"
            )

        old = self._values.get(name)
        binding = self._spec.bindings[name]

        # Per-binding coercion (e.g. ListBinding merges partial updates).
        coerce = getattr(binding, "coerce", None)
        new_value = coerce(value, old) if callable(coerce) else value

        # Some bindings (e.g. images) always count as changed because their
        # values aren't cheaply comparable.
        if getattr(binding, "force_dirty", False):
            self._values[name] = new_value
            return True

        if old == new_value:
            return False

        self._values[name] = new_value
        return True

    def set_many(self, **kwargs: Any) -> bool:
        """Set multiple binding values at once.

        Returns
        -------
        bool
            ``True`` if any value changed.
        """
        changed = False
        for name, value in kwargs.items():
            if self.set(name, value):
                changed = True
        return changed

    def get(self, name: str) -> Any:
        """Get the current value of a binding.

        Raises
        ------
        KeyError
            If *name* is not a known binding.
        """
        if name not in self._spec.bindings:
            raise KeyError(
                f"Unknown binding '{name}'. Available: {sorted(self._spec.bindings)}"
            )
        return self._values.get(name)

    def set_target_size(self, width: int, height: int) -> None:
        """Set the target rasterisation dimensions.

        When set, the SVG ``width`` and ``height`` attributes are
        overridden to these values before rasterisation, enabling
        vector-level scaling from the ``viewBox`` design canvas to the
        device's native pixel dimensions.

        Parameters
        ----------
        width : int
            Target width in pixels.
        height : int
            Target height in pixels.
        """
        self._target_width = width
        self._target_height = height

    @property
    def rendering_context(self) -> RenderingContext | None:
        """The explicit rendering context, or ``None`` for global defaults.

        Returns
        -------
        RenderingContext or None
            The context set via :meth:`set_rendering_context`.
        """
        return self._rendering_ctx

    def set_rendering_context(self, ctx: RenderingContext | None) -> None:
        """Set an explicit rendering context for this renderer.

        When set, the context's stylesheet and backend override the
        module-level globals during rasterisation.  Pass ``None`` to
        revert to the global defaults.

        Parameters
        ----------
        ctx : RenderingContext or None
            The rendering context to use, or ``None`` for defaults.
        """
        self._rendering_ctx = ctx

    def collect_icon_names(self) -> builtins.set[str]:
        """Return all Iconify icon identifiers needed by this renderer.

        Scans bindings for :class:`IconifyBinding` defaults and current
        values, as well as :class:`ListBinding` items prefixed with
        ``icon:``.  The result includes both default and currently-bound
        icon names so that a caller can prefetch everything before the
        first render.

        Returns
        -------
        set[str]
            A set of ``"prefix:icon"`` strings.
        """
        icons: set[str] = set()
        for name, binding in self._spec.bindings.items():
            if isinstance(binding, IconifyBinding):
                # Collect default
                if binding.default:
                    icons.add(str(binding.default))
                # Collect current value
                val = self._values.get(name)
                if val and val != binding.default:
                    icons.add(str(val))
            elif isinstance(binding, ListBinding):
                # Collect icon items from defaults
                for item in binding.default_items:
                    if isinstance(item, str) and item.startswith("icon:"):
                        icons.add(item[5:])
                # Collect icon items from current value
                val = self._values.get(name)
                if isinstance(val, dict):
                    for item in val.get("items", []):
                        if isinstance(item, str) and item.startswith("icon:"):
                            icons.add(item[5:])
        return icons

    def set_base_layer(
        self,
        bg_root: ET.Element,
        card_index: int,
        panel_width: int,
        panel_height: int,
    ) -> None:
        """Set a background SVG layer underneath the card content.

        The background SVG's ``viewBox`` is sliced to the region
        corresponding to *card_index*, then composed as a layer beneath
        the card's own SVG template.  The composed tree replaces
        ``_base_root`` so that subsequent :meth:`render` calls produce
        a single SVG document with both layers.

        Call this when the background SVG or the card's slot assignment
        changes — not on every render.

        Parameters
        ----------
        bg_root : ET.Element
            The full-width background ``<svg>`` root element.
        card_index : int
            Zero-based panel index.
        panel_width : int
            Width of a single panel in pixels.
        panel_height : int
            Height of a single panel in pixels.
        """
        bg_slice = slice_background_viewbox(bg_root, card_index, panel_width, panel_height)
        card_layer = copy.deepcopy(self._original_root)
        card_layer.set("width", str(panel_width))
        card_layer.set("height", str(panel_height))

        composed = compose_svg_layers(panel_width, panel_height, [bg_slice, card_layer])
        self._base_root = composed

    def clear_base_layer(self) -> None:
        """Remove the background layer and revert to the original SVG template.

        After calling this, :meth:`render` will produce output from the
        card's own SVG only, without any background layer.
        """
        self._base_root = copy.deepcopy(self._original_root)

    def _get_parent_map(self, root: ET.Element) -> dict[ET.Element, ET.Element]:
        """Return a cached child→parent map for *root* for the current render.

        The map is rebuilt only when *root* differs from the previously
        cached tree (i.e. at the start of a new render pass).  Subsequent
        calls within the same render reuse the cached map, avoiding the
        O(N) walk per text-binding that was the dominant cost of dense
        cards with multiple text bindings.

        Parameters
        ----------
        root : ET.Element
            The root of the SVG tree currently being rendered.

        Returns
        -------
        dict[ET.Element, ET.Element]
            Mapping of each child element to its parent element.
        """
        if self._parent_map_root is not root or self._parent_map_cache is None:
            self._parent_map_root = root
            self._parent_map_cache = _build_parent_map(root)
        return self._parent_map_cache

    def _reset_parent_map_cache(self) -> None:
        """Drop the cached parent map.

        Called at the start of each render so that the map is rebuilt
        for the freshly cloned tree.
        """
        self._parent_map_root = None
        self._parent_map_cache = None

    def render(self) -> Image.Image:
        """Rasterise the SVG with current binding values to a PIL Image.

        Returns
        -------
        Image.Image
            An RGBA :class:`~PIL.Image.Image`.  When target dimensions
            are set via :meth:`set_target_size` the image is rasterised
            at those dimensions (vector scaling); otherwise at the SVG's
            native dimensions.
        """
        root = copy.deepcopy(self._base_root)
        self._reset_parent_map_cache()

        for name, binding in self._spec.bindings.items():
            value = self._values.get(name)
            self._apply_binding(root, name, binding, value)

        self._inline_assets(root)
        self._hide_spinner_node(root)

        svg_bytes = ET.tostring(root, encoding="unicode", xml_declaration=True)
        logger.debug("Rendered SVG before rasterisation:\n%s", svg_bytes)
        return self._rasterise(svg_bytes.encode("utf-8"))

    def render_bytes(
        self,
        *,
        output_format: str = "jpeg",
        background: str | None = None,
        quality: int = 90,
    ) -> bytes:
        """Rasterise the SVG directly to encoded image bytes.

        This is the SVG-native pipeline entry point.  It applies
        bindings, optionally injects a background colour, sets the
        target dimensions, and rasterises to the requested format in
        a single pass — no intermediate PIL Image.

        Parameters
        ----------
        output_format : str, default="jpeg"
            Target image format: ``"jpeg"``, ``"bmp"``, or ``"png"``.
        background : str or None, optional
            CSS colour for a solid background rect injected under all
            content.  When ``None``, no background is injected (the
            SVG's own background or transparency is preserved).
        quality : int, default=90
            JPEG quality (ignored for other formats).

        Returns
        -------
        bytes
            Encoded image bytes ready to send to the device.
        """
        root = copy.deepcopy(self._base_root)
        self._reset_parent_map_cache()

        for name, binding in self._spec.bindings.items():
            value = self._values.get(name)
            self._apply_binding(root, name, binding, value)

        self._inline_assets(root)
        self._hide_spinner_node(root)

        if background is not None:
            inject_background_rect(root, background)

        # Determine rasterisation dimensions.
        if self._target_width is not None and self._target_height is not None:
            width = self._target_width
            height = self._target_height
        else:
            width = int(float(root.get("width", "197")))
            height = int(float(root.get("height", "98")))

        set_svg_dimensions(root, width, height)

        svg_bytes = ET.tostring(root, encoding="unicode", xml_declaration=True)
        return _rasterize_svg(
            svg_bytes.encode("utf-8"),
            width,
            height,
            output_format=output_format,
            quality=quality,
            ctx=self._rendering_ctx,
        )

    def render_svg(self) -> str:
        """Return the SVG source with current bindings applied (not rasterised).

        This is used by the spinner system to generate frames that
        reflect the current binding state rather than the raw template.

        Returns
        -------
        str
            SVG markup as a Unicode string.
        """
        root = copy.deepcopy(self._base_root)
        self._reset_parent_map_cache()

        for name, binding in self._spec.bindings.items():
            value = self._values.get(name)
            self._apply_binding(root, name, binding, value)

        self._inline_assets(root)
        self._hide_spinner_node(root)

        return ET.tostring(root, encoding="unicode", xml_declaration=True)

    def _hide_spinner_node(self, root: ET.Element) -> None:
        """Hide the spinner and its background node so they are invisible at rest.

        DUI package authors may not set ``display="none"`` on the spinner
        element or its background, which would make them visible in every
        non-busy render.  This method forces both nodes hidden; the spinner
        frame generators remove ``display="none"`` when producing animation
        frames.

        Parameters
        ----------
        root
            The parsed SVG element tree (will be mutated in place).
        """
        spinner = self._spec.spinner
        if spinner is not None and spinner.node is not None:
            elem = _find_element_by_id(root, spinner.node)
            if elem is not None:
                elem.set("display", "none")
        if spinner is not None and spinner.background_node is not None:
            bg_elem = _find_element_by_id(root, spinner.background_node)
            if bg_elem is not None:
                bg_elem.set("display", "none")

    #: Dispatch table mapping binding types to handler methods.
    #: Populated per-instance in :meth:`__init__` (bound to ``self``) so that
    #: handler resolution is uniform across binding types and overriding
    #: ``_apply_*`` in subclasses automatically takes effect.

    def _apply_binding(
        self,
        root: ET.Element,
        name: str,
        binding: Binding,
        value: Any,
    ) -> None:
        """Apply a single binding to the SVG tree.

        Uses a dispatch table to route each binding type to its handler,
        allowing new binding types to be added without modifying this method.
        """
        if isinstance(binding, ToggleBinding):
            elem_on = _find_element_by_id(root, binding.node_on)
            elem_off = _find_element_by_id(root, binding.node_off)
            if elem_on is None:
                logger.warning(
                    "Binding '%s': node_on '%s' not found in SVG",
                    name,
                    binding.node_on,
                )
            if elem_off is None:
                logger.warning(
                    "Binding '%s': node_off '%s' not found in SVG",
                    name,
                    binding.node_off,
                )
            self._apply_toggle(elem_on, elem_off, value)
            return

        elem = _find_element_by_id(root, binding.node)
        if elem is None:
            logger.warning(
                "Binding '%s': node '%s' not found in SVG", name, binding.node
            )
            return

        handler = self._binding_handlers.get(type(binding))
        if handler is not None:
            handler(root, elem, name, binding, value)
        else:
            logger.warning(
                "Binding '%s': no handler registered for type '%s'",
                name,
                type(binding).__name__,
            )

    def _apply_text(
        self,
        root: ET.Element,
        elem: ET.Element,
        binding: TextBinding,
        value: Any,
    ) -> None:
        """Set text content, applying wrapping or truncation if configured.

        Parameters
        ----------
        root : ET.Element
            The SVG document root (needed for font resolution during wrapping).
        elem : ET.Element
            The ``<text>`` element whose content is being set.
        binding : TextBinding
            The text binding definition from the manifest.
        value : Any
            The text value to render; coerced to ``str``.
        """
        text = str(value) if value is not None else binding.default

        if binding.wrap and binding.max_width is not None:
            self._apply_wrapped_text(root, elem, binding, text)
            return

        if binding.max_width is not None:
            family, size_f = _resolve_font_attrs(root, elem, self._get_parent_map(root))
            font = _load_font(family, int(size_f))
            text = _truncate_text(text, binding.max_width, binding.overflow, font=font)
        elem.text = text

    def _apply_wrapped_text(
        self,
        root: ET.Element,
        elem: ET.Element,
        binding: TextBinding,
        text: str,
    ) -> None:
        """Word-wrap text into ``<tspan>`` children of *elem*.

        Each ``<tspan>`` carries the parent ``<text>`` element's ``x``
        attribute so that ``text-anchor`` alignment is respected on
        every line.
        """
        family, size_f = _resolve_font_attrs(root, elem, self._get_parent_map(root))
        font = _load_font(family, int(size_f))

        line_height = binding.line_height or (size_f * _DEFAULT_LINE_HEIGHT_RATIO)

        lines = _wrap_text(
            text,
            binding.max_width,  # type: ignore[arg-type]  # validated non-None
            font,
            binding.overflow,
            max_height=binding.max_height,
            line_height=line_height,
        )

        elem.text = None
        for child in list(elem):
            elem.remove(child)

        x_attr = elem.get("x", "0")

        for i, line in enumerate(lines):
            tspan = ET.SubElement(elem, f"{{{_SVG_NS}}}tspan")
            tspan.set("x", x_attr)
            tspan.set("dy", "0" if i == 0 else str(line_height))
            tspan.text = line

    def _apply_image(
        self,
        root: ET.Element,
        elem: ET.Element,
        binding: ImageBinding,
        value: Any,
    ) -> None:
        """Set an image element's href to a data URI.

        Parameters
        ----------
        root : ET.Element
            The SVG document root (used to locate placeholder nodes).
        elem : ET.Element
            The ``<image>`` element to update.
        binding : ImageBinding
            The image binding definition from the manifest.
        value : Any
            A ``PIL.Image.Image``, ``bytes``, or ``None`` to clear the image.
        """
        if value is None:
            elem.set("href", "")
            elem.set("display", "none")
            if binding.placeholder_node:
                placeholder = _find_element_by_id(root, binding.placeholder_node)
                if placeholder is not None:
                    placeholder.attrib.pop("display", None)
            return

        elem.attrib.pop("display", None)
        if binding.placeholder_node:
            placeholder = _find_element_by_id(root, binding.placeholder_node)
            if placeholder is not None:
                placeholder.set("display", "none")

        if isinstance(value, bytes):
            img_bytes = value
        else:
            # Accept PIL Image objects — encode to PNG bytes for embedding.
            if isinstance(value, Image.Image):
                _buf = io.BytesIO()
                value.convert("RGBA").save(_buf, format="PNG")
                img_bytes = _buf.getvalue()
            else:
                logger.warning("Image binding: unsupported value type %s", type(value))
                return

        # Embed as data URI and let SVG-level preserveAspectRatio handle fitting.
        data_uri = _bytes_to_data_uri(img_bytes)
        elem.set("href", data_uri)
        elem.set(f"{{{_XLINK_NS}}}href", data_uri)

        # Set preserveAspectRatio based on the binding's fit mode.
        par = _fit_image_preserveAspectRatio(binding.fit)
        elem.set("preserveAspectRatio", par)

    def _apply_visibility(self, elem: ET.Element, value: Any) -> None:
        """Toggle element visibility via the ``display`` attribute.

        Parameters
        ----------
        elem : ET.Element
            The SVG element to show or hide.
        value : Any
            Truthy to show, falsy to hide (sets ``display="none"``).
        """
        if value:
            elem.attrib.pop("display", None)
        else:
            elem.set("display", "none")

    def _apply_css_class(self, elem: ET.Element, value: Any) -> None:
        """Set or remove the ``class`` attribute on an SVG element.

        Parameters
        ----------
        elem : ET.Element
            The SVG element to update.
        value : Any
            A string class value.  Non-empty strings are set as the
            ``class`` attribute; empty or ``None`` removes it.
        """
        class_str = str(value) if value else ""
        if class_str:
            elem.set("class", class_str)
        else:
            elem.attrib.pop("class", None)

    def _apply_toggle(
        self,
        elem_on: ET.Element | None,
        elem_off: ET.Element | None,
        value: Any,
    ) -> None:
        """Toggle visibility between two elements based on a boolean value.

        Parameters
        ----------
        elem_on : ET.Element | None
            The element shown when *value* is truthy.
        elem_off : ET.Element | None
            The element shown when *value* is falsy.
        value : Any
            Boolean-like value controlling which element is visible.
        """
        if value:
            if elem_on is not None:
                elem_on.attrib.pop("display", None)
            if elem_off is not None:
                elem_off.set("display", "none")
        else:
            if elem_off is not None:
                elem_off.attrib.pop("display", None)
            if elem_on is not None:
                elem_on.set("display", "none")

    def _apply_color(self, elem: ET.Element, binding: ColorBinding, value: Any) -> None:
        """Set an element's fill, stroke, or color attribute.

        Parameters
        ----------
        elem : ET.Element
            The SVG element to modify.
        binding : ColorBinding
            The color binding definition specifying the target attribute.
        value : Any
            CSS color string (e.g. ``"#ff0000"``); falls back to *binding.default*.
        """
        color_val = str(value) if value is not None else binding.default
        elem.set(binding.attribute, color_val)

    def _apply_range(
        self,
        elem: ET.Element,
        name: str,
        binding: RangeBinding,
        value: Any,
    ) -> None:
        """Scale an element's width or height proportional to a 0--1 value.

        Parameters
        ----------
        elem : ET.Element
            The SVG element whose dimension is being scaled.
        name : str
            Binding name, used to look up the cached original extent.
        binding : RangeBinding
            The range binding definition from the manifest.
        value : Any
            A float in ``[0.0, 1.0]``; clamped if out of range.
        """
        ratio = max(
            0.0, min(1.0, float(value if value is not None else binding.default))
        )
        if name not in self._range_extents:
            # Lazily capture the original extent from the unmodified template
            # the first time this binding is applied, since per-render clones
            # already carry the previously-mutated value.
            original = _find_element_by_id(self._base_root, binding.node)
            attr_lookup = (
                "width" if binding.direction == RangeDirection.HORIZONTAL else "height"
            )
            self._range_extents[name] = (
                float(original.get(attr_lookup, "0")) if original is not None else 0.0
            )
        extent = self._range_extents[name]
        attr = "width" if binding.direction == RangeDirection.HORIZONTAL else "height"
        elem.set(attr, str(ratio * extent))

    def _apply_slider(
        self,
        elem: ET.Element,
        binding: SliderBinding,
        value: Any,
    ) -> None:
        """Translate an element's x or y between *min_pos* and *max_pos*.

        Parameters
        ----------
        elem : ET.Element
            The SVG element to reposition.
        binding : SliderBinding
            The slider binding definition containing position limits.
        value : Any
            A float in ``[0.0, 1.0]`` interpolated between *min_pos* and *max_pos*.
        """
        ratio = max(
            0.0, min(1.0, float(value if value is not None else binding.default))
        )
        pos = binding.min_pos + ratio * (binding.max_pos - binding.min_pos)
        attr = "x" if binding.direction == RangeDirection.HORIZONTAL else "y"
        elem.set(attr, str(pos))

    def _apply_transform(
        self,
        elem: ET.Element,
        binding: TransformBinding,
        value: Any,
    ) -> None:
        """Apply composed SVG transforms to an element proportional to a 0–1 value.

        Parameters
        ----------
        elem : ET.Element
            The SVG element to transform.
        binding : TransformBinding
            The transform binding definition from the manifest.
        value : Any
            A float in ``[0.0, 1.0]``; clamped if out of range.
        """
        ratio = max(
            0.0, min(1.0, float(value if value is not None else binding.default))
        )

        parts: list[str] = []
        for spec in binding.transforms:
            if isinstance(spec, RotateTransform):
                angle = spec.from_angle + (spec.to_angle - spec.from_angle) * ratio
                cx, cy = self._resolve_transform_origin(elem, spec.origin)
                parts.append(f"rotate({angle:.4g},{cx:.4g},{cy:.4g})")

        if parts:
            elem.set("transform", " ".join(parts))

    @staticmethod
    def _resolve_transform_origin(
        elem: ET.Element, origin: str
    ) -> tuple[float, float]:
        """Resolve a transform origin string to x, y coordinates.

        Parameters
        ----------
        elem : ET.Element
            The target SVG element (used for ``"center"`` resolution).
        origin : str
            Either ``"center"`` (computes from element geometry) or an
            explicit ``"x y"`` coordinate pair.

        Returns
        -------
        tuple[float, float]
            The resolved (cx, cy) origin coordinates.
        """
        if origin == "center":
            x = float(elem.get("x", "0"))
            y = float(elem.get("y", "0"))
            w = float(elem.get("width", "0"))
            h = float(elem.get("height", "0"))
            return (x + w / 2.0, y + h / 2.0)

        # Explicit "x y" format.
        parts = origin.split()
        if len(parts) == 2:
            try:
                return (float(parts[0]), float(parts[1]))
            except ValueError:
                pass
        # Fallback to 0,0 if unparseable.
        return (0.0, 0.0)

    def _apply_iconify(
        self,
        elem: ET.Element,
        binding: IconifyBinding,
        value: Any,
    ) -> None:
        """Load an Iconify icon by name and embed it into a ``<g>`` node.

        The existing children of *elem* are replaced by a single
        ``<svg>`` child that contains the icon.  Passing ``None`` or an
        empty string clears the group.
        """
        elem.text = None
        for child in list(elem):
            elem.remove(child)

        if value is None or value == "":
            return
        name = str(value)

        try:
            svg_source = fetch_icon(str(name))
        except IconifyError as exc:
            logger.warning("Iconify binding '%s': %s", binding.node, exc)
            return

        try:
            icon_root = safe_fromstring(svg_source)  # untrusted: network (Iconify)
        except (ET.ParseError, DefusedXmlException) as exc:
            logger.warning(
                "Iconify binding '%s': failed to parse icon SVG: %s",
                binding.node,
                exc,
            )
            return

        size = str(binding.size)
        icon_root.set("width", size)
        icon_root.set("height", size)

        elem.append(icon_root)

    def _apply_list(
        self,
        root: ET.Element,
        elem: ET.Element,
        binding: ListBinding,
        value: Any,
    ) -> None:
        """Render a list of items as repeated child elements.

        Each item becomes a ``<child_tag>`` child of *elem*.  The item
        at *index* receives *active_attrs*; all others receive
        *inactive_attrs*.  An index of ``None`` (or ``-1``, normalised
        earlier) means every item is styled as inactive.

        Items prefixed with ``icon:`` are rendered as inline Iconify
        icons via :meth:`_apply_list_icon`.

        Parameters
        ----------
        root : ET.Element
            The SVG document root (needed for font resolution on icon
            items).
        elem : ET.Element
            The parent SVG element whose children are rebuilt.
        binding : ListBinding
            The list binding definition from the manifest.
        value : Any
            A dict with ``"items"`` (list of str) and ``"index"``
            (int or None).
        """
        if not isinstance(value, dict):
            value = {"items": list(binding.default_items), "index": binding.default_index}

        items: list[str] = value.get("items", [])
        index: int | None = value.get("index")
        if index == -1:
            index = None

        # Clear existing children.
        elem.text = None
        for child in list(elem):
            elem.remove(child)

        for i, item in enumerate(items):
            # Separator between items.
            if binding.separator and i > 0:
                sep = ET.SubElement(elem, f"{{{_SVG_NS}}}{binding.child_tag}")
                sep.text = binding.separator
                for attr_k, attr_v in binding.inactive_attrs.items():
                    sep.set(attr_k, attr_v)

            is_active = index is not None and i == index
            attrs = binding.active_attrs if is_active else binding.inactive_attrs

            if item.startswith("icon:"):
                self._apply_list_icon(elem, binding, item[5:], attrs)
            else:
                child_elem = ET.SubElement(elem, f"{{{_SVG_NS}}}{binding.child_tag}")
                child_elem.text = item
                for attr_k, attr_v in attrs.items():
                    child_elem.set(attr_k, attr_v)

    def _apply_list_icon(
        self,
        parent: ET.Element,
        binding: ListBinding,
        icon_name: str,
        attrs: dict[str, str],
    ) -> None:
        """Render a single Iconify icon as a child of *parent*.

        Fetches the icon SVG via the Iconify API, wraps it in a
        ``<child_tag>`` element, and applies the given attributes.

        Parameters
        ----------
        parent : ET.Element
            The parent SVG element to append the icon child to.
        binding : ListBinding
            The list binding definition (provides ``child_tag`` and
            ``icon_size``).
        icon_name : str
            Iconify icon identifier (e.g. ``"mdi:home"``).
        attrs : dict[str, str]
            SVG attributes to apply to the wrapper element.
        """
        try:
            svg_source = fetch_icon(icon_name)
        except IconifyError as exc:
            logger.warning("List binding icon '%s': %s", icon_name, exc)
            return

        try:
            icon_root = safe_fromstring(svg_source)  # untrusted: network (Iconify)
        except (ET.ParseError, DefusedXmlException) as exc:
            logger.warning(
                "List binding icon '%s': failed to parse SVG: %s", icon_name, exc
            )
            return

        size = str(binding.icon_size)
        icon_root.set("width", size)
        icon_root.set("height", size)

        wrapper = ET.SubElement(parent, f"{{{_SVG_NS}}}{binding.child_tag}")
        for attr_k, attr_v in attrs.items():
            wrapper.set(attr_k, attr_v)
        wrapper.append(icon_root)

    def _inline_assets(self, root: ET.Element) -> None:
        """Replace relative asset ``href`` references with data URIs.

        Parameters
        ----------
        root : ET.Element
            The SVG document root to scan for asset references.
        """
        if not self._spec.assets:
            return

        for elem in root.iter():
            href = elem.get("href") or elem.get(f"{{{_XLINK_NS}}}href")
            if not href:
                continue

            asset_name: str | None = None
            if href.startswith("assets/"):
                asset_name = href[len("assets/") :]
            elif "/" not in href and href in self._spec.assets:
                asset_name = href

            if asset_name and asset_name in self._spec.assets:
                data_uri = _bytes_to_data_uri(self._spec.assets[asset_name])
                elem.set("href", data_uri)
                elem.set(f"{{{_XLINK_NS}}}href", data_uri)

    def _rasterise(self, svg_data: bytes) -> Image.Image:
        """Rasterise SVG bytes to a PIL Image.

        The image is returned in RGBA mode so that transparent regions
        in the SVG are preserved.  This allows compositing onto a
        background tile when a touchstrip background SVG is active.

        When target dimensions have been set via :meth:`set_target_size`,
        the SVG is rasterised at those dimensions (vector scaling by the
        rasteriser backend).  Otherwise the SVG's intrinsic ``width`` and
        ``height`` attributes are used.

        Parameters
        ----------
        svg_data : bytes
            UTF-8 encoded SVG markup.

        Returns
        -------
        Image.Image
            An RGBA :class:`~PIL.Image.Image`.
        """
        if self._target_width is not None and self._target_height is not None:
            width = self._target_width
            height = self._target_height
        else:
            width = int(float(self._base_root.get("width", "197")))
            height = int(float(self._base_root.get("height", "98")))

        return _svg_to_image(svg_data, width, height, mode="RGBA", ctx=self._rendering_ctx)

rendering_context property

rendering_context: RenderingContext | None

The explicit rendering context, or None for global defaults.

Returns:

Type	Description
RenderingContext or None	The context set via :meth:set_rendering_context.

set

set(name: str, value: Any) -> bool

Set a binding value.

Parameters:

Name	Type	Description	Default
name	str	Binding name as defined in the manifest.	required
value	Any	The new value. Type depends on the binding: text → str, image → PIL.Image.Image or bytes, visibility → bool, color → str.	required

Returns:

Type	Description
bool	True if the value actually changed (triggers dirty flag).

Raises:

Type	Description
KeyError	If name is not a known binding.

Source code in src/deux/dui/svg_renderer.py

def set(self, name: str, value: Any) -> bool:
    """Set a binding value.

    Parameters
    ----------
    name
        Binding name as defined in the manifest.
    value
        The new value.  Type depends on the binding:
        text → ``str``, image → ``PIL.Image.Image`` or ``bytes``,
        visibility → ``bool``, color → ``str``.

    Returns
    -------
    bool
        ``True`` if the value actually changed (triggers dirty flag).

    Raises
    ------
    KeyError
        If *name* is not a known binding.
    """
    if name not in self._spec.bindings:
        raise KeyError(
            f"Unknown binding '{name}'. Available: {sorted(self._spec.bindings)}"
        )

    old = self._values.get(name)
    binding = self._spec.bindings[name]

    # Per-binding coercion (e.g. ListBinding merges partial updates).
    coerce = getattr(binding, "coerce", None)
    new_value = coerce(value, old) if callable(coerce) else value

    # Some bindings (e.g. images) always count as changed because their
    # values aren't cheaply comparable.
    if getattr(binding, "force_dirty", False):
        self._values[name] = new_value
        return True

    if old == new_value:
        return False

    self._values[name] = new_value
    return True

set_many

set_many(**kwargs: Any) -> bool

Set multiple binding values at once.

Returns:

Type	Description
bool	True if any value changed.

Source code in src/deux/dui/svg_renderer.py

def set_many(self, **kwargs: Any) -> bool:
    """Set multiple binding values at once.

    Returns
    -------
    bool
        ``True`` if any value changed.
    """
    changed = False
    for name, value in kwargs.items():
        if self.set(name, value):
            changed = True
    return changed

get

get(name: str) -> Any

Get the current value of a binding.

Raises:

Type	Description
KeyError	If name is not a known binding.

Source code in src/deux/dui/svg_renderer.py

def get(self, name: str) -> Any:
    """Get the current value of a binding.

    Raises
    ------
    KeyError
        If *name* is not a known binding.
    """
    if name not in self._spec.bindings:
        raise KeyError(
            f"Unknown binding '{name}'. Available: {sorted(self._spec.bindings)}"
        )
    return self._values.get(name)

set_target_size

set_target_size(width: int, height: int) -> None

Set the target rasterisation dimensions.

When set, the SVG width and height attributes are overridden to these values before rasterisation, enabling vector-level scaling from the viewBox design canvas to the device's native pixel dimensions.

Parameters:

Name	Type	Description	Default
width	int	Target width in pixels.	required
height	int	Target height in pixels.	required

Source code in src/deux/dui/svg_renderer.py

def set_target_size(self, width: int, height: int) -> None:
    """Set the target rasterisation dimensions.

    When set, the SVG ``width`` and ``height`` attributes are
    overridden to these values before rasterisation, enabling
    vector-level scaling from the ``viewBox`` design canvas to the
    device's native pixel dimensions.

    Parameters
    ----------
    width : int
        Target width in pixels.
    height : int
        Target height in pixels.
    """
    self._target_width = width
    self._target_height = height

set_rendering_context

set_rendering_context(ctx: RenderingContext | None) -> None

Set an explicit rendering context for this renderer.

When set, the context's stylesheet and backend override the module-level globals during rasterisation. Pass None to revert to the global defaults.

Parameters:

Name	Type	Description	Default
ctx	RenderingContext or None	The rendering context to use, or None for defaults.	required

Source code in src/deux/dui/svg_renderer.py

def set_rendering_context(self, ctx: RenderingContext | None) -> None:
    """Set an explicit rendering context for this renderer.

    When set, the context's stylesheet and backend override the
    module-level globals during rasterisation.  Pass ``None`` to
    revert to the global defaults.

    Parameters
    ----------
    ctx : RenderingContext or None
        The rendering context to use, or ``None`` for defaults.
    """
    self._rendering_ctx = ctx

collect_icon_names

collect_icon_names() -> builtins.set[str]

Return all Iconify icon identifiers needed by this renderer.

Scans bindings for :class:IconifyBinding defaults and current values, as well as :class:ListBinding items prefixed with icon:. The result includes both default and currently-bound icon names so that a caller can prefetch everything before the first render.

Returns:

Type	Description
set[str]	A set of "prefix:icon" strings.

Source code in src/deux/dui/svg_renderer.py

def collect_icon_names(self) -> builtins.set[str]:
    """Return all Iconify icon identifiers needed by this renderer.

    Scans bindings for :class:`IconifyBinding` defaults and current
    values, as well as :class:`ListBinding` items prefixed with
    ``icon:``.  The result includes both default and currently-bound
    icon names so that a caller can prefetch everything before the
    first render.

    Returns
    -------
    set[str]
        A set of ``"prefix:icon"`` strings.
    """
    icons: set[str] = set()
    for name, binding in self._spec.bindings.items():
        if isinstance(binding, IconifyBinding):
            # Collect default
            if binding.default:
                icons.add(str(binding.default))
            # Collect current value
            val = self._values.get(name)
            if val and val != binding.default:
                icons.add(str(val))
        elif isinstance(binding, ListBinding):
            # Collect icon items from defaults
            for item in binding.default_items:
                if isinstance(item, str) and item.startswith("icon:"):
                    icons.add(item[5:])
            # Collect icon items from current value
            val = self._values.get(name)
            if isinstance(val, dict):
                for item in val.get("items", []):
                    if isinstance(item, str) and item.startswith("icon:"):
                        icons.add(item[5:])
    return icons

set_base_layer

set_base_layer(bg_root: Element, card_index: int, panel_width: int, panel_height: int) -> None

Set a background SVG layer underneath the card content.

The background SVG's viewBox is sliced to the region corresponding to card_index, then composed as a layer beneath the card's own SVG template. The composed tree replaces _base_root so that subsequent :meth:render calls produce a single SVG document with both layers.

Call this when the background SVG or the card's slot assignment changes — not on every render.

Parameters:

Name	Type	Description	Default
bg_root	Element	The full-width background <svg> root element.	required
card_index	int	Zero-based panel index.	required
panel_width	int	Width of a single panel in pixels.	required
panel_height	int	Height of a single panel in pixels.	required

Source code in src/deux/dui/svg_renderer.py

def set_base_layer(
    self,
    bg_root: ET.Element,
    card_index: int,
    panel_width: int,
    panel_height: int,
) -> None:
    """Set a background SVG layer underneath the card content.

    The background SVG's ``viewBox`` is sliced to the region
    corresponding to *card_index*, then composed as a layer beneath
    the card's own SVG template.  The composed tree replaces
    ``_base_root`` so that subsequent :meth:`render` calls produce
    a single SVG document with both layers.

    Call this when the background SVG or the card's slot assignment
    changes — not on every render.

    Parameters
    ----------
    bg_root : ET.Element
        The full-width background ``<svg>`` root element.
    card_index : int
        Zero-based panel index.
    panel_width : int
        Width of a single panel in pixels.
    panel_height : int
        Height of a single panel in pixels.
    """
    bg_slice = slice_background_viewbox(bg_root, card_index, panel_width, panel_height)
    card_layer = copy.deepcopy(self._original_root)
    card_layer.set("width", str(panel_width))
    card_layer.set("height", str(panel_height))

    composed = compose_svg_layers(panel_width, panel_height, [bg_slice, card_layer])
    self._base_root = composed

clear_base_layer

clear_base_layer() -> None

Remove the background layer and revert to the original SVG template.

After calling this, :meth:render will produce output from the card's own SVG only, without any background layer.

Source code in src/deux/dui/svg_renderer.py

def clear_base_layer(self) -> None:
    """Remove the background layer and revert to the original SVG template.

    After calling this, :meth:`render` will produce output from the
    card's own SVG only, without any background layer.
    """
    self._base_root = copy.deepcopy(self._original_root)

render

render() -> Image.Image

Rasterise the SVG with current binding values to a PIL Image.

Returns:

Type	Description
Image	An RGBA :class:~PIL.Image.Image. When target dimensions are set via :meth:set_target_size the image is rasterised at those dimensions (vector scaling); otherwise at the SVG's native dimensions.

Source code in src/deux/dui/svg_renderer.py

def render(self) -> Image.Image:
    """Rasterise the SVG with current binding values to a PIL Image.

    Returns
    -------
    Image.Image
        An RGBA :class:`~PIL.Image.Image`.  When target dimensions
        are set via :meth:`set_target_size` the image is rasterised
        at those dimensions (vector scaling); otherwise at the SVG's
        native dimensions.
    """
    root = copy.deepcopy(self._base_root)
    self._reset_parent_map_cache()

    for name, binding in self._spec.bindings.items():
        value = self._values.get(name)
        self._apply_binding(root, name, binding, value)

    self._inline_assets(root)
    self._hide_spinner_node(root)

    svg_bytes = ET.tostring(root, encoding="unicode", xml_declaration=True)
    logger.debug("Rendered SVG before rasterisation:\n%s", svg_bytes)
    return self._rasterise(svg_bytes.encode("utf-8"))

render_bytes

render_bytes(*, output_format: str = 'jpeg', background: str | None = None, quality: int = 90) -> bytes

Rasterise the SVG directly to encoded image bytes.

This is the SVG-native pipeline entry point. It applies bindings, optionally injects a background colour, sets the target dimensions, and rasterises to the requested format in a single pass — no intermediate PIL Image.

Parameters:

Name	Type	Description	Default
output_format	str	Target image format: "jpeg", "bmp", or "png".	"jpeg"
background	str or None	CSS colour for a solid background rect injected under all content. When None, no background is injected (the SVG's own background or transparency is preserved).	None
quality	int	JPEG quality (ignored for other formats).	90

Returns:

Type	Description
bytes	Encoded image bytes ready to send to the device.

Source code in src/deux/dui/svg_renderer.py

def render_bytes(
    self,
    *,
    output_format: str = "jpeg",
    background: str | None = None,
    quality: int = 90,
) -> bytes:
    """Rasterise the SVG directly to encoded image bytes.

    This is the SVG-native pipeline entry point.  It applies
    bindings, optionally injects a background colour, sets the
    target dimensions, and rasterises to the requested format in
    a single pass — no intermediate PIL Image.

    Parameters
    ----------
    output_format : str, default="jpeg"
        Target image format: ``"jpeg"``, ``"bmp"``, or ``"png"``.
    background : str or None, optional
        CSS colour for a solid background rect injected under all
        content.  When ``None``, no background is injected (the
        SVG's own background or transparency is preserved).
    quality : int, default=90
        JPEG quality (ignored for other formats).

    Returns
    -------
    bytes
        Encoded image bytes ready to send to the device.
    """
    root = copy.deepcopy(self._base_root)
    self._reset_parent_map_cache()

    for name, binding in self._spec.bindings.items():
        value = self._values.get(name)
        self._apply_binding(root, name, binding, value)

    self._inline_assets(root)
    self._hide_spinner_node(root)

    if background is not None:
        inject_background_rect(root, background)

    # Determine rasterisation dimensions.
    if self._target_width is not None and self._target_height is not None:
        width = self._target_width
        height = self._target_height
    else:
        width = int(float(root.get("width", "197")))
        height = int(float(root.get("height", "98")))

    set_svg_dimensions(root, width, height)

    svg_bytes = ET.tostring(root, encoding="unicode", xml_declaration=True)
    return _rasterize_svg(
        svg_bytes.encode("utf-8"),
        width,
        height,
        output_format=output_format,
        quality=quality,
        ctx=self._rendering_ctx,
    )

render_svg

render_svg() -> str

Return the SVG source with current bindings applied (not rasterised).

This is used by the spinner system to generate frames that reflect the current binding state rather than the raw template.

Returns:

Type	Description
str	SVG markup as a Unicode string.

Source code in src/deux/dui/svg_renderer.py

def render_svg(self) -> str:
    """Return the SVG source with current bindings applied (not rasterised).

    This is used by the spinner system to generate frames that
    reflect the current binding state rather than the raw template.

    Returns
    -------
    str
        SVG markup as a Unicode string.
    """
    root = copy.deepcopy(self._base_root)
    self._reset_parent_map_cache()

    for name, binding in self._spec.bindings.items():
        value = self._values.get(name)
        self._apply_binding(root, name, binding, value)

    self._inline_assets(root)
    self._hide_spinner_node(root)

    return ET.tostring(root, encoding="unicode", xml_declaration=True)

fetch_icon

fetch_icon(name: str) -> str

Fetch an Iconify icon by prefix:icon name.

The lookup order is: in-memory cache, disk cache, network. Successful fetches are stored in both caches. Negative lookups (404 / network failure) are cached in memory only so a restart retries previously-failed icons.

Parameters:

Name	Type	Description	Default
name	str	Icon identifier in "prefix:icon" form, e.g. "line-md:home".	required

Returns:

Type	Description
str	The raw SVG source string as served by the Iconify API.

Raises:

Type	Description
IconifyError	If the name is malformed, the icon does not exist, or the network request fails.
SSRFError	If the constructed API URL resolves to a private address and private URLs have not been explicitly allowed.

Source code in src/deux/dui/iconify.py

def fetch_icon(name: str) -> str:
    """Fetch an Iconify icon by ``prefix:icon`` name.

    The lookup order is: in-memory cache, disk cache, network.
    Successful fetches are stored in both caches.  Negative lookups
    (404 / network failure) are cached in memory only so a restart
    retries previously-failed icons.

    Parameters
    ----------
    name : str
        Icon identifier in ``"prefix:icon"`` form, e.g.
        ``"line-md:home"``.

    Returns
    -------
    str
        The raw SVG source string as served by the Iconify API.

    Raises
    ------
    IconifyError
        If the name is malformed, the icon does not
        exist, or the network request fails.
    SSRFError
        If the constructed API URL resolves to a private address
        and private URLs have not been explicitly allowed.
    """
    prefix, icon = _parse_name(name)
    key = f"{prefix}:{icon}"

    # 1. In-memory cache
    with _cache_lock:
        if key in _cache:
            cached = _cache[key]
            if cached is None:
                raise IconifyError(f"Iconify icon '{key}' previously failed to load")
            return cached

    # 2. Disk cache
    disk_hit = _read_disk_cache(prefix, icon)
    if disk_hit is not None:
        with _cache_lock:
            _cache[key] = disk_hit
        logger.debug("Loaded Iconify icon '%s' from disk cache", key)
        return disk_hit

    # 3. Network fetch
    url = f"{ICONIFY_API_URL}/{prefix}/{icon}.svg"
    check_url(url)
    try:
        body = _http_get(url)
    except (urllib.error.URLError, OSError) as exc:
        with _cache_lock:
            _cache[key] = None
        raise IconifyError(f"Failed to fetch Iconify icon '{key}': {exc}") from exc

    stripped = body.strip()
    if stripped == "404" or not stripped.startswith("<"):
        with _cache_lock:
            _cache[key] = None
        raise IconifyError(f"Iconify icon '{key}' not found")

    with _cache_lock:
        _cache[key] = body

    _write_disk_cache(prefix, icon, body)

    logger.debug("Fetched Iconify icon '%s' (%d bytes)", key, len(body))
    return body

prefetch_icons async

prefetch_icons(names: Iterable[str]) -> dict[str, str | None]

Fetch multiple Iconify icons concurrently, warming the cache.

Each icon is fetched in a separate thread via :func:asyncio.to_thread, so network I/O runs in parallel without blocking the event loop. Icons that are already cached (in memory or on disk) return immediately.

Parameters:

Name	Type	Description	Default
names	Iterable[str]	Icon identifiers in "prefix:icon" form (e.g. "mdi:play"). Duplicates are deduplicated automatically.	required

Returns:

Type	Description
dict[str, str | None]	Mapping of icon name to SVG string on success, or None for icons that failed to load (404, network error, malformed name).

Source code in src/deux/dui/iconify.py

async def prefetch_icons(names: Iterable[str]) -> dict[str, str | None]:
    """Fetch multiple Iconify icons concurrently, warming the cache.

    Each icon is fetched in a separate thread via
    :func:`asyncio.to_thread`, so network I/O runs in parallel without
    blocking the event loop.  Icons that are already cached (in memory
    or on disk) return immediately.

    Parameters
    ----------
    names : Iterable[str]
        Icon identifiers in ``"prefix:icon"`` form (e.g.
        ``"mdi:play"``).  Duplicates are deduplicated automatically.

    Returns
    -------
    dict[str, str | None]
        Mapping of icon name to SVG string on success, or ``None`` for
        icons that failed to load (404, network error, malformed name).
    """
    unique = dict.fromkeys(names)  # deduplicate, preserve order
    if not unique:
        return {}

    async def _fetch_one(name: str) -> tuple[str, str | None]:
        try:
            svg = await asyncio.to_thread(fetch_icon, name)
            return (name, svg)
        except (IconifyError, Exception):
            logger.debug("Prefetch failed for icon '%s'", name, exc_info=True)
            return (name, None)

    results = await asyncio.gather(*[_fetch_one(n) for n in unique])
    return dict(results)

clear_iconify_cache

clear_iconify_cache(*, persistent: bool = False) -> None

Drop all cached Iconify icons.

Parameters:

Name	Type	Description	Default
persistent	bool	When True, also remove the on-disk cache directory. By default only the in-memory cache is cleared.	False

Source code in src/deux/dui/iconify.py

def clear_cache(*, persistent: bool = False) -> None:
    """Drop all cached Iconify icons.

    Parameters
    ----------
    persistent : bool, default=False
        When ``True``, also remove the on-disk cache directory.
        By default only the in-memory cache is cleared.
    """
    global _disk_cache_dir  # noqa: PLW0603
    with _cache_lock:
        _cache.clear()
    if persistent:
        with _disk_cache_dir_lock:
            if _disk_cache_dir is not None:
                shutil.rmtree(_disk_cache_dir, ignore_errors=True)
                _disk_cache_dir = None

load_all_packages

load_all_packages(directory: str | Path) -> dict[str, PackageSpec]

Load all .dui packages from a directory.

Parameters:

Name	Type	Description	Default
directory	str | Path	Path to scan for .dui subdirectories.	required

Returns:

Type	Description
dict[str, PackageSpec]	A dict mapping package names to their specs.

Raises:

Type	Description
PackageError	If any package fails validation.

Source code in src/deux/dui/loader.py

def load_all_packages(directory: str | Path) -> dict[str, PackageSpec]:
    """Load all .dui packages from a directory.

    Parameters
    ----------
    directory
        Path to scan for ``.dui`` subdirectories.

    Returns
    -------
    dict[str, PackageSpec]
        A dict mapping package names to their specs.

    Raises
    ------
    PackageError
        If any package fails validation.
    """
    base = Path(directory)
    if not base.is_dir():
        raise PackageError(f"Not a directory: {base}")

    packages: dict[str, PackageSpec] = {}
    for entry in sorted(base.iterdir()):
        if entry.is_dir() and entry.suffix == ".dui":
            spec = load_package(entry)
            packages[spec.name] = spec

    logger.info("Loaded %d .dui packages from %s", len(packages), base)
    return packages

load_package

load_package(path: str | Path, *, strict: bool = True) -> PackageSpec

Load a .dui package directory into a validated PackageSpec.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the .dui directory.	required
strict	bool	When True, unknown manifest keys raise :exc:PackageError. Set to False for forward-compatible loading that only warns.	True

Returns:

Type	Description
PackageSpec	A frozen :class:PackageSpec ready to be used by :class:~deux.dui.card.DuiCard or :class:~deux.dui.key.DuiKey.

Raises:

Type	Description
PackageError	If the package is invalid or incomplete.

Source code in src/deux/dui/loader.py

def load_package(path: str | Path, *, strict: bool = True) -> PackageSpec:
    """Load a .dui package directory into a validated PackageSpec.

    Parameters
    ----------
    path
        Path to the ``.dui`` directory.
    strict : bool, default=True
        When ``True``, unknown manifest keys raise :exc:`PackageError`.
        Set to ``False`` for forward-compatible loading that only warns.

    Returns
    -------
    PackageSpec
        A frozen :class:`PackageSpec` ready to be used by
        :class:`~deux.dui.card.DuiCard` or
        :class:`~deux.dui.key.DuiKey`.

    Raises
    ------
    PackageError
        If the package is invalid or incomplete.
    """
    pkg_dir = Path(path)
    if not pkg_dir.is_dir():
        raise PackageError(f"Package path is not a directory: {pkg_dir}")

    manifest = _load_manifest(pkg_dir)
    name, pkg_type, version, layout_file = _parse_core_manifest(manifest)

    layout_path = pkg_dir / layout_file
    if not layout_path.exists():
        raise PackageError(f"Layout file not found: {layout_path}")
    svg_source = layout_path.read_text(encoding="utf-8")
    svg_ids = _find_svg_ids(svg_source)

    _check_unknown_keys(manifest, name, strict)

    metadata = _parse_metadata(manifest)
    bindings = _parse_bindings(manifest, svg_ids)
    events = _parse_events(manifest)
    regions = _parse_regions(manifest)
    assets = _load_assets(pkg_dir)
    spinner = _parse_and_validate_spinner(manifest, svg_ids, assets)

    logger.info(
        "Loaded .dui package '%s' (%s, %d bindings, %d events)",
        name,
        pkg_type.value,
        len(bindings),
        len(events),
    )

    return PackageSpec(
        name=name,
        type=pkg_type,
        version=version,
        svg_source=svg_source,
        bindings=bindings,
        events=tuple(events),
        regions=tuple(regions),
        assets=assets,
        spinner=spinner,
        **metadata,
    )

add_dui_path

add_dui_path(path: str | Path) -> None

Register a directory as a DUI package source.

The directory is inserted at the highest priority position. Packages in this directory will override bundled packages and packages from previously added directories when names collide.

Parameters:

Name	Type	Description	Default
path	str or Path	Directory containing .dui package subdirectories.	required

Raises:

Type	Description
PackageError	If path does not exist or is not a directory.

Examples:

::

import deux

deux.add_dui_path("/home/user/my-packages")
card = deux.DuiCard("MyCustomCard")

Source code in src/deux/dui/repository.py

def add_dui_path(path: str | Path) -> None:
    """Register a directory as a DUI package source.

    The directory is inserted at the highest priority position.
    Packages in this directory will override bundled packages and
    packages from previously added directories when names collide.

    Parameters
    ----------
    path : str or Path
        Directory containing ``.dui`` package subdirectories.

    Raises
    ------
    PackageError
        If *path* does not exist or is not a directory.

    Examples
    --------
    ::

        import deux

        deux.add_dui_path("/home/user/my-packages")
        card = deux.DuiCard("MyCustomCard")
    """
    _get_repository().add_path(path)

clear_dui_cache

clear_dui_cache() -> None

Drop all cached package specs from the default repository.

Subsequent DuiCard("name") / DuiKey("name") calls will re-read packages from disk.

Source code in src/deux/dui/repository.py

def clear_dui_cache() -> None:
    """Drop all cached package specs from the default repository.

    Subsequent ``DuiCard("name")`` / ``DuiKey("name")`` calls will
    re-read packages from disk.
    """
    _get_repository().clear_cache()

list_dui_packages

list_dui_packages() -> list[str]

List all DUI package names visible across all search paths.

Returns:

Type	Description
list[str]	Sorted package names (without the .dui suffix).

Source code in src/deux/dui/repository.py

def list_dui_packages() -> list[str]:
    """List all DUI package names visible across all search paths.

    Returns
    -------
    list[str]
        Sorted package names (without the ``.dui`` suffix).
    """
    return _get_repository().list_packages()

remove_dui_path

remove_dui_path(path: str | Path) -> None

Unregister a previously added DUI package directory.

Parameters:

Name	Type	Description	Default
path	str or Path	Previously registered directory.	required

Raises:

Type	Description
ValueError	If path is not currently registered.

Source code in src/deux/dui/repository.py

def remove_dui_path(path: str | Path) -> None:
    """Unregister a previously added DUI package directory.

    Parameters
    ----------
    path : str or Path
        Previously registered directory.

    Raises
    ------
    ValueError
        If *path* is not currently registered.
    """
    _get_repository().remove_path(path)

resolve_dui

resolve_dui(name: str) -> PackageSpec

Look up a DUI package by name and return its spec.

This is the function called internally when DuiCard("name") or DuiKey("name") receive a string argument.

Parameters:

Name	Type	Description	Default
name	str	Package name without the .dui suffix.	required

Returns:

Type	Description
PackageSpec	A validated, frozen package specification.

Raises:

Type	Description
PackageError	If no package with that name exists in any registered path.

Source code in src/deux/dui/repository.py

def resolve_dui(name: str) -> PackageSpec:
    """Look up a DUI package by name and return its spec.

    This is the function called internally when ``DuiCard("name")``
    or ``DuiKey("name")`` receive a string argument.

    Parameters
    ----------
    name : str
        Package name without the ``.dui`` suffix.

    Returns
    -------
    PackageSpec
        A validated, frozen package specification.

    Raises
    ------
    PackageError
        If no package with that name exists in any registered path.
    """
    return _get_repository().resolve(name)