♻️(frontend) decouple pip state and simplify pip options

Prevent PiP actions from affecting main panel state and reduce PiP-only noise.

CHANGELOG.md

@@ -8,6 +8,13 @@ and this project adheres to
 
 ## [Unreleased]
 
+### Added
+
+- ✨(backend) monitor throttling rate failure through sentry #964
+- 🚀(paas) add PaaS deployment scripts, tested on Scalingo #957
+- ✨(feat) Introduce Picture-in-Picture (PiP) #890
+
+
 ### Changed
 
 - ♿️(frontend) improve spinner reduced‑motion fallback #931
@@ -20,6 +27,7 @@ and this project adheres to
 ### Fixed
 
 - 🔐(backend) enforce object-level permission checks on room endpoint #959
+- 🔒️(backend) add application validation when consuming external JWT #963
 
 ## [1.5.0] - 2026-01-28
 

Procfile

@@ -0,0 +1,2 @@
+web: bin/buildpack_start.sh
+postdeploy: python manage.py migrate

bin/buildpack_postcompile.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+set -o errexit    # always exit on error
+set -o pipefail   # don't ignore exit codes when piping output
+
+echo "-----> Running post-compile script"
+
+# Cleanup
+rm -rf docker docs env.d gitlint

bin/buildpack_postfrontend.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+
+set -o errexit    # always exit on error
+set -o pipefail   # don't ignore exit codes when piping output
+
+echo "-----> Running post-frontend script"
+
+# Move the frontend build to the nginx root and clean up
+mkdir -p build/
+mv src/frontend/dist build/frontend-out
+
+ASSETS_DIR=build/frontend-out/assets
+if [ -n "$CUSTOM_LOGO_URL" ]; then
+    # Ensure https
+    [[ ! "$CUSTOM_LOGO_URL" =~ ^https:// ]] && echo "[custom-logo] ERROR: URL must use HTTPS" >&2 && exit 1
+
+    # Prevent SSRF
+    HOSTNAME=$(echo "$CUSTOM_LOGO_URL" | sed -E 's|^https://([^/:]+).*|\1|')
+    [[ "$HOSTNAME" =~ ^(localhost|127\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.|0\.0\.0\.0|\[::1\]) ]] && echo "[custom-logo] ERROR: SSRF blocked: $HOSTNAME" >&2 && exit 1
+
+    LOGO_FILE="${ASSETS_DIR}/logo.svg"
+    TMP_FILE=$(mktemp "${LOGO_FILE}.XXXXXX.tmp")
+
+    # Actual download
+    echo "[custom-logo] INFO: Downloading custom logo from: $CUSTOM_LOGO_URL"
+    curl -fsSL --tlsv1.2 -o "$TMP_FILE" "$CUSTOM_LOGO_URL"
+
+    # Validate filesize
+    FILESIZE=$(stat -c%s "$TMP_FILE" 2>/dev/null || stat -f%z "$TMP_FILE")
+    [[ "$FILESIZE" -eq 0 ]] && echo "[custom-logo] ERROR: empty file" >&2 && exit 1
+    [[ "$FILESIZE" -gt 5242880 ]] && echo "[custom-logo] ERROR: file too large (${FILESIZE}B > 5MB)" >&2 && exit 1
+
+    # Validate file type
+    IS_SVG=false
+
+    HEADER=$(head -c 100 "$TMP_FILE" | tr -d '\0' | tr '[:upper:]' '[:lower:]')
+    [[ "$HEADER" =~ ^.*"<svg".*$ ]] && IS_SVG=true
+    [[ "$HEADER" =~ ^.*"<?xml".*"<svg".*$ ]] && IS_SVG=true
+
+    [[ "$IS_SVG" == false ]] && echo "[custom-logo] ERROR: not a valid SVG file" >&2 && exit 1
+
+    mv -f "$TMP_FILE" "$LOGO_FILE"
+    echo "[custom-logo] INFO: Custom logo downloaded successfuly"
+fi
+
+mv src/backend/* ./
+mv deploy/paas/* ./
+
+echo "3.13" > .python-version
+echo "." > requirements.txt

bin/buildpack_start.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+# Start the Django backend server
+gunicorn -b 0.0.0.0:8000 meet.wsgi:application --log-file - &
+
+# Start the Nginx server
+bin/run &
+
+# if the current shell is killed, also terminate all its children     
+trap "pkill SIGTERM -P $$" SIGTERM
+
+# wait for a single child to finish,
+wait -n
+# then kill all the other tasks
+pkill -P $$

deploy/paas/servers.conf.erb

@@ -0,0 +1,52 @@
+# ERB templated nginx configuration
+# see https://doc.scalingo.com/platform/deployment/buildpacks/nginx
+
+upstream backend_server {
+	server localhost:8000 fail_timeout=0;
+}
+
+server {
+  listen <%= ENV["PORT"] %>;
+  server_name _;
+  server_tokens off;
+
+  root /app/build/frontend-out;
+
+  # Django rest framework
+  location ^~ /api/ {
+      proxy_set_header X-Forwarded-Proto https;
+      proxy_set_header Host $http_host;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+
+      proxy_redirect off;
+      proxy_pass http://backend_server;
+  }
+
+  # Django admin
+  location ^~ /admin/ {
+      proxy_set_header X-Forwarded-Proto https;
+      proxy_set_header Host $http_host;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+
+      proxy_redirect off;
+      proxy_pass http://backend_server;
+  }
+
+  # Serve static files with caching
+  location ~* ^/assets/.*\.(css|js|json|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+      expires 30d;
+      add_header Cache-Control "public, max-age=2592000";
+  }
+
+  # Serve static files
+  location / {
+      try_files $uri $uri/ /index.html;
+      # Add no-cache headers
+      add_header Cache-Control "no-cache, no-store, must-revalidate";
+      add_header Pragma "no-cache";  # HTTP 1.0 header for backward compatibility
+      add_header Expires 0;
+  }
+
+  # Optionally, handle 404 errors by redirecting to index.html
+  error_page 404 =200 /index.html;
+}

docs/installation/README.md

@@ -9,6 +9,10 @@ La Suite Meet maintainers use only the Kubernetes deployment method in productio
 We understand that not everyone has a Kubernetes cluster available, please follow the instructions provided [here](/docs/installation/compose.md) to set up a docker compose instance.
 We also provide [Docker images](https://hub.docker.com/u/lasuite?page=1&search=meet) that can be deployed using Compose.
 
+## Scalingo
+
+La Suite Meet can be deployed on Scalingo PaaS using the Suite Numérique buildpack. See the [Scalingo deployment guide](./scalingo.md) for detailed instructions.
+
 ## Other ways to install La Suite Meet
 Community members have contributed alternative ways to install La Suite Meet 🙏. While maintainers may not provide direct support, we help keep these instructions up to date, and you can reach out to contributors or the community for assistance.
 

docs/installation/scalingo.md

@@ -0,0 +1,185 @@
+# Deployment on Scalingo
+
+This guide explains how to deploy La Suite Meet on [Scalingo](https://scalingo.com/) using the [Suite Numérique buildpack](https://github.com/suitenumerique/buildpack).
+
+## Overview
+
+Scalingo is a Platform-as-a-Service (PaaS) that simplifies application deployment. This setup uses a custom buildpack to handle both the frontend (Vite) and backend (Django) builds, serving them through Nginx.
+
+## Prerequisites
+
+- A Scalingo account
+- Scalingo CLI installed (optional but recommended)
+- A PostgreSQL database addon
+- A Redis addon (for caching and sessions)
+
+## Step 1: Create Your App
+
+Create a new app on Scalingo using `scalingo` cli or using the [Scalingo dashboard](https://dashboard.scalingo.com/).
+
+## Step 2: Provision Addons
+
+Add the required PostgreSQL and Redis services.
+
+This will set the following environment variables automatically:
+- `SCALINGO_POSTGRESQL_URL` - Database connection string
+- `SCALINGO_REDIS_URL` - Redis connection string
+
+## Step 3: Configure Environment Variables
+
+Set the following environment variables in your Scalingo app:
+
+### Buildpack Configuration
+
+```bash
+scalingo env-set BUILDBACK_URL="https://github.com/suitenumerique/buildpack#main"
+scalingo env-set LASUITE_APP_NAME="meet"
+scalingo env-set LASUITE_BACKEND_DIR="."
+scalingo env-set LASUITE_FRONTEND_DIR="src/frontend/"
+scalingo env-set LASUITE_NGINX_DIR="."
+scalingo env-set LASUITE_SCRIPT_POSTCOMPILE="bin/buildpack_postcompile.sh"
+scalingo env-set LASUITE_SCRIPT_POSTFRONTEND="bin/buildpack_postfrontend.sh"
+```
+
+### Database and Cache
+
+```bash
+scalingo env-set DATABASE_URL="\$SCALINGO_POSTGRESQL_URL"
+scalingo env-set REDIS_URL="\$SCALINGO_REDIS_URL"
+```
+
+### Django Settings
+
+```bash
+scalingo env-set DJANGO_SETTINGS_MODULE="meet.settings"
+scalingo env-set DJANGO_CONFIGURATION="Production"
+scalingo env-set DJANGO_SECRET_KEY="<generate-a-secure-secret-key>"
+scalingo env-set DJANGO_ALLOWED_HOSTS="my-meet-app.osc-fr1.scalingo.io"
+```
+
+### OIDC Authentication
+
+Configure your OIDC provider (e.g., Keycloak, Authentik):
+
+```bash
+scalingo env-set OIDC_OP_BASE_URL="https://auth.yourdomain.com/realms/meet"
+scalingo env-set OIDC_RP_CLIENT_ID="meet-client-id"
+scalingo env-set OIDC_RP_CLIENT_SECRET="<your-client-secret>"
+scalingo env-set OIDC_RP_SIGN_ALGO="RS256"
+```
+
+### LiveKit Configuration
+
+Meet requires a LiveKit server for video conferencing:
+
+```bash
+scalingo env-set LIVEKIT_API_URL="wss://livekit.yourdomain.com"
+scalingo env-set LIVEKIT_API_KEY="<your-livekit-api-key>"
+scalingo env-set LIVEKIT_API_SECRET="<your-livekit-api-secret>"
+```
+
+### Email Configuration (Optional)
+
+For email notifications see https://doc.scalingo.com/platform/app/sending-emails:
+
+```bash
+scalingo env-set DJANGO_EMAIL_HOST="smtp.example.org"
+scalingo env-set DJANGO_EMAIL_PORT="587"
+scalingo env-set DJANGO_EMAIL_HOST_USER="<smtp-user>"
+scalingo env-set DJANGO_EMAIL_HOST_PASSWORD="<smtp-password>"
+scalingo env-set DJANGO_EMAIL_USE_TLS="True"
+scalingo env-set DJANGO_EMAIL_FROM="meet@yourdomain.com"
+```
+
+## Step 4: Deploy
+
+Deploy your application:
+
+```bash
+git push scalingo main
+```
+
+The Procfile will automatically:
+1. Build the frontend (Vite)
+2. Build the backend (Django)
+3. Run the post-compile script (cleanup)
+4. Run the post-frontend script (move assets and prepare for deployment)
+5. Start Nginx and Gunicorn
+6. Run django migrations
+
+## Step 5: Create superuser
+
+After the first deployment, create an admin user:
+
+```bash
+scalingo run python manage.py createsuperuser
+```
+
+## Custom Domain (Optional)
+
+To use a custom domain:
+
+1. Add the domain in Scalingo dashboard
+2. Update `DJANGO_ALLOWED_HOSTS` with your custom domain
+3. Configure your DNS to point to Scalingo
+
+```bash
+scalingo domains-add meet.yourdomain.com
+scalingo env-set DJANGO_ALLOWED_HOSTS="meet.yourdomain.com,my-meet-app.osc-fr1.scalingo.io"
+```
+
+## Custom Logo (Optional)
+
+To use a custom logo, set the `CUSTOM_LOGO_URL` environment variable with an HTTPS URL pointing to an SVG item (max 5MB):
+
+```bash
+scalingo env-set CUSTOM_LOGO_URL="https://cdn.yourdomain.com/logo.svg"
+```
+
+## Troubleshooting
+
+### Check Logs
+
+```bash
+scalingo logs --tail
+```
+
+### Common Issues
+
+1. **Build fails**: Check that all required environment variables are set
+2. **Database connection error**: Verify `DATABASE_URL` is correctly set to `$SCALINGO_POSTGRESQL_URL`
+3. **Static files not served**: Ensure the buildpack post-frontend script ran successfully
+4. **OIDC errors**: Verify your OIDC provider configuration and callback URLs
+
+### Useful Commands
+
+```bash
+# Open a console
+scalingo run bash
+
+# Restart the app
+scalingo restart
+
+# Scale containers
+scalingo scale web:2
+
+# One-off command
+scalingo run python manage.py shell
+```
+
+## Architecture
+
+On Scalingo, the application runs as follows:
+
+1. **Build Phase**: The buildpack compiles both frontend and backend
+2. **Runtime**:
+   - Nginx serves static files and proxies to the backend
+   - Gunicorn runs the Django WSGI application
+   - Both processes are managed by the `bin/buildpack_start.sh` script
+
+## Additional Resources
+
+- [Scalingo Documentation](https://doc.scalingo.com/)
+- [Suite Numérique Buildpack](https://github.com/suitenumerique/buildpack)
+- [Meet Environment Variables](../../src/helm/meet/README.md)
+- [Django Configurations Documentation](https://django-configurations.readthedocs.io/)

src/backend/core/api/throttling.py

@@ -0,0 +1,26 @@
+"""Throttling modules for the API."""
+
+from lasuite.drf.throttling import MonitoredThrottleMixin
+from rest_framework.throttling import AnonRateThrottle
+from sentry_sdk import capture_message
+
+
+def sentry_monitoring_throttle_failure(message):
+    """Log when a failure occurs to detect rate limiting issues."""
+    capture_message(message, "warning")
+
+
+class MonitoredAnonRateThrottle(MonitoredThrottleMixin, AnonRateThrottle):
+    """Throttle for the monitored scoped rate throttle."""
+
+
+class RequestEntryAnonRateThrottle(MonitoredAnonRateThrottle):
+    """Throttle Anonymous user requesting room entry"""
+
+    scope = "request_entry"
+
+
+class CreationCallbackAnonRateThrottle(MonitoredAnonRateThrottle):
+    """Throttle Anonymous user requesting room generation callback"""
+
+    scope = "creation_callback"

src/backend/core/api/viewsets.py

@@ -10,7 +10,7 @@ from django.http import Http404
 from django.shortcuts import get_object_or_404
 from django.utils.text import slugify
 
-from rest_framework import decorators, mixins, pagination, throttling, viewsets
+from rest_framework import decorators, mixins, pagination, viewsets
 from rest_framework import (
     exceptions as drf_exceptions,
 )
@@ -58,7 +58,7 @@ from core.services.room_creation import RoomCreation
 from core.services.subtitle import SubtitleException, SubtitleService
 
 from ..authentication.livekit import LiveKitTokenAuthentication
-from . import permissions, serializers
+from . import permissions, serializers, throttling
 from .feature_flag import FeatureFlag
 
 # pylint: disable=too-many-ancestors
@@ -191,18 +191,6 @@ class UserViewSet(
         )
 
 
-class RequestEntryAnonRateThrottle(throttling.AnonRateThrottle):
-    """Throttle Anonymous user requesting room entry"""
-
-    scope = "request_entry"
-
-
-class CreationCallbackAnonRateThrottle(throttling.AnonRateThrottle):
-    """Throttle Anonymous user requesting room generation callback"""
-
-    scope = "creation_callback"
-
-
 class RoomViewSet(
     mixins.CreateModelMixin,
     mixins.DestroyModelMixin,
@@ -379,7 +367,7 @@ class RoomViewSet(
         methods=["post"],
         url_path="request-entry",
         permission_classes=[],
-        throttle_classes=[RequestEntryAnonRateThrottle],
+        throttle_classes=[throttling.RequestEntryAnonRateThrottle],
     )
     def request_entry(self, request, pk=None):  # pylint: disable=unused-argument
         """Request entry to a room"""
@@ -489,7 +477,7 @@ class RoomViewSet(
         methods=["post"],
         url_path="creation-callback",
         permission_classes=[],
-        throttle_classes=[CreationCallbackAnonRateThrottle],
+        throttle_classes=[throttling.CreationCallbackAnonRateThrottle],
     )
     def creation_callback(self, request):
         """Retrieve cached room data via an unauthenticated request with a unique ID.

src/backend/core/external_api/authentication.py

@@ -10,6 +10,8 @@ import jwt as pyJwt
 from lasuite.oidc_resource_server.backend import ResourceServerBackend as LaSuiteBackend
 from rest_framework import authentication, exceptions
 
+from core.models import Application
+
 User = get_user_model()
 logger = logging.getLogger(__name__)
 
@@ -94,6 +96,18 @@ class ApplicationJWTAuthentication(authentication.BaseAuthentication):
             logger.warning("Missing 'client_id' in JWT payload")
             raise exceptions.AuthenticationFailed("Invalid token claims.")
 
+        try:
+            application = Application.objects.get(client_id=client_id)
+        except Application.DoesNotExist as e:
+            logger.warning("Application not found: %s", client_id)
+            raise exceptions.AuthenticationFailed("Application not found.") from e
+
+        if not application.active:
+            logger.warning(
+                "Inactive application attempted authentication: %s", client_id
+            )
+            raise exceptions.AuthenticationFailed("Application is disabled.")
+
         if not is_delegated:
             logger.warning("Token is not marked as delegated")
             raise exceptions.AuthenticationFailed("Invalid token type.")

src/backend/core/tests/test_external_api_rooms.py

@@ -16,10 +16,7 @@ import responses
 from lasuite.oidc_resource_server.authentication import ResourceServerAuthentication
 from rest_framework.test import APIClient
 
-from core.factories import (
-    RoomFactory,
-    UserFactory,
-)
+from core.factories import ApplicationFactory, RoomFactory, UserFactory
 from core.models import ApplicationScope, RoleChoices, Room, RoomAccessLevel, User
 
 pytestmark = pytest.mark.django_db
@@ -30,12 +27,14 @@ def generate_test_token(user, scopes):
     now = datetime.now(timezone.utc)
     scope_string = " ".join(scopes)
 
+    application = ApplicationFactory()
+
     payload = {
         "iss": settings.APPLICATION_JWT_ISSUER,
         "aud": settings.APPLICATION_JWT_AUDIENCE,
         "iat": now,
         "exp": now + timedelta(seconds=settings.APPLICATION_JWT_EXPIRATION_SECONDS),
-        "client_id": "test-client-id",
+        "client_id": str(application.client_id),
         "scope": scope_string,
         "user_id": str(user.id),
         "delegated": True,
@@ -664,6 +663,7 @@ def test_api_rooms_token_scope_case_insensitive(settings):
     """Token's scope should be case-insensitive."""
     settings.APPLICATION_JWT_SECRET_KEY = "devKey"
     user = UserFactory()
+    application = ApplicationFactory()
 
     # Generate token with mixed-case scope "Rooms:List" to verify that scope
     # validation is case-insensitive (should match "rooms:list")
@@ -673,7 +673,7 @@ def test_api_rooms_token_scope_case_insensitive(settings):
         "aud": settings.APPLICATION_JWT_AUDIENCE,
         "iat": now,
         "exp": now + timedelta(hours=1),
-        "client_id": "test-client",
+        "client_id": str(application.client_id),
         "scope": "Rooms:List",  # Mixed case - should be accepted as "rooms:list"
         "user_id": str(user.id),
         "delegated": True,
@@ -695,6 +695,7 @@ def test_api_rooms_token_without_delegated_flag(settings):
     """Token without delegated flag should be rejected."""
     settings.APPLICATION_JWT_SECRET_KEY = "devKey"
     user = UserFactory()
+    application = ApplicationFactory()
 
     # Generate token without delegated flag
     now = datetime.now(timezone.utc)
@@ -703,7 +704,7 @@ def test_api_rooms_token_without_delegated_flag(settings):
         "aud": settings.APPLICATION_JWT_AUDIENCE,
         "iat": now,
         "exp": now + timedelta(hours=1),
-        "client_id": "test-client",
+        "client_id": str(application.client_id),
         "scope": "rooms:list",
         "user_id": str(user.id),
         "delegated": False,  # Not delegated
@@ -727,6 +728,7 @@ def test_api_rooms_token_invalid_signature(mock_rs_authenticate, settings):
     """Token signed with an invalid key should defer to the next authentication."""
     settings.APPLICATION_JWT_SECRET_KEY = "devKey"
     user = UserFactory()
+    application = ApplicationFactory()
 
     # Generate token without delegated flag
     now = datetime.now(timezone.utc)
@@ -735,7 +737,7 @@ def test_api_rooms_token_invalid_signature(mock_rs_authenticate, settings):
         "aud": settings.APPLICATION_JWT_AUDIENCE,
         "iat": now,
         "exp": now + timedelta(hours=1),
-        "client_id": "test-client",
+        "client_id": str(application.client_id),
         "scope": "rooms:list",
         "user_id": str(user.id),
         "delegated": True,
@@ -820,6 +822,7 @@ def test_api_rooms_token_missing_client_id(settings):
 def test_api_rooms_token_missing_user_id(settings):
     """Token without user_id should be rejected."""
     settings.APPLICATION_JWT_SECRET_KEY = "devKey"
+    application = ApplicationFactory()
 
     now = datetime.now(timezone.utc)
     payload = {
@@ -827,7 +830,7 @@ def test_api_rooms_token_missing_user_id(settings):
         "aud": settings.APPLICATION_JWT_AUDIENCE,
         "iat": now,
         "exp": now + timedelta(hours=1),
-        "client_id": "test-client",
+        "client_id": str(application.client_id),
         "scope": "rooms:list",
         "delegated": True,
         # Missing user_id
@@ -850,6 +853,7 @@ def test_api_rooms_token_invalid_audience(settings):
     """Token with an invalid audience should be rejected."""
     settings.APPLICATION_JWT_SECRET_KEY = "devKey"
     user = UserFactory()
+    application = ApplicationFactory()
 
     now = datetime.now(timezone.utc)
     payload = {
@@ -857,7 +861,7 @@ def test_api_rooms_token_invalid_audience(settings):
         "aud": "invalid-audience",
         "iat": now,
         "exp": now + timedelta(hours=1),
-        "client_id": "test-client",
+        "client_id": str(application.client_id),
         "user_id": str(user.id),
         "scope": "rooms:list",
         "delegated": True,
@@ -879,6 +883,7 @@ def test_api_rooms_token_invalid_audience(settings):
 def test_api_rooms_token_unknown_user(settings):
     """Token for unknown user should be rejected."""
     settings.APPLICATION_JWT_SECRET_KEY = "devKey"
+    application = ApplicationFactory()
 
     now = datetime.now(timezone.utc)
     payload = {
@@ -886,7 +891,7 @@ def test_api_rooms_token_unknown_user(settings):
         "aud": settings.APPLICATION_JWT_AUDIENCE,
         "iat": now,
         "exp": now + timedelta(hours=1),
-        "client_id": "test-client",
+        "client_id": str(application.client_id),
         "user_id": str(uuid.uuid4()),
         "scope": "rooms:list",
         "delegated": True,
@@ -905,6 +910,65 @@ def test_api_rooms_token_unknown_user(settings):
     assert "user not found." in str(response.data).lower()
 
 
+def test_api_rooms_token_unknown_application(settings):
+    """Token for unknown application should be rejected."""
+    settings.APPLICATION_JWT_SECRET_KEY = "devKey"
+
+    now = datetime.now(timezone.utc)
+    payload = {
+        "iss": settings.APPLICATION_JWT_ISSUER,
+        "aud": settings.APPLICATION_JWT_AUDIENCE,
+        "iat": now,
+        "exp": now + timedelta(hours=1),
+        "client_id": "unknown-client-id",
+        "user_id": str(uuid.uuid4()),
+        "scope": "rooms:list",
+        "delegated": True,
+    }
+    token = jwt.encode(
+        payload,
+        settings.APPLICATION_JWT_SECRET_KEY,
+        algorithm=settings.APPLICATION_JWT_ALG,
+    )
+
+    client = APIClient()
+    client.credentials(HTTP_AUTHORIZATION=f"Bearer {token}")
+    response = client.get("/external-api/v1.0/rooms/")
+
+    assert response.status_code == 401
+    assert "application not found." in str(response.data).lower()
+
+
+def test_api_rooms_token_inactive_application(settings):
+    """Token for inactive application should be rejected."""
+    settings.APPLICATION_JWT_SECRET_KEY = "devKey"
+    application = ApplicationFactory(active=False)
+
+    now = datetime.now(timezone.utc)
+    payload = {
+        "iss": settings.APPLICATION_JWT_ISSUER,
+        "aud": settings.APPLICATION_JWT_AUDIENCE,
+        "iat": now,
+        "exp": now + timedelta(hours=1),
+        "client_id": str(application.client_id),
+        "user_id": str(uuid.uuid4()),
+        "scope": "rooms:list",
+        "delegated": True,
+    }
+    token = jwt.encode(
+        payload,
+        settings.APPLICATION_JWT_SECRET_KEY,
+        algorithm=settings.APPLICATION_JWT_ALG,
+    )
+
+    client = APIClient()
+    client.credentials(HTTP_AUTHORIZATION=f"Bearer {token}")
+    response = client.get("/external-api/v1.0/rooms/")
+
+    assert response.status_code == 401
+    assert "application is disabled." in str(response.data).lower()
+
+
 @responses.activate
 def test_resource_server_creates_user_on_first_authentication(settings):
     """New user should be created during first authentication.

src/backend/meet/settings.py

@@ -18,6 +18,7 @@ from socket import gethostbyname, gethostname
 
 from django.utils.translation import gettext_lazy as _
 
+import dj_database_url
 import sentry_sdk
 from configurations import Configuration, values
 from lasuite.configuration.values import SecretFileValue
@@ -92,7 +93,11 @@ class Base(Configuration):
 
     # Database
     DATABASES = {
-        "default": {
+        "default": dj_database_url.config()
+        if values.DatabaseURLValue(
+            None, environ_name="DATABASE_URL", environ_prefix=None
+        )
+        else {
             "ENGINE": values.Value(
                 "django.db.backends.postgresql_psycopg2",
                 environ_name="DB_ENGINE",
@@ -292,6 +297,9 @@ class Base(Configuration):
             ),
         },
     }
+    MONITORED_THROTTLE_FAILURE_CALLBACK = (
+        "core.api.throttling.sentry_monitoring_throttle_failure"
+    )
 
     SPECTACULAR_SETTINGS = {
         "TITLE": "Meet API",

src/backend/pyproject.toml

@@ -29,6 +29,7 @@ dependencies = [
     "Brotli==1.2.0",
     "brevo-python==1.2.0",
     "celery[redis]==5.5.3",
+    "dj-database-url==3.1.0",
     "django-configurations==2.5.1",
     "django-cors-headers==4.9.0",
     "django-countries==8.0.0",

src/frontend/@types/react-aria-overlays.d.ts

@@ -0,0 +1,18 @@
+import type * as React from 'react';
+
+declare module '@react-aria/overlays' {
+  export type PortalProviderContextValue = {
+    getContainer: () => HTMLElement | null;
+  };
+
+  export type PortalProviderProps = {
+    getContainer: () => HTMLElement | null;
+    children: React.ReactNode;
+  };
+
+  export function useUNSAFE_PortalContext(): PortalProviderContextValue;
+  export function UNSAFE_PortalProvider(
+    props: PortalProviderProps,
+  ): JSX.Element;
+}
+

src/frontend/src/features/pip/components/DocumentPiPPortal.tsx

@@ -0,0 +1,193 @@
+import { type ReactNode, useEffect, useMemo, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { useDocumentPiP } from '../hooks/useDocumentPiP'
+import { UNSAFE_PortalProvider } from '@react-aria/overlays'
+
+// Minimal base styles so the PiP window renders correctly on first paint.
+const ensureBaseStyles = (target: Document) => {
+  if (target.getElementById('pip-base-styles')) return
+  const style = target.createElement('style')
+  style.id = 'pip-base-styles'
+  style.textContent = `
+    html, body { margin: 0; padding: 0; height: 100%; background: #0b0f19; }
+    body { overflow: hidden; }
+    * { box-sizing: border-box; }
+  `
+  target.head.appendChild(style)
+}
+
+// Clone existing styles to keep the PiP window visually consistent.
+const copyStyles = (source: Document, target: Document) => {
+  if (target.getElementById('pip-style-clone')) return
+  const marker = target.createElement('meta')
+  marker.id = 'pip-style-clone'
+  target.head.appendChild(marker)
+
+  source.querySelectorAll('style, link[rel="stylesheet"]').forEach((node) => {
+    const cloned = node.cloneNode(true) as HTMLElement
+    target.head.appendChild(cloned)
+  })
+}
+
+const syncThemeAttribute = (source: Document, target: Document) => {
+  const theme = source.documentElement.getAttribute('data-lk-theme')
+  if (theme) {
+    target.documentElement.setAttribute('data-lk-theme', theme)
+  }
+}
+
+const cssVarNameCacheByElement = new WeakMap<HTMLElement, string[]>()
+const cssVarNameCacheByUri = new Map<string, string[]>()
+
+const syncCssVariables = (source: Document, target: Document) => {
+  const sourceView = source.defaultView
+  if (!sourceView) return
+
+  const getCachedVarNames = () => {
+    const docEl = source.documentElement
+    if (!docEl) return []
+
+    const cachedByElement = cssVarNameCacheByElement.get(docEl)
+    if (cachedByElement) return cachedByElement
+
+    const cachedByUri = source.baseURI
+      ? cssVarNameCacheByUri.get(source.baseURI)
+      : undefined
+    if (cachedByUri) return cachedByUri
+
+    const varNames = new Set<string>()
+    const collectVarsFrom = (element: HTMLElement | null) => {
+      if (!element) return
+      const styles = sourceView.getComputedStyle(element)
+      for (let i = 0; i < styles.length; i += 1) {
+        const property = styles[i]
+        if (property.startsWith('--')) {
+          varNames.add(property)
+        }
+      }
+    }
+
+    collectVarsFrom(source.documentElement)
+    collectVarsFrom(source.body)
+
+    const result = Array.from(varNames)
+    cssVarNameCacheByElement.set(docEl, result)
+    if (source.baseURI) {
+      cssVarNameCacheByUri.set(source.baseURI, result)
+    }
+    return result
+  }
+
+  const varNames = getCachedVarNames()
+  if (!varNames.length) return
+
+  const rootStyles = sourceView.getComputedStyle(source.documentElement)
+  const bodyStyles = source.body
+    ? sourceView.getComputedStyle(source.body)
+    : null
+
+  varNames.forEach((property) => {
+    const bodyValue = bodyStyles?.getPropertyValue(property)
+    const value = bodyValue || rootStyles.getPropertyValue(property)
+    if (value) {
+      target.documentElement.style.setProperty(property, value)
+    }
+  })
+}
+
+/**
+ * React Portal that renders children into a Document Picture-in-Picture window.
+ * Handles PiP window lifecycle, style injection, React root management, and uses UNSAFE_PortalProvider
+ * to ensure React Aria overlays render correctly within the PiP window.
+ * Creates a fresh React root on reopen to prevent black screen issues.
+ */
+export const DocumentPiPPortal = ({
+  isOpen,
+  width,
+  height,
+  children,
+  onClose,
+}: {
+  isOpen: boolean
+  width?: number
+  height?: number
+  children: React.ReactNode
+  onClose?: () => void
+}): ReactNode => {
+  const { openPiP, closePiP, pipWindow, isSupported } = useDocumentPiP({
+    width,
+    height,
+  })
+  const [container, setContainer] = useState<HTMLElement | null>(null)
+  const containerRef = useRef<HTMLElement | null>(null)
+
+  useEffect(() => {
+    if (!isOpen) {
+      closePiP()
+      setContainer(null)
+      containerRef.current = null
+      return
+    }
+
+    if (!isSupported) return
+
+    let cancelled = false
+    openPiP().then((win) => {
+      if (!win || cancelled) return
+      const doc = win.document
+      ensureBaseStyles(doc)
+      copyStyles(document, doc)
+      syncThemeAttribute(document, doc)
+      syncCssVariables(document, doc)
+      const existingContainer = containerRef.current
+      if (!existingContainer || existingContainer.ownerDocument !== doc) {
+        const nextContainer = doc.createElement('div')
+        nextContainer.id = 'pip-root'
+        nextContainer.style.width = '100%'
+        nextContainer.style.height = '100%'
+        nextContainer.style.display = 'flex'
+        nextContainer.style.alignItems = 'stretch'
+        nextContainer.style.justifyContent = 'center'
+        doc.body.appendChild(nextContainer)
+        containerRef.current = nextContainer
+        setContainer(nextContainer)
+      } else {
+        setContainer(existingContainer)
+      }
+    })
+
+    return () => {
+      cancelled = true
+    }
+  }, [closePiP, isOpen, isSupported, openPiP])
+
+  useEffect(() => {
+    if (!pipWindow) return
+    const handleClose = () => {
+      // Reset container so reopening PiP mounts a fresh root.
+      containerRef.current = null
+      setContainer(null)
+      onClose?.()
+    }
+    pipWindow.addEventListener('pagehide', handleClose)
+    pipWindow.addEventListener('beforeunload', handleClose)
+    return () => {
+      pipWindow.removeEventListener('pagehide', handleClose)
+      pipWindow.removeEventListener('beforeunload', handleClose)
+    }
+  }, [onClose, pipWindow])
+
+  const portal = useMemo(() => {
+    if (!container) return null
+    return createPortal(
+      // "UNSAFE" because it bypasses react-aria's default portal container.
+      // We need it to target the PiP document; otherwise overlays render in the main window.
+      <UNSAFE_PortalProvider getContainer={() => container}>
+        {children}
+      </UNSAFE_PortalProvider>,
+      container
+    )
+  }, [children, container])
+
+  return portal as unknown as ReactNode
+}

src/frontend/src/features/pip/components/PipControlBar.tsx

@@ -0,0 +1,59 @@
+import { styled } from '@/styled-system/jsx'
+import { AudioDevicesControl } from '@/features/rooms/livekit/components/controls/Device/AudioDevicesControl'
+import { VideoDeviceControl } from '@/features/rooms/livekit/components/controls/Device/VideoDeviceControl'
+import { ScreenShareToggle } from '@/features/rooms/livekit/components/controls/ScreenShareToggle'
+import { LeaveButton } from '@/features/rooms/livekit/components/controls/LeaveButton'
+import { ReactionsToggle } from '@/features/rooms/livekit/components/controls/ReactionsToggle'
+import { SubtitlesToggle } from '@/features/rooms/livekit/components/controls/SubtitlesToggle'
+import { HandToggle } from '@/features/rooms/livekit/components/controls/HandToggle'
+import { OptionsButton } from '@/features/rooms/livekit/components/controls/Options/OptionsButton'
+import { StartMediaButton } from '@/features/rooms/livekit/components/controls/StartMediaButton'
+
+/**
+ * Compact control bar for the Picture-in-Picture window.
+ * Centralizes all PiP controls (devices, reactions, screen share, options, etc.) in one reusable component.
+ */
+export const PipControlBar = ({
+  showScreenShare,
+}: {
+  showScreenShare: boolean
+}) => (
+  <PipControls>
+    <PipControlsCenter>
+      <AudioDevicesControl hideMenu />
+      <VideoDeviceControl hideMenu />
+      <ReactionsToggle />
+      {showScreenShare && <ScreenShareToggle />}
+      <SubtitlesToggle />
+      <HandToggle />
+      <OptionsButton />
+      <LeaveButton />
+      <StartMediaButton />
+    </PipControlsCenter>
+  </PipControls>
+)
+
+const PipControls = styled('div', {
+  base: {
+    flex: '0 0 auto',
+    display: 'flex',
+    justifyContent: 'center',
+    alignItems: 'center',
+    gap: '0.5rem',
+    padding: '0.5rem 0.75rem',
+    backgroundColor: 'primaryDark.50',
+    width: '100%',
+    position: 'relative',
+  },
+})
+
+const PipControlsCenter = styled('div', {
+  base: {
+    display: 'flex',
+    flexWrap: 'wrap',
+    justifyContent: 'center',
+    alignItems: 'center',
+    gap: '0.4rem',
+    flex: '1 1 auto',
+  },
+})

src/frontend/src/features/pip/components/PipView.tsx

@@ -0,0 +1,110 @@
+import { styled } from '@/styled-system/jsx'
+import { supportsScreenSharing } from '@livekit/components-core'
+import {
+  isTrackReference,
+  TrackReferenceOrPlaceholder,
+} from '@livekit/components-core'
+import { useTracks } from '@livekit/components-react'
+import { Track } from 'livekit-client'
+import { ParticipantTile } from '@/features/rooms/livekit/components/ParticipantTile'
+import { GridLayout } from '@/features/rooms/livekit/components/layout/GridLayout'
+import { SidePanel } from '@/features/rooms/livekit/components/SidePanel'
+import { pipLayoutStore } from '../stores/pipLayoutStore'
+import { PipControlBar } from './PipControlBar'
+
+const pickTrackForPip = (
+  tracks: TrackReferenceOrPlaceholder[]
+): TrackReferenceOrPlaceholder | undefined => {
+  // Prefer screen share when present; otherwise fallback to first available track.
+  const screenShareTrack = tracks
+    .filter(isTrackReference)
+    .find((track) => track.publication.source === Track.Source.ScreenShare)
+
+  if (screenShareTrack) return screenShareTrack
+  return tracks[0]
+}
+
+/**
+ * Main view component for the Picture-in-Picture window.
+ * Handles track selection (prioritizes screen share), layout switching (grid for multiple participants),
+ * and renders the control bar and side panel within the PiP window.
+ */
+export const PipView = () => {
+  const tracks = useTracks(
+    [
+      { source: Track.Source.Camera, withPlaceholder: true },
+      { source: Track.Source.ScreenShare, withPlaceholder: false },
+    ],
+    { onlySubscribed: false }
+  )
+
+  const trackRef = pickTrackForPip(tracks)
+  const browserSupportsScreenSharing = supportsScreenSharing()
+  const hasMultipleTiles = tracks.length > 1
+
+  if (!trackRef && !hasMultipleTiles) return null
+
+  return (
+    <PipContainer>
+      {/* Keep stage height stable to avoid layout shifting on track changes. */}
+      <PipStage>
+        {hasMultipleTiles ? (
+          <PipGridWrapper>
+            <GridLayout tracks={tracks} style={{ height: '100%' }}>
+              <ParticipantTile disableMetadata />
+            </GridLayout>
+          </PipGridWrapper>
+        ) : (
+          <ParticipantTile trackRef={trackRef} disableMetadata />
+        )}
+      </PipStage>
+      {/* Compact control bar for PiP; extend here when adding more actions. */}
+      <PipControlBar showScreenShare={browserSupportsScreenSharing} />
+      {/* Side panel (effects, settings, etc.) opens within PiP window. */}
+      <SidePanel store={pipLayoutStore} />
+    </PipContainer>
+  )
+}
+
+const PipContainer = styled('div', {
+  base: {
+    width: '100%',
+    height: '100%',
+    display: 'grid',
+    gridTemplateRows: 'minmax(0, 1fr) auto',
+    backgroundColor: 'primaryDark.50',
+    '& .lk-participant-tile': {
+      height: '100%',
+    },
+    '& .lk-participant-media': {
+      height: '100%',
+    },
+    '& .lk-participant-media-video': {
+      height: '100%',
+      objectFit: 'cover',
+    },
+    '& .lk-grid-layout': {
+      height: '100%',
+      width: '100%',
+    },
+  },
+})
+
+const PipStage = styled('div', {
+  base: {
+    position: 'relative',
+    minHeight: 0,
+  },
+})
+
+const PipGridWrapper = styled('div', {
+  base: {
+    position: 'relative',
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: '100%',
+    height: '100%',
+  },
+})

src/frontend/src/features/pip/components/RoomPiP.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react'
+
+import { DocumentPiPPortal } from './DocumentPiPPortal'
+import { PipView } from './PipView'
+import { useRoomPiP } from '../hooks/useRoomPiP'
+
+/**
+ * Wrapper that mounts the PiP UI when room-level PiP state is enabled.
+ * Bridges Valtio-backed PiP state with DocumentPiPPortal and PipView rendering.
+ * PiP panel state is decoupled via explicit pipLayoutStore injection.
+ */
+export const RoomPiP = (): ReactNode => {
+  const { isOpen, close } = useRoomPiP()
+
+  const portal = DocumentPiPPortal({
+    isOpen,
+    onClose: close,
+    children: <PipView />,
+  })
+  return portal as ReactNode
+}

src/frontend/src/features/pip/components/controls/PipOptionsMenu.tsx

@@ -0,0 +1,86 @@
+import React, { useEffect } from 'react'
+import { RiMoreFill } from '@remixicon/react'
+import { Box, Button } from '@/primitives'
+import { css } from '@/styled-system/css'
+import { PipOptionsMenuItems } from './PipOptionsMenuItems'
+
+type PipOptionsMenuProps = {
+  wrapperRef: React.RefObject<HTMLDivElement>
+  isOpen: boolean
+  setIsOpen: (isOpen: boolean) => void
+  label: string
+}
+
+/**
+ * PiP-specific options menu with absolute positioning for correct alignment in PiP window.
+ * Renders locally (unlike standard Menu) and closes automatically on item click or outside click.
+ */
+export const PipOptionsMenu = ({
+  wrapperRef,
+  isOpen,
+  setIsOpen,
+  label,
+}: PipOptionsMenuProps) => {
+  // Close menu when a menu item action completes (e.g., transcription, effects, recording).
+  useEffect(() => {
+    if (!isOpen) return
+    const doc = wrapperRef.current?.ownerDocument ?? document
+
+    const handleMenuItemClick = (event: MouseEvent) => {
+      const target = event.target as HTMLElement | null
+      const wrapper = wrapperRef.current
+      if (!wrapper || !target) return
+
+      // Don't close if clicking the trigger button
+      if (wrapper.querySelector('button')?.contains(target)) return
+
+      // Close if clicking a menu item (action will have fired)
+      if (target.closest('[role="menuitem"]')) {
+        // Use requestAnimationFrame to ensure action completes first, without visible delay
+        requestAnimationFrame(() => {
+          setIsOpen(false)
+        })
+      }
+    }
+
+    doc.addEventListener('click', handleMenuItemClick, true)
+    return () => {
+      doc.removeEventListener('click', handleMenuItemClick, true)
+    }
+  }, [isOpen, setIsOpen, wrapperRef])
+
+  return (
+    <div
+      ref={wrapperRef}
+      className={css({
+        position: 'relative',
+      })}
+    >
+      <Button
+        id="room-options-trigger"
+        square
+        variant="primaryDark"
+        aria-label={label}
+        tooltip={label}
+        onPress={() => setIsOpen(!isOpen)}
+      >
+        <RiMoreFill />
+      </Button>
+      {isOpen && (
+        <div
+          className={css({
+            position: 'absolute',
+            left: '50%',
+            bottom: 'calc(100% + 0.85rem)',
+            transform: 'translateX(-50%)',
+            zIndex: 10,
+          })}
+        >
+          <Box size="sm" type="popover" variant="dark">
+            <PipOptionsMenuItems />
+          </Box>
+        </div>
+      )}
+    </div>
+  )
+}

src/frontend/src/features/pip/components/controls/PipOptionsMenuItems.tsx

@@ -0,0 +1,32 @@
+import { Menu as RACMenu, MenuSection } from 'react-aria-components'
+import { Separator } from '@/primitives/Separator'
+import { SettingsMenuItem } from '@/features/rooms/livekit/components/controls/Options/SettingsMenuItem'
+import { FeedbackMenuItem } from '@/features/rooms/livekit/components/controls/Options/FeedbackMenuItem'
+import { EffectsMenuItem } from '@/features/rooms/livekit/components/controls/Options/EffectsMenuItem'
+import { SupportMenuItem } from '@/features/rooms/livekit/components/controls/Options/SupportMenuItem'
+import { PictureInPictureMenuItem } from '@/features/rooms/livekit/components/controls/Options/PictureInPictureMenuItem'
+import { pipLayoutStore } from '@/features/pip/stores/pipLayoutStore'
+
+/**
+ * PiP options menu items: excludes transcript, screen recording, and full screen
+ * (those features are not relevant in the PiP window context).
+ */
+export const PipOptionsMenuItems = () => (
+  <RACMenu
+    style={{
+      minWidth: '150px',
+      width: '300px',
+    }}
+  >
+    <MenuSection>
+      <PictureInPictureMenuItem />
+      <EffectsMenuItem store={pipLayoutStore} />
+    </MenuSection>
+    <Separator />
+    <MenuSection>
+      <SupportMenuItem />
+      <FeedbackMenuItem />
+      <SettingsMenuItem />
+    </MenuSection>
+  </RACMenu>
+)

src/frontend/src/features/pip/hooks/useDocumentPiP.ts

@@ -0,0 +1,96 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+type DocumentPictureInPicture = {
+  requestWindow: (options?: {
+    width?: number
+    height?: number
+  }) => Promise<Window>
+}
+
+type WindowWithDocumentPiP = Window & {
+  documentPictureInPicture?: DocumentPictureInPicture
+}
+
+export const useDocumentPiP = ({
+  width = 480,
+  height = 270,
+}: {
+  width?: number
+  height?: number
+} = {}) => {
+  const [pipWindow, setPipWindow] = useState<Window | null>(null)
+  const pipWindowRef = useRef<Window | null>(null)
+  const pendingPiPRef = useRef<Promise<Window | null> | null>(null)
+
+  const [isSupported] = useState(() => {
+    if (typeof window === 'undefined') return false
+    return 'documentPictureInPicture' in window
+  })
+
+  const openPiP = useCallback(async () => {
+    if (!isSupported) return null
+    const existingWindow = pipWindowRef.current
+    if (existingWindow && !existingWindow.closed) return existingWindow
+
+    if (pendingPiPRef.current) return pendingPiPRef.current
+
+    // Request a new PiP window from the browser API.
+    const pip = (window as WindowWithDocumentPiP).documentPictureInPicture
+    if (!pip) return null
+
+    const requestPromise = (async () => {
+      try {
+        const win = await pip.requestWindow({ width, height })
+        const currentWindow = pipWindowRef.current
+        if (currentWindow && !currentWindow.closed) return currentWindow
+        setPipWindow(win)
+        return win
+      } catch (error) {
+        // Avoid unhandled rejections if the user blocks or closes the request.
+        console.error('Failed to open Picture-in-Picture window', error)
+        return null
+      } finally {
+        pendingPiPRef.current = null
+      }
+    })()
+
+    pendingPiPRef.current = requestPromise
+    return requestPromise
+  }, [height, isSupported, width])
+
+  const closePiP = useCallback(() => {
+    if (!pipWindow) return
+    if (!pipWindow.closed) {
+      pipWindow.close()
+    }
+    setPipWindow(null)
+  }, [pipWindow])
+
+  useEffect(() => {
+    pipWindowRef.current = pipWindow
+  }, [pipWindow])
+
+  useEffect(() => {
+    if (!pipWindow) return
+
+    const handleClose = () => {
+      setPipWindow(null)
+    }
+
+    pipWindow.addEventListener('pagehide', handleClose)
+    pipWindow.addEventListener('beforeunload', handleClose)
+
+    return () => {
+      pipWindow.removeEventListener('pagehide', handleClose)
+      pipWindow.removeEventListener('beforeunload', handleClose)
+    }
+  }, [pipWindow])
+
+  return {
+    isSupported,
+    isOpen: !!pipWindow && !pipWindow.closed,
+    pipWindow,
+    openPiP,
+    closePiP,
+  }
+}

src/frontend/src/features/pip/hooks/useRoomPiP.tsx

@@ -0,0 +1,29 @@
+import { useCallback } from 'react'
+import { useSnapshot } from 'valtio'
+import { roomPiPStore } from '@/stores/roomPiP'
+
+export const useRoomPiP = () => {
+  const { isOpen } = useSnapshot(roomPiPStore)
+  const isSupported =
+    typeof window !== 'undefined' && 'documentPictureInPicture' in window
+
+  const open = useCallback(() => {
+    roomPiPStore.isOpen = true
+  }, [])
+
+  const close = useCallback(() => {
+    roomPiPStore.isOpen = false
+  }, [])
+
+  const toggle = useCallback(() => {
+    roomPiPStore.isOpen = !roomPiPStore.isOpen
+  }, [])
+
+  return {
+    isSupported,
+    isOpen,
+    open,
+    close,
+    toggle,
+  }
+}

src/frontend/src/features/pip/stores/pipLayoutStore.ts

@@ -0,0 +1,17 @@
+import { proxy } from 'valtio'
+import type { PanelId, SubPanelId } from '@/features/rooms/livekit/types/panel'
+
+type PipLayoutState = {
+  activePanelId: PanelId | null
+  activeSubPanelId: SubPanelId | null
+}
+
+/**
+ * Separate layout store for the PiP window.
+ * Decouples PiP side panel state from the main view so opening Chat/Info/etc.
+ * in PiP does not affect the main window and vice versa.
+ */
+export const pipLayoutStore = proxy<PipLayoutState>({
+  activePanelId: null,
+  activeSubPanelId: null,
+})

src/frontend/src/features/rooms/livekit/components/SidePanel.tsx

@@ -1,4 +1,3 @@
-import { layoutStore } from '@/stores/layout'
 import { css } from '@/styled-system/css'
 import { Heading } from 'react-aria-components'
 import { text } from '@/primitives/Text'
@@ -6,7 +5,7 @@ import { Button, Div } from '@/primitives'
 import { RiArrowLeftLine, RiCloseLine } from '@remixicon/react'
 import { useTranslation } from 'react-i18next'
 import { ParticipantsList } from './controls/Participants/ParticipantsList'
-import { useSidePanel } from '../hooks/useSidePanel'
+import { type SidePanelStore, useSidePanel } from '../hooks/useSidePanel'
 import { ReactNode } from 'react'
 import { Chat } from '../prefabs/Chat'
 import { Effects } from './effects/Effects'
@@ -135,7 +134,7 @@ const Panel = ({ isOpen, keepAlive = false, children }: PanelProps) => (
     {keepAlive || isOpen ? children : null}
   </div>
 )
-export const SidePanel = () => {
+export const SidePanel = ({ store }: { store?: SidePanelStore }) => {
   const {
     activePanelId,
     isParticipantsOpen,
@@ -147,24 +146,23 @@ export const SidePanel = () => {
     isInfoOpen,
     isSubPanelOpen,
     activeSubPanelId,
-  } = useSidePanel()
+    closePanel,
+    goBack,
+  } = useSidePanel(store)
   const { t } = useTranslation('rooms', { keyPrefix: 'sidePanel' })
 
   return (
     <StyledSidePanel
       title={t(`heading.${activeSubPanelId || activePanelId}`)}
       ariaLabel={t('ariaLabel')}
-      onClose={() => {
-        layoutStore.activePanelId = null
-        layoutStore.activeSubPanelId = null
-      }}
+      onClose={closePanel}
       closeButtonTooltip={t('closeButton', {
         content: t(`content.${activeSubPanelId || activePanelId}`),
       })}
       isClosed={!isSidePanelOpen}
       isSubmenu={isSubPanelOpen}
       backButtonLabel={t('backToTools')}
-      onBack={() => (layoutStore.activeSubPanelId = null)}
+      onBack={goBack}
     >
       <Panel isOpen={isParticipantsOpen}>
         <ParticipantsList />

src/frontend/src/features/rooms/livekit/components/controls/Options/EffectsMenuItem.tsx

@@ -2,11 +2,11 @@ import { RiImageCircleAiFill } from '@remixicon/react'
 import { MenuItem } from 'react-aria-components'
 import { useTranslation } from 'react-i18next'
 import { menuRecipe } from '@/primitives/menuRecipe'
-import { useSidePanel } from '../../../hooks/useSidePanel'
+import { type SidePanelStore, useSidePanel } from '../../../hooks/useSidePanel'
 
-export const EffectsMenuItem = () => {
+export const EffectsMenuItem = ({ store }: { store?: SidePanelStore }) => {
   const { t } = useTranslation('rooms', { keyPrefix: 'options.items' })
-  const { toggleEffects } = useSidePanel()
+  const { toggleEffects } = useSidePanel(store)
 
   return (
     <MenuItem

src/frontend/src/features/rooms/livekit/components/controls/Options/OptionsButton.tsx

@@ -2,9 +2,27 @@ import { useTranslation } from 'react-i18next'
 import { RiMoreFill } from '@remixicon/react'
 import { Button, Menu } from '@/primitives'
 import { OptionsMenuItems } from './OptionsMenuItems'
+import { useOverlayPortalContainer } from '@/primitives/useOverlayPortalContainer'
+import { useRef, useState } from 'react'
+import { PipOptionsMenu } from '@/features/pip/components/controls/PipOptionsMenu'
 
 export const OptionsButton = () => {
   const { t } = useTranslation('rooms')
+  const portalContainer = useOverlayPortalContainer()
+  const isInPiP = portalContainer && portalContainer.ownerDocument !== document
+  const [isOpen, setIsOpen] = useState(false)
+  const wrapperRef = useRef<HTMLDivElement>(null)
+
+  if (isInPiP) {
+    return (
+      <PipOptionsMenu
+        wrapperRef={wrapperRef}
+        isOpen={isOpen}
+        setIsOpen={setIsOpen}
+        label={t('options.buttonLabel')}
+      />
+    )
+  }
 
   return (
     <Menu variant="dark">

src/frontend/src/features/rooms/livekit/components/controls/Options/OptionsMenuItems.tsx

@@ -7,6 +7,7 @@ import { EffectsMenuItem } from './EffectsMenuItem'
 import { SupportMenuItem } from './SupportMenuItem'
 import { TranscriptMenuItem } from './TranscriptMenuItem'
 import { ScreenRecordingMenuItem } from './ScreenRecordingMenuItem'
+import { PictureInPictureMenuItem } from './PictureInPictureMenuItem'
 
 // @todo try refactoring it to use MenuList component
 export const OptionsMenuItems = () => {
@@ -21,6 +22,7 @@ export const OptionsMenuItems = () => {
         <TranscriptMenuItem />
         <ScreenRecordingMenuItem />
         <FullScreenMenuItem />
+        <PictureInPictureMenuItem />
         <EffectsMenuItem />
       </MenuSection>
       <Separator />

src/frontend/src/features/rooms/livekit/components/controls/Options/PictureInPictureMenuItem.tsx

@@ -0,0 +1,23 @@
+import { MenuItem } from 'react-aria-components'
+import { useTranslation } from 'react-i18next'
+import { RiPictureInPicture2Line } from '@remixicon/react'
+import { menuRecipe } from '@/primitives/menuRecipe'
+import { useRoomPiP } from '@/features/pip/hooks/useRoomPiP'
+
+export const PictureInPictureMenuItem = () => {
+  const { t } = useTranslation('rooms', { keyPrefix: 'options.items' })
+  const { isSupported, isOpen, toggle } = useRoomPiP()
+
+  // Hide the entry when the browser doesn't support Document PiP.
+  if (!isSupported) return null
+
+  return (
+    <MenuItem
+      onAction={toggle}
+      className={menuRecipe({ icon: true, variant: 'dark' }).item}
+    >
+      <RiPictureInPicture2Line size={20} />
+      {isOpen ? t('pictureInPicture.exit') : t('pictureInPicture.enter')}
+    </MenuItem>
+  )
+}

src/frontend/src/features/rooms/livekit/hooks/useSidePanel.ts

@@ -1,74 +1,77 @@
 import { useSnapshot } from 'valtio'
 import { layoutStore } from '@/stores/layout'
+import { PanelId, SubPanelId } from '../types/panel'
 
-export enum PanelId {
-  PARTICIPANTS = 'participants',
-  EFFECTS = 'effects',
-  CHAT = 'chat',
-  TOOLS = 'tools',
-  ADMIN = 'admin',
-  INFO = 'info',
+export { PanelId, SubPanelId }
+
+export type SidePanelStore = {
+  activePanelId: PanelId | null
+  activeSubPanelId: SubPanelId | null
 }
 
-export enum SubPanelId {
-  TRANSCRIPT = 'transcript',
-  SCREEN_RECORDING = 'screenRecording',
-}
-
-export const useSidePanel = () => {
-  const layoutSnap = useSnapshot(layoutStore)
+export const useSidePanel = (store: SidePanelStore = layoutStore) => {
+  const layoutSnap = useSnapshot(store)
   const activePanelId = layoutSnap.activePanelId
   const activeSubPanelId = layoutSnap.activeSubPanelId
 
-  const isParticipantsOpen = activePanelId == PanelId.PARTICIPANTS
-  const isEffectsOpen = activePanelId == PanelId.EFFECTS
-  const isChatOpen = activePanelId == PanelId.CHAT
-  const isToolsOpen = activePanelId == PanelId.TOOLS
-  const isAdminOpen = activePanelId == PanelId.ADMIN
-  const isInfoOpen = activePanelId == PanelId.INFO
-  const isTranscriptOpen = activeSubPanelId == SubPanelId.TRANSCRIPT
-  const isScreenRecordingOpen = activeSubPanelId == SubPanelId.SCREEN_RECORDING
+  const isParticipantsOpen = activePanelId === PanelId.PARTICIPANTS
+  const isEffectsOpen = activePanelId === PanelId.EFFECTS
+  const isChatOpen = activePanelId === PanelId.CHAT
+  const isToolsOpen = activePanelId === PanelId.TOOLS
+  const isAdminOpen = activePanelId === PanelId.ADMIN
+  const isInfoOpen = activePanelId === PanelId.INFO
+  const isTranscriptOpen = activeSubPanelId === SubPanelId.TRANSCRIPT
+  const isScreenRecordingOpen = activeSubPanelId === SubPanelId.SCREEN_RECORDING
   const isSidePanelOpen = !!activePanelId
   const isSubPanelOpen = !!activeSubPanelId
 
   const toggleAdmin = () => {
-    layoutStore.activePanelId = isAdminOpen ? null : PanelId.ADMIN
-    if (layoutSnap.activeSubPanelId) layoutStore.activeSubPanelId = null
+    store.activePanelId = isAdminOpen ? null : PanelId.ADMIN
+    if (layoutSnap.activeSubPanelId) store.activeSubPanelId = null
   }
 
   const toggleParticipants = () => {
-    layoutStore.activePanelId = isParticipantsOpen ? null : PanelId.PARTICIPANTS
-    if (layoutSnap.activeSubPanelId) layoutStore.activeSubPanelId = null
+    store.activePanelId = isParticipantsOpen ? null : PanelId.PARTICIPANTS
+    if (layoutSnap.activeSubPanelId) store.activeSubPanelId = null
   }
 
   const toggleChat = () => {
-    layoutStore.activePanelId = isChatOpen ? null : PanelId.CHAT
-    if (layoutSnap.activeSubPanelId) layoutStore.activeSubPanelId = null
+    store.activePanelId = isChatOpen ? null : PanelId.CHAT
+    if (layoutSnap.activeSubPanelId) store.activeSubPanelId = null
   }
 
   const toggleEffects = () => {
-    layoutStore.activePanelId = isEffectsOpen ? null : PanelId.EFFECTS
-    if (layoutSnap.activeSubPanelId) layoutStore.activeSubPanelId = null
+    store.activePanelId = isEffectsOpen ? null : PanelId.EFFECTS
+    if (layoutSnap.activeSubPanelId) store.activeSubPanelId = null
   }
 
   const toggleTools = () => {
-    layoutStore.activePanelId = isToolsOpen ? null : PanelId.TOOLS
-    if (layoutSnap.activeSubPanelId) layoutStore.activeSubPanelId = null
+    store.activePanelId = isToolsOpen ? null : PanelId.TOOLS
+    if (layoutSnap.activeSubPanelId) store.activeSubPanelId = null
   }
 
   const toggleInfo = () => {
-    layoutStore.activePanelId = isInfoOpen ? null : PanelId.INFO
-    if (layoutSnap.activeSubPanelId) layoutStore.activeSubPanelId = null
+    store.activePanelId = isInfoOpen ? null : PanelId.INFO
+    if (layoutSnap.activeSubPanelId) store.activeSubPanelId = null
   }
 
   const openTranscript = () => {
-    layoutStore.activeSubPanelId = SubPanelId.TRANSCRIPT
-    layoutStore.activePanelId = PanelId.TOOLS
+    store.activeSubPanelId = SubPanelId.TRANSCRIPT
+    store.activePanelId = PanelId.TOOLS
   }
 
   const openScreenRecording = () => {
-    layoutStore.activeSubPanelId = SubPanelId.SCREEN_RECORDING
-    layoutStore.activePanelId = PanelId.TOOLS
+    store.activeSubPanelId = SubPanelId.SCREEN_RECORDING
+    store.activePanelId = PanelId.TOOLS
+  }
+
+  const closePanel = () => {
+    store.activePanelId = null
+    store.activeSubPanelId = null
+  }
+
+  const goBack = () => {
+    store.activeSubPanelId = null
   }
 
   return {
@@ -82,6 +85,8 @@ export const useSidePanel = () => {
     toggleInfo,
     openTranscript,
     openScreenRecording,
+    closePanel,
+    goBack,
     isSubPanelOpen,
     isChatOpen,
     isParticipantsOpen,

src/frontend/src/features/rooms/livekit/prefabs/VideoConference.tsx

@@ -38,9 +38,16 @@ import { Subtitles } from '@/features/subtitle/component/Subtitles'
 import { CarouselLayout } from '../components/layout/CarouselLayout'
 import { GridLayout } from '../components/layout/GridLayout'
 import { IsIdleDisconnectModal } from '../components/IsIdleDisconnectModal'
+import { RoomPiP } from '@/features/pip/components/RoomPiP'
+import { useRoomPiP } from '@/features/pip/hooks/useRoomPiP'
 import { getParticipantName } from '@/features/rooms/utils/getParticipantName'
 import { useScreenReaderAnnounce } from '@/hooks/useScreenReaderAnnounce'
 
+const SIDE_PANEL_WIDTH = '358px'
+const CONTROL_BAR_HEIGHT = '80px'
+const SIDE_PANEL_OFFSET = '16px'
+const SIDE_PANEL_GAP = '3rem'
+
 const LayoutWrapper = styled(
   'div',
   cva({
@@ -243,8 +250,16 @@ export function VideoConference({ ...props }: VideoConferenceProps) {
 
   const { isSidePanelOpen } = useSidePanel()
   const { areSubtitlesOpen } = useSubtitles()
+  const { isOpen: isPiPOpen } = useRoomPiP()
+  const shouldRenderMainLayout = !isPiPOpen
 
   const [isShareErrorVisible, setIsShareErrorVisible] = useState(false)
+  const layoutInsetVars = {
+    '--lk-side-panel-width': SIDE_PANEL_WIDTH,
+    '--lk-controlbar-height': CONTROL_BAR_HEIGHT,
+    '--lk-side-panel-offset': SIDE_PANEL_OFFSET,
+    '--lk-side-panel-gap': SIDE_PANEL_GAP,
+  } as React.CSSProperties
 
   return (
     <div
@@ -259,75 +274,78 @@ export function VideoConference({ ...props }: VideoConferenceProps) {
           value={layoutContext}
           // onPinChange={handleFocusStateChange}
         >
-          <ScreenShareErrorModal
-            isOpen={isShareErrorVisible}
-            onClose={() => setIsShareErrorVisible(false)}
-          />
-          <IsIdleDisconnectModal />
-          <div
-            // todo - extract these magic values into constant
-            style={{
-              position: 'absolute',
-              inset: isSidePanelOpen
-                ? `var(--lk-grid-gap) calc(358px + 3rem) calc(80px + var(--lk-grid-gap)) 16px`
-                : `var(--lk-grid-gap) var(--lk-grid-gap) calc(80px + var(--lk-grid-gap))`,
-              transition: 'inset .5s cubic-bezier(0.4,0,0.2,1) 5ms',
-              maxHeight: '100%',
-            }}
-          >
-            <LayoutWrapper areSubtitlesOpen={areSubtitlesOpen}>
-              <div
-                style={{
-                  display: 'flex',
-                  position: 'relative',
-                  width: '100%',
-                }}
-              >
-                {!focusTrack ? (
+            <ScreenShareErrorModal
+              isOpen={isShareErrorVisible}
+              onClose={() => setIsShareErrorVisible(false)}
+            />
+            <IsIdleDisconnectModal />
+            <div
+              style={{
+                position: 'absolute',
+                ...layoutInsetVars,
+                inset: isSidePanelOpen
+                  ? `var(--lk-grid-gap) calc(var(--lk-side-panel-width) + var(--lk-side-panel-gap)) calc(var(--lk-controlbar-height) + var(--lk-grid-gap)) var(--lk-side-panel-offset)`
+                  : `var(--lk-grid-gap) var(--lk-grid-gap) calc(var(--lk-controlbar-height) + var(--lk-grid-gap))`,
+                transition: 'inset .5s cubic-bezier(0.4,0,0.2,1) 5ms',
+                maxHeight: '100%',
+              }}
+            >
+              {shouldRenderMainLayout && (
+                <LayoutWrapper areSubtitlesOpen={areSubtitlesOpen}>
                   <div
-                    className="lk-grid-layout-wrapper"
-                    style={{ height: 'auto' }}
+                    style={{
+                      display: 'flex',
+                      position: 'relative',
+                      width: '100%',
+                    }}
                   >
-                    <GridLayout tracks={tracks} style={{ padding: 0 }}>
-                      <ParticipantTile />
-                    </GridLayout>
-                  </div>
-                ) : (
-                  <div
-                    className="lk-focus-layout-wrapper"
-                    style={{ height: 'auto' }}
-                  >
-                    <FocusLayoutContainer style={{ padding: 0 }}>
-                      <CarouselLayout
-                        tracks={carouselTracks}
-                        style={{
-                          minWidth: '200px',
-                        }}
+                    {!focusTrack ? (
+                      <div
+                        className="lk-grid-layout-wrapper"
+                        style={{ height: 'auto' }}
                       >
-                        <ParticipantTile />
-                      </CarouselLayout>
-                      {focusTrack && <FocusLayout trackRef={focusTrack} />}
-                    </FocusLayoutContainer>
+                        <GridLayout tracks={tracks} style={{ padding: 0 }}>
+                          <ParticipantTile />
+                        </GridLayout>
+                      </div>
+                    ) : (
+                      <div
+                        className="lk-focus-layout-wrapper"
+                        style={{ height: 'auto' }}
+                      >
+                        <FocusLayoutContainer style={{ padding: 0 }}>
+                          <CarouselLayout
+                            tracks={carouselTracks}
+                            style={{
+                              minWidth: '200px',
+                            }}
+                          >
+                            <ParticipantTile />
+                          </CarouselLayout>
+                          {focusTrack && <FocusLayout trackRef={focusTrack} />}
+                        </FocusLayoutContainer>
+                      </div>
+                    )}
                   </div>
-                )}
-              </div>
-            </LayoutWrapper>
-            <Subtitles />
-            <MainNotificationToast />
-          </div>
-          <ControlBar
-            onDeviceError={(e) => {
-              console.error(e)
-              if (
-                e.source == Track.Source.ScreenShare &&
-                e.error.toString() ==
-                  'NotAllowedError: Permission denied by system'
-              ) {
-                setIsShareErrorVisible(true)
-              }
-            }}
-          />
-          <SidePanel />
+                </LayoutWrapper>
+              )}
+              <Subtitles />
+              <MainNotificationToast />
+            </div>
+            <ControlBar
+              onDeviceError={(e) => {
+                console.error(e)
+                if (
+                  e.source == Track.Source.ScreenShare &&
+                  e.error.toString() ==
+                    'NotAllowedError: Permission denied by system'
+                ) {
+                  setIsShareErrorVisible(true)
+                }
+              }}
+            />
+            <SidePanel />
+            <RoomPiP />
         </LayoutContextProvider>
       )}
       <RoomAudioRenderer />

src/frontend/src/features/rooms/livekit/types/panel.ts

@@ -0,0 +1,17 @@
+/**
+ * Panel identifiers for the side panel (Info, Chat, Participants, etc.).
+ * Extracted to avoid circular dependencies between layout store and useSidePanel.
+ */
+export enum PanelId {
+  PARTICIPANTS = 'participants',
+  EFFECTS = 'effects',
+  CHAT = 'chat',
+  TOOLS = 'tools',
+  ADMIN = 'admin',
+  INFO = 'info',
+}
+
+export enum SubPanelId {
+  TRANSCRIPT = 'transcript',
+  SCREEN_RECORDING = 'screenRecording',
+}

src/frontend/src/locales/de/rooms.json

@@ -234,6 +234,10 @@
       "username": "Ihren Namen aktualisieren",
       "effects": "Effekte anwenden",
       "switchCamera": "Kamera wechseln",
+      "pictureInPicture": {
+        "enter": "Bild-im-Bild",
+        "exit": "Bild-im-Bild schließen"
+      },
       "fullscreen": {
         "enter": "Vollbild",
         "exit": "Vollbildmodus verlassen"

src/frontend/src/locales/en/rooms.json

@@ -234,6 +234,10 @@
       "username": "Update Your Name",
       "effects": "Backgrounds and Effects",
       "switchCamera": "Switch camera",
+      "pictureInPicture": {
+        "enter": "Picture-in-picture",
+        "exit": "Close picture-in-picture"
+      },
       "fullscreen": {
         "enter": "Fullscreen",
         "exit": "Exit fullscreen mode"

src/frontend/src/locales/fr/rooms.json

@@ -234,6 +234,10 @@
       "username": "Choisir votre nom",
       "effects": "Arrière-plans et effets",
       "switchCamera": "Changer de caméra",
+      "pictureInPicture": {
+        "enter": "Image dans l'image",
+        "exit": "Fermer l'image dans l'image"
+      },
       "fullscreen": {
         "enter": "Plein écran",
         "exit": "Quitter le mode plein écran"

src/frontend/src/locales/nl/rooms.json

@@ -234,6 +234,10 @@
       "username": "Verander uw naam",
       "effects": "Pas effecten toe",
       "switchCamera": "Selecteer camera",
+      "pictureInPicture": {
+        "enter": "Beeld-in-beeld",
+        "exit": "Beeld-in-beeld sluiten"
+      },
       "fullscreen": {
         "enter": "Volledig scherm",
         "exit": "Stop volledig scherm stand"

src/frontend/src/primitives/Menu.tsx

@@ -1,10 +1,16 @@
-import { ReactNode } from 'react'
+import { ReactNode, useMemo } from 'react'
 import { MenuTrigger } from 'react-aria-components'
 import { StyledPopover } from './Popover'
 import { Box } from './Box'
+import {
+  useOverlayBoundaryElement,
+  useOverlayPortalContainer,
+} from './useOverlayPortalContainer'
 
 /**
  * a Menu is a tuple of a trigger component (most usually a Button) that toggles menu items in a tooltip around the trigger
+ *
+ * Uses UNSAFE_PortalProvider context automatically for portal container (no need for UNSTABLE_portalContainer).
  */
 export const Menu = ({
   children,
@@ -16,10 +22,30 @@ export const Menu = ({
   placement?: 'bottom' | 'top' | 'left' | 'right'
 }) => {
   const [trigger, menu] = children
+  const boundaryElement = useOverlayBoundaryElement()
+  const portalContainer = useOverlayPortalContainer()
+
+  // Detect if we're in PiP: portal container is in a different document than the main window
+  const isInPiP = useMemo(
+    () =>
+      portalContainer &&
+      portalContainer.ownerDocument &&
+      portalContainer.ownerDocument !== document,
+    [portalContainer]
+  )
+
+  // Default placement: 'bottom' in PiP, 'top' elsewhere (to match existing behavior)
+  const defaultPlacement = isInPiP ? 'bottom' : 'top'
+  const shouldFlip = isInPiP ? false : undefined
+
   return (
     <MenuTrigger>
       {trigger}
-      <StyledPopover placement={placement}>
+      <StyledPopover
+        placement={placement ?? defaultPlacement}
+        shouldFlip={shouldFlip}
+        boundaryElement={boundaryElement}
+      >
         <Box size="sm" type="popover" variant={variant}>
           {menu}
         </Box>

src/frontend/src/primitives/Popover.tsx

@@ -8,6 +8,7 @@ import {
 } from 'react-aria-components'
 import { styled } from '@/styled-system/jsx'
 import { Box } from './Box'
+import { useOverlayBoundaryElement } from './useOverlayPortalContainer'
 
 export const StyledPopover = styled(RACPopover, {
   base: {
@@ -65,6 +66,8 @@ const StyledOverlayArrow = styled(OverlayArrow, {
  *
  * Note: to show a list of actionable items, like a dropdown menu, prefer using a <Menu> or <Select>.
  * This is here when needing to show unrestricted content in a box.
+ *
+ * Uses UNSAFE_PortalProvider context automatically for portal container (no need for UNSTABLE_portalContainer).
  */
 export const Popover = ({
   children,
@@ -82,10 +85,11 @@ export const Popover = ({
   withArrow?: boolean
 } & Omit<DialogProps, 'children'>) => {
   const [trigger, popoverContent] = children
+  const boundaryElement = useOverlayBoundaryElement()
   return (
     <DialogTrigger>
       {trigger}
-      <StyledPopover>
+      <StyledPopover boundaryElement={boundaryElement}>
         {withArrow && (
           <StyledOverlayArrow variant={variant}>
             <svg width={12} height={12} viewBox="0 0 12 12">

src/frontend/src/primitives/TooltipWrapper.tsx

@@ -6,12 +6,17 @@ import {
   type TooltipProps,
 } from 'react-aria-components'
 import { styled } from '@/styled-system/jsx'
+import { useOverlayPortalContainer } from './useOverlayPortalContainer'
+import { VisualOnlyTooltip } from './VisualOnlyTooltip'
 
 export type TooltipWrapperProps = {
   tooltip?: string
   tooltipType?: 'instant' | 'delayed'
 }
 
+const INSTANT_TOOLTIP_DELAY_MS = 150
+const DELAYED_TOOLTIP_DELAY_MS = 1000
+
 /**
  * Wrap a component you want to apply a tooltip on (for example a Button)
  *
@@ -24,11 +29,25 @@ export const TooltipWrapper = ({
 }: {
   children: ReactNode
 } & TooltipWrapperProps) => {
+  const portalContainer = useOverlayPortalContainer()
+  const isExternalDocument =
+    portalContainer && portalContainer.ownerDocument !== document
+
   return tooltip ? (
-    <TooltipTrigger delay={tooltipType === 'instant' ? 150 : 1000}>
-      {children}
-      <Tooltip>{tooltip}</Tooltip>
-    </TooltipTrigger>
+    isExternalDocument ? (
+      <VisualOnlyTooltip tooltip={tooltip}>{children}</VisualOnlyTooltip>
+    ) : (
+      <TooltipTrigger
+        delay={
+          tooltipType === 'instant'
+            ? INSTANT_TOOLTIP_DELAY_MS
+            : DELAYED_TOOLTIP_DELAY_MS
+        }
+      >
+        {children}
+        <Tooltip>{tooltip}</Tooltip>
+      </TooltipTrigger>
+    )
   ) : (
     children
   )
@@ -39,6 +58,8 @@ export const TooltipWrapper = ({
  *
  * Style taken from example at https://react-spectrum.adobe.com/react-aria/Tooltip.html
  */
+const DEFAULT_TOOLTIP_GAP_PX = 8
+
 const StyledTooltip = styled(RACTooltip, {
   base: {
     boxShadow: '0 8px 20px rgba(0 0 0 / 0.1)',
@@ -53,11 +74,11 @@ const StyledTooltip = styled(RACTooltip, {
     fontSize: 14,
     transform: 'translate3d(0, 0, 0)',
     '&[data-placement=top]': {
-      marginBottom: '8px',
+      marginBottom: `${DEFAULT_TOOLTIP_GAP_PX}px`,
       '--origin': 'translateY(4px)',
     },
     '&[data-placement=bottom]': {
-      marginTop: '8px',
+      marginTop: `${DEFAULT_TOOLTIP_GAP_PX}px`,
       '--origin': 'translateY(-4px)',
     },
     '&[data-placement=right]': {
@@ -107,10 +128,13 @@ const TooltipArrow = () => {
 
 const Tooltip = ({
   children,
+  arrowBoundaryOffset,
   ...props
-}: Omit<TooltipProps, 'children'> & { children: ReactNode }) => {
+}: {
+  children: ReactNode
+} & Partial<Omit<TooltipProps, 'children'>>) => {
   return (
-    <StyledTooltip {...props}>
+    <StyledTooltip arrowBoundaryOffset={arrowBoundaryOffset ?? 0} {...props}>
       <TooltipArrow />
       {children}
     </StyledTooltip>

src/frontend/src/primitives/VisualOnlyTooltip.tsx

@@ -2,11 +2,14 @@ import {
   type ReactElement,
   cloneElement,
   isValidElement,
+  useLayoutEffect,
+  useMemo,
   useRef,
   useState,
 } from 'react'
 import { createPortal } from 'react-dom'
 import { css } from '@/styled-system/css'
+import { useUNSAFE_PortalContext } from '@react-aria/overlays'
 
 export type VisualOnlyTooltipProps = {
   children: ReactElement
@@ -32,11 +35,17 @@ export const VisualOnlyTooltip = ({
   tooltipPosition = 'top',
 }: VisualOnlyTooltipProps) => {
   const [isVisible, setIsVisible] = useState(false)
+  const { getContainer } = useUNSAFE_PortalContext()
   const wrapperRef = useRef<HTMLDivElement>(null)
+  const tooltipRef = useRef<HTMLDivElement>(null)
   const [position, setPosition] = useState<{
     top: number
     left: number
   } | null>(null)
+  const [computedStyle, setComputedStyle] = useState<{
+    left: number
+    arrowLeft: number
+  } | null>(null)
 
   const isBottom = tooltipPosition === 'bottom'
 
@@ -53,9 +62,28 @@ export const VisualOnlyTooltip = ({
   const hideTooltip = () => {
     setIsVisible(false)
     setPosition(null)
+    setComputedStyle(null)
   }
 
-  const tooltipData = isVisible && position ? { isVisible, position } : null
+  useLayoutEffect(() => {
+    if (!tooltipRef.current || !isVisible || !position) return
+    const tooltipWidth = tooltipRef.current.getBoundingClientRect().width
+    const doc = tooltipRef.current.ownerDocument
+    const viewportWidth = doc.defaultView?.innerWidth ?? window.innerWidth
+    const padding = 8
+    const desiredLeft = position.left - tooltipWidth / 2
+    const maxLeft = viewportWidth - padding - tooltipWidth
+    if (desiredLeft <= maxLeft) {
+      setComputedStyle(null)
+      return
+    }
+    setComputedStyle({ left: maxLeft, arrowLeft: position.left - maxLeft })
+  }, [isVisible, position])
+
+  const portalContainer = useMemo(() => {
+    if (getContainer) return getContainer()
+    return wrapperRef.current?.ownerDocument?.body ?? document.body
+  }, [getContainer])
   const wrappedChild = isValidElement(children)
     ? cloneElement(children, {
         ...(ariaLabel ? { 'aria-label': ariaLabel } : {}),
@@ -73,11 +101,14 @@ export const VisualOnlyTooltip = ({
       >
         {wrappedChild}
       </div>
-      {tooltipData &&
+      {isVisible &&
+        position &&
+        portalContainer &&
         createPortal(
           <div
             aria-hidden="true"
             role="presentation"
+            ref={tooltipRef}
             className={css({
               position: 'fixed',
               padding: '2px 8px',
@@ -87,12 +118,12 @@ export const VisualOnlyTooltip = ({
               fontSize: 14,
               whiteSpace: 'nowrap',
               pointerEvents: 'none',
-              zIndex: 9999,
+              zIndex: 100001,
               boxShadow: '0 8px 20px rgba(0 0 0 / 0.1)',
               '&::after': {
                 content: '""',
                 position: 'absolute',
-                left: '50%',
+                left: 'var(--tooltip-arrow-left, 50%)',
                 transform: 'translateX(-50%)',
                 border: '4px solid transparent',
                 ...(isBottom
@@ -107,16 +138,27 @@ export const VisualOnlyTooltip = ({
               },
             })}
             style={{
-              top: `${tooltipData.position.top}px`,
-              left: `${tooltipData.position.left}px`,
-              transform: isBottom
-                ? 'translate(-50%, 0)'
-                : 'translate(-50%, -100%)',
+              top: `${position.top}px`,
+              left: computedStyle
+                ? `${computedStyle.left}px`
+                : `${position.left}px`,
+              transform: computedStyle
+                ? isBottom
+                  ? 'translateY(0)'
+                  : 'translateY(-100%)'
+                : isBottom
+                  ? 'translate(-50%, 0)'
+                  : 'translate(-50%, -100%)',
+              ...(computedStyle
+                ? {
+                    '--tooltip-arrow-left': `${computedStyle.arrowLeft}px`,
+                  }
+                : null),
             }}
           >
             {tooltip}
           </div>,
-          document.body
+          portalContainer
         )}
     </>
   )

src/frontend/src/primitives/useOverlayPortalContainer.tsx

@@ -0,0 +1,21 @@
+import { useMemo } from 'react'
+import { useUNSAFE_PortalContext } from '@react-aria/overlays'
+
+/**
+ * Hook to retrieve the portal container for overlays (menus, tooltips, popovers).
+ * Returns the container from UNSAFE_PortalProvider context (pip-root in PiP, undefined in main window).
+ */
+export const useOverlayPortalContainer = () => {
+  const { getContainer } = useUNSAFE_PortalContext()
+
+  return useMemo(() => getContainer?.() ?? undefined, [getContainer])
+}
+
+/**
+ * Hook to retrieve the boundary element for overlay positioning.
+ * Returns the portal container in PiP (for PiP-relative positioning), undefined in main window.
+ */
+export const useOverlayBoundaryElement = () => {
+  const portalContainer = useOverlayPortalContainer()
+  return portalContainer
+}

src/frontend/src/stores/layout.ts

@@ -2,7 +2,7 @@ import { proxy } from 'valtio'
 import {
   PanelId,
   SubPanelId,
-} from '@/features/rooms/livekit/hooks/useSidePanel'
+} from '@/features/rooms/livekit/types/panel'
 
 type State = {
   showHeader: boolean

src/frontend/src/stores/roomPiP.ts

@@ -0,0 +1,9 @@
+import { proxy } from 'valtio'
+
+type State = {
+  isOpen: boolean
+}
+
+export const roomPiPStore = proxy<State>({
+  isOpen: false,
+})