"""Camera input capture module — stub implementation.

.. warning::
    This module is a stub. Camera capture is not yet implemented.
    ``render_camera_panel()`` returns ``None`` and emits an explicit warning
    so the caller knows it is using default steering data.

Full implementation will add:
    - OpenCV webcam capture
    - JPEG frame export for Gemma 3n visual prompting
    - Real-time frame preview in Streamlit
"""

from __future__ import annotations

import warnings
from pathlib import Path
from typing import Optional


def render_camera_panel(
    *,
    key_prefix: str = "camera",
    output_dir: Optional[str] = None,
) -> Optional[dict]:
    """Render a camera input panel in the Streamlit UI.

    .. warning::
        **STUB** — camera_input not yet implemented.
        Returns ``None`` and uses default steering for generation.

    Parameters
    ----------
    key_prefix : str
        Streamlit widget key prefix (for state isolation).
    output_dir : str, optional
        Directory to save captured frames.

    Returns
    -------
    dict | None
        ``{"image_path": str, "timestamp": str}`` — ``None`` in this stub.
    """
    warnings.warn(
        "camera_input not yet implemented — using default steering. "
        "Implement modules/camera_input.py for real webcam capture.",
        UserWarning,
        stacklevel=2,
    )

    try:
        import streamlit as st
        st.info(
            "📷 **Camera Input**: Webcam capture not yet implemented. "
            "Using default visual context.",
            icon="ℹ️",
        )
    except ImportError:
        pass

    return None