agent-starter-pack 0.12.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

src/cli/utils/gcp.py

@@ -14,9 +14,11 @@
 
 # ruff: noqa: E722
 import subprocess
+import time
 
 import google.auth
 from google.api_core.client_options import ClientOptions
+from google.api_core.exceptions import PermissionDenied
 from google.api_core.gapic_v1.client_info import ClientInfo
 from google.cloud.aiplatform import initializer
 from google.cloud.aiplatform_v1beta1.services.prediction_service import (
@@ -25,9 +27,94 @@ from google.cloud.aiplatform_v1beta1.services.prediction_service import (
 from google.cloud.aiplatform_v1beta1.types.prediction_service import (
     CountTokensRequest,
 )
+from rich.console import Console
+from rich.prompt import Confirm
 
 from src.cli.utils.version import PACKAGE_NAME, get_current_version
 
+console = Console()
+
+
+def enable_vertex_ai_api(project_id: str, auto_approve: bool = False) -> bool:
+    """Enable Vertex AI API with user confirmation and propagation waiting."""
+    api_name = "aiplatform.googleapis.com"
+
+    # First test if API is already working with a direct connection
+    if _test_vertex_ai_connection(project_id):
+        return True
+
+    if not auto_approve:
+        console.print(
+            f"Vertex AI API is not enabled in project '{project_id}'.", style="yellow"
+        )
+        console.print(
+            "To continue, we need to enable the Vertex AI API.", style="yellow"
+        )
+
+        if not Confirm.ask(
+            "Do you want to enable the Vertex AI API now?", default=True
+        ):
+            return False
+
+    try:
+        console.print("Enabling Vertex AI API...")
+        subprocess.run(
+            [
+                "gcloud",
+                "services",
+                "enable",
+                api_name,
+                "--project",
+                project_id,
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        console.print("✓ Vertex AI API enabled successfully")
+
+        # Wait for API propagation
+        console.print("⏳ Waiting for API availability to propagate...")
+        max_wait_time = 180  # 3 minutes
+        check_interval = 10  # 10 seconds
+        start_time = time.time()
+
+        while time.time() - start_time < max_wait_time:
+            if _test_vertex_ai_connection(project_id):
+                console.print("✓ Vertex AI API is now available")
+                return True
+            time.sleep(check_interval)
+            console.print("⏳ Still waiting for API propagation...")
+
+        console.print(
+            "⚠️ API propagation took longer than expected, but continuing...",
+            style="yellow",
+        )
+        return True
+
+    except subprocess.CalledProcessError as e:
+        console.print(f"Failed to enable Vertex AI API: {e.stderr}", style="bold red")
+        return False
+
+
+def _test_vertex_ai_connection(project_id: str, location: str = "us-central1") -> bool:
+    """Test Vertex AI connection without raising exceptions."""
+    try:
+        credentials, _ = google.auth.default()
+        client = PredictionServiceClient(
+            credentials=credentials,
+            client_options=ClientOptions(
+                api_endpoint=f"{location}-aiplatform.googleapis.com"
+            ),
+            client_info=get_client_info(),
+            transport=initializer.global_config._api_transport,
+        )
+        request = get_dummy_request(project_id=project_id)
+        client.count_tokens(request=request)
+        return True
+    except Exception:
+        return False
+
 
 def get_user_agent() -> str:
     """Returns custom user agent header tuple (version, agent string)."""
@@ -52,8 +139,18 @@ def get_dummy_request(project_id: str) -> CountTokensRequest:
 def verify_vertex_connection(
     project_id: str,
     location: str = "us-central1",
+    auto_approve: bool = False,
 ) -> None:
     """Verifies Vertex AI connection with a test Gemini request."""
+    # First try direct connection - if it works, we're done
+    if _test_vertex_ai_connection(project_id, location):
+        return
+
+    # If that failed, try to enable the API
+    if not enable_vertex_ai_api(project_id, auto_approve):
+        raise Exception("Vertex AI API is not enabled and user declined to enable it")
+
+    # After enabling, test again with proper error handling
     credentials, _ = google.auth.default()
     client = PredictionServiceClient(
         credentials=credentials,
@@ -64,7 +161,31 @@ def verify_vertex_connection(
         transport=initializer.global_config._api_transport,
     )
     request = get_dummy_request(project_id=project_id)
-    client.count_tokens(request=request)
+
+    try:
+        client.count_tokens(request=request)
+    except PermissionDenied as e:
+        error_message = str(e)
+        # Check if the error is specifically about API not being enabled
+        if (
+            "has not been used" in error_message
+            and "aiplatform.googleapis.com" in error_message
+        ):
+            # This shouldn't happen since we checked above, but handle it gracefully
+            console.print(
+                "⚠️ API may still be propagating, retrying in 30 seconds...",
+                style="yellow",
+            )
+            time.sleep(30)
+            try:
+                client.count_tokens(request=request)
+            except PermissionDenied:
+                raise Exception(
+                    "Vertex AI API is enabled but not yet available. Please wait a few more minutes and try again."
+                ) from e
+        else:
+            # Re-raise other permission errors
+            raise
 
 
 def verify_credentials() -> dict:

src/cli/utils/remote_template.py

@@ -18,12 +18,17 @@ import pathlib
 import re
 import shutil
 import subprocess
+import sys
 import tempfile
-import tomllib
 from dataclasses import dataclass
 from typing import Any
 
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
 from jinja2 import Environment
+from rich.console import Console
 
 
 @dataclass
@@ -90,10 +95,14 @@ def parse_agent_spec(agent_spec: str) -> RemoteTemplateSpec | None:
             template_path = path_parts[0]
             git_ref = path_parts[1]
 
+        # Check if this is the ADK samples repository
+        is_adk_samples = repo_url == "https://github.com/google/adk-samples"
+
         return RemoteTemplateSpec(
             repo_url=repo_url,
             template_path=template_path.strip("/"),
             git_ref=git_ref,
+            is_adk_samples=is_adk_samples,
         )
 
     # GitHub shorthand: <org>/<repo>[/<path>][@<ref>]
@@ -104,10 +113,15 @@ def parse_agent_spec(agent_spec: str) -> RemoteTemplateSpec | None:
         repo = match.group(2)
         template_path = match.group(3) or ""
         git_ref = match.group(4) or "main"
+
+        # Check if this is the ADK samples repository
+        is_adk_samples = org == "google" and repo == "adk-samples"
+
         return RemoteTemplateSpec(
             repo_url=f"https://github.com/{org}/{repo}",
             template_path=template_path,
             git_ref=git_ref,
+            is_adk_samples=is_adk_samples,
         )
 
     return None
@@ -183,29 +197,66 @@ def fetch_remote_template(
         ) from e
 
 
+def _infer_agent_directory_for_adk(
+    template_dir: pathlib.Path, is_adk_sample: bool
+) -> dict[str, Any]:
+    """Infer agent configuration for ADK samples only using Python conventions.
+
+    Args:
+        template_dir: Path to template directory
+        is_adk_sample: Whether this is an ADK sample
+
+    Returns:
+        Dictionary with inferred configuration, or empty dict if not ADK sample
+    """
+    if not is_adk_sample:
+        return {}
+
+    # Convert folder name to Python package convention (hyphens to underscores)
+    folder_name = template_dir.name
+    agent_directory = folder_name.replace("-", "_")
+
+    logging.debug(
+        f"Inferred agent_directory '{agent_directory}' from folder name '{folder_name}' for ADK sample"
+    )
+
+    return {
+        "settings": {
+            "agent_directory": agent_directory,
+        },
+        "has_explicit_config": False,  # Track that this was inferred
+    }
+
+
 def load_remote_template_config(
-    template_dir: pathlib.Path, cli_overrides: dict[str, Any] | None = None
+    template_dir: pathlib.Path,
+    cli_overrides: dict[str, Any] | None = None,
+    is_adk_sample: bool = False,
 ) -> dict[str, Any]:
     """Load template configuration from remote template's pyproject.toml with CLI overrides.
 
     Loads configuration from [tool.agent-starter-pack] section with fallbacks
     to [project] section for name and description if not specified. CLI overrides
-    take precedence over all other sources.
+    take precedence over all other sources. For ADK samples without explicit config,
+    uses smart inference for agent directory naming.
 
     Args:
         template_dir: Path to template directory
         cli_overrides: Configuration overrides from CLI (takes highest precedence)
+        is_adk_sample: Whether this is an ADK sample (enables smart inference)
 
     Returns:
         Template configuration dictionary with merged sources
     """
-    config = {}
+    config: dict[str, Any] = {}
+    has_explicit_config = False
 
     # Start with defaults
     defaults = {
         "base_template": "adk_base",
         "name": template_dir.name,
         "description": "",
+        "agent_directory": "app",  # Default for non-ADK samples
     }
     config.update(defaults)
 
@@ -222,9 +273,13 @@ def load_remote_template_config(
             # Fallback to [project] fields if not specified in agent-starter-pack section
             project_info = pyproject_data.get("project", {})
 
+            # Track if we have explicit configuration
+            has_explicit_config = bool(toml_config)
+
             # Apply pyproject.toml configuration (overrides defaults)
             if toml_config:
                 config.update(toml_config)
+                logging.debug("Found explicit [tool.agent-starter-pack] configuration")
 
             # Apply [project] fallbacks if not already set
             if "name" not in toml_config and "name" in project_info:
@@ -236,6 +291,31 @@ def load_remote_template_config(
             logging.debug(f"Loaded template config from {pyproject_path}")
         except Exception as e:
             logging.error(f"Error loading pyproject.toml config: {e}")
+    else:
+        # No pyproject.toml found
+        if is_adk_sample:
+            logging.debug(
+                f"No pyproject.toml found for ADK sample {template_dir.name}, will use inference"
+            )
+        else:
+            logging.debug(
+                f"No pyproject.toml found for template {template_dir.name}, using defaults"
+            )
+
+    # Apply ADK inference if no explicit config and this is an ADK sample
+    if not has_explicit_config and is_adk_sample:
+        try:
+            inferred_config = _infer_agent_directory_for_adk(
+                template_dir, is_adk_sample
+            )
+            config.update(inferred_config)
+            logging.debug("Applied ADK inference for template without explicit config")
+        except Exception as e:
+            logging.warning(f"Failed to apply ADK inference for {template_dir}: {e}")
+            # Continue with default configuration
+
+    # Add metadata about configuration source
+    config["has_explicit_config"] = bool(has_explicit_config)
 
     # Apply CLI overrides (highest precedence) using deep merge
     if cli_overrides:
@@ -287,6 +367,97 @@ def merge_template_configs(
     return deep_merge(merged_config, remote_config)
 
 
+def discover_adk_agents(repo_path: pathlib.Path) -> dict[int, dict[str, Any]]:
+    """Discover and load all ADK agents from a repository with inference support.
+
+    Args:
+        repo_path: Path to the cloned ADK samples repository
+
+    Returns:
+        Dictionary mapping agent numbers to agent info with keys:
+        - name: Agent display name
+        - description: Agent description
+        - path: Relative path from repo root
+        - spec: adk@ specification string
+        - has_explicit_config: Whether agent has explicit configuration
+    """
+    import logging
+
+    adk_agents = {}
+
+    # Search specifically for agents in python/agents/* directories
+    agents_dir = repo_path / "python" / "agents"
+    logging.debug(f"Looking for agents in: {agents_dir}")
+    if agents_dir.exists():
+        all_items = list(agents_dir.iterdir())
+        logging.debug(
+            f"Found items in agents directory: {[item.name for item in all_items]}"
+        )
+
+        # Collect all agents first, then sort by configuration type
+        all_agents = []
+
+        for agent_dir in sorted(agents_dir.iterdir()):
+            if not agent_dir.is_dir():
+                logging.debug(f"Skipping non-directory: {agent_dir.name}")
+                continue
+            logging.debug(f"Processing agent directory: {agent_dir.name}")
+
+            try:
+                # Load configuration with ADK inference support
+                config = load_remote_template_config(
+                    template_dir=agent_dir, is_adk_sample=True
+                )
+
+                agent_name = config.get("name", agent_dir.name)
+                description = config.get("description", "")
+                has_explicit_config = config.get("has_explicit_config", False)
+
+                # Get the relative path from repo root
+                relative_path = agent_dir.relative_to(repo_path)
+                agent_spec_name = agent_dir.name
+
+                agent_info = {
+                    "name": agent_name,
+                    "description": description,
+                    "path": str(relative_path),
+                    "spec": f"adk@{agent_spec_name}",
+                    "has_explicit_config": has_explicit_config,
+                }
+                all_agents.append(agent_info)
+
+            except Exception as e:
+                logging.warning(f"Could not load agent from {agent_dir}: {e}")
+
+        # Sort agents: explicit config first, then inferred (both alphabetically within their groups)
+        all_agents.sort(key=lambda x: (not x["has_explicit_config"], x["name"].lower()))
+
+        # Convert to numbered dictionary
+        for i, agent_info in enumerate(all_agents, 1):
+            adk_agents[i] = agent_info
+
+    return adk_agents
+
+
+def display_adk_caveat_if_needed(agents: dict[int, dict[str, Any]]) -> None:
+    """Display helpful note for agents that use inference.
+
+    Args:
+        agents: Dictionary of agent info from discover_adk_agents
+    """
+    console = Console()
+    inferred_agents = [
+        a for a in agents.values() if not a.get("has_explicit_config", True)
+    ]
+    if inferred_agents:
+        console.print(
+            "\n[blue]ℹ️  Note: Agents marked with * are templated using starter pack heuristics for ADK samples.[/]"
+        )
+        console.print(
+            "[dim]   The starter pack attempts to create a working codebase, but you'll need to follow the generated README for complete setup.[/]"
+        )
+
+
 def render_and_merge_makefiles(
     base_template_path: pathlib.Path,
     final_destination: pathlib.Path,

src/cli/utils/template.py

@@ -686,7 +686,7 @@ def process_template(
                 llm_txt_content = f.read()
 
             cookiecutter_config = {
-                "project_name": "my-project",
+                "project_name": project_name,
                 "agent_name": agent_name,
                 "package_version": get_current_version(),
                 "agent_description": template_config.get("description", ""),
@@ -752,6 +752,53 @@ def process_template(
                 logging.debug(
                     f"Copying remote template files from {remote_template_path} to {generated_project_dir}"
                 )
+
+                # Preserve base template README and pyproject.toml files before overwriting
+                preserve_files = ["README.md"]
+
+                # Only preserve pyproject.toml if the remote template doesn't have starter pack integration
+                remote_pyproject = remote_template_path / "pyproject.toml"
+                if remote_pyproject.exists():
+                    try:
+                        remote_pyproject_content = remote_pyproject.read_text()
+                        # Check for starter pack integration markers
+                        has_starter_pack_integration = (
+                            "[tool.agent-starter-pack]" in remote_pyproject_content
+                        )
+                        if not has_starter_pack_integration:
+                            preserve_files.append("pyproject.toml")
+                            logging.debug(
+                                "Remote pyproject.toml lacks starter pack integration - will preserve base template version"
+                            )
+                        else:
+                            logging.debug(
+                                "Remote pyproject.toml has starter pack integration - using remote version only"
+                            )
+                    except Exception as e:
+                        logging.warning(
+                            f"Could not read remote pyproject.toml: {e}. Will preserve base template version."
+                        )
+                        preserve_files.append("pyproject.toml")
+                else:
+                    preserve_files.append("pyproject.toml")
+
+                for preserve_file in preserve_files:
+                    base_file = generated_project_dir / preserve_file
+                    remote_file = remote_template_path / preserve_file
+
+                    if base_file.exists() and remote_file.exists():
+                        # Preserve the base template file with starter_pack prefix
+                        base_name = pathlib.Path(preserve_file).stem
+                        extension = pathlib.Path(preserve_file).suffix
+                        preserved_file = (
+                            generated_project_dir
+                            / f"starter_pack_{base_name}{extension}"
+                        )
+                        shutil.copy2(base_file, preserved_file)
+                        logging.debug(
+                            f"Preserved base template {preserve_file} as starter_pack_{base_name}{extension}"
+                        )
+
                 copy_files(
                     remote_template_path,
                     generated_project_dir,
@@ -884,11 +931,35 @@ def process_template(
                 )
 
                 if generated_project_dir.exists():
+                    # Check for existing README and pyproject.toml files before removing destination
+                    existing_preserved_files = []
                     if final_destination.exists():
+                        for item in final_destination.iterdir():
+                            if item.is_file() and (
+                                item.name.lower().startswith("readme")
+                                or item.name == "pyproject.toml"
+                            ):
+                                existing_preserved_files.append(
+                                    (item.name, item.read_text())
+                                )
                         shutil.rmtree(final_destination)
+
                     shutil.copytree(
                         generated_project_dir, final_destination, dirs_exist_ok=True
                     )
+
+                    # Restore existing README and pyproject.toml files with starter_pack prefix
+                    for file_name, file_content in existing_preserved_files:
+                        base_name = pathlib.Path(file_name).stem
+                        extension = pathlib.Path(file_name).suffix
+                        preserved_file_path = (
+                            final_destination / f"starter_pack_{base_name}{extension}"
+                        )
+                        preserved_file_path.write_text(file_content)
+                        logging.debug(
+                            f"File preservation: existing {file_name} preserved as starter_pack_{base_name}{extension}"
+                        )
+
                     logging.debug(
                         f"Project successfully created at {final_destination}"
                     )

src/deployment_targets/cloud_run/Dockerfile

@@ -16,12 +16,28 @@ FROM python:3.11-slim
 
 RUN pip install --no-cache-dir uv==0.6.12
 
+{%- if cookiecutter.agent_name == 'live_api' %}
+# Install Node.js for frontend build
+RUN apt-get update && apt-get install -y \
+    curl \
+    && curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \
+    && apt-get install -y nodejs \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+{%- endif %}
+
 WORKDIR /code
 
 COPY ./pyproject.toml ./README.md ./uv.lock* ./
 
 COPY ./{{cookiecutter.agent_directory}} ./{{cookiecutter.agent_directory}}
 
+{%- if cookiecutter.agent_name == 'live_api' %}
+# Copy and build frontend
+COPY ./frontend ./frontend
+RUN cd frontend && npm ci && npm run build
+{%- endif %}
+
 RUN uv sync --frozen
 
 ARG COMMIT_SHA=""

src/deployment_targets/cloud_run/{{cookiecutter.agent_directory}}/server.py

@@ -16,11 +16,14 @@ import asyncio
 import json
 import logging
 from collections.abc import Callable
+from pathlib import Path
 from typing import Any, Literal
 
 import backoff
-from fastapi import FastAPI, WebSocket
+from fastapi import FastAPI, HTTPException, WebSocket
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
 from google.cloud import logging as google_cloud_logging
 from google.genai import types
 from google.genai.types import LiveServerToolCall
@@ -36,6 +39,18 @@ app.add_middleware(
     allow_methods=["*"],
     allow_headers=["*"],
 )
+
+# Get the path to the frontend build directory
+current_dir = Path(__file__).parent
+frontend_build_dir = current_dir.parent / "frontend" / "build"
+
+# Mount static files if build directory exists
+if frontend_build_dir.exists():
+    app.mount(
+        "/static",
+        StaticFiles(directory=str(frontend_build_dir / "static")),
+        name="static",
+    )
 logging_client = google_cloud_logging.Client()
 logger = logging_client.logger(__name__)
 logging.basicConfig(level=logging.INFO)
@@ -382,8 +397,41 @@ def collect_feedback(feedback: Feedback) -> dict[str, str]:
     """
     logger.log_struct(feedback.model_dump(), severity="INFO")
     return {"status": "success"}
+{% if cookiecutter.agent_name == "live_api" %}
+
+@app.get("/")
+async def serve_frontend_root() -> FileResponse:
+    """Serve the frontend index.html at the root path."""
+    index_file = frontend_build_dir / "index.html"
+    if index_file.exists():
+        return FileResponse(str(index_file))
+    raise HTTPException(
+        status_code=404,
+        detail="Frontend not built. Run 'npm run build' in the frontend directory.",
+    )
 
 
+@app.get("/{full_path:path}")
+async def serve_frontend_spa(full_path: str) -> FileResponse:
+    """Catch-all route to serve the frontend for SPA routing.
+
+    This ensures that client-side routes are handled by the React app.
+    Excludes API routes (ws, feedback) and static assets.
+    """
+    # Don't intercept API routes
+    if full_path.startswith(("ws", "feedback", "static", "api")):
+        raise HTTPException(status_code=404, detail="Not found")
+
+    # Serve index.html for all other routes (SPA routing)
+    index_file = frontend_build_dir / "index.html"
+    if index_file.exists():
+        return FileResponse(str(index_file))
+    raise HTTPException(
+        status_code=404,
+        detail="Frontend not built. Run 'npm run build' in the frontend directory.",
+    )
+{% endif %}
+
 # Main execution
 if __name__ == "__main__":
     import uvicorn

src/frontends/live_api_react/frontend/package-lock.json

@@ -5914,9 +5914,9 @@
       "license": "ISC"
     },
     "node_modules/brace-expansion": {
-      "version": "1.1.11",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
-      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^1.0.0",
@@ -9051,9 +9051,9 @@
       }
     },
     "node_modules/filelist/node_modules/brace-expansion": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz",
-      "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==",
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",
+      "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^1.0.0"
@@ -16819,9 +16819,9 @@
       }
     },
     "node_modules/sucrase/node_modules/brace-expansion": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz",
-      "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==",
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",
+      "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^1.0.0"

src/frontends/live_api_react/frontend/src/App.tsx

@@ -21,8 +21,9 @@ import SidePanel from "./components/side-panel/SidePanel";
 import ControlTray from "./components/control-tray/ControlTray";
 import cn from "classnames";
 
-const defaultHost = "localhost:8000";
-const defaultUri = `ws://${defaultHost}/`;
+// Use relative URLs that work with integrated setup and deployments
+const defaultHost = window.location.host;
+const defaultUri = `${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${defaultHost}/`;
 
 function App() {
   const videoRef = useRef<HTMLVideoElement>(null);