Initial plan

Co-authored-by: Rajat Agarwal <rajat.agarwal@infocusp.com>

.github/dependabot.yml

@@ -25,6 +25,10 @@ updates:
       interval: "weekly"
     open-pull-requests-limit: 2
     groups:
+      lexical:
+        patterns:
+          - "lexical"
+          - "@lexical/*"
       storybook:
         patterns:
           - "storybook"
@@ -33,5 +37,7 @@ updates:
         patterns:
           - "*"
         exclude-patterns:
+          - "lexical"
+          - "@lexical/*"
           - "storybook"
           - "@storybook/*"

README.md

@@ -133,7 +133,7 @@ Star Dify on GitHub and be instantly notified of new releases.
 
 ### Custom configurations
 
-If you need to customize the configuration, please refer to the comments in our [.env.example](docker/.env.example) file and update the corresponding values in your `.env` file. Additionally, you might need to make adjustments to the `docker-compose.yaml` file itself, such as changing image versions, port mappings, or volume mounts, based on your specific deployment environment and requirements. After making any changes, please re-run `docker-compose up -d`. You can find the full list of available environment variables [here](https://docs.dify.ai/getting-started/install-self-hosted/environments).
+If you need to customize the configuration, please refer to the comments in our [.env.example](docker/.env.example) file and update the corresponding values in your `.env` file. Additionally, you might need to make adjustments to the `docker-compose.yaml` file itself, such as changing image versions, port mappings, or volume mounts, based on your specific deployment environment and requirements. After making any changes, please re-run `docker compose up -d`. You can find the full list of available environment variables [here](https://docs.dify.ai/getting-started/install-self-hosted/environments).
 
 #### Customizing Suggested Questions
 

api/commands.py

@@ -30,6 +30,7 @@ from extensions.ext_redis import redis_client
 from extensions.ext_storage import storage
 from extensions.storage.opendal_storage import OpenDALStorage
 from extensions.storage.storage_type import StorageType
+from libs.datetime_utils import naive_utc_now
 from libs.db_migration_lock import DbMigrationAutoRenewLock
 from libs.helper import email as email_validate
 from libs.password import hash_password, password_pattern, valid_password
@@ -2598,15 +2599,29 @@ def migrate_oss(
 @click.option(
     "--start-from",
     type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
-    required=True,
+    required=False,
+    default=None,
     help="Lower bound (inclusive) for created_at.",
 )
 @click.option(
     "--end-before",
     type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
-    required=True,
+    required=False,
+    default=None,
     help="Upper bound (exclusive) for created_at.",
 )
+@click.option(
+    "--from-days-ago",
+    type=int,
+    default=None,
+    help="Relative lower bound in days ago (inclusive). Must be used with --before-days.",
+)
+@click.option(
+    "--before-days",
+    type=int,
+    default=None,
+    help="Relative upper bound in days ago (exclusive). Required for relative mode.",
+)
 @click.option("--batch-size", default=1000, show_default=True, help="Batch size for selecting messages.")
 @click.option(
     "--graceful-period",
@@ -2618,8 +2633,10 @@ def migrate_oss(
 def clean_expired_messages(
     batch_size: int,
     graceful_period: int,
-    start_from: datetime.datetime,
-    end_before: datetime.datetime,
+    start_from: datetime.datetime | None,
+    end_before: datetime.datetime | None,
+    from_days_ago: int | None,
+    before_days: int | None,
     dry_run: bool,
 ):
     """
@@ -2630,18 +2647,70 @@ def clean_expired_messages(
     start_at = time.perf_counter()
 
     try:
+        abs_mode = start_from is not None and end_before is not None
+        rel_mode = before_days is not None
+
+        if abs_mode and rel_mode:
+            raise click.UsageError(
+                "Options are mutually exclusive: use either (--start-from,--end-before) "
+                "or (--from-days-ago,--before-days)."
+            )
+
+        if from_days_ago is not None and before_days is None:
+            raise click.UsageError("--from-days-ago must be used together with --before-days.")
+
+        if (start_from is None) ^ (end_before is None):
+            raise click.UsageError("Both --start-from and --end-before are required when using absolute time range.")
+
+        if not abs_mode and not rel_mode:
+            raise click.UsageError(
+                "You must provide either (--start-from,--end-before) or (--before-days [--from-days-ago])."
+            )
+
+        if rel_mode:
+            assert before_days is not None
+            if before_days < 0:
+                raise click.UsageError("--before-days must be >= 0.")
+            if from_days_ago is not None:
+                if from_days_ago < 0:
+                    raise click.UsageError("--from-days-ago must be >= 0.")
+                if from_days_ago <= before_days:
+                    raise click.UsageError("--from-days-ago must be greater than --before-days.")
+
         # Create policy based on billing configuration
         # NOTE: graceful_period will be ignored when billing is disabled.
         policy = create_message_clean_policy(graceful_period_days=graceful_period)
 
         # Create and run the cleanup service
-        service = MessagesCleanService.from_time_range(
-            policy=policy,
-            start_from=start_from,
-            end_before=end_before,
-            batch_size=batch_size,
-            dry_run=dry_run,
-        )
+        if abs_mode:
+            assert start_from is not None
+            assert end_before is not None
+            service = MessagesCleanService.from_time_range(
+                policy=policy,
+                start_from=start_from,
+                end_before=end_before,
+                batch_size=batch_size,
+                dry_run=dry_run,
+            )
+        elif from_days_ago is None:
+            assert before_days is not None
+            service = MessagesCleanService.from_days(
+                policy=policy,
+                days=before_days,
+                batch_size=batch_size,
+                dry_run=dry_run,
+            )
+        else:
+            assert before_days is not None
+            assert from_days_ago is not None
+            now = naive_utc_now()
+            service = MessagesCleanService.from_time_range(
+                policy=policy,
+                start_from=now - datetime.timedelta(days=from_days_ago),
+                end_before=now - datetime.timedelta(days=before_days),
+                batch_size=batch_size,
+                dry_run=dry_run,
+            )
         stats = service.run()
 
         end_at = time.perf_counter()

api/controllers/console/app/error.py

@@ -121,9 +121,3 @@ class NeedAddIdsError(BaseHTTPException):
     error_code = "need_add_ids"
     description = "Need to add ids."
     code = 400
-
-
-class VariableValidationError(BaseHTTPException):
-    error_code = "variable_validation_error"
-    description = "Variable validation failed."
-    code = 400

api/controllers/console/app/workflow.py

@@ -11,12 +11,7 @@ from werkzeug.exceptions import Forbidden, InternalServerError, NotFound
 
 import services
 from controllers.console import console_ns
-from controllers.console.app.error import (
-    ConversationCompletedError,
-    DraftWorkflowNotExist,
-    DraftWorkflowNotSync,
-    VariableValidationError,
-)
+from controllers.console.app.error import ConversationCompletedError, DraftWorkflowNotExist, DraftWorkflowNotSync
 from controllers.console.app.workflow_run import workflow_run_node_execution_model
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import account_initialization_required, edit_permission_required, setup_required
@@ -37,7 +32,6 @@ from dify_graph.enums import NodeType
 from dify_graph.file.models import File
 from dify_graph.graph_engine.manager import GraphEngineManager
 from dify_graph.model_runtime.utils.encoders import jsonable_encoder
-from dify_graph.variables.exc import VariableError
 from extensions.ext_database import db
 from extensions.ext_redis import redis_client
 from factories import file_factory, variable_factory
@@ -308,8 +302,6 @@ class DraftWorkflowApi(Resource):
             )
         except WorkflowHashNotEqualError:
             raise DraftWorkflowNotSync()
-        except VariableError as e:
-            raise VariableValidationError(description=str(e))
 
         return {
             "result": "success",

api/controllers/web/message.py

@@ -239,7 +239,7 @@ class MessageSuggestedQuestionApi(WebApiResource):
     def get(self, app_model, end_user, message_id):
         app_mode = AppMode.value_of(app_model.mode)
         if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
-            raise NotCompletionAppError()
+            raise NotChatAppError()
 
         message_id = str(message_id)
 

api/core/tools/workflow_as_tool/provider.py

@@ -37,6 +37,7 @@ VARIABLE_TO_PARAMETER_TYPE_MAPPING = {
     VariableEntityType.CHECKBOX: ToolParameter.ToolParameterType.BOOLEAN,
     VariableEntityType.FILE: ToolParameter.ToolParameterType.FILE,
     VariableEntityType.FILE_LIST: ToolParameter.ToolParameterType.FILES,
+    VariableEntityType.JSON_OBJECT: ToolParameter.ToolParameterType.OBJECT,
 }
 
 

api/dify_graph/nodes/document_extractor/node.py

@@ -4,6 +4,7 @@ import json
 import logging
 import os
 import tempfile
+import zipfile
 from collections.abc import Mapping, Sequence
 from typing import TYPE_CHECKING, Any
 
@@ -82,8 +83,18 @@ class DocumentExtractorNode(Node[DocumentExtractorNodeData]):
 
         value = variable.value
         inputs = {"variable_selector": variable_selector}
+        if isinstance(value, list):
+            value = list(filter(lambda x: x, value))
         process_data = {"documents": value if isinstance(value, list) else [value]}
 
+        if not value:
+            return NodeRunResult(
+                status=WorkflowNodeExecutionStatus.SUCCEEDED,
+                inputs=inputs,
+                process_data=process_data,
+                outputs={"text": ArrayStringSegment(value=[])},
+            )
+
         try:
             if isinstance(value, list):
                 extracted_text_list = [
@@ -111,6 +122,7 @@ class DocumentExtractorNode(Node[DocumentExtractorNodeData]):
             else:
                 raise DocumentExtractorError(f"Unsupported variable type: {type(value)}")
         except DocumentExtractorError as e:
+            logger.warning(e, exc_info=True)
             return NodeRunResult(
                 status=WorkflowNodeExecutionStatus.FAILED,
                 error=str(e),
@@ -385,6 +397,32 @@ def parser_docx_part(block, doc: Document, content_items, i):
         content_items.append((i, "table", Table(block, doc)))
 
 
+def _normalize_docx_zip(file_content: bytes) -> bytes:
+    """
+    Some DOCX files (e.g. exported by Evernote on Windows) are malformed:
+    ZIP entry names use backslash (\\) as path separator instead of the forward
+    slash (/) required by both the ZIP spec and OOXML.  On Linux/Mac the entry
+    "word\\document.xml" is never found when python-docx looks for
+    "word/document.xml", which triggers a KeyError about a missing relationship.
+
+    This function rewrites the ZIP in-memory, normalizing all entry names to
+    use forward slashes without touching any actual document content.
+    """
+    try:
+        with zipfile.ZipFile(io.BytesIO(file_content), "r") as zin:
+            out_buf = io.BytesIO()
+            with zipfile.ZipFile(out_buf, "w", compression=zipfile.ZIP_DEFLATED) as zout:
+                for item in zin.infolist():
+                    data = zin.read(item.filename)
+                    # Normalize backslash path separators to forward slash
+                    item.filename = item.filename.replace("\\", "/")
+                    zout.writestr(item, data)
+            return out_buf.getvalue()
+    except zipfile.BadZipFile:
+        # Not a valid zip — return as-is and let python-docx report the real error
+        return file_content
+
+
 def _extract_text_from_docx(file_content: bytes) -> str:
     """
     Extract text from a DOCX file.
@@ -392,7 +430,15 @@ def _extract_text_from_docx(file_content: bytes) -> str:
     """
     try:
         doc_file = io.BytesIO(file_content)
-        doc = docx.Document(doc_file)
+        try:
+            doc = docx.Document(doc_file)
+        except Exception as e:
+            logger.warning("Failed to parse DOCX, attempting to normalize ZIP entry paths: %s", e)
+            # Some DOCX files exported by tools like Evernote on Windows use
+            # backslash path separators in ZIP entries and/or single-quoted XML
+            # attributes, both of which break python-docx on Linux. Normalize and retry.
+            file_content = _normalize_docx_zip(file_content)
+            doc = docx.Document(io.BytesIO(file_content))
         text = []
 
         # Keep track of paragraph and table positions

api/dify_graph/nodes/knowledge_retrieval/knowledge_retrieval_node.py

@@ -23,7 +23,11 @@ from dify_graph.variables import (
 )
 from dify_graph.variables.segments import ArrayObjectSegment
 
-from .entities import KnowledgeRetrievalNodeData
+from .entities import (
+    Condition,
+    KnowledgeRetrievalNodeData,
+    MetadataFilteringCondition,
+)
 from .exc import (
     KnowledgeRetrievalNodeError,
     RateLimitExceededError,
@@ -171,6 +175,12 @@ class KnowledgeRetrievalNode(LLMUsageTrackingMixin, Node[KnowledgeRetrievalNodeD
         if node_data.metadata_filtering_mode is not None:
             metadata_filtering_mode = node_data.metadata_filtering_mode
 
+        resolved_metadata_conditions = (
+            self._resolve_metadata_filtering_conditions(node_data.metadata_filtering_conditions)
+            if node_data.metadata_filtering_conditions
+            else None
+        )
+
         if str(node_data.retrieval_mode) == DatasetRetrieveConfigEntity.RetrieveStrategy.SINGLE and query:
             # fetch model config
             if node_data.single_retrieval_config is None:
@@ -189,7 +199,7 @@ class KnowledgeRetrievalNode(LLMUsageTrackingMixin, Node[KnowledgeRetrievalNodeD
                     model_mode=model.mode,
                     model_name=model.name,
                     metadata_model_config=node_data.metadata_model_config,
-                    metadata_filtering_conditions=node_data.metadata_filtering_conditions,
+                    metadata_filtering_conditions=resolved_metadata_conditions,
                     metadata_filtering_mode=metadata_filtering_mode,
                     query=query,
                 )
@@ -247,7 +257,7 @@ class KnowledgeRetrievalNode(LLMUsageTrackingMixin, Node[KnowledgeRetrievalNodeD
                     weights=weights,
                     reranking_enable=node_data.multiple_retrieval_config.reranking_enable,
                     metadata_model_config=node_data.metadata_model_config,
-                    metadata_filtering_conditions=node_data.metadata_filtering_conditions,
+                    metadata_filtering_conditions=resolved_metadata_conditions,
                     metadata_filtering_mode=metadata_filtering_mode,
                     attachment_ids=[attachment.related_id for attachment in attachments] if attachments else None,
                 )
@@ -256,6 +266,48 @@ class KnowledgeRetrievalNode(LLMUsageTrackingMixin, Node[KnowledgeRetrievalNodeD
         usage = self._rag_retrieval.llm_usage
         return retrieval_resource_list, usage
 
+    def _resolve_metadata_filtering_conditions(
+        self, conditions: MetadataFilteringCondition
+    ) -> MetadataFilteringCondition:
+        if conditions.conditions is None:
+            return MetadataFilteringCondition(
+                logical_operator=conditions.logical_operator,
+                conditions=None,
+            )
+
+        variable_pool = self.graph_runtime_state.variable_pool
+        resolved_conditions: list[Condition] = []
+        for cond in conditions.conditions or []:
+            value = cond.value
+            if isinstance(value, str):
+                segment_group = variable_pool.convert_template(value)
+                if len(segment_group.value) == 1:
+                    resolved_value = segment_group.value[0].to_object()
+                else:
+                    resolved_value = segment_group.text
+            elif isinstance(value, Sequence) and all(isinstance(v, str) for v in value):
+                resolved_values = []
+                for v in value:  # type: ignore
+                    segment_group = variable_pool.convert_template(v)
+                    if len(segment_group.value) == 1:
+                        resolved_values.append(segment_group.value[0].to_object())
+                    else:
+                        resolved_values.append(segment_group.text)
+                resolved_value = resolved_values
+            else:
+                resolved_value = value
+            resolved_conditions.append(
+                Condition(
+                    name=cond.name,
+                    comparison_operator=cond.comparison_operator,
+                    value=resolved_value,
+                )
+            )
+        return MetadataFilteringCondition(
+            logical_operator=conditions.logical_operator or "and",
+            conditions=resolved_conditions,
+        )
+
     @classmethod
     def _extract_variable_selector_to_variable_mapping(
         cls,

api/factories/variable_factory.py

@@ -72,18 +72,9 @@ SEGMENT_TO_VARIABLE_MAP = {
 }
 
 
-_MAX_VARIABLE_DESCRIPTION_LENGTH = 255
-
-
 def build_conversation_variable_from_mapping(mapping: Mapping[str, Any], /) -> VariableBase:
     if not mapping.get("name"):
         raise VariableError("missing name")
-    description = mapping.get("description", "")
-    if len(description) > _MAX_VARIABLE_DESCRIPTION_LENGTH:
-        raise VariableError(
-            f"description of variable '{mapping['name']}' is too long"
-            f" (max {_MAX_VARIABLE_DESCRIPTION_LENGTH} characters)"
-        )
     return _build_variable_from_mapping(mapping=mapping, selector=[CONVERSATION_VARIABLE_NODE_ID, mapping["name"]])
 
 

api/models/workflow.py

@@ -1589,8 +1589,6 @@ class WorkflowDraftVariable(Base):
         variable.file_id = file_id
         variable._set_selector(list(variable_utils.to_selector(node_id, name)))
         variable.node_execution_id = node_execution_id
-        variable.visible = True
-        variable.is_default_value = False
         return variable
 
     @classmethod

api/schedule/queue_monitor_task.py

@@ -21,6 +21,10 @@ celery_redis = Redis(
     ssl_cert_reqs=getattr(dify_config, "REDIS_SSL_CERT_REQS", None) if dify_config.BROKER_USE_SSL else None,
     ssl_certfile=getattr(dify_config, "REDIS_SSL_CERTFILE", None) if dify_config.BROKER_USE_SSL else None,
     ssl_keyfile=getattr(dify_config, "REDIS_SSL_KEYFILE", None) if dify_config.BROKER_USE_SSL else None,
+    # Add conservative socket timeouts and health checks to avoid long-lived half-open sockets
+    socket_timeout=5,
+    socket_connect_timeout=5,
+    health_check_interval=30,
 )
 
 logger = logging.getLogger(__name__)

api/schedule/trigger_provider_refresh_task.py

@@ -3,6 +3,7 @@ import math
 import time
 from collections.abc import Iterable, Sequence
 
+from celery import group
 from sqlalchemy import ColumnElement, and_, func, or_, select
 from sqlalchemy.engine.row import Row
 from sqlalchemy.orm import Session
@@ -85,20 +86,25 @@ def trigger_provider_refresh() -> None:
             lock_keys: list[str] = build_trigger_refresh_lock_keys(subscriptions)
             acquired: list[bool] = _acquire_locks(keys=lock_keys, ttl_seconds=lock_ttl)
 
-            enqueued: int = 0
-            for (tenant_id, subscription_id), is_locked in zip(subscriptions, acquired):
-                if not is_locked:
-                    continue
-                trigger_subscription_refresh.delay(tenant_id=tenant_id, subscription_id=subscription_id)
-                enqueued += 1
+            if not any(acquired):
+                continue
+
+            jobs = [
+                trigger_subscription_refresh.s(tenant_id=tenant_id, subscription_id=subscription_id)
+                for (tenant_id, subscription_id), is_locked in zip(subscriptions, acquired)
+                if is_locked
+            ]
+            result = group(jobs).apply_async()
+            enqueued = len(jobs)
 
             logger.info(
-                "Trigger refresh page %d/%d: scanned=%d locks_acquired=%d enqueued=%d",
+                "Trigger refresh page %d/%d: scanned=%d locks_acquired=%d enqueued=%d result=%s",
                 page + 1,
                 pages,
                 len(subscriptions),
                 sum(1 for x in acquired if x),
                 enqueued,
+                result,
             )
 
     logger.info("Trigger refresh scan done: due=%d", total_due)

api/schedule/workflow_schedule_task.py

@@ -1,6 +1,6 @@
 import logging
 
-from celery import group, shared_task
+from celery import current_app, group, shared_task
 from sqlalchemy import and_, select
 from sqlalchemy.orm import Session, sessionmaker
 
@@ -29,31 +29,27 @@ def poll_workflow_schedules() -> None:
     with session_factory() as session:
         total_dispatched = 0
 
-        # Process in batches until we've handled all due schedules or hit the limit
         while True:
             due_schedules = _fetch_due_schedules(session)
 
             if not due_schedules:
                 break
 
-            dispatched_count = _process_schedules(session, due_schedules)
-            total_dispatched += dispatched_count
+            with current_app.producer_or_acquire() as producer:  # type: ignore
+                dispatched_count = _process_schedules(session, due_schedules, producer)
+                total_dispatched += dispatched_count
 
-            logger.debug("Batch processed: %d dispatched", dispatched_count)
-
-            # Circuit breaker: check if we've hit the per-tick limit (if enabled)
-            if (
-                dify_config.WORKFLOW_SCHEDULE_MAX_DISPATCH_PER_TICK > 0
-                and total_dispatched >= dify_config.WORKFLOW_SCHEDULE_MAX_DISPATCH_PER_TICK
-            ):
-                logger.warning(
-                    "Circuit breaker activated: reached dispatch limit (%d), will continue next tick",
-                    dify_config.WORKFLOW_SCHEDULE_MAX_DISPATCH_PER_TICK,
-                )
-                break
+                logger.debug("Batch processed: %d dispatched", dispatched_count)
 
+                # Circuit breaker: check if we've hit the per-tick limit (if enabled)
+                if 0 < dify_config.WORKFLOW_SCHEDULE_MAX_DISPATCH_PER_TICK <= total_dispatched:
+                    logger.warning(
+                        "Circuit breaker activated: reached dispatch limit (%d), will continue next tick",
+                        dify_config.WORKFLOW_SCHEDULE_MAX_DISPATCH_PER_TICK,
+                    )
+                    break
         if total_dispatched > 0:
-            logger.info("Total processed: %d dispatched", total_dispatched)
+            logger.info("Total processed: %d workflow schedule(s) dispatched", total_dispatched)
 
 
 def _fetch_due_schedules(session: Session) -> list[WorkflowSchedulePlan]:
@@ -90,7 +86,7 @@ def _fetch_due_schedules(session: Session) -> list[WorkflowSchedulePlan]:
     return list(due_schedules)
 
 
-def _process_schedules(session: Session, schedules: list[WorkflowSchedulePlan]) -> int:
+def _process_schedules(session: Session, schedules: list[WorkflowSchedulePlan], producer=None) -> int:
     """Process schedules: check quota, update next run time and dispatch to Celery in parallel."""
     if not schedules:
         return 0
@@ -107,7 +103,7 @@ def _process_schedules(session: Session, schedules: list[WorkflowSchedulePlan])
 
     if tasks_to_dispatch:
         job = group(run_schedule_trigger.s(schedule_id) for schedule_id in tasks_to_dispatch)
-        job.apply_async()
+        job.apply_async(producer=producer)
 
         logger.debug("Dispatched %d tasks in parallel", len(tasks_to_dispatch))
 

api/services/retention/conversation/messages_clean_service.py

@@ -12,6 +12,7 @@ from sqlalchemy.engine import CursorResult
 from sqlalchemy.orm import Session
 
 from extensions.ext_database import db
+from libs.datetime_utils import naive_utc_now
 from models.model import (
     App,
     AppAnnotationHitHistory,
@@ -142,7 +143,7 @@ class MessagesCleanService:
         if batch_size <= 0:
             raise ValueError(f"batch_size ({batch_size}) must be greater than 0")
 
-        end_before = datetime.datetime.now() - datetime.timedelta(days=days)
+        end_before = naive_utc_now() - datetime.timedelta(days=days)
 
         logger.info(
             "clean_messages: days=%s, end_before=%s, batch_size=%s, policy=%s",

api/services/workflow_draft_variable_service.py

@@ -700,8 +700,6 @@ def _model_to_insertion_dict(model: WorkflowDraftVariable) -> dict[str, Any]:
         d["updated_at"] = model.updated_at
     if model.description is not None:
         d["description"] = model.description
-    if model.is_default_value is not None:
-        d["is_default_value"] = model.is_default_value
     return d
 
 

api/tasks/document_indexing_task.py

@@ -1,9 +1,10 @@
 import logging
 import time
-from collections.abc import Callable, Sequence
+from collections.abc import Sequence
+from typing import Any, Protocol
 
 import click
-from celery import shared_task
+from celery import current_app, shared_task
 
 from configs import dify_config
 from core.db.session_factory import session_factory
@@ -19,6 +20,12 @@ from tasks.generate_summary_index_task import generate_summary_index_task
 logger = logging.getLogger(__name__)
 
 
+class CeleryTaskLike(Protocol):
+    def delay(self, *args: Any, **kwargs: Any) -> Any: ...
+
+    def apply_async(self, *args: Any, **kwargs: Any) -> Any: ...
+
+
 @shared_task(queue="dataset")
 def document_indexing_task(dataset_id: str, document_ids: list):
     """
@@ -179,8 +186,8 @@ def _document_indexing(dataset_id: str, document_ids: Sequence[str]):
 
 
 def _document_indexing_with_tenant_queue(
-    tenant_id: str, dataset_id: str, document_ids: Sequence[str], task_func: Callable[[str, str, Sequence[str]], None]
-):
+    tenant_id: str, dataset_id: str, document_ids: Sequence[str], task_func: CeleryTaskLike
+) -> None:
     try:
         _document_indexing(dataset_id, document_ids)
     except Exception:
@@ -201,16 +208,20 @@ def _document_indexing_with_tenant_queue(
         logger.info("document indexing tenant isolation queue %s next tasks: %s", tenant_id, next_tasks)
 
         if next_tasks:
-            for next_task in next_tasks:
-                document_task = DocumentTask(**next_task)
-                # Process the next waiting task
-                # Keep the flag set to indicate a task is running
-                tenant_isolated_task_queue.set_task_waiting_time()
-                task_func.delay(  # type: ignore
-                    tenant_id=document_task.tenant_id,
-                    dataset_id=document_task.dataset_id,
-                    document_ids=document_task.document_ids,
-                )
+            with current_app.producer_or_acquire() as producer:  # type: ignore
+                for next_task in next_tasks:
+                    document_task = DocumentTask(**next_task)
+                    # Keep the flag set to indicate a task is running
+                    tenant_isolated_task_queue.set_task_waiting_time()
+                    task_func.apply_async(
+                        kwargs={
+                            "tenant_id": document_task.tenant_id,
+                            "dataset_id": document_task.dataset_id,
+                            "document_ids": document_task.document_ids,
+                        },
+                        producer=producer,
+                    )
+
         else:
             # No more waiting tasks, clear the flag
             tenant_isolated_task_queue.delete_task_key()

api/tasks/rag_pipeline/rag_pipeline_run_task.py

@@ -3,12 +3,13 @@ import json
 import logging
 import time
 import uuid
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 from concurrent.futures import ThreadPoolExecutor
+from itertools import islice
 from typing import Any
 
 import click
-from celery import shared_task  # type: ignore
+from celery import group, shared_task
 from flask import current_app, g
 from sqlalchemy.orm import Session, sessionmaker
 
@@ -27,6 +28,11 @@ from services.file_service import FileService
 logger = logging.getLogger(__name__)
 
 
+def chunked(iterable: Sequence, size: int):
+    it = iter(iterable)
+    return iter(lambda: list(islice(it, size)), [])
+
+
 @shared_task(queue="pipeline")
 def rag_pipeline_run_task(
     rag_pipeline_invoke_entities_file_id: str,
@@ -83,16 +89,24 @@ def rag_pipeline_run_task(
         logger.info("rag pipeline tenant isolation queue %s next files: %s", tenant_id, next_file_ids)
 
         if next_file_ids:
-            for next_file_id in next_file_ids:
-                # Process the next waiting task
-                # Keep the flag set to indicate a task is running
-                tenant_isolated_task_queue.set_task_waiting_time()
-                rag_pipeline_run_task.delay(  # type: ignore
-                    rag_pipeline_invoke_entities_file_id=next_file_id.decode("utf-8")
-                    if isinstance(next_file_id, bytes)
-                    else next_file_id,
-                    tenant_id=tenant_id,
-                )
+            for batch in chunked(next_file_ids, 100):
+                jobs = []
+                for next_file_id in batch:
+                    tenant_isolated_task_queue.set_task_waiting_time()
+
+                    file_id = (
+                        next_file_id.decode("utf-8") if isinstance(next_file_id, (bytes, bytearray)) else next_file_id
+                    )
+
+                    jobs.append(
+                        rag_pipeline_run_task.s(
+                            rag_pipeline_invoke_entities_file_id=file_id,
+                            tenant_id=tenant_id,
+                        )
+                    )
+
+                if jobs:
+                    group(jobs).apply_async()
         else:
             # No more waiting tasks, clear the flag
             tenant_isolated_task_queue.delete_task_key()

api/tests/test_containers_integration_tests/tasks/test_dataset_indexing_task.py

@@ -322,11 +322,14 @@ class TestDatasetIndexingTaskIntegration:
             _document_indexing_with_tenant_queue(dataset.tenant_id, dataset.id, document_ids, task_dispatch_spy)
 
         # Assert
-        task_dispatch_spy.delay.assert_called_once_with(
-            tenant_id=next_task["tenant_id"],
-            dataset_id=next_task["dataset_id"],
-            document_ids=next_task["document_ids"],
-        )
+        # apply_async is used by implementation; assert it was called once with expected kwargs
+        assert task_dispatch_spy.apply_async.call_count == 1
+        call_kwargs = task_dispatch_spy.apply_async.call_args.kwargs.get("kwargs", {})
+        assert call_kwargs == {
+            "tenant_id": next_task["tenant_id"],
+            "dataset_id": next_task["dataset_id"],
+            "document_ids": next_task["document_ids"],
+        }
         set_waiting_spy.assert_called_once()
         delete_key_spy.assert_not_called()
 
@@ -352,7 +355,7 @@ class TestDatasetIndexingTaskIntegration:
             _document_indexing_with_tenant_queue(dataset.tenant_id, dataset.id, document_ids, task_dispatch_spy)
 
         # Assert
-        task_dispatch_spy.delay.assert_not_called()
+        task_dispatch_spy.apply_async.assert_not_called()
         delete_key_spy.assert_called_once()
 
     def test_validation_failure_sets_error_status_when_vector_space_at_limit(
@@ -447,7 +450,7 @@ class TestDatasetIndexingTaskIntegration:
             _document_indexing_with_tenant_queue(dataset.tenant_id, dataset.id, document_ids, task_dispatch_spy)
 
         # Assert
-        task_dispatch_spy.delay.assert_called_once()
+        task_dispatch_spy.apply_async.assert_called_once()
 
     def test_sessions_close_on_successful_indexing(
         self,
@@ -534,7 +537,7 @@ class TestDatasetIndexingTaskIntegration:
             _document_indexing_with_tenant_queue(dataset.tenant_id, dataset.id, document_ids, task_dispatch_spy)
 
         # Assert
-        assert task_dispatch_spy.delay.call_count == concurrency_limit
+        assert task_dispatch_spy.apply_async.call_count == concurrency_limit
         assert set_waiting_spy.call_count == concurrency_limit
 
     def test_task_queue_fifo_ordering(self, db_session_with_containers, patched_external_dependencies):
@@ -565,9 +568,10 @@ class TestDatasetIndexingTaskIntegration:
             _document_indexing_with_tenant_queue(dataset.tenant_id, dataset.id, document_ids, task_dispatch_spy)
 
         # Assert
-        assert task_dispatch_spy.delay.call_count == 3
+        assert task_dispatch_spy.apply_async.call_count == 3
         for index, expected_task in enumerate(ordered_tasks):
-            assert task_dispatch_spy.delay.call_args_list[index].kwargs["document_ids"] == expected_task["document_ids"]
+            call_kwargs = task_dispatch_spy.apply_async.call_args_list[index].kwargs.get("kwargs", {})
+            assert call_kwargs.get("document_ids") == expected_task["document_ids"]
 
     def test_billing_disabled_skips_limit_checks(self, db_session_with_containers, patched_external_dependencies):
         """Skip limit checks when billing feature is disabled."""

api/tests/test_containers_integration_tests/tasks/test_document_indexing_task.py

@@ -762,11 +762,12 @@ class TestDocumentIndexingTasks:
         mock_external_service_dependencies["indexing_runner_instance"].run.assert_called_once()
 
         # Verify task function was called for each waiting task
-        assert mock_task_func.delay.call_count == 1
+        assert mock_task_func.apply_async.call_count == 1
 
         # Verify correct parameters for each call
-        calls = mock_task_func.delay.call_args_list
-        assert calls[0][1] == {"tenant_id": tenant_id, "dataset_id": dataset_id, "document_ids": ["waiting-doc-1"]}
+        calls = mock_task_func.apply_async.call_args_list
+        sent_kwargs = calls[0][1]["kwargs"]
+        assert sent_kwargs == {"tenant_id": tenant_id, "dataset_id": dataset_id, "document_ids": ["waiting-doc-1"]}
 
         # Verify queue is empty after processing (tasks were pulled)
         remaining_tasks = queue.pull_tasks(count=10)  # Pull more than we added
@@ -830,11 +831,15 @@ class TestDocumentIndexingTasks:
             assert updated_document.processing_started_at is not None
 
         # Verify waiting task was still processed despite core processing error
-        mock_task_func.delay.assert_called_once()
+        mock_task_func.apply_async.assert_called_once()
 
         # Verify correct parameters for the call
-        call = mock_task_func.delay.call_args
-        assert call[1] == {"tenant_id": tenant_id, "dataset_id": dataset_id, "document_ids": ["waiting-doc-1"]}
+        call = mock_task_func.apply_async.call_args
+        assert call[1]["kwargs"] == {
+            "tenant_id": tenant_id,
+            "dataset_id": dataset_id,
+            "document_ids": ["waiting-doc-1"],
+        }
 
         # Verify queue is empty after processing (task was pulled)
         remaining_tasks = queue.pull_tasks(count=10)
@@ -896,9 +901,13 @@ class TestDocumentIndexingTasks:
         mock_external_service_dependencies["indexing_runner_instance"].run.assert_called_once()
 
         # Verify only tenant1's waiting task was processed
-        mock_task_func.delay.assert_called_once()
-        call = mock_task_func.delay.call_args
-        assert call[1] == {"tenant_id": tenant1_id, "dataset_id": dataset1_id, "document_ids": ["tenant1-doc-1"]}
+        mock_task_func.apply_async.assert_called_once()
+        call = mock_task_func.apply_async.call_args
+        assert call[1]["kwargs"] == {
+            "tenant_id": tenant1_id,
+            "dataset_id": dataset1_id,
+            "document_ids": ["tenant1-doc-1"],
+        }
 
         # Verify tenant1's queue is empty
         remaining_tasks1 = queue1.pull_tasks(count=10)

api/tests/test_containers_integration_tests/tasks/test_rag_pipeline_run_tasks.py

@@ -1,6 +1,6 @@
 import json
 import uuid
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
 
 import pytest
 from faker import Faker
@@ -388,8 +388,10 @@ class TestRagPipelineRunTasks:
         # Set the task key to indicate there are waiting tasks (legacy behavior)
         redis_client.set(legacy_task_key, 1, ex=60 * 60)
 
-        # Mock the task function calls
-        with patch("tasks.rag_pipeline.rag_pipeline_run_task.rag_pipeline_run_task.delay") as mock_delay:
+        # Mock the Celery group scheduling used by the implementation
+        with patch("tasks.rag_pipeline.rag_pipeline_run_task.group") as mock_group:
+            mock_group.return_value.apply_async = MagicMock()
+
             # Act: Execute the priority task with new code but legacy queue data
             rag_pipeline_run_task(file_id, tenant.id)
 
@@ -398,13 +400,14 @@ class TestRagPipelineRunTasks:
             mock_file_service["delete_file"].assert_called_once_with(file_id)
             assert mock_pipeline_generator.call_count == 1
 
-            # Verify waiting tasks were processed, pull 1 task a time by default
-            assert mock_delay.call_count == 1
+            # Verify waiting tasks were processed via group, pull 1 task a time by default
+            assert mock_group.return_value.apply_async.called
 
-            # Verify correct parameters for the call
-            call_kwargs = mock_delay.call_args[1] if mock_delay.call_args else {}
-            assert call_kwargs.get("rag_pipeline_invoke_entities_file_id") == legacy_file_ids[0]
-            assert call_kwargs.get("tenant_id") == tenant.id
+            # Verify correct parameters for the first scheduled job signature
+            jobs = mock_group.call_args.args[0] if mock_group.call_args else []
+            first_kwargs = jobs[0].kwargs if jobs else {}
+            assert first_kwargs.get("rag_pipeline_invoke_entities_file_id") == legacy_file_ids[0]
+            assert first_kwargs.get("tenant_id") == tenant.id
 
             # Verify that new code can process legacy queue entries
             # The new TenantIsolatedTaskQueue should be able to read from the legacy format
@@ -446,8 +449,10 @@ class TestRagPipelineRunTasks:
         waiting_file_ids = [str(uuid.uuid4()) for _ in range(3)]
         queue.push_tasks(waiting_file_ids)
 
-        # Mock the task function calls
-        with patch("tasks.rag_pipeline.rag_pipeline_run_task.rag_pipeline_run_task.delay") as mock_delay:
+        # Mock the Celery group scheduling used by the implementation
+        with patch("tasks.rag_pipeline.rag_pipeline_run_task.group") as mock_group:
+            mock_group.return_value.apply_async = MagicMock()
+
             # Act: Execute the regular task
             rag_pipeline_run_task(file_id, tenant.id)
 
@@ -456,13 +461,14 @@ class TestRagPipelineRunTasks:
             mock_file_service["delete_file"].assert_called_once_with(file_id)
             assert mock_pipeline_generator.call_count == 1
 
-            # Verify waiting tasks were processed, pull 1 task a time by default
-            assert mock_delay.call_count == 1
+            # Verify waiting tasks were processed via group.apply_async
+            assert mock_group.return_value.apply_async.called
 
-            # Verify correct parameters for the call
-            call_kwargs = mock_delay.call_args[1] if mock_delay.call_args else {}
-            assert call_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_ids[0]
-            assert call_kwargs.get("tenant_id") == tenant.id
+            # Verify correct parameters for the first scheduled job signature
+            jobs = mock_group.call_args.args[0] if mock_group.call_args else []
+            first_kwargs = jobs[0].kwargs if jobs else {}
+            assert first_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_ids[0]
+            assert first_kwargs.get("tenant_id") == tenant.id
 
             # Verify queue still has remaining tasks (only 1 was pulled)
             remaining_tasks = queue.pull_tasks(count=10)
@@ -557,8 +563,10 @@ class TestRagPipelineRunTasks:
         waiting_file_id = str(uuid.uuid4())
         queue.push_tasks([waiting_file_id])
 
-        # Mock the task function calls
-        with patch("tasks.rag_pipeline.rag_pipeline_run_task.rag_pipeline_run_task.delay") as mock_delay:
+        # Mock the Celery group scheduling used by the implementation
+        with patch("tasks.rag_pipeline.rag_pipeline_run_task.group") as mock_group:
+            mock_group.return_value.apply_async = MagicMock()
+
             # Act: Execute the regular task (should not raise exception)
             rag_pipeline_run_task(file_id, tenant.id)
 
@@ -569,12 +577,13 @@ class TestRagPipelineRunTasks:
             assert mock_pipeline_generator.call_count == 1
 
             # Verify waiting task was still processed despite core processing error
-            mock_delay.assert_called_once()
+            assert mock_group.return_value.apply_async.called
 
-            # Verify correct parameters for the call
-            call_kwargs = mock_delay.call_args[1] if mock_delay.call_args else {}
-            assert call_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_id
-            assert call_kwargs.get("tenant_id") == tenant.id
+            # Verify correct parameters for the first scheduled job signature
+            jobs = mock_group.call_args.args[0] if mock_group.call_args else []
+            first_kwargs = jobs[0].kwargs if jobs else {}
+            assert first_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_id
+            assert first_kwargs.get("tenant_id") == tenant.id
 
             # Verify queue is empty after processing (task was pulled)
             remaining_tasks = queue.pull_tasks(count=10)
@@ -684,8 +693,10 @@ class TestRagPipelineRunTasks:
         queue1.push_tasks([waiting_file_id1])
         queue2.push_tasks([waiting_file_id2])
 
-        # Mock the task function calls
-        with patch("tasks.rag_pipeline.rag_pipeline_run_task.rag_pipeline_run_task.delay") as mock_delay:
+        # Mock the Celery group scheduling used by the implementation
+        with patch("tasks.rag_pipeline.rag_pipeline_run_task.group") as mock_group:
+            mock_group.return_value.apply_async = MagicMock()
+
             # Act: Execute the regular task for tenant1 only
             rag_pipeline_run_task(file_id1, tenant1.id)
 
@@ -694,11 +705,12 @@ class TestRagPipelineRunTasks:
             assert mock_file_service["delete_file"].call_count == 1
             assert mock_pipeline_generator.call_count == 1
 
-            # Verify only tenant1's waiting task was processed
-            mock_delay.assert_called_once()
-            call_kwargs = mock_delay.call_args[1] if mock_delay.call_args else {}
-            assert call_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_id1
-            assert call_kwargs.get("tenant_id") == tenant1.id
+            # Verify only tenant1's waiting task was processed (via group)
+            assert mock_group.return_value.apply_async.called
+            jobs = mock_group.call_args.args[0] if mock_group.call_args else []
+            first_kwargs = jobs[0].kwargs if jobs else {}
+            assert first_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_id1
+            assert first_kwargs.get("tenant_id") == tenant1.id
 
             # Verify tenant1's queue is empty
             remaining_tasks1 = queue1.pull_tasks(count=10)
@@ -913,8 +925,10 @@ class TestRagPipelineRunTasks:
         waiting_file_id = str(uuid.uuid4())
         queue.push_tasks([waiting_file_id])
 
-        # Mock the task function calls
-        with patch("tasks.rag_pipeline.rag_pipeline_run_task.rag_pipeline_run_task.delay") as mock_delay:
+        # Mock the Celery group scheduling used by the implementation
+        with patch("tasks.rag_pipeline.rag_pipeline_run_task.group") as mock_group:
+            mock_group.return_value.apply_async = MagicMock()
+
             # Act & Assert: Execute the regular task (should raise Exception)
             with pytest.raises(Exception, match="File not found"):
                 rag_pipeline_run_task(file_id, tenant.id)
@@ -924,12 +938,13 @@ class TestRagPipelineRunTasks:
             mock_pipeline_generator.assert_not_called()
 
             # Verify waiting task was still processed despite file error
-            mock_delay.assert_called_once()
+            assert mock_group.return_value.apply_async.called
 
-            # Verify correct parameters for the call
-            call_kwargs = mock_delay.call_args[1] if mock_delay.call_args else {}
-            assert call_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_id
-            assert call_kwargs.get("tenant_id") == tenant.id
+            # Verify correct parameters for the first scheduled job signature
+            jobs = mock_group.call_args.args[0] if mock_group.call_args else []
+            first_kwargs = jobs[0].kwargs if jobs else {}
+            assert first_kwargs.get("rag_pipeline_invoke_entities_file_id") == waiting_file_id
+            assert first_kwargs.get("tenant_id") == tenant.id
 
             # Verify queue is empty after processing (task was pulled)
             remaining_tasks = queue.pull_tasks(count=10)

api/tests/test_containers_integration_tests/trigger/conftest.py

@@ -105,18 +105,26 @@ def app_model(
 
 
 class MockCeleryGroup:
-    """Mock for celery group() function that collects dispatched tasks."""
+    """Mock for celery group() function that collects dispatched tasks.
+
+    Matches the Celery group API loosely, accepting arbitrary kwargs on apply_async
+    (e.g. producer) so production code can pass broker-related options without
+    breaking tests.
+    """
 
     def __init__(self) -> None:
         self.collected: list[dict[str, Any]] = []
         self._applied = False
+        self.last_apply_async_kwargs: dict[str, Any] | None = None
 
     def __call__(self, items: Any) -> MockCeleryGroup:
         self.collected = list(items)
         return self
 
-    def apply_async(self) -> None:
+    def apply_async(self, **kwargs: Any) -> None:
+        # Accept arbitrary kwargs like producer to be compatible with Celery
         self._applied = True
+        self.last_apply_async_kwargs = kwargs
 
     @property
     def applied(self) -> bool:

api/tests/unit_tests/commands/test_clean_expired_messages.py

@@ -0,0 +1,181 @@
+import datetime
+import re
+from unittest.mock import MagicMock, patch
+
+import click
+import pytest
+
+from commands import clean_expired_messages
+
+
+def _mock_service() -> MagicMock:
+    service = MagicMock()
+    service.run.return_value = {
+        "batches": 1,
+        "total_messages": 10,
+        "filtered_messages": 5,
+        "total_deleted": 5,
+    }
+    return service
+
+
+def test_absolute_mode_calls_from_time_range():
+    policy = object()
+    service = _mock_service()
+    start_from = datetime.datetime(2024, 1, 1, 0, 0, 0)
+    end_before = datetime.datetime(2024, 2, 1, 0, 0, 0)
+
+    with (
+        patch("commands.create_message_clean_policy", return_value=policy),
+        patch("commands.MessagesCleanService.from_time_range", return_value=service) as mock_from_time_range,
+        patch("commands.MessagesCleanService.from_days") as mock_from_days,
+    ):
+        clean_expired_messages.callback(
+            batch_size=200,
+            graceful_period=21,
+            start_from=start_from,
+            end_before=end_before,
+            from_days_ago=None,
+            before_days=None,
+            dry_run=True,
+        )
+
+    mock_from_time_range.assert_called_once_with(
+        policy=policy,
+        start_from=start_from,
+        end_before=end_before,
+        batch_size=200,
+        dry_run=True,
+    )
+    mock_from_days.assert_not_called()
+
+
+def test_relative_mode_before_days_only_calls_from_days():
+    policy = object()
+    service = _mock_service()
+
+    with (
+        patch("commands.create_message_clean_policy", return_value=policy),
+        patch("commands.MessagesCleanService.from_days", return_value=service) as mock_from_days,
+        patch("commands.MessagesCleanService.from_time_range") as mock_from_time_range,
+    ):
+        clean_expired_messages.callback(
+            batch_size=500,
+            graceful_period=14,
+            start_from=None,
+            end_before=None,
+            from_days_ago=None,
+            before_days=30,
+            dry_run=False,
+        )
+
+    mock_from_days.assert_called_once_with(
+        policy=policy,
+        days=30,
+        batch_size=500,
+        dry_run=False,
+    )
+    mock_from_time_range.assert_not_called()
+
+
+def test_relative_mode_with_from_days_ago_calls_from_time_range():
+    policy = object()
+    service = _mock_service()
+    fixed_now = datetime.datetime(2024, 8, 20, 12, 0, 0)
+
+    with (
+        patch("commands.create_message_clean_policy", return_value=policy),
+        patch("commands.MessagesCleanService.from_time_range", return_value=service) as mock_from_time_range,
+        patch("commands.MessagesCleanService.from_days") as mock_from_days,
+        patch("commands.naive_utc_now", return_value=fixed_now),
+    ):
+        clean_expired_messages.callback(
+            batch_size=1000,
+            graceful_period=21,
+            start_from=None,
+            end_before=None,
+            from_days_ago=60,
+            before_days=30,
+            dry_run=False,
+        )
+
+    mock_from_time_range.assert_called_once_with(
+        policy=policy,
+        start_from=fixed_now - datetime.timedelta(days=60),
+        end_before=fixed_now - datetime.timedelta(days=30),
+        batch_size=1000,
+        dry_run=False,
+    )
+    mock_from_days.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "message"),
+    [
+        (
+            {
+                "start_from": datetime.datetime(2024, 1, 1),
+                "end_before": datetime.datetime(2024, 2, 1),
+                "from_days_ago": None,
+                "before_days": 30,
+            },
+            "mutually exclusive",
+        ),
+        (
+            {
+                "start_from": datetime.datetime(2024, 1, 1),
+                "end_before": None,
+                "from_days_ago": None,
+                "before_days": None,
+            },
+            "Both --start-from and --end-before are required",
+        ),
+        (
+            {
+                "start_from": None,
+                "end_before": None,
+                "from_days_ago": 10,
+                "before_days": None,
+            },
+            "--from-days-ago must be used together with --before-days",
+        ),
+        (
+            {
+                "start_from": None,
+                "end_before": None,
+                "from_days_ago": None,
+                "before_days": -1,
+            },
+            "--before-days must be >= 0",
+        ),
+        (
+            {
+                "start_from": None,
+                "end_before": None,
+                "from_days_ago": 30,
+                "before_days": 30,
+            },
+            "--from-days-ago must be greater than --before-days",
+        ),
+        (
+            {
+                "start_from": None,
+                "end_before": None,
+                "from_days_ago": None,
+                "before_days": None,
+            },
+            "You must provide either (--start-from,--end-before) or (--before-days [--from-days-ago])",
+        ),
+    ],
+)
+def test_invalid_inputs_raise_usage_error(kwargs: dict, message: str):
+    with pytest.raises(click.UsageError, match=re.escape(message)):
+        clean_expired_messages.callback(
+            batch_size=1000,
+            graceful_period=21,
+            start_from=kwargs["start_from"],
+            end_before=kwargs["end_before"],
+            from_days_ago=kwargs["from_days_ago"],
+            before_days=kwargs["before_days"],
+            dry_run=False,
+        )

api/tests/unit_tests/controllers/web/conftest.py

@@ -0,0 +1,85 @@
+"""Shared fixtures for controllers.web unit tests."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+from flask import Flask
+
+
+@pytest.fixture
+def app() -> Flask:
+    """Minimal Flask app for request contexts."""
+    flask_app = Flask(__name__)
+    flask_app.config["TESTING"] = True
+    return flask_app
+
+
+class FakeSession:
+    """Stand-in for db.session that returns pre-seeded objects by model class name."""
+
+    def __init__(self, mapping: dict[str, Any] | None = None):
+        self._mapping: dict[str, Any] = mapping or {}
+        self._model_name: str | None = None
+
+    def query(self, model: type) -> FakeSession:
+        self._model_name = model.__name__
+        return self
+
+    def where(self, *_args: object, **_kwargs: object) -> FakeSession:
+        return self
+
+    def first(self) -> Any:
+        assert self._model_name is not None
+        return self._mapping.get(self._model_name)
+
+
+class FakeDB:
+    """Minimal db stub exposing engine and session."""
+
+    def __init__(self, session: FakeSession | None = None):
+        self.session = session or FakeSession()
+        self.engine = object()
+
+
+def make_app_model(
+    *,
+    app_id: str = "app-1",
+    tenant_id: str = "tenant-1",
+    mode: str = "chat",
+    enable_site: bool = True,
+    status: str = "normal",
+) -> SimpleNamespace:
+    """Build a fake App model with common defaults."""
+    tenant = SimpleNamespace(
+        id=tenant_id,
+        status="normal",
+        plan="basic",
+        custom_config_dict={},
+    )
+    return SimpleNamespace(
+        id=app_id,
+        tenant_id=tenant_id,
+        tenant=tenant,
+        mode=mode,
+        enable_site=enable_site,
+        status=status,
+        workflow=None,
+        app_model_config=None,
+    )
+
+
+def make_end_user(
+    *,
+    user_id: str = "end-user-1",
+    session_id: str = "session-1",
+    external_user_id: str = "ext-user-1",
+) -> SimpleNamespace:
+    """Build a fake EndUser model with common defaults."""
+    return SimpleNamespace(
+        id=user_id,
+        session_id=session_id,
+        external_user_id=external_user_id,
+    )

api/tests/unit_tests/controllers/web/test_app.py

@@ -0,0 +1,165 @@
+"""Unit tests for controllers.web.app endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+from controllers.web.app import AppAccessMode, AppMeta, AppParameterApi, AppWebAuthPermission
+from controllers.web.error import AppUnavailableError
+
+
+# ---------------------------------------------------------------------------
+# AppParameterApi
+# ---------------------------------------------------------------------------
+class TestAppParameterApi:
+    def test_advanced_chat_mode_uses_workflow(self, app: Flask) -> None:
+        features_dict = {"opening_statement": "Hello"}
+        workflow = SimpleNamespace(
+            features_dict=features_dict,
+            user_input_form=lambda to_old_structure=False: [],
+        )
+        app_model = SimpleNamespace(mode="advanced-chat", workflow=workflow)
+
+        with (
+            app.test_request_context("/parameters"),
+            patch("controllers.web.app.get_parameters_from_feature_dict", return_value={}) as mock_params,
+            patch("controllers.web.app.fields.Parameters") as mock_fields,
+        ):
+            mock_fields.model_validate.return_value.model_dump.return_value = {"result": "ok"}
+            result = AppParameterApi().get(app_model, SimpleNamespace())
+
+        mock_params.assert_called_once_with(features_dict=features_dict, user_input_form=[])
+        assert result == {"result": "ok"}
+
+    def test_workflow_mode_uses_workflow(self, app: Flask) -> None:
+        features_dict = {}
+        workflow = SimpleNamespace(
+            features_dict=features_dict,
+            user_input_form=lambda to_old_structure=False: [{"var": "x"}],
+        )
+        app_model = SimpleNamespace(mode="workflow", workflow=workflow)
+
+        with (
+            app.test_request_context("/parameters"),
+            patch("controllers.web.app.get_parameters_from_feature_dict", return_value={}) as mock_params,
+            patch("controllers.web.app.fields.Parameters") as mock_fields,
+        ):
+            mock_fields.model_validate.return_value.model_dump.return_value = {}
+            AppParameterApi().get(app_model, SimpleNamespace())
+
+        mock_params.assert_called_once_with(features_dict=features_dict, user_input_form=[{"var": "x"}])
+
+    def test_advanced_chat_mode_no_workflow_raises(self, app: Flask) -> None:
+        app_model = SimpleNamespace(mode="advanced-chat", workflow=None)
+        with app.test_request_context("/parameters"):
+            with pytest.raises(AppUnavailableError):
+                AppParameterApi().get(app_model, SimpleNamespace())
+
+    def test_standard_mode_uses_app_model_config(self, app: Flask) -> None:
+        config = SimpleNamespace(to_dict=lambda: {"user_input_form": [{"var": "y"}], "key": "val"})
+        app_model = SimpleNamespace(mode="chat", app_model_config=config)
+
+        with (
+            app.test_request_context("/parameters"),
+            patch("controllers.web.app.get_parameters_from_feature_dict", return_value={}) as mock_params,
+            patch("controllers.web.app.fields.Parameters") as mock_fields,
+        ):
+            mock_fields.model_validate.return_value.model_dump.return_value = {}
+            AppParameterApi().get(app_model, SimpleNamespace())
+
+        call_kwargs = mock_params.call_args
+        assert call_kwargs.kwargs["user_input_form"] == [{"var": "y"}]
+
+    def test_standard_mode_no_config_raises(self, app: Flask) -> None:
+        app_model = SimpleNamespace(mode="chat", app_model_config=None)
+        with app.test_request_context("/parameters"):
+            with pytest.raises(AppUnavailableError):
+                AppParameterApi().get(app_model, SimpleNamespace())
+
+
+# ---------------------------------------------------------------------------
+# AppMeta
+# ---------------------------------------------------------------------------
+class TestAppMeta:
+    @patch("controllers.web.app.AppService")
+    def test_get_returns_meta(self, mock_service_cls: MagicMock, app: Flask) -> None:
+        mock_service_cls.return_value.get_app_meta.return_value = {"tool_icons": {}}
+        app_model = SimpleNamespace(id="app-1")
+
+        with app.test_request_context("/meta"):
+            result = AppMeta().get(app_model, SimpleNamespace())
+
+        assert result == {"tool_icons": {}}
+
+
+# ---------------------------------------------------------------------------
+# AppAccessMode
+# ---------------------------------------------------------------------------
+class TestAppAccessMode:
+    @patch("controllers.web.app.FeatureService.get_system_features")
+    def test_returns_public_when_webapp_auth_disabled(self, mock_features: MagicMock, app: Flask) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+
+        with app.test_request_context("/webapp/access-mode?appId=app-1"):
+            result = AppAccessMode().get()
+
+        assert result == {"accessMode": "public"}
+
+    @patch("controllers.web.app.EnterpriseService.WebAppAuth.get_app_access_mode_by_id")
+    @patch("controllers.web.app.FeatureService.get_system_features")
+    def test_returns_access_mode_with_app_id(
+        self, mock_features: MagicMock, mock_access: MagicMock, app: Flask
+    ) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=True))
+        mock_access.return_value = SimpleNamespace(access_mode="internal")
+
+        with app.test_request_context("/webapp/access-mode?appId=app-1"):
+            result = AppAccessMode().get()
+
+        assert result == {"accessMode": "internal"}
+        mock_access.assert_called_once_with("app-1")
+
+    @patch("controllers.web.app.AppService.get_app_id_by_code", return_value="resolved-id")
+    @patch("controllers.web.app.EnterpriseService.WebAppAuth.get_app_access_mode_by_id")
+    @patch("controllers.web.app.FeatureService.get_system_features")
+    def test_resolves_app_code_to_id(
+        self, mock_features: MagicMock, mock_access: MagicMock, mock_resolve: MagicMock, app: Flask
+    ) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=True))
+        mock_access.return_value = SimpleNamespace(access_mode="external")
+
+        with app.test_request_context("/webapp/access-mode?appCode=code1"):
+            result = AppAccessMode().get()
+
+        mock_resolve.assert_called_once_with("code1")
+        mock_access.assert_called_once_with("resolved-id")
+        assert result == {"accessMode": "external"}
+
+    @patch("controllers.web.app.FeatureService.get_system_features")
+    def test_raises_when_no_app_id_or_code(self, mock_features: MagicMock, app: Flask) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=True))
+
+        with app.test_request_context("/webapp/access-mode"):
+            with pytest.raises(ValueError, match="appId or appCode"):
+                AppAccessMode().get()
+
+
+# ---------------------------------------------------------------------------
+# AppWebAuthPermission
+# ---------------------------------------------------------------------------
+class TestAppWebAuthPermission:
+    @patch("controllers.web.app.WebAppAuthService.is_app_require_permission_check", return_value=False)
+    def test_returns_true_when_no_permission_check_required(self, mock_check: MagicMock, app: Flask) -> None:
+        with app.test_request_context("/webapp/permission?appId=app-1", headers={"X-App-Code": "code1"}):
+            result = AppWebAuthPermission().get()
+
+        assert result == {"result": True}
+
+    def test_raises_when_missing_app_id(self, app: Flask) -> None:
+        with app.test_request_context("/webapp/permission", headers={"X-App-Code": "code1"}):
+            with pytest.raises(ValueError, match="appId"):
+                AppWebAuthPermission().get()

api/tests/unit_tests/controllers/web/test_audio.py

@@ -0,0 +1,135 @@
+"""Unit tests for controllers.web.audio endpoints."""
+
+from __future__ import annotations
+
+from io import BytesIO
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+from controllers.web.audio import AudioApi, TextApi
+from controllers.web.error import (
+    AudioTooLargeError,
+    CompletionRequestError,
+    NoAudioUploadedError,
+    ProviderModelCurrentlyNotSupportError,
+    ProviderNotInitializeError,
+    ProviderNotSupportSpeechToTextError,
+    ProviderQuotaExceededError,
+    UnsupportedAudioTypeError,
+)
+from core.errors.error import ModelCurrentlyNotSupportError, ProviderTokenNotInitError, QuotaExceededError
+from dify_graph.model_runtime.errors.invoke import InvokeError
+from services.errors.audio import (
+    AudioTooLargeServiceError,
+    NoAudioUploadedServiceError,
+    ProviderNotSupportSpeechToTextServiceError,
+    UnsupportedAudioTypeServiceError,
+)
+
+
+def _app_model() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="chat")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1", external_user_id="ext-1")
+
+
+# ---------------------------------------------------------------------------
+# AudioApi (audio-to-text)
+# ---------------------------------------------------------------------------
+class TestAudioApi:
+    @patch("controllers.web.audio.AudioService.transcript_asr", return_value={"text": "hello"})
+    def test_happy_path(self, mock_asr: MagicMock, app: Flask) -> None:
+        app.config["RESTX_MASK_HEADER"] = "X-Fields"
+        data = {"file": (BytesIO(b"fake-audio"), "test.mp3")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            result = AudioApi().post(_app_model(), _end_user())
+
+        assert result == {"text": "hello"}
+
+    @patch("controllers.web.audio.AudioService.transcript_asr", side_effect=NoAudioUploadedServiceError())
+    def test_no_audio_uploaded(self, mock_asr: MagicMock, app: Flask) -> None:
+        data = {"file": (BytesIO(b""), "empty.mp3")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(NoAudioUploadedError):
+                AudioApi().post(_app_model(), _end_user())
+
+    @patch("controllers.web.audio.AudioService.transcript_asr", side_effect=AudioTooLargeServiceError("too big"))
+    def test_audio_too_large(self, mock_asr: MagicMock, app: Flask) -> None:
+        data = {"file": (BytesIO(b"big"), "big.mp3")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(AudioTooLargeError):
+                AudioApi().post(_app_model(), _end_user())
+
+    @patch("controllers.web.audio.AudioService.transcript_asr", side_effect=UnsupportedAudioTypeServiceError())
+    def test_unsupported_type(self, mock_asr: MagicMock, app: Flask) -> None:
+        data = {"file": (BytesIO(b"bad"), "bad.xyz")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(UnsupportedAudioTypeError):
+                AudioApi().post(_app_model(), _end_user())
+
+    @patch(
+        "controllers.web.audio.AudioService.transcript_asr",
+        side_effect=ProviderNotSupportSpeechToTextServiceError(),
+    )
+    def test_provider_not_support(self, mock_asr: MagicMock, app: Flask) -> None:
+        data = {"file": (BytesIO(b"x"), "x.mp3")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(ProviderNotSupportSpeechToTextError):
+                AudioApi().post(_app_model(), _end_user())
+
+    @patch(
+        "controllers.web.audio.AudioService.transcript_asr",
+        side_effect=ProviderTokenNotInitError(description="no token"),
+    )
+    def test_provider_not_init(self, mock_asr: MagicMock, app: Flask) -> None:
+        data = {"file": (BytesIO(b"x"), "x.mp3")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(ProviderNotInitializeError):
+                AudioApi().post(_app_model(), _end_user())
+
+    @patch("controllers.web.audio.AudioService.transcript_asr", side_effect=QuotaExceededError())
+    def test_quota_exceeded(self, mock_asr: MagicMock, app: Flask) -> None:
+        data = {"file": (BytesIO(b"x"), "x.mp3")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(ProviderQuotaExceededError):
+                AudioApi().post(_app_model(), _end_user())
+
+    @patch("controllers.web.audio.AudioService.transcript_asr", side_effect=ModelCurrentlyNotSupportError())
+    def test_model_not_support(self, mock_asr: MagicMock, app: Flask) -> None:
+        data = {"file": (BytesIO(b"x"), "x.mp3")}
+        with app.test_request_context("/audio-to-text", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(ProviderModelCurrentlyNotSupportError):
+                AudioApi().post(_app_model(), _end_user())
+
+
+# ---------------------------------------------------------------------------
+# TextApi (text-to-audio)
+# ---------------------------------------------------------------------------
+class TestTextApi:
+    @patch("controllers.web.audio.AudioService.transcript_tts", return_value="audio-bytes")
+    @patch("controllers.web.audio.web_ns")
+    def test_happy_path(self, mock_ns: MagicMock, mock_tts: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"text": "hello", "voice": "alloy"}
+
+        with app.test_request_context("/text-to-audio", method="POST"):
+            result = TextApi().post(_app_model(), _end_user())
+
+        assert result == "audio-bytes"
+        mock_tts.assert_called_once()
+
+    @patch(
+        "controllers.web.audio.AudioService.transcript_tts",
+        side_effect=InvokeError(description="invoke failed"),
+    )
+    @patch("controllers.web.audio.web_ns")
+    def test_invoke_error_mapped(self, mock_ns: MagicMock, mock_tts: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"text": "hello"}
+
+        with app.test_request_context("/text-to-audio", method="POST"):
+            with pytest.raises(CompletionRequestError):
+                TextApi().post(_app_model(), _end_user())

api/tests/unit_tests/controllers/web/test_completion.py

@@ -0,0 +1,161 @@
+"""Unit tests for controllers.web.completion endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+from controllers.web.completion import ChatApi, ChatStopApi, CompletionApi, CompletionStopApi
+from controllers.web.error import (
+    CompletionRequestError,
+    NotChatAppError,
+    NotCompletionAppError,
+    ProviderModelCurrentlyNotSupportError,
+    ProviderNotInitializeError,
+    ProviderQuotaExceededError,
+)
+from core.errors.error import ModelCurrentlyNotSupportError, ProviderTokenNotInitError, QuotaExceededError
+from dify_graph.model_runtime.errors.invoke import InvokeError
+
+
+def _completion_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="completion")
+
+
+def _chat_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="chat")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+# ---------------------------------------------------------------------------
+# CompletionApi
+# ---------------------------------------------------------------------------
+class TestCompletionApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/completion-messages", method="POST"):
+            with pytest.raises(NotCompletionAppError):
+                CompletionApi().post(_chat_app(), _end_user())
+
+    @patch("controllers.web.completion.helper.compact_generate_response", return_value={"answer": "hi"})
+    @patch("controllers.web.completion.AppGenerateService.generate")
+    @patch("controllers.web.completion.web_ns")
+    def test_happy_path(self, mock_ns: MagicMock, mock_gen: MagicMock, mock_compact: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}, "query": "test"}
+        mock_gen.return_value = "response-obj"
+
+        with app.test_request_context("/completion-messages", method="POST"):
+            result = CompletionApi().post(_completion_app(), _end_user())
+
+        assert result == {"answer": "hi"}
+
+    @patch(
+        "controllers.web.completion.AppGenerateService.generate",
+        side_effect=ProviderTokenNotInitError(description="not init"),
+    )
+    @patch("controllers.web.completion.web_ns")
+    def test_provider_not_init_error(self, mock_ns: MagicMock, mock_gen: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}}
+
+        with app.test_request_context("/completion-messages", method="POST"):
+            with pytest.raises(ProviderNotInitializeError):
+                CompletionApi().post(_completion_app(), _end_user())
+
+    @patch(
+        "controllers.web.completion.AppGenerateService.generate",
+        side_effect=QuotaExceededError(),
+    )
+    @patch("controllers.web.completion.web_ns")
+    def test_quota_exceeded_error(self, mock_ns: MagicMock, mock_gen: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}}
+
+        with app.test_request_context("/completion-messages", method="POST"):
+            with pytest.raises(ProviderQuotaExceededError):
+                CompletionApi().post(_completion_app(), _end_user())
+
+    @patch(
+        "controllers.web.completion.AppGenerateService.generate",
+        side_effect=ModelCurrentlyNotSupportError(),
+    )
+    @patch("controllers.web.completion.web_ns")
+    def test_model_not_support_error(self, mock_ns: MagicMock, mock_gen: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}}
+
+        with app.test_request_context("/completion-messages", method="POST"):
+            with pytest.raises(ProviderModelCurrentlyNotSupportError):
+                CompletionApi().post(_completion_app(), _end_user())
+
+
+# ---------------------------------------------------------------------------
+# CompletionStopApi
+# ---------------------------------------------------------------------------
+class TestCompletionStopApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/completion-messages/task-1/stop", method="POST"):
+            with pytest.raises(NotCompletionAppError):
+                CompletionStopApi().post(_chat_app(), _end_user(), "task-1")
+
+    @patch("controllers.web.completion.AppTaskService.stop_task")
+    def test_stop_success(self, mock_stop: MagicMock, app: Flask) -> None:
+        with app.test_request_context("/completion-messages/task-1/stop", method="POST"):
+            result, status = CompletionStopApi().post(_completion_app(), _end_user(), "task-1")
+
+        assert status == 200
+        assert result == {"result": "success"}
+
+
+# ---------------------------------------------------------------------------
+# ChatApi
+# ---------------------------------------------------------------------------
+class TestChatApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/chat-messages", method="POST"):
+            with pytest.raises(NotChatAppError):
+                ChatApi().post(_completion_app(), _end_user())
+
+    @patch("controllers.web.completion.helper.compact_generate_response", return_value={"answer": "reply"})
+    @patch("controllers.web.completion.AppGenerateService.generate")
+    @patch("controllers.web.completion.web_ns")
+    def test_happy_path(self, mock_ns: MagicMock, mock_gen: MagicMock, mock_compact: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}, "query": "hi"}
+        mock_gen.return_value = "response"
+
+        with app.test_request_context("/chat-messages", method="POST"):
+            result = ChatApi().post(_chat_app(), _end_user())
+
+        assert result == {"answer": "reply"}
+
+    @patch(
+        "controllers.web.completion.AppGenerateService.generate",
+        side_effect=InvokeError(description="rate limit"),
+    )
+    @patch("controllers.web.completion.web_ns")
+    def test_invoke_error_mapped(self, mock_ns: MagicMock, mock_gen: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}, "query": "x"}
+
+        with app.test_request_context("/chat-messages", method="POST"):
+            with pytest.raises(CompletionRequestError):
+                ChatApi().post(_chat_app(), _end_user())
+
+
+# ---------------------------------------------------------------------------
+# ChatStopApi
+# ---------------------------------------------------------------------------
+class TestChatStopApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/chat-messages/task-1/stop", method="POST"):
+            with pytest.raises(NotChatAppError):
+                ChatStopApi().post(_completion_app(), _end_user(), "task-1")
+
+    @patch("controllers.web.completion.AppTaskService.stop_task")
+    def test_stop_success(self, mock_stop: MagicMock, app: Flask) -> None:
+        with app.test_request_context("/chat-messages/task-1/stop", method="POST"):
+            result, status = ChatStopApi().post(_chat_app(), _end_user(), "task-1")
+
+        assert status == 200
+        assert result == {"result": "success"}

api/tests/unit_tests/controllers/web/test_conversation.py

@@ -0,0 +1,183 @@
+"""Unit tests for controllers.web.conversation endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+from uuid import uuid4
+
+import pytest
+from flask import Flask
+from werkzeug.exceptions import NotFound
+
+from controllers.web.conversation import (
+    ConversationApi,
+    ConversationListApi,
+    ConversationPinApi,
+    ConversationRenameApi,
+    ConversationUnPinApi,
+)
+from controllers.web.error import NotChatAppError
+from services.errors.conversation import ConversationNotExistsError
+
+
+def _chat_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="chat")
+
+
+def _completion_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="completion")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+# ---------------------------------------------------------------------------
+# ConversationListApi
+# ---------------------------------------------------------------------------
+class TestConversationListApi:
+    def test_non_chat_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/conversations"):
+            with pytest.raises(NotChatAppError):
+                ConversationListApi().get(_completion_app(), _end_user())
+
+    @patch("controllers.web.conversation.WebConversationService.pagination_by_last_id")
+    @patch("controllers.web.conversation.db")
+    def test_happy_path(self, mock_db: MagicMock, mock_paginate: MagicMock, app: Flask) -> None:
+        conv_id = str(uuid4())
+        conv = SimpleNamespace(
+            id=conv_id,
+            name="Test",
+            inputs={},
+            status="normal",
+            introduction="",
+            created_at=1700000000,
+            updated_at=1700000000,
+        )
+        mock_paginate.return_value = SimpleNamespace(limit=20, has_more=False, data=[conv])
+        mock_db.engine = "engine"
+
+        session_mock = MagicMock()
+        session_ctx = MagicMock()
+        session_ctx.__enter__ = MagicMock(return_value=session_mock)
+        session_ctx.__exit__ = MagicMock(return_value=False)
+
+        with (
+            app.test_request_context("/conversations?limit=20"),
+            patch("controllers.web.conversation.Session", return_value=session_ctx),
+        ):
+            result = ConversationListApi().get(_chat_app(), _end_user())
+
+        assert result["limit"] == 20
+        assert result["has_more"] is False
+
+
+# ---------------------------------------------------------------------------
+# ConversationApi (delete)
+# ---------------------------------------------------------------------------
+class TestConversationApi:
+    def test_non_chat_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context(f"/conversations/{uuid4()}"):
+            with pytest.raises(NotChatAppError):
+                ConversationApi().delete(_completion_app(), _end_user(), uuid4())
+
+    @patch("controllers.web.conversation.ConversationService.delete")
+    def test_delete_success(self, mock_delete: MagicMock, app: Flask) -> None:
+        c_id = uuid4()
+        with app.test_request_context(f"/conversations/{c_id}"):
+            result, status = ConversationApi().delete(_chat_app(), _end_user(), c_id)
+
+        assert status == 204
+        assert result["result"] == "success"
+
+    @patch("controllers.web.conversation.ConversationService.delete", side_effect=ConversationNotExistsError())
+    def test_delete_not_found(self, mock_delete: MagicMock, app: Flask) -> None:
+        c_id = uuid4()
+        with app.test_request_context(f"/conversations/{c_id}"):
+            with pytest.raises(NotFound, match="Conversation Not Exists"):
+                ConversationApi().delete(_chat_app(), _end_user(), c_id)
+
+
+# ---------------------------------------------------------------------------
+# ConversationRenameApi
+# ---------------------------------------------------------------------------
+class TestConversationRenameApi:
+    def test_non_chat_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context(f"/conversations/{uuid4()}/name", method="POST", json={"name": "x"}):
+            with pytest.raises(NotChatAppError):
+                ConversationRenameApi().post(_completion_app(), _end_user(), uuid4())
+
+    @patch("controllers.web.conversation.ConversationService.rename")
+    @patch("controllers.web.conversation.web_ns")
+    def test_rename_success(self, mock_ns: MagicMock, mock_rename: MagicMock, app: Flask) -> None:
+        c_id = uuid4()
+        mock_ns.payload = {"name": "New Name", "auto_generate": False}
+        conv = SimpleNamespace(
+            id=str(c_id),
+            name="New Name",
+            inputs={},
+            status="normal",
+            introduction="",
+            created_at=1700000000,
+            updated_at=1700000000,
+        )
+        mock_rename.return_value = conv
+
+        with app.test_request_context(f"/conversations/{c_id}/name", method="POST", json={"name": "New Name"}):
+            result = ConversationRenameApi().post(_chat_app(), _end_user(), c_id)
+
+        assert result["name"] == "New Name"
+
+    @patch(
+        "controllers.web.conversation.ConversationService.rename",
+        side_effect=ConversationNotExistsError(),
+    )
+    @patch("controllers.web.conversation.web_ns")
+    def test_rename_not_found(self, mock_ns: MagicMock, mock_rename: MagicMock, app: Flask) -> None:
+        c_id = uuid4()
+        mock_ns.payload = {"name": "X", "auto_generate": False}
+
+        with app.test_request_context(f"/conversations/{c_id}/name", method="POST", json={"name": "X"}):
+            with pytest.raises(NotFound, match="Conversation Not Exists"):
+                ConversationRenameApi().post(_chat_app(), _end_user(), c_id)
+
+
+# ---------------------------------------------------------------------------
+# ConversationPinApi / ConversationUnPinApi
+# ---------------------------------------------------------------------------
+class TestConversationPinApi:
+    def test_non_chat_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context(f"/conversations/{uuid4()}/pin", method="PATCH"):
+            with pytest.raises(NotChatAppError):
+                ConversationPinApi().patch(_completion_app(), _end_user(), uuid4())
+
+    @patch("controllers.web.conversation.WebConversationService.pin")
+    def test_pin_success(self, mock_pin: MagicMock, app: Flask) -> None:
+        c_id = uuid4()
+        with app.test_request_context(f"/conversations/{c_id}/pin", method="PATCH"):
+            result = ConversationPinApi().patch(_chat_app(), _end_user(), c_id)
+
+        assert result["result"] == "success"
+
+    @patch("controllers.web.conversation.WebConversationService.pin", side_effect=ConversationNotExistsError())
+    def test_pin_not_found(self, mock_pin: MagicMock, app: Flask) -> None:
+        c_id = uuid4()
+        with app.test_request_context(f"/conversations/{c_id}/pin", method="PATCH"):
+            with pytest.raises(NotFound):
+                ConversationPinApi().patch(_chat_app(), _end_user(), c_id)
+
+
+class TestConversationUnPinApi:
+    def test_non_chat_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context(f"/conversations/{uuid4()}/unpin", method="PATCH"):
+            with pytest.raises(NotChatAppError):
+                ConversationUnPinApi().patch(_completion_app(), _end_user(), uuid4())
+
+    @patch("controllers.web.conversation.WebConversationService.unpin")
+    def test_unpin_success(self, mock_unpin: MagicMock, app: Flask) -> None:
+        c_id = uuid4()
+        with app.test_request_context(f"/conversations/{c_id}/unpin", method="PATCH"):
+            result = ConversationUnPinApi().patch(_chat_app(), _end_user(), c_id)
+
+        assert result["result"] == "success"

api/tests/unit_tests/controllers/web/test_error.py

@@ -0,0 +1,75 @@
+"""Unit tests for controllers.web.error HTTP exception classes."""
+
+from __future__ import annotations
+
+import pytest
+
+from controllers.web.error import (
+    AppMoreLikeThisDisabledError,
+    AppSuggestedQuestionsAfterAnswerDisabledError,
+    AppUnavailableError,
+    AudioTooLargeError,
+    CompletionRequestError,
+    ConversationCompletedError,
+    InvalidArgumentError,
+    InvokeRateLimitError,
+    NoAudioUploadedError,
+    NotChatAppError,
+    NotCompletionAppError,
+    NotFoundError,
+    NotWorkflowAppError,
+    ProviderModelCurrentlyNotSupportError,
+    ProviderNotInitializeError,
+    ProviderNotSupportSpeechToTextError,
+    ProviderQuotaExceededError,
+    UnsupportedAudioTypeError,
+    WebAppAuthAccessDeniedError,
+    WebAppAuthRequiredError,
+    WebFormRateLimitExceededError,
+)
+
+_ERROR_SPECS: list[tuple[type, str, int]] = [
+    (AppUnavailableError, "app_unavailable", 400),
+    (NotCompletionAppError, "not_completion_app", 400),
+    (NotChatAppError, "not_chat_app", 400),
+    (NotWorkflowAppError, "not_workflow_app", 400),
+    (ConversationCompletedError, "conversation_completed", 400),
+    (ProviderNotInitializeError, "provider_not_initialize", 400),
+    (ProviderQuotaExceededError, "provider_quota_exceeded", 400),
+    (ProviderModelCurrentlyNotSupportError, "model_currently_not_support", 400),
+    (CompletionRequestError, "completion_request_error", 400),
+    (AppMoreLikeThisDisabledError, "app_more_like_this_disabled", 403),
+    (AppSuggestedQuestionsAfterAnswerDisabledError, "app_suggested_questions_after_answer_disabled", 403),
+    (NoAudioUploadedError, "no_audio_uploaded", 400),
+    (AudioTooLargeError, "audio_too_large", 413),
+    (UnsupportedAudioTypeError, "unsupported_audio_type", 415),
+    (ProviderNotSupportSpeechToTextError, "provider_not_support_speech_to_text", 400),
+    (WebAppAuthRequiredError, "web_sso_auth_required", 401),
+    (WebAppAuthAccessDeniedError, "web_app_access_denied", 401),
+    (InvokeRateLimitError, "rate_limit_error", 429),
+    (WebFormRateLimitExceededError, "web_form_rate_limit_exceeded", 429),
+    (NotFoundError, "not_found", 404),
+    (InvalidArgumentError, "invalid_param", 400),
+]
+
+
+@pytest.mark.parametrize(
+    ("cls", "expected_code", "expected_status"),
+    _ERROR_SPECS,
+    ids=[cls.__name__ for cls, _, _ in _ERROR_SPECS],
+)
+def test_error_class_attributes(cls: type, expected_code: str, expected_status: int) -> None:
+    """Each error class exposes the correct error_code and HTTP status code."""
+    assert cls.error_code == expected_code
+    assert cls.code == expected_status
+
+
+def test_error_classes_have_description() -> None:
+    """Every error class has a description (string or None for generic errors)."""
+    # NotFoundError and InvalidArgumentError use None description by design
+    _NO_DESCRIPTION = {NotFoundError, InvalidArgumentError}
+    for cls, _, _ in _ERROR_SPECS:
+        if cls in _NO_DESCRIPTION:
+            continue
+        assert isinstance(cls.description, str), f"{cls.__name__} missing description"
+        assert len(cls.description) > 0, f"{cls.__name__} has empty description"

api/tests/unit_tests/controllers/web/test_feature.py

@@ -0,0 +1,38 @@
+"""Unit tests for controllers.web.feature endpoints."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from flask import Flask
+
+from controllers.web.feature import SystemFeatureApi
+
+
+class TestSystemFeatureApi:
+    @patch("controllers.web.feature.FeatureService.get_system_features")
+    def test_returns_system_features(self, mock_features: MagicMock, app: Flask) -> None:
+        mock_model = MagicMock()
+        mock_model.model_dump.return_value = {"sso_enforced_for_signin": False, "webapp_auth": {"enabled": False}}
+        mock_features.return_value = mock_model
+
+        with app.test_request_context("/system-features"):
+            result = SystemFeatureApi().get()
+
+        assert result == {"sso_enforced_for_signin": False, "webapp_auth": {"enabled": False}}
+        mock_features.assert_called_once()
+
+    @patch("controllers.web.feature.FeatureService.get_system_features")
+    def test_unauthenticated_access(self, mock_features: MagicMock, app: Flask) -> None:
+        """SystemFeatureApi is unauthenticated by design — no WebApiResource decorator."""
+        mock_model = MagicMock()
+        mock_model.model_dump.return_value = {}
+        mock_features.return_value = mock_model
+
+        # Verify it's a bare Resource, not WebApiResource
+        from flask_restx import Resource
+
+        from controllers.web.wraps import WebApiResource
+
+        assert issubclass(SystemFeatureApi, Resource)
+        assert not issubclass(SystemFeatureApi, WebApiResource)

api/tests/unit_tests/controllers/web/test_files.py

@@ -0,0 +1,89 @@
+"""Unit tests for controllers.web.files endpoints."""
+
+from __future__ import annotations
+
+from io import BytesIO
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+from controllers.common.errors import (
+    FilenameNotExistsError,
+    FileTooLargeError,
+    NoFileUploadedError,
+    TooManyFilesError,
+)
+from controllers.web.files import FileApi
+
+
+def _app_model() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+class TestFileApi:
+    def test_no_file_uploaded(self, app: Flask) -> None:
+        with app.test_request_context("/files/upload", method="POST", content_type="multipart/form-data"):
+            with pytest.raises(NoFileUploadedError):
+                FileApi().post(_app_model(), _end_user())
+
+    def test_too_many_files(self, app: Flask) -> None:
+        data = {
+            "file": (BytesIO(b"a"), "a.txt"),
+            "file2": (BytesIO(b"b"), "b.txt"),
+        }
+        with app.test_request_context("/files/upload", method="POST", data=data, content_type="multipart/form-data"):
+            # Now has "file" key but len(request.files) > 1
+            with pytest.raises(TooManyFilesError):
+                FileApi().post(_app_model(), _end_user())
+
+    def test_filename_missing(self, app: Flask) -> None:
+        data = {"file": (BytesIO(b"content"), "")}
+        with app.test_request_context("/files/upload", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(FilenameNotExistsError):
+                FileApi().post(_app_model(), _end_user())
+
+    @patch("controllers.web.files.FileService")
+    @patch("controllers.web.files.db")
+    def test_upload_success(self, mock_db: MagicMock, mock_file_svc_cls: MagicMock, app: Flask) -> None:
+        mock_db.engine = "engine"
+        from datetime import datetime
+
+        upload_file = SimpleNamespace(
+            id="file-1",
+            name="test.txt",
+            size=100,
+            extension="txt",
+            mime_type="text/plain",
+            created_by="eu-1",
+            created_at=datetime(2024, 1, 1),
+        )
+        mock_file_svc_cls.return_value.upload_file.return_value = upload_file
+
+        data = {"file": (BytesIO(b"content"), "test.txt")}
+        with app.test_request_context("/files/upload", method="POST", data=data, content_type="multipart/form-data"):
+            result, status = FileApi().post(_app_model(), _end_user())
+
+        assert status == 201
+        assert result["id"] == "file-1"
+        assert result["name"] == "test.txt"
+
+    @patch("controllers.web.files.FileService")
+    @patch("controllers.web.files.db")
+    def test_file_too_large_from_service(self, mock_db: MagicMock, mock_file_svc_cls: MagicMock, app: Flask) -> None:
+        import services.errors.file
+
+        mock_db.engine = "engine"
+        mock_file_svc_cls.return_value.upload_file.side_effect = services.errors.file.FileTooLargeError(
+            description="max 10MB"
+        )
+
+        data = {"file": (BytesIO(b"big"), "big.txt")}
+        with app.test_request_context("/files/upload", method="POST", data=data, content_type="multipart/form-data"):
+            with pytest.raises(FileTooLargeError):
+                FileApi().post(_app_model(), _end_user())

api/tests/unit_tests/controllers/web/test_message_endpoints.py

@@ -0,0 +1,156 @@
+"""Unit tests for controllers.web.message — feedback, more-like-this, suggested questions."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+from uuid import uuid4
+
+import pytest
+from flask import Flask
+from werkzeug.exceptions import NotFound
+
+from controllers.web.error import (
+    AppMoreLikeThisDisabledError,
+    NotChatAppError,
+    NotCompletionAppError,
+)
+from controllers.web.message import (
+    MessageFeedbackApi,
+    MessageMoreLikeThisApi,
+    MessageSuggestedQuestionApi,
+)
+from services.errors.app import MoreLikeThisDisabledError
+from services.errors.message import MessageNotExistsError
+
+
+def _chat_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="chat")
+
+
+def _completion_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="completion")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+# ---------------------------------------------------------------------------
+# MessageFeedbackApi
+# ---------------------------------------------------------------------------
+class TestMessageFeedbackApi:
+    @patch("controllers.web.message.MessageService.create_feedback")
+    @patch("controllers.web.message.web_ns")
+    def test_feedback_success(self, mock_ns: MagicMock, mock_create: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"rating": "like", "content": "great"}
+        msg_id = uuid4()
+
+        with app.test_request_context(f"/messages/{msg_id}/feedbacks", method="POST"):
+            result = MessageFeedbackApi().post(_chat_app(), _end_user(), msg_id)
+
+        assert result == {"result": "success"}
+        mock_create.assert_called_once()
+
+    @patch("controllers.web.message.MessageService.create_feedback")
+    @patch("controllers.web.message.web_ns")
+    def test_feedback_null_rating(self, mock_ns: MagicMock, mock_create: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"rating": None}
+        msg_id = uuid4()
+
+        with app.test_request_context(f"/messages/{msg_id}/feedbacks", method="POST"):
+            result = MessageFeedbackApi().post(_chat_app(), _end_user(), msg_id)
+
+        assert result == {"result": "success"}
+
+    @patch(
+        "controllers.web.message.MessageService.create_feedback",
+        side_effect=MessageNotExistsError(),
+    )
+    @patch("controllers.web.message.web_ns")
+    def test_feedback_message_not_found(self, mock_ns: MagicMock, mock_create: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"rating": "dislike"}
+        msg_id = uuid4()
+
+        with app.test_request_context(f"/messages/{msg_id}/feedbacks", method="POST"):
+            with pytest.raises(NotFound, match="Message Not Exists"):
+                MessageFeedbackApi().post(_chat_app(), _end_user(), msg_id)
+
+
+# ---------------------------------------------------------------------------
+# MessageMoreLikeThisApi
+# ---------------------------------------------------------------------------
+class TestMessageMoreLikeThisApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/messages/{msg_id}/more-like-this?response_mode=blocking"):
+            with pytest.raises(NotCompletionAppError):
+                MessageMoreLikeThisApi().get(_chat_app(), _end_user(), msg_id)
+
+    @patch("controllers.web.message.helper.compact_generate_response", return_value={"answer": "similar"})
+    @patch("controllers.web.message.AppGenerateService.generate_more_like_this")
+    def test_happy_path(self, mock_gen: MagicMock, mock_compact: MagicMock, app: Flask) -> None:
+        msg_id = uuid4()
+        mock_gen.return_value = "response"
+
+        with app.test_request_context(f"/messages/{msg_id}/more-like-this?response_mode=blocking"):
+            result = MessageMoreLikeThisApi().get(_completion_app(), _end_user(), msg_id)
+
+        assert result == {"answer": "similar"}
+
+    @patch(
+        "controllers.web.message.AppGenerateService.generate_more_like_this",
+        side_effect=MessageNotExistsError(),
+    )
+    def test_message_not_found(self, mock_gen: MagicMock, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/messages/{msg_id}/more-like-this?response_mode=blocking"):
+            with pytest.raises(NotFound, match="Message Not Exists"):
+                MessageMoreLikeThisApi().get(_completion_app(), _end_user(), msg_id)
+
+    @patch(
+        "controllers.web.message.AppGenerateService.generate_more_like_this",
+        side_effect=MoreLikeThisDisabledError(),
+    )
+    def test_feature_disabled(self, mock_gen: MagicMock, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/messages/{msg_id}/more-like-this?response_mode=blocking"):
+            with pytest.raises(AppMoreLikeThisDisabledError):
+                MessageMoreLikeThisApi().get(_completion_app(), _end_user(), msg_id)
+
+
+# ---------------------------------------------------------------------------
+# MessageSuggestedQuestionApi
+# ---------------------------------------------------------------------------
+class TestMessageSuggestedQuestionApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/messages/{msg_id}/suggested-questions"):
+            with pytest.raises(NotChatAppError):
+                MessageSuggestedQuestionApi().get(_completion_app(), _end_user(), msg_id)
+
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/messages/{msg_id}/suggested-questions"):
+            with pytest.raises(NotChatAppError):
+                MessageSuggestedQuestionApi().get(_completion_app(), _end_user(), msg_id)
+
+    @patch("controllers.web.message.MessageService.get_suggested_questions_after_answer")
+    def test_happy_path(self, mock_suggest: MagicMock, app: Flask) -> None:
+        msg_id = uuid4()
+        mock_suggest.return_value = ["What about X?", "Tell me more about Y."]
+
+        with app.test_request_context(f"/messages/{msg_id}/suggested-questions"):
+            result = MessageSuggestedQuestionApi().get(_chat_app(), _end_user(), msg_id)
+
+        assert result["data"] == ["What about X?", "Tell me more about Y."]
+
+    @patch(
+        "controllers.web.message.MessageService.get_suggested_questions_after_answer",
+        side_effect=MessageNotExistsError(),
+    )
+    def test_message_not_found(self, mock_suggest: MagicMock, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/messages/{msg_id}/suggested-questions"):
+            with pytest.raises(NotFound, match="Message not found"):
+                MessageSuggestedQuestionApi().get(_chat_app(), _end_user(), msg_id)

api/tests/unit_tests/controllers/web/test_passport.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+from werkzeug.exceptions import NotFound, Unauthorized
+
+from controllers.web.error import WebAppAuthRequiredError
+from controllers.web.passport import (
+    PassportService,
+    decode_enterprise_webapp_user_id,
+    exchange_token_for_existing_web_user,
+    generate_session_id,
+)
+from services.webapp_auth_service import WebAppAuthType
+
+
+def test_decode_enterprise_webapp_user_id_none() -> None:
+    assert decode_enterprise_webapp_user_id(None) is None
+
+
+def test_decode_enterprise_webapp_user_id_invalid_source(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(PassportService, "verify", lambda *_args, **_kwargs: {"token_source": "bad"})
+    with pytest.raises(Unauthorized):
+        decode_enterprise_webapp_user_id("token")
+
+
+def test_decode_enterprise_webapp_user_id_valid(monkeypatch: pytest.MonkeyPatch) -> None:
+    decoded = {"token_source": "webapp_login_token", "user_id": "u1"}
+    monkeypatch.setattr(PassportService, "verify", lambda *_args, **_kwargs: decoded)
+    assert decode_enterprise_webapp_user_id("token") == decoded
+
+
+def test_exchange_token_public_flow(monkeypatch: pytest.MonkeyPatch) -> None:
+    site = SimpleNamespace(id="s1", app_id="a1", code="code", status="normal")
+    app_model = SimpleNamespace(id="a1", status="normal", enable_site=True)
+
+    def _scalar_side_effect(*_args, **_kwargs):
+        if not hasattr(_scalar_side_effect, "calls"):
+            _scalar_side_effect.calls = 0
+        _scalar_side_effect.calls += 1
+        return site if _scalar_side_effect.calls == 1 else app_model
+
+    db_session = SimpleNamespace(scalar=_scalar_side_effect)
+    monkeypatch.setattr("controllers.web.passport.db", SimpleNamespace(session=db_session))
+    monkeypatch.setattr("controllers.web.passport._exchange_for_public_app_token", lambda *_args, **_kwargs: "resp")
+
+    decoded = {"auth_type": "public"}
+    result = exchange_token_for_existing_web_user("code", decoded, WebAppAuthType.PUBLIC)
+    assert result == "resp"
+
+
+def test_exchange_token_requires_external(monkeypatch: pytest.MonkeyPatch) -> None:
+    site = SimpleNamespace(id="s1", app_id="a1", code="code", status="normal")
+    app_model = SimpleNamespace(id="a1", status="normal", enable_site=True)
+
+    def _scalar_side_effect(*_args, **_kwargs):
+        if not hasattr(_scalar_side_effect, "calls"):
+            _scalar_side_effect.calls = 0
+        _scalar_side_effect.calls += 1
+        return site if _scalar_side_effect.calls == 1 else app_model
+
+    db_session = SimpleNamespace(scalar=_scalar_side_effect)
+    monkeypatch.setattr("controllers.web.passport.db", SimpleNamespace(session=db_session))
+
+    decoded = {"auth_type": "internal"}
+    with pytest.raises(WebAppAuthRequiredError):
+        exchange_token_for_existing_web_user("code", decoded, WebAppAuthType.EXTERNAL)
+
+
+def test_exchange_token_missing_session_id(monkeypatch: pytest.MonkeyPatch) -> None:
+    site = SimpleNamespace(id="s1", app_id="a1", code="code", status="normal")
+    app_model = SimpleNamespace(id="a1", status="normal", enable_site=True, tenant_id="t1")
+
+    def _scalar_side_effect(*_args, **_kwargs):
+        if not hasattr(_scalar_side_effect, "calls"):
+            _scalar_side_effect.calls = 0
+        _scalar_side_effect.calls += 1
+        if _scalar_side_effect.calls == 1:
+            return site
+        if _scalar_side_effect.calls == 2:
+            return app_model
+        return None
+
+    db_session = SimpleNamespace(scalar=_scalar_side_effect, add=lambda *_a, **_k: None, commit=lambda: None)
+    monkeypatch.setattr("controllers.web.passport.db", SimpleNamespace(session=db_session))
+
+    decoded = {"auth_type": "internal"}
+    with pytest.raises(NotFound):
+        exchange_token_for_existing_web_user("code", decoded, WebAppAuthType.INTERNAL)
+
+
+def test_generate_session_id(monkeypatch: pytest.MonkeyPatch) -> None:
+    counts = [1, 0]
+
+    def _scalar(*_args, **_kwargs):
+        return counts.pop(0)
+
+    db_session = SimpleNamespace(scalar=_scalar)
+    monkeypatch.setattr("controllers.web.passport.db", SimpleNamespace(session=db_session))
+
+    session_id = generate_session_id()
+    assert session_id

api/tests/unit_tests/controllers/web/test_pydantic_models.py

@@ -0,0 +1,423 @@
+"""Unit tests for Pydantic models defined in controllers.web modules.
+
+Covers validation logic, field defaults, constraints, and custom validators
+for all ~15 Pydantic models across the web controller layer.
+"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+import pytest
+from pydantic import ValidationError
+
+# ---------------------------------------------------------------------------
+# app.py models
+# ---------------------------------------------------------------------------
+from controllers.web.app import AppAccessModeQuery
+
+
+class TestAppAccessModeQuery:
+    def test_alias_resolution(self) -> None:
+        q = AppAccessModeQuery.model_validate({"appId": "abc", "appCode": "xyz"})
+        assert q.app_id == "abc"
+        assert q.app_code == "xyz"
+
+    def test_defaults_to_none(self) -> None:
+        q = AppAccessModeQuery.model_validate({})
+        assert q.app_id is None
+        assert q.app_code is None
+
+    def test_accepts_snake_case(self) -> None:
+        q = AppAccessModeQuery(app_id="id1", app_code="code1")
+        assert q.app_id == "id1"
+        assert q.app_code == "code1"
+
+
+# ---------------------------------------------------------------------------
+# audio.py models
+# ---------------------------------------------------------------------------
+from controllers.web.audio import TextToAudioPayload
+
+
+class TestTextToAudioPayload:
+    def test_defaults(self) -> None:
+        p = TextToAudioPayload.model_validate({})
+        assert p.message_id is None
+        assert p.voice is None
+        assert p.text is None
+        assert p.streaming is None
+
+    def test_valid_uuid_message_id(self) -> None:
+        uid = str(uuid4())
+        p = TextToAudioPayload(message_id=uid)
+        assert p.message_id == uid
+
+    def test_none_message_id_passthrough(self) -> None:
+        p = TextToAudioPayload(message_id=None)
+        assert p.message_id is None
+
+    def test_invalid_uuid_message_id(self) -> None:
+        with pytest.raises(ValidationError, match="not a valid uuid"):
+            TextToAudioPayload(message_id="not-a-uuid")
+
+
+# ---------------------------------------------------------------------------
+# completion.py models
+# ---------------------------------------------------------------------------
+from controllers.web.completion import ChatMessagePayload, CompletionMessagePayload
+
+
+class TestCompletionMessagePayload:
+    def test_defaults(self) -> None:
+        p = CompletionMessagePayload(inputs={})
+        assert p.query == ""
+        assert p.files is None
+        assert p.response_mode is None
+        assert p.retriever_from == "web_app"
+
+    def test_accepts_full_payload(self) -> None:
+        p = CompletionMessagePayload(
+            inputs={"key": "val"},
+            query="test",
+            files=[{"id": "f1"}],
+            response_mode="streaming",
+        )
+        assert p.response_mode == "streaming"
+        assert p.files == [{"id": "f1"}]
+
+    def test_invalid_response_mode(self) -> None:
+        with pytest.raises(ValidationError):
+            CompletionMessagePayload(inputs={}, response_mode="invalid")
+
+
+class TestChatMessagePayload:
+    def test_valid_uuid_fields(self) -> None:
+        cid = str(uuid4())
+        pid = str(uuid4())
+        p = ChatMessagePayload(inputs={}, query="hi", conversation_id=cid, parent_message_id=pid)
+        assert p.conversation_id == cid
+        assert p.parent_message_id == pid
+
+    def test_none_uuid_fields(self) -> None:
+        p = ChatMessagePayload(inputs={}, query="hi")
+        assert p.conversation_id is None
+        assert p.parent_message_id is None
+
+    def test_invalid_conversation_id(self) -> None:
+        with pytest.raises(ValidationError, match="not a valid uuid"):
+            ChatMessagePayload(inputs={}, query="hi", conversation_id="bad")
+
+    def test_invalid_parent_message_id(self) -> None:
+        with pytest.raises(ValidationError, match="not a valid uuid"):
+            ChatMessagePayload(inputs={}, query="hi", parent_message_id="bad")
+
+    def test_query_required(self) -> None:
+        with pytest.raises(ValidationError):
+            ChatMessagePayload(inputs={})
+
+
+# ---------------------------------------------------------------------------
+# conversation.py models
+# ---------------------------------------------------------------------------
+from controllers.web.conversation import ConversationListQuery, ConversationRenamePayload
+
+
+class TestConversationListQuery:
+    def test_defaults(self) -> None:
+        q = ConversationListQuery()
+        assert q.last_id is None
+        assert q.limit == 20
+        assert q.pinned is None
+        assert q.sort_by == "-updated_at"
+
+    def test_limit_lower_bound(self) -> None:
+        with pytest.raises(ValidationError):
+            ConversationListQuery(limit=0)
+
+    def test_limit_upper_bound(self) -> None:
+        with pytest.raises(ValidationError):
+            ConversationListQuery(limit=101)
+
+    def test_limit_boundaries_valid(self) -> None:
+        assert ConversationListQuery(limit=1).limit == 1
+        assert ConversationListQuery(limit=100).limit == 100
+
+    def test_valid_sort_by_options(self) -> None:
+        for opt in ("created_at", "-created_at", "updated_at", "-updated_at"):
+            assert ConversationListQuery(sort_by=opt).sort_by == opt
+
+    def test_invalid_sort_by(self) -> None:
+        with pytest.raises(ValidationError):
+            ConversationListQuery(sort_by="invalid")
+
+    def test_valid_last_id(self) -> None:
+        uid = str(uuid4())
+        assert ConversationListQuery(last_id=uid).last_id == uid
+
+    def test_invalid_last_id(self) -> None:
+        with pytest.raises(ValidationError, match="not a valid uuid"):
+            ConversationListQuery(last_id="not-uuid")
+
+
+class TestConversationRenamePayload:
+    def test_auto_generate_true_no_name_required(self) -> None:
+        p = ConversationRenamePayload(auto_generate=True)
+        assert p.name is None
+
+    def test_auto_generate_false_requires_name(self) -> None:
+        with pytest.raises(ValidationError, match="name is required"):
+            ConversationRenamePayload(auto_generate=False)
+
+    def test_auto_generate_false_blank_name_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="name is required"):
+            ConversationRenamePayload(auto_generate=False, name="   ")
+
+    def test_auto_generate_false_with_valid_name(self) -> None:
+        p = ConversationRenamePayload(auto_generate=False, name="My Chat")
+        assert p.name == "My Chat"
+
+    def test_defaults(self) -> None:
+        p = ConversationRenamePayload(name="test")
+        assert p.auto_generate is False
+        assert p.name == "test"
+
+
+# ---------------------------------------------------------------------------
+# message.py models
+# ---------------------------------------------------------------------------
+from controllers.web.message import MessageFeedbackPayload, MessageListQuery, MessageMoreLikeThisQuery
+
+
+class TestMessageListQuery:
+    def test_valid_query(self) -> None:
+        cid = str(uuid4())
+        q = MessageListQuery(conversation_id=cid)
+        assert q.conversation_id == cid
+        assert q.first_id is None
+        assert q.limit == 20
+
+    def test_invalid_conversation_id(self) -> None:
+        with pytest.raises(ValidationError, match="not a valid uuid"):
+            MessageListQuery(conversation_id="bad")
+
+    def test_limit_bounds(self) -> None:
+        cid = str(uuid4())
+        with pytest.raises(ValidationError):
+            MessageListQuery(conversation_id=cid, limit=0)
+        with pytest.raises(ValidationError):
+            MessageListQuery(conversation_id=cid, limit=101)
+
+    def test_valid_first_id(self) -> None:
+        cid = str(uuid4())
+        fid = str(uuid4())
+        q = MessageListQuery(conversation_id=cid, first_id=fid)
+        assert q.first_id == fid
+
+    def test_invalid_first_id(self) -> None:
+        cid = str(uuid4())
+        with pytest.raises(ValidationError, match="not a valid uuid"):
+            MessageListQuery(conversation_id=cid, first_id="invalid")
+
+
+class TestMessageFeedbackPayload:
+    def test_defaults(self) -> None:
+        p = MessageFeedbackPayload()
+        assert p.rating is None
+        assert p.content is None
+
+    def test_valid_ratings(self) -> None:
+        assert MessageFeedbackPayload(rating="like").rating == "like"
+        assert MessageFeedbackPayload(rating="dislike").rating == "dislike"
+
+    def test_invalid_rating(self) -> None:
+        with pytest.raises(ValidationError):
+            MessageFeedbackPayload(rating="neutral")
+
+
+class TestMessageMoreLikeThisQuery:
+    def test_valid_modes(self) -> None:
+        assert MessageMoreLikeThisQuery(response_mode="blocking").response_mode == "blocking"
+        assert MessageMoreLikeThisQuery(response_mode="streaming").response_mode == "streaming"
+
+    def test_invalid_mode(self) -> None:
+        with pytest.raises(ValidationError):
+            MessageMoreLikeThisQuery(response_mode="invalid")
+
+    def test_required(self) -> None:
+        with pytest.raises(ValidationError):
+            MessageMoreLikeThisQuery()
+
+
+# ---------------------------------------------------------------------------
+# remote_files.py models
+# ---------------------------------------------------------------------------
+from controllers.web.remote_files import RemoteFileUploadPayload
+
+
+class TestRemoteFileUploadPayload:
+    def test_valid_url(self) -> None:
+        p = RemoteFileUploadPayload(url="https://example.com/file.pdf")
+        assert str(p.url) == "https://example.com/file.pdf"
+
+    def test_invalid_url(self) -> None:
+        with pytest.raises(ValidationError):
+            RemoteFileUploadPayload(url="not-a-url")
+
+    def test_url_required(self) -> None:
+        with pytest.raises(ValidationError):
+            RemoteFileUploadPayload()
+
+
+# ---------------------------------------------------------------------------
+# saved_message.py models
+# ---------------------------------------------------------------------------
+from controllers.web.saved_message import SavedMessageCreatePayload, SavedMessageListQuery
+
+
+class TestSavedMessageListQuery:
+    def test_defaults(self) -> None:
+        q = SavedMessageListQuery()
+        assert q.last_id is None
+        assert q.limit == 20
+
+    def test_limit_bounds(self) -> None:
+        with pytest.raises(ValidationError):
+            SavedMessageListQuery(limit=0)
+        with pytest.raises(ValidationError):
+            SavedMessageListQuery(limit=101)
+
+    def test_valid_last_id(self) -> None:
+        uid = str(uuid4())
+        q = SavedMessageListQuery(last_id=uid)
+        assert q.last_id == uid
+
+    def test_empty_last_id(self) -> None:
+        q = SavedMessageListQuery(last_id="")
+        assert q.last_id == ""
+
+
+class TestSavedMessageCreatePayload:
+    def test_valid_message_id(self) -> None:
+        uid = str(uuid4())
+        p = SavedMessageCreatePayload(message_id=uid)
+        assert p.message_id == uid
+
+    def test_required(self) -> None:
+        with pytest.raises(ValidationError):
+            SavedMessageCreatePayload()
+
+
+# ---------------------------------------------------------------------------
+# workflow.py models
+# ---------------------------------------------------------------------------
+from controllers.web.workflow import WorkflowRunPayload
+
+
+class TestWorkflowRunPayload:
+    def test_defaults(self) -> None:
+        p = WorkflowRunPayload(inputs={})
+        assert p.inputs == {}
+        assert p.files is None
+
+    def test_with_files(self) -> None:
+        p = WorkflowRunPayload(inputs={"k": "v"}, files=[{"id": "f1"}])
+        assert p.files == [{"id": "f1"}]
+
+    def test_inputs_required(self) -> None:
+        with pytest.raises(ValidationError):
+            WorkflowRunPayload()
+
+
+# ---------------------------------------------------------------------------
+# forgot_password.py models
+# ---------------------------------------------------------------------------
+from controllers.web.forgot_password import (
+    ForgotPasswordCheckPayload,
+    ForgotPasswordResetPayload,
+    ForgotPasswordSendPayload,
+)
+
+
+class TestForgotPasswordSendPayload:
+    def test_valid_email(self) -> None:
+        p = ForgotPasswordSendPayload(email="user@example.com")
+        assert p.email == "user@example.com"
+
+    def test_invalid_email(self) -> None:
+        with pytest.raises(ValidationError, match="not a valid email"):
+            ForgotPasswordSendPayload(email="not-an-email")
+
+    def test_language_optional(self) -> None:
+        p = ForgotPasswordSendPayload(email="a@b.com")
+        assert p.language is None
+
+
+class TestForgotPasswordCheckPayload:
+    def test_valid(self) -> None:
+        p = ForgotPasswordCheckPayload(email="a@b.com", code="1234", token="tok")
+        assert p.email == "a@b.com"
+        assert p.code == "1234"
+        assert p.token == "tok"
+
+    def test_empty_token_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            ForgotPasswordCheckPayload(email="a@b.com", code="1234", token="")
+
+
+class TestForgotPasswordResetPayload:
+    def test_valid_passwords(self) -> None:
+        p = ForgotPasswordResetPayload(token="tok", new_password="Valid1234", password_confirm="Valid1234")
+        assert p.new_password == "Valid1234"
+
+    def test_weak_password_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="Password must contain"):
+            ForgotPasswordResetPayload(token="tok", new_password="short", password_confirm="short")
+
+    def test_letters_only_password_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="Password must contain"):
+            ForgotPasswordResetPayload(token="tok", new_password="abcdefghi", password_confirm="abcdefghi")
+
+    def test_digits_only_password_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="Password must contain"):
+            ForgotPasswordResetPayload(token="tok", new_password="123456789", password_confirm="123456789")
+
+
+# ---------------------------------------------------------------------------
+# login.py models
+# ---------------------------------------------------------------------------
+from controllers.web.login import EmailCodeLoginSendPayload, EmailCodeLoginVerifyPayload, LoginPayload
+
+
+class TestLoginPayload:
+    def test_valid(self) -> None:
+        p = LoginPayload(email="a@b.com", password="Valid1234")
+        assert p.email == "a@b.com"
+
+    def test_invalid_email(self) -> None:
+        with pytest.raises(ValidationError, match="not a valid email"):
+            LoginPayload(email="bad", password="Valid1234")
+
+    def test_weak_password(self) -> None:
+        with pytest.raises(ValidationError, match="Password must contain"):
+            LoginPayload(email="a@b.com", password="weak")
+
+
+class TestEmailCodeLoginSendPayload:
+    def test_valid(self) -> None:
+        p = EmailCodeLoginSendPayload(email="a@b.com")
+        assert p.language is None
+
+    def test_with_language(self) -> None:
+        p = EmailCodeLoginSendPayload(email="a@b.com", language="zh-Hans")
+        assert p.language == "zh-Hans"
+
+
+class TestEmailCodeLoginVerifyPayload:
+    def test_valid(self) -> None:
+        p = EmailCodeLoginVerifyPayload(email="a@b.com", code="1234", token="tok")
+        assert p.code == "1234"
+
+    def test_empty_token_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            EmailCodeLoginVerifyPayload(email="a@b.com", code="1234", token="")

api/tests/unit_tests/controllers/web/test_remote_files.py

@@ -0,0 +1,147 @@
+"""Unit tests for controllers.web.remote_files endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+from controllers.common.errors import FileTooLargeError, RemoteFileUploadError
+from controllers.web.remote_files import RemoteFileInfoApi, RemoteFileUploadApi
+
+
+def _app_model() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+# ---------------------------------------------------------------------------
+# RemoteFileInfoApi
+# ---------------------------------------------------------------------------
+class TestRemoteFileInfoApi:
+    @patch("controllers.web.remote_files.ssrf_proxy")
+    def test_head_success(self, mock_proxy: MagicMock, app: Flask) -> None:
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.headers = {"Content-Type": "application/pdf", "Content-Length": "1024"}
+        mock_proxy.head.return_value = mock_resp
+
+        with app.test_request_context("/remote-files/https%3A%2F%2Fexample.com%2Ffile.pdf"):
+            result = RemoteFileInfoApi().get(_app_model(), _end_user(), "https%3A%2F%2Fexample.com%2Ffile.pdf")
+
+        assert result["file_type"] == "application/pdf"
+        assert result["file_length"] == 1024
+
+    @patch("controllers.web.remote_files.ssrf_proxy")
+    def test_fallback_to_get(self, mock_proxy: MagicMock, app: Flask) -> None:
+        head_resp = MagicMock()
+        head_resp.status_code = 405  # Method not allowed
+        get_resp = MagicMock()
+        get_resp.status_code = 200
+        get_resp.headers = {"Content-Type": "text/plain", "Content-Length": "42"}
+        get_resp.raise_for_status = MagicMock()
+        mock_proxy.head.return_value = head_resp
+        mock_proxy.get.return_value = get_resp
+
+        with app.test_request_context("/remote-files/https%3A%2F%2Fexample.com%2Ffile.txt"):
+            result = RemoteFileInfoApi().get(_app_model(), _end_user(), "https%3A%2F%2Fexample.com%2Ffile.txt")
+
+        assert result["file_type"] == "text/plain"
+        mock_proxy.get.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# RemoteFileUploadApi
+# ---------------------------------------------------------------------------
+class TestRemoteFileUploadApi:
+    @patch("controllers.web.remote_files.file_helpers.get_signed_file_url", return_value="https://signed-url")
+    @patch("controllers.web.remote_files.FileService")
+    @patch("controllers.web.remote_files.helpers.guess_file_info_from_response")
+    @patch("controllers.web.remote_files.ssrf_proxy")
+    @patch("controllers.web.remote_files.web_ns")
+    @patch("controllers.web.remote_files.db")
+    def test_upload_success(
+        self,
+        mock_db: MagicMock,
+        mock_ns: MagicMock,
+        mock_proxy: MagicMock,
+        mock_guess: MagicMock,
+        mock_file_svc_cls: MagicMock,
+        mock_signed: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_db.engine = "engine"
+        mock_ns.payload = {"url": "https://example.com/file.pdf"}
+        head_resp = MagicMock()
+        head_resp.status_code = 200
+        head_resp.content = b"pdf-content"
+        head_resp.request.method = "HEAD"
+        mock_proxy.head.return_value = head_resp
+        get_resp = MagicMock()
+        get_resp.content = b"pdf-content"
+        mock_proxy.get.return_value = get_resp
+
+        mock_guess.return_value = SimpleNamespace(
+            filename="file.pdf", extension="pdf", mimetype="application/pdf", size=100
+        )
+        mock_file_svc_cls.is_file_size_within_limit.return_value = True
+
+        from datetime import datetime
+
+        upload_file = SimpleNamespace(
+            id="f-1",
+            name="file.pdf",
+            size=100,
+            extension="pdf",
+            mime_type="application/pdf",
+            created_by="eu-1",
+            created_at=datetime(2024, 1, 1),
+        )
+        mock_file_svc_cls.return_value.upload_file.return_value = upload_file
+
+        with app.test_request_context("/remote-files/upload", method="POST"):
+            result, status = RemoteFileUploadApi().post(_app_model(), _end_user())
+
+        assert status == 201
+        assert result["id"] == "f-1"
+
+    @patch("controllers.web.remote_files.FileService.is_file_size_within_limit", return_value=False)
+    @patch("controllers.web.remote_files.helpers.guess_file_info_from_response")
+    @patch("controllers.web.remote_files.ssrf_proxy")
+    @patch("controllers.web.remote_files.web_ns")
+    def test_file_too_large(
+        self,
+        mock_ns: MagicMock,
+        mock_proxy: MagicMock,
+        mock_guess: MagicMock,
+        mock_size_check: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_ns.payload = {"url": "https://example.com/big.zip"}
+        head_resp = MagicMock()
+        head_resp.status_code = 200
+        mock_proxy.head.return_value = head_resp
+        mock_guess.return_value = SimpleNamespace(
+            filename="big.zip", extension="zip", mimetype="application/zip", size=999999999
+        )
+
+        with app.test_request_context("/remote-files/upload", method="POST"):
+            with pytest.raises(FileTooLargeError):
+                RemoteFileUploadApi().post(_app_model(), _end_user())
+
+    @patch("controllers.web.remote_files.ssrf_proxy")
+    @patch("controllers.web.remote_files.web_ns")
+    def test_fetch_failure_raises(self, mock_ns: MagicMock, mock_proxy: MagicMock, app: Flask) -> None:
+        import httpx
+
+        mock_ns.payload = {"url": "https://example.com/bad"}
+        mock_proxy.head.side_effect = httpx.RequestError("connection failed")
+
+        with app.test_request_context("/remote-files/upload", method="POST"):
+            with pytest.raises(RemoteFileUploadError):
+                RemoteFileUploadApi().post(_app_model(), _end_user())

api/tests/unit_tests/controllers/web/test_saved_message.py

@@ -0,0 +1,97 @@
+"""Unit tests for controllers.web.saved_message endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+from uuid import uuid4
+
+import pytest
+from flask import Flask
+from werkzeug.exceptions import NotFound
+
+from controllers.web.error import NotCompletionAppError
+from controllers.web.saved_message import SavedMessageApi, SavedMessageListApi
+from services.errors.message import MessageNotExistsError
+
+
+def _completion_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="completion")
+
+
+def _chat_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="chat")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+# ---------------------------------------------------------------------------
+# SavedMessageListApi (GET)
+# ---------------------------------------------------------------------------
+class TestSavedMessageListApiGet:
+    def test_non_completion_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/saved-messages"):
+            with pytest.raises(NotCompletionAppError):
+                SavedMessageListApi().get(_chat_app(), _end_user())
+
+    @patch("controllers.web.saved_message.SavedMessageService.pagination_by_last_id")
+    def test_happy_path(self, mock_paginate: MagicMock, app: Flask) -> None:
+        mock_paginate.return_value = SimpleNamespace(limit=20, has_more=False, data=[])
+
+        with app.test_request_context("/saved-messages?limit=20"):
+            result = SavedMessageListApi().get(_completion_app(), _end_user())
+
+        assert result["limit"] == 20
+        assert result["has_more"] is False
+
+
+# ---------------------------------------------------------------------------
+# SavedMessageListApi (POST)
+# ---------------------------------------------------------------------------
+class TestSavedMessageListApiPost:
+    def test_non_completion_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/saved-messages", method="POST"):
+            with pytest.raises(NotCompletionAppError):
+                SavedMessageListApi().post(_chat_app(), _end_user())
+
+    @patch("controllers.web.saved_message.SavedMessageService.save")
+    @patch("controllers.web.saved_message.web_ns")
+    def test_save_success(self, mock_ns: MagicMock, mock_save: MagicMock, app: Flask) -> None:
+        msg_id = str(uuid4())
+        mock_ns.payload = {"message_id": msg_id}
+
+        with app.test_request_context("/saved-messages", method="POST"):
+            result = SavedMessageListApi().post(_completion_app(), _end_user())
+
+        assert result["result"] == "success"
+
+    @patch("controllers.web.saved_message.SavedMessageService.save", side_effect=MessageNotExistsError())
+    @patch("controllers.web.saved_message.web_ns")
+    def test_save_not_found(self, mock_ns: MagicMock, mock_save: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"message_id": str(uuid4())}
+
+        with app.test_request_context("/saved-messages", method="POST"):
+            with pytest.raises(NotFound, match="Message Not Exists"):
+                SavedMessageListApi().post(_completion_app(), _end_user())
+
+
+# ---------------------------------------------------------------------------
+# SavedMessageApi (DELETE)
+# ---------------------------------------------------------------------------
+class TestSavedMessageApi:
+    def test_non_completion_mode_raises(self, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/saved-messages/{msg_id}", method="DELETE"):
+            with pytest.raises(NotCompletionAppError):
+                SavedMessageApi().delete(_chat_app(), _end_user(), msg_id)
+
+    @patch("controllers.web.saved_message.SavedMessageService.delete")
+    def test_delete_success(self, mock_delete: MagicMock, app: Flask) -> None:
+        msg_id = uuid4()
+        with app.test_request_context(f"/saved-messages/{msg_id}", method="DELETE"):
+            result, status = SavedMessageApi().delete(_completion_app(), _end_user(), msg_id)
+
+        assert status == 204
+        assert result["result"] == "success"

api/tests/unit_tests/controllers/web/test_site.py

@@ -0,0 +1,126 @@
+"""Unit tests for controllers.web.site endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+from werkzeug.exceptions import Forbidden
+
+from controllers.web.site import AppSiteApi, AppSiteInfo
+
+
+def _tenant(*, status: str = "normal") -> SimpleNamespace:
+    return SimpleNamespace(
+        id="tenant-1",
+        status=status,
+        plan="basic",
+        custom_config_dict={"remove_webapp_brand": False, "replace_webapp_logo": False},
+    )
+
+
+def _site() -> SimpleNamespace:
+    return SimpleNamespace(
+        title="Site",
+        icon_type="emoji",
+        icon="robot",
+        icon_background="#fff",
+        description="desc",
+        default_language="en",
+        chat_color_theme="light",
+        chat_color_theme_inverted=False,
+        copyright=None,
+        privacy_policy=None,
+        custom_disclaimer=None,
+        prompt_public=False,
+        show_workflow_steps=True,
+        use_icon_as_answer_icon=False,
+    )
+
+
+# ---------------------------------------------------------------------------
+# AppSiteApi
+# ---------------------------------------------------------------------------
+class TestAppSiteApi:
+    @patch("controllers.web.site.FeatureService.get_features")
+    @patch("controllers.web.site.db")
+    def test_happy_path(self, mock_db: MagicMock, mock_features: MagicMock, app: Flask) -> None:
+        app.config["RESTX_MASK_HEADER"] = "X-Fields"
+        mock_features.return_value = SimpleNamespace(can_replace_logo=False)
+        site_obj = _site()
+        mock_db.session.query.return_value.where.return_value.first.return_value = site_obj
+        tenant = _tenant()
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1", tenant=tenant, enable_site=True)
+        end_user = SimpleNamespace(id="eu-1")
+
+        with app.test_request_context("/site"):
+            result = AppSiteApi().get(app_model, end_user)
+
+        # marshal_with serializes AppSiteInfo to a dict
+        assert result["app_id"] == "app-1"
+        assert result["plan"] == "basic"
+        assert result["enable_site"] is True
+
+    @patch("controllers.web.site.db")
+    def test_missing_site_raises_forbidden(self, mock_db: MagicMock, app: Flask) -> None:
+        app.config["RESTX_MASK_HEADER"] = "X-Fields"
+        mock_db.session.query.return_value.where.return_value.first.return_value = None
+        tenant = _tenant()
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1", tenant=tenant)
+        end_user = SimpleNamespace(id="eu-1")
+
+        with app.test_request_context("/site"):
+            with pytest.raises(Forbidden):
+                AppSiteApi().get(app_model, end_user)
+
+    @patch("controllers.web.site.db")
+    def test_archived_tenant_raises_forbidden(self, mock_db: MagicMock, app: Flask) -> None:
+        app.config["RESTX_MASK_HEADER"] = "X-Fields"
+        from models.account import TenantStatus
+
+        mock_db.session.query.return_value.where.return_value.first.return_value = _site()
+        tenant = SimpleNamespace(
+            id="tenant-1",
+            status=TenantStatus.ARCHIVE,
+            plan="basic",
+            custom_config_dict={},
+        )
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1", tenant=tenant)
+        end_user = SimpleNamespace(id="eu-1")
+
+        with app.test_request_context("/site"):
+            with pytest.raises(Forbidden):
+                AppSiteApi().get(app_model, end_user)
+
+
+# ---------------------------------------------------------------------------
+# AppSiteInfo
+# ---------------------------------------------------------------------------
+class TestAppSiteInfo:
+    def test_basic_fields(self) -> None:
+        tenant = _tenant()
+        site_obj = _site()
+        info = AppSiteInfo(tenant, SimpleNamespace(id="app-1", enable_site=True), site_obj, "eu-1", False)
+
+        assert info.app_id == "app-1"
+        assert info.end_user_id == "eu-1"
+        assert info.enable_site is True
+        assert info.plan == "basic"
+        assert info.can_replace_logo is False
+        assert info.model_config is None
+
+    @patch("controllers.web.site.dify_config", SimpleNamespace(FILES_URL="https://files.example.com"))
+    def test_can_replace_logo_sets_custom_config(self) -> None:
+        tenant = SimpleNamespace(
+            id="tenant-1",
+            plan="pro",
+            custom_config_dict={"remove_webapp_brand": True, "replace_webapp_logo": True},
+        )
+        site_obj = _site()
+        info = AppSiteInfo(tenant, SimpleNamespace(id="app-1", enable_site=True), site_obj, "eu-1", True)
+
+        assert info.can_replace_logo is True
+        assert info.custom_config["remove_webapp_brand"] is True
+        assert "webapp-logo" in info.custom_config["replace_webapp_logo"]

api/tests/unit_tests/controllers/web/test_web_login.py

@@ -5,7 +5,8 @@ from unittest.mock import MagicMock, patch
 import pytest
 from flask import Flask
 
-from controllers.web.login import EmailCodeLoginApi, EmailCodeLoginSendEmailApi
+import services.errors.account
+from controllers.web.login import EmailCodeLoginApi, EmailCodeLoginSendEmailApi, LoginApi, LoginStatusApi, LogoutApi
 
 
 def encode_code(code: str) -> str:
@@ -89,3 +90,114 @@ class TestEmailCodeLoginApi:
         mock_revoke_token.assert_called_once_with("token-123")
         mock_login.assert_called_once()
         mock_reset_login_rate.assert_called_once_with("user@example.com")
+
+
+class TestLoginApi:
+    @patch("controllers.web.login.WebAppAuthService.login", return_value="access-tok")
+    @patch("controllers.web.login.WebAppAuthService.authenticate")
+    def test_login_success(self, mock_auth: MagicMock, mock_login: MagicMock, app: Flask) -> None:
+        mock_auth.return_value = MagicMock()
+
+        with app.test_request_context(
+            "/web/login",
+            method="POST",
+            json={"email": "user@example.com", "password": base64.b64encode(b"Valid1234").decode()},
+        ):
+            response = LoginApi().post()
+
+        assert response.get_json()["data"]["access_token"] == "access-tok"
+        mock_auth.assert_called_once()
+
+    @patch(
+        "controllers.web.login.WebAppAuthService.authenticate",
+        side_effect=services.errors.account.AccountLoginError(),
+    )
+    def test_login_banned_account(self, mock_auth: MagicMock, app: Flask) -> None:
+        from controllers.console.error import AccountBannedError
+
+        with app.test_request_context(
+            "/web/login",
+            method="POST",
+            json={"email": "user@example.com", "password": base64.b64encode(b"Valid1234").decode()},
+        ):
+            with pytest.raises(AccountBannedError):
+                LoginApi().post()
+
+    @patch(
+        "controllers.web.login.WebAppAuthService.authenticate",
+        side_effect=services.errors.account.AccountPasswordError(),
+    )
+    def test_login_wrong_password(self, mock_auth: MagicMock, app: Flask) -> None:
+        from controllers.console.auth.error import AuthenticationFailedError
+
+        with app.test_request_context(
+            "/web/login",
+            method="POST",
+            json={"email": "user@example.com", "password": base64.b64encode(b"Valid1234").decode()},
+        ):
+            with pytest.raises(AuthenticationFailedError):
+                LoginApi().post()
+
+
+class TestLoginStatusApi:
+    @patch("controllers.web.login.extract_webapp_access_token", return_value=None)
+    def test_no_app_code_returns_logged_in_false(self, mock_extract: MagicMock, app: Flask) -> None:
+        with app.test_request_context("/web/login/status"):
+            result = LoginStatusApi().get()
+
+        assert result["logged_in"] is False
+        assert result["app_logged_in"] is False
+
+    @patch("controllers.web.login.decode_jwt_token")
+    @patch("controllers.web.login.PassportService")
+    @patch("controllers.web.login.WebAppAuthService.is_app_require_permission_check", return_value=False)
+    @patch("controllers.web.login.AppService.get_app_id_by_code", return_value="app-1")
+    @patch("controllers.web.login.extract_webapp_access_token", return_value="tok")
+    def test_public_app_user_logged_in(
+        self,
+        mock_extract: MagicMock,
+        mock_app_id: MagicMock,
+        mock_perm: MagicMock,
+        mock_passport: MagicMock,
+        mock_decode: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_decode.return_value = (MagicMock(), MagicMock())
+
+        with app.test_request_context("/web/login/status?app_code=code1"):
+            result = LoginStatusApi().get()
+
+        assert result["logged_in"] is True
+        assert result["app_logged_in"] is True
+
+    @patch("controllers.web.login.decode_jwt_token", side_effect=Exception("bad"))
+    @patch("controllers.web.login.PassportService")
+    @patch("controllers.web.login.WebAppAuthService.is_app_require_permission_check", return_value=True)
+    @patch("controllers.web.login.AppService.get_app_id_by_code", return_value="app-1")
+    @patch("controllers.web.login.extract_webapp_access_token", return_value="tok")
+    def test_private_app_passport_fails(
+        self,
+        mock_extract: MagicMock,
+        mock_app_id: MagicMock,
+        mock_perm: MagicMock,
+        mock_passport_cls: MagicMock,
+        mock_decode: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_passport_cls.return_value.verify.side_effect = Exception("bad")
+
+        with app.test_request_context("/web/login/status?app_code=code1"):
+            result = LoginStatusApi().get()
+
+        assert result["logged_in"] is False
+        assert result["app_logged_in"] is False
+
+
+class TestLogoutApi:
+    @patch("controllers.web.login.clear_webapp_access_token_from_cookie")
+    def test_logout_success(self, mock_clear: MagicMock, app: Flask) -> None:
+        with app.test_request_context("/web/logout", method="POST"):
+            response = LogoutApi().post()
+
+        assert response.get_json() == {"result": "success"}
+        mock_clear.assert_called_once()

api/tests/unit_tests/controllers/web/test_web_passport.py

@@ -0,0 +1,192 @@
+"""Unit tests for controllers.web.passport — token issuance and enterprise auth exchange."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+from werkzeug.exceptions import NotFound, Unauthorized
+
+from controllers.web.error import WebAppAuthRequiredError
+from controllers.web.passport import (
+    PassportResource,
+    decode_enterprise_webapp_user_id,
+    exchange_token_for_existing_web_user,
+    generate_session_id,
+)
+from services.webapp_auth_service import WebAppAuthType
+
+
+# ---------------------------------------------------------------------------
+# decode_enterprise_webapp_user_id
+# ---------------------------------------------------------------------------
+class TestDecodeEnterpriseWebappUserId:
+    def test_none_token_returns_none(self) -> None:
+        assert decode_enterprise_webapp_user_id(None) is None
+
+    @patch("controllers.web.passport.PassportService")
+    def test_valid_token_returns_decoded(self, mock_passport_cls: MagicMock) -> None:
+        mock_passport_cls.return_value.verify.return_value = {
+            "token_source": "webapp_login_token",
+            "user_id": "u1",
+        }
+        result = decode_enterprise_webapp_user_id("valid-jwt")
+        assert result["user_id"] == "u1"
+
+    @patch("controllers.web.passport.PassportService")
+    def test_wrong_source_raises_unauthorized(self, mock_passport_cls: MagicMock) -> None:
+        mock_passport_cls.return_value.verify.return_value = {
+            "token_source": "other_source",
+        }
+        with pytest.raises(Unauthorized, match="Expected 'webapp_login_token'"):
+            decode_enterprise_webapp_user_id("bad-jwt")
+
+    @patch("controllers.web.passport.PassportService")
+    def test_missing_source_raises_unauthorized(self, mock_passport_cls: MagicMock) -> None:
+        mock_passport_cls.return_value.verify.return_value = {}
+        with pytest.raises(Unauthorized, match="Expected 'webapp_login_token'"):
+            decode_enterprise_webapp_user_id("no-source-jwt")
+
+
+# ---------------------------------------------------------------------------
+# generate_session_id
+# ---------------------------------------------------------------------------
+class TestGenerateSessionId:
+    @patch("controllers.web.passport.db")
+    def test_returns_unique_session_id(self, mock_db: MagicMock) -> None:
+        mock_db.session.scalar.return_value = 0
+        sid = generate_session_id()
+        assert isinstance(sid, str)
+        assert len(sid) == 36  # UUID format
+
+    @patch("controllers.web.passport.db")
+    def test_retries_on_collision(self, mock_db: MagicMock) -> None:
+        # First call returns count=1 (collision), second returns 0
+        mock_db.session.scalar.side_effect = [1, 0]
+        sid = generate_session_id()
+        assert isinstance(sid, str)
+        assert mock_db.session.scalar.call_count == 2
+
+
+# ---------------------------------------------------------------------------
+# exchange_token_for_existing_web_user
+# ---------------------------------------------------------------------------
+class TestExchangeTokenForExistingWebUser:
+    @patch("controllers.web.passport.PassportService")
+    @patch("controllers.web.passport.db")
+    def test_external_auth_type_mismatch_raises(self, mock_db: MagicMock, mock_passport_cls: MagicMock) -> None:
+        site = SimpleNamespace(code="code1", app_id="app-1")
+        app_model = SimpleNamespace(id="app-1", status="normal", enable_site=True, tenant_id="t1")
+        mock_db.session.scalar.side_effect = [site, app_model]
+
+        decoded = {"user_id": "u1", "auth_type": "internal"}  # mismatch: expected "external"
+        with pytest.raises(WebAppAuthRequiredError, match="external"):
+            exchange_token_for_existing_web_user(
+                app_code="code1", enterprise_user_decoded=decoded, auth_type=WebAppAuthType.EXTERNAL
+            )
+
+    @patch("controllers.web.passport.PassportService")
+    @patch("controllers.web.passport.db")
+    def test_internal_auth_type_mismatch_raises(self, mock_db: MagicMock, mock_passport_cls: MagicMock) -> None:
+        site = SimpleNamespace(code="code1", app_id="app-1")
+        app_model = SimpleNamespace(id="app-1", status="normal", enable_site=True, tenant_id="t1")
+        mock_db.session.scalar.side_effect = [site, app_model]
+
+        decoded = {"user_id": "u1", "auth_type": "external"}  # mismatch: expected "internal"
+        with pytest.raises(WebAppAuthRequiredError, match="internal"):
+            exchange_token_for_existing_web_user(
+                app_code="code1", enterprise_user_decoded=decoded, auth_type=WebAppAuthType.INTERNAL
+            )
+
+    @patch("controllers.web.passport.PassportService")
+    @patch("controllers.web.passport.db")
+    def test_site_not_found_raises(self, mock_db: MagicMock, mock_passport_cls: MagicMock) -> None:
+        mock_db.session.scalar.return_value = None
+        decoded = {"user_id": "u1", "auth_type": "external"}
+        with pytest.raises(NotFound):
+            exchange_token_for_existing_web_user(
+                app_code="code1", enterprise_user_decoded=decoded, auth_type=WebAppAuthType.EXTERNAL
+            )
+
+
+# ---------------------------------------------------------------------------
+# PassportResource.get
+# ---------------------------------------------------------------------------
+class TestPassportResource:
+    @patch("controllers.web.passport.FeatureService.get_system_features")
+    def test_missing_app_code_raises_unauthorized(self, mock_features: MagicMock, app: Flask) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+        with app.test_request_context("/passport"):
+            with pytest.raises(Unauthorized, match="X-App-Code"):
+                PassportResource().get()
+
+    @patch("controllers.web.passport.PassportService")
+    @patch("controllers.web.passport.generate_session_id", return_value="new-sess-id")
+    @patch("controllers.web.passport.db")
+    @patch("controllers.web.passport.FeatureService.get_system_features")
+    def test_creates_new_end_user_when_no_user_id(
+        self,
+        mock_features: MagicMock,
+        mock_db: MagicMock,
+        mock_gen_session: MagicMock,
+        mock_passport_cls: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+        site = SimpleNamespace(app_id="app-1", code="code1")
+        app_model = SimpleNamespace(id="app-1", status="normal", enable_site=True, tenant_id="t1")
+        mock_db.session.scalar.side_effect = [site, app_model]
+        mock_passport_cls.return_value.issue.return_value = "issued-token"
+
+        with app.test_request_context("/passport", headers={"X-App-Code": "code1"}):
+            response = PassportResource().get()
+
+        assert response.get_json()["access_token"] == "issued-token"
+        mock_db.session.add.assert_called_once()
+        mock_db.session.commit.assert_called_once()
+
+    @patch("controllers.web.passport.PassportService")
+    @patch("controllers.web.passport.db")
+    @patch("controllers.web.passport.FeatureService.get_system_features")
+    def test_reuses_existing_end_user_when_user_id_provided(
+        self,
+        mock_features: MagicMock,
+        mock_db: MagicMock,
+        mock_passport_cls: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+        site = SimpleNamespace(app_id="app-1", code="code1")
+        app_model = SimpleNamespace(id="app-1", status="normal", enable_site=True, tenant_id="t1")
+        existing_user = SimpleNamespace(id="eu-1", session_id="sess-existing")
+        mock_db.session.scalar.side_effect = [site, app_model, existing_user]
+        mock_passport_cls.return_value.issue.return_value = "reused-token"
+
+        with app.test_request_context("/passport?user_id=sess-existing", headers={"X-App-Code": "code1"}):
+            response = PassportResource().get()
+
+        assert response.get_json()["access_token"] == "reused-token"
+        # Should not create a new end user
+        mock_db.session.add.assert_not_called()
+
+    @patch("controllers.web.passport.db")
+    @patch("controllers.web.passport.FeatureService.get_system_features")
+    def test_site_not_found_raises(self, mock_features: MagicMock, mock_db: MagicMock, app: Flask) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+        mock_db.session.scalar.return_value = None
+        with app.test_request_context("/passport", headers={"X-App-Code": "code1"}):
+            with pytest.raises(NotFound):
+                PassportResource().get()
+
+    @patch("controllers.web.passport.db")
+    @patch("controllers.web.passport.FeatureService.get_system_features")
+    def test_disabled_app_raises_not_found(self, mock_features: MagicMock, mock_db: MagicMock, app: Flask) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+        site = SimpleNamespace(app_id="app-1", code="code1")
+        disabled_app = SimpleNamespace(id="app-1", status="normal", enable_site=False)
+        mock_db.session.scalar.side_effect = [site, disabled_app]
+        with app.test_request_context("/passport", headers={"X-App-Code": "code1"}):
+            with pytest.raises(NotFound):
+                PassportResource().get()

api/tests/unit_tests/controllers/web/test_workflow.py

@@ -0,0 +1,95 @@
+"""Unit tests for controllers.web.workflow endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+from controllers.web.error import (
+    NotWorkflowAppError,
+    ProviderNotInitializeError,
+    ProviderQuotaExceededError,
+)
+from controllers.web.workflow import WorkflowRunApi, WorkflowTaskStopApi
+from core.errors.error import ProviderTokenNotInitError, QuotaExceededError
+
+
+def _workflow_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="workflow")
+
+
+def _chat_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", mode="chat")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+# ---------------------------------------------------------------------------
+# WorkflowRunApi
+# ---------------------------------------------------------------------------
+class TestWorkflowRunApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/workflows/run", method="POST"):
+            with pytest.raises(NotWorkflowAppError):
+                WorkflowRunApi().post(_chat_app(), _end_user())
+
+    @patch("controllers.web.workflow.helper.compact_generate_response", return_value={"result": "ok"})
+    @patch("controllers.web.workflow.AppGenerateService.generate")
+    @patch("controllers.web.workflow.web_ns")
+    def test_happy_path(self, mock_ns: MagicMock, mock_gen: MagicMock, mock_compact: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {"key": "val"}}
+        mock_gen.return_value = "response"
+
+        with app.test_request_context("/workflows/run", method="POST"):
+            result = WorkflowRunApi().post(_workflow_app(), _end_user())
+
+        assert result == {"result": "ok"}
+
+    @patch(
+        "controllers.web.workflow.AppGenerateService.generate",
+        side_effect=ProviderTokenNotInitError(description="not init"),
+    )
+    @patch("controllers.web.workflow.web_ns")
+    def test_provider_not_init(self, mock_ns: MagicMock, mock_gen: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}}
+
+        with app.test_request_context("/workflows/run", method="POST"):
+            with pytest.raises(ProviderNotInitializeError):
+                WorkflowRunApi().post(_workflow_app(), _end_user())
+
+    @patch(
+        "controllers.web.workflow.AppGenerateService.generate",
+        side_effect=QuotaExceededError(),
+    )
+    @patch("controllers.web.workflow.web_ns")
+    def test_quota_exceeded(self, mock_ns: MagicMock, mock_gen: MagicMock, app: Flask) -> None:
+        mock_ns.payload = {"inputs": {}}
+
+        with app.test_request_context("/workflows/run", method="POST"):
+            with pytest.raises(ProviderQuotaExceededError):
+                WorkflowRunApi().post(_workflow_app(), _end_user())
+
+
+# ---------------------------------------------------------------------------
+# WorkflowTaskStopApi
+# ---------------------------------------------------------------------------
+class TestWorkflowTaskStopApi:
+    def test_wrong_mode_raises(self, app: Flask) -> None:
+        with app.test_request_context("/workflows/tasks/task-1/stop", method="POST"):
+            with pytest.raises(NotWorkflowAppError):
+                WorkflowTaskStopApi().post(_chat_app(), _end_user(), "task-1")
+
+    @patch("controllers.web.workflow.GraphEngineManager.send_stop_command")
+    @patch("controllers.web.workflow.AppQueueManager.set_stop_flag_no_user_check")
+    def test_stop_calls_both_mechanisms(self, mock_legacy: MagicMock, mock_graph: MagicMock, app: Flask) -> None:
+        with app.test_request_context("/workflows/tasks/task-1/stop", method="POST"):
+            result = WorkflowTaskStopApi().post(_workflow_app(), _end_user(), "task-1")
+
+        assert result == {"result": "success"}
+        mock_legacy.assert_called_once_with("task-1")
+        mock_graph.assert_called_once_with("task-1")

api/tests/unit_tests/controllers/web/test_workflow_events.py

@@ -0,0 +1,127 @@
+"""Unit tests for controllers.web.workflow_events endpoints."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+from controllers.web.error import NotFoundError
+from controllers.web.workflow_events import WorkflowEventsApi
+from models.enums import CreatorUserRole
+
+
+def _workflow_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-1", tenant_id="tenant-1", mode="workflow")
+
+
+def _end_user() -> SimpleNamespace:
+    return SimpleNamespace(id="eu-1")
+
+
+# ---------------------------------------------------------------------------
+# WorkflowEventsApi
+# ---------------------------------------------------------------------------
+class TestWorkflowEventsApi:
+    @patch("controllers.web.workflow_events.DifyAPIRepositoryFactory")
+    @patch("controllers.web.workflow_events.db")
+    def test_workflow_run_not_found(self, mock_db: MagicMock, mock_factory: MagicMock, app: Flask) -> None:
+        mock_db.engine = "engine"
+        mock_repo = MagicMock()
+        mock_repo.get_workflow_run_by_id_and_tenant_id.return_value = None
+        mock_factory.create_api_workflow_run_repository.return_value = mock_repo
+
+        with app.test_request_context("/workflow/run-1/events"):
+            with pytest.raises(NotFoundError):
+                WorkflowEventsApi().get(_workflow_app(), _end_user(), "run-1")
+
+    @patch("controllers.web.workflow_events.DifyAPIRepositoryFactory")
+    @patch("controllers.web.workflow_events.db")
+    def test_workflow_run_wrong_app(self, mock_db: MagicMock, mock_factory: MagicMock, app: Flask) -> None:
+        mock_db.engine = "engine"
+        run = SimpleNamespace(
+            id="run-1",
+            app_id="other-app",
+            created_by_role=CreatorUserRole.END_USER,
+            created_by="eu-1",
+            finished_at=None,
+        )
+        mock_repo = MagicMock()
+        mock_repo.get_workflow_run_by_id_and_tenant_id.return_value = run
+        mock_factory.create_api_workflow_run_repository.return_value = mock_repo
+
+        with app.test_request_context("/workflow/run-1/events"):
+            with pytest.raises(NotFoundError):
+                WorkflowEventsApi().get(_workflow_app(), _end_user(), "run-1")
+
+    @patch("controllers.web.workflow_events.DifyAPIRepositoryFactory")
+    @patch("controllers.web.workflow_events.db")
+    def test_workflow_run_not_created_by_end_user(
+        self, mock_db: MagicMock, mock_factory: MagicMock, app: Flask
+    ) -> None:
+        mock_db.engine = "engine"
+        run = SimpleNamespace(
+            id="run-1",
+            app_id="app-1",
+            created_by_role=CreatorUserRole.ACCOUNT,
+            created_by="eu-1",
+            finished_at=None,
+        )
+        mock_repo = MagicMock()
+        mock_repo.get_workflow_run_by_id_and_tenant_id.return_value = run
+        mock_factory.create_api_workflow_run_repository.return_value = mock_repo
+
+        with app.test_request_context("/workflow/run-1/events"):
+            with pytest.raises(NotFoundError):
+                WorkflowEventsApi().get(_workflow_app(), _end_user(), "run-1")
+
+    @patch("controllers.web.workflow_events.DifyAPIRepositoryFactory")
+    @patch("controllers.web.workflow_events.db")
+    def test_workflow_run_wrong_end_user(self, mock_db: MagicMock, mock_factory: MagicMock, app: Flask) -> None:
+        mock_db.engine = "engine"
+        run = SimpleNamespace(
+            id="run-1",
+            app_id="app-1",
+            created_by_role=CreatorUserRole.END_USER,
+            created_by="other-user",
+            finished_at=None,
+        )
+        mock_repo = MagicMock()
+        mock_repo.get_workflow_run_by_id_and_tenant_id.return_value = run
+        mock_factory.create_api_workflow_run_repository.return_value = mock_repo
+
+        with app.test_request_context("/workflow/run-1/events"):
+            with pytest.raises(NotFoundError):
+                WorkflowEventsApi().get(_workflow_app(), _end_user(), "run-1")
+
+    @patch("controllers.web.workflow_events.WorkflowResponseConverter")
+    @patch("controllers.web.workflow_events.DifyAPIRepositoryFactory")
+    @patch("controllers.web.workflow_events.db")
+    def test_finished_run_returns_sse_response(
+        self, mock_db: MagicMock, mock_factory: MagicMock, mock_converter: MagicMock, app: Flask
+    ) -> None:
+        from datetime import datetime
+
+        mock_db.engine = "engine"
+        run = SimpleNamespace(
+            id="run-1",
+            app_id="app-1",
+            created_by_role=CreatorUserRole.END_USER,
+            created_by="eu-1",
+            finished_at=datetime(2024, 1, 1),
+        )
+        mock_repo = MagicMock()
+        mock_repo.get_workflow_run_by_id_and_tenant_id.return_value = run
+        mock_factory.create_api_workflow_run_repository.return_value = mock_repo
+
+        finish_response = MagicMock()
+        finish_response.model_dump.return_value = {"task_id": "run-1"}
+        finish_response.event.value = "workflow_finished"
+        mock_converter.workflow_run_result_to_finish_response.return_value = finish_response
+
+        with app.test_request_context("/workflow/run-1/events"):
+            response = WorkflowEventsApi().get(_workflow_app(), _end_user(), "run-1")
+
+        assert response.mimetype == "text/event-stream"

api/tests/unit_tests/controllers/web/test_wraps.py

@@ -0,0 +1,393 @@
+"""Unit tests for controllers.web.wraps — JWT auth decorator and validation helpers."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+from werkzeug.exceptions import BadRequest, NotFound, Unauthorized
+
+from controllers.web.error import WebAppAuthAccessDeniedError, WebAppAuthRequiredError
+from controllers.web.wraps import (
+    _validate_user_accessibility,
+    _validate_webapp_token,
+    decode_jwt_token,
+)
+
+
+# ---------------------------------------------------------------------------
+# _validate_webapp_token
+# ---------------------------------------------------------------------------
+class TestValidateWebappToken:
+    def test_enterprise_enabled_and_app_auth_requires_webapp_source(self) -> None:
+        """When both flags are true, a non-webapp source must raise."""
+        decoded = {"token_source": "other"}
+        with pytest.raises(WebAppAuthRequiredError):
+            _validate_webapp_token(decoded, app_web_auth_enabled=True, system_webapp_auth_enabled=True)
+
+    def test_enterprise_enabled_and_app_auth_accepts_webapp_source(self) -> None:
+        decoded = {"token_source": "webapp"}
+        _validate_webapp_token(decoded, app_web_auth_enabled=True, system_webapp_auth_enabled=True)
+
+    def test_enterprise_enabled_and_app_auth_missing_source_raises(self) -> None:
+        decoded = {}
+        with pytest.raises(WebAppAuthRequiredError):
+            _validate_webapp_token(decoded, app_web_auth_enabled=True, system_webapp_auth_enabled=True)
+
+    def test_public_app_rejects_webapp_source(self) -> None:
+        """When auth is not required, a webapp-sourced token must be rejected."""
+        decoded = {"token_source": "webapp"}
+        with pytest.raises(Unauthorized):
+            _validate_webapp_token(decoded, app_web_auth_enabled=False, system_webapp_auth_enabled=False)
+
+    def test_public_app_accepts_non_webapp_source(self) -> None:
+        decoded = {"token_source": "other"}
+        _validate_webapp_token(decoded, app_web_auth_enabled=False, system_webapp_auth_enabled=False)
+
+    def test_public_app_accepts_no_source(self) -> None:
+        decoded = {}
+        _validate_webapp_token(decoded, app_web_auth_enabled=False, system_webapp_auth_enabled=False)
+
+    def test_system_enabled_but_app_public(self) -> None:
+        """system_webapp_auth_enabled=True but app is public — webapp source rejected."""
+        decoded = {"token_source": "webapp"}
+        with pytest.raises(Unauthorized):
+            _validate_webapp_token(decoded, app_web_auth_enabled=False, system_webapp_auth_enabled=True)
+
+
+# ---------------------------------------------------------------------------
+# _validate_user_accessibility
+# ---------------------------------------------------------------------------
+class TestValidateUserAccessibility:
+    def test_skips_when_auth_disabled(self) -> None:
+        """No checks when system or app auth is disabled."""
+        _validate_user_accessibility(
+            decoded={},
+            app_code="code",
+            app_web_auth_enabled=False,
+            system_webapp_auth_enabled=False,
+            webapp_settings=None,
+        )
+
+    def test_missing_user_id_raises(self) -> None:
+        decoded = {}
+        with pytest.raises(WebAppAuthRequiredError):
+            _validate_user_accessibility(
+                decoded=decoded,
+                app_code="code",
+                app_web_auth_enabled=True,
+                system_webapp_auth_enabled=True,
+                webapp_settings=SimpleNamespace(access_mode="internal"),
+            )
+
+    def test_missing_webapp_settings_raises(self) -> None:
+        decoded = {"user_id": "u1"}
+        with pytest.raises(WebAppAuthRequiredError, match="settings not found"):
+            _validate_user_accessibility(
+                decoded=decoded,
+                app_code="code",
+                app_web_auth_enabled=True,
+                system_webapp_auth_enabled=True,
+                webapp_settings=None,
+            )
+
+    def test_missing_auth_type_raises(self) -> None:
+        decoded = {"user_id": "u1", "granted_at": 1}
+        settings = SimpleNamespace(access_mode="public")
+        with pytest.raises(WebAppAuthAccessDeniedError, match="auth_type"):
+            _validate_user_accessibility(
+                decoded=decoded,
+                app_code="code",
+                app_web_auth_enabled=True,
+                system_webapp_auth_enabled=True,
+                webapp_settings=settings,
+            )
+
+    def test_missing_granted_at_raises(self) -> None:
+        decoded = {"user_id": "u1", "auth_type": "external"}
+        settings = SimpleNamespace(access_mode="public")
+        with pytest.raises(WebAppAuthAccessDeniedError, match="granted_at"):
+            _validate_user_accessibility(
+                decoded=decoded,
+                app_code="code",
+                app_web_auth_enabled=True,
+                system_webapp_auth_enabled=True,
+                webapp_settings=settings,
+            )
+
+    @patch("controllers.web.wraps.EnterpriseService.get_app_sso_settings_last_update_time")
+    @patch("controllers.web.wraps.WebAppAuthService.is_app_require_permission_check", return_value=False)
+    def test_external_auth_type_checks_sso_update_time(
+        self, mock_perm_check: MagicMock, mock_sso_time: MagicMock
+    ) -> None:
+        # granted_at is before SSO update time → denied
+        mock_sso_time.return_value = datetime.now(UTC)
+        old_granted = int((datetime.now(UTC) - timedelta(hours=1)).timestamp())
+        decoded = {"user_id": "u1", "auth_type": "external", "granted_at": old_granted}
+        settings = SimpleNamespace(access_mode="public")
+        with pytest.raises(WebAppAuthAccessDeniedError, match="SSO settings"):
+            _validate_user_accessibility(
+                decoded=decoded,
+                app_code="code",
+                app_web_auth_enabled=True,
+                system_webapp_auth_enabled=True,
+                webapp_settings=settings,
+            )
+
+    @patch("controllers.web.wraps.EnterpriseService.get_workspace_sso_settings_last_update_time")
+    @patch("controllers.web.wraps.WebAppAuthService.is_app_require_permission_check", return_value=False)
+    def test_internal_auth_type_checks_workspace_sso_update_time(
+        self, mock_perm_check: MagicMock, mock_workspace_sso: MagicMock
+    ) -> None:
+        mock_workspace_sso.return_value = datetime.now(UTC)
+        old_granted = int((datetime.now(UTC) - timedelta(hours=1)).timestamp())
+        decoded = {"user_id": "u1", "auth_type": "internal", "granted_at": old_granted}
+        settings = SimpleNamespace(access_mode="public")
+        with pytest.raises(WebAppAuthAccessDeniedError, match="SSO settings"):
+            _validate_user_accessibility(
+                decoded=decoded,
+                app_code="code",
+                app_web_auth_enabled=True,
+                system_webapp_auth_enabled=True,
+                webapp_settings=settings,
+            )
+
+    @patch("controllers.web.wraps.EnterpriseService.get_app_sso_settings_last_update_time")
+    @patch("controllers.web.wraps.WebAppAuthService.is_app_require_permission_check", return_value=False)
+    def test_external_auth_passes_when_granted_after_sso_update(
+        self, mock_perm_check: MagicMock, mock_sso_time: MagicMock
+    ) -> None:
+        mock_sso_time.return_value = datetime.now(UTC) - timedelta(hours=2)
+        recent_granted = int(datetime.now(UTC).timestamp())
+        decoded = {"user_id": "u1", "auth_type": "external", "granted_at": recent_granted}
+        settings = SimpleNamespace(access_mode="public")
+        # Should not raise
+        _validate_user_accessibility(
+            decoded=decoded,
+            app_code="code",
+            app_web_auth_enabled=True,
+            system_webapp_auth_enabled=True,
+            webapp_settings=settings,
+        )
+
+    @patch("controllers.web.wraps.EnterpriseService.WebAppAuth.is_user_allowed_to_access_webapp", return_value=False)
+    @patch("controllers.web.wraps.AppService.get_app_id_by_code", return_value="app-id-1")
+    @patch("controllers.web.wraps.WebAppAuthService.is_app_require_permission_check", return_value=True)
+    def test_permission_check_denies_unauthorized_user(
+        self, mock_perm: MagicMock, mock_app_id: MagicMock, mock_allowed: MagicMock
+    ) -> None:
+        decoded = {"user_id": "u1", "auth_type": "external", "granted_at": int(datetime.now(UTC).timestamp())}
+        settings = SimpleNamespace(access_mode="internal")
+        with pytest.raises(WebAppAuthAccessDeniedError):
+            _validate_user_accessibility(
+                decoded=decoded,
+                app_code="code",
+                app_web_auth_enabled=True,
+                system_webapp_auth_enabled=True,
+                webapp_settings=settings,
+            )
+
+
+# ---------------------------------------------------------------------------
+# decode_jwt_token
+# ---------------------------------------------------------------------------
+class TestDecodeJwtToken:
+    @patch("controllers.web.wraps._validate_user_accessibility")
+    @patch("controllers.web.wraps._validate_webapp_token")
+    @patch("controllers.web.wraps.EnterpriseService.WebAppAuth.get_app_access_mode_by_id")
+    @patch("controllers.web.wraps.AppService.get_app_id_by_code")
+    @patch("controllers.web.wraps.FeatureService.get_system_features")
+    @patch("controllers.web.wraps.PassportService")
+    @patch("controllers.web.wraps.extract_webapp_passport")
+    @patch("controllers.web.wraps.db")
+    def test_happy_path(
+        self,
+        mock_db: MagicMock,
+        mock_extract: MagicMock,
+        mock_passport_cls: MagicMock,
+        mock_features: MagicMock,
+        mock_app_id: MagicMock,
+        mock_access_mode: MagicMock,
+        mock_validate_token: MagicMock,
+        mock_validate_user: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_extract.return_value = "jwt-token"
+        mock_passport_cls.return_value.verify.return_value = {
+            "app_code": "code1",
+            "app_id": "app-1",
+            "end_user_id": "eu-1",
+        }
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+
+        app_model = SimpleNamespace(id="app-1", enable_site=True)
+        site = SimpleNamespace(code="code1")
+        end_user = SimpleNamespace(id="eu-1", session_id="sess-1")
+
+        # Configure session mock to return correct objects via scalar()
+        session_mock = MagicMock()
+        session_mock.scalar.side_effect = [app_model, site, end_user]
+        session_ctx = MagicMock()
+        session_ctx.__enter__ = MagicMock(return_value=session_mock)
+        session_ctx.__exit__ = MagicMock(return_value=False)
+        mock_db.engine = "engine"
+
+        with patch("controllers.web.wraps.Session", return_value=session_ctx):
+            with app.test_request_context("/", headers={"X-App-Code": "code1"}):
+                result_app, result_user = decode_jwt_token()
+
+        assert result_app.id == "app-1"
+        assert result_user.id == "eu-1"
+
+    @patch("controllers.web.wraps.FeatureService.get_system_features")
+    @patch("controllers.web.wraps.extract_webapp_passport")
+    def test_missing_token_raises_unauthorized(
+        self, mock_extract: MagicMock, mock_features: MagicMock, app: Flask
+    ) -> None:
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+        mock_extract.return_value = None
+
+        with app.test_request_context("/", headers={"X-App-Code": "code1"}):
+            with pytest.raises(Unauthorized):
+                decode_jwt_token()
+
+    @patch("controllers.web.wraps.FeatureService.get_system_features")
+    @patch("controllers.web.wraps.PassportService")
+    @patch("controllers.web.wraps.extract_webapp_passport")
+    @patch("controllers.web.wraps.db")
+    def test_missing_app_raises_not_found(
+        self,
+        mock_db: MagicMock,
+        mock_extract: MagicMock,
+        mock_passport_cls: MagicMock,
+        mock_features: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_extract.return_value = "jwt-token"
+        mock_passport_cls.return_value.verify.return_value = {
+            "app_code": "code1",
+            "app_id": "app-1",
+            "end_user_id": "eu-1",
+        }
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+
+        session_mock = MagicMock()
+        session_mock.scalar.return_value = None  # No app found
+        session_ctx = MagicMock()
+        session_ctx.__enter__ = MagicMock(return_value=session_mock)
+        session_ctx.__exit__ = MagicMock(return_value=False)
+        mock_db.engine = "engine"
+
+        with patch("controllers.web.wraps.Session", return_value=session_ctx):
+            with app.test_request_context("/", headers={"X-App-Code": "code1"}):
+                with pytest.raises(NotFound):
+                    decode_jwt_token()
+
+    @patch("controllers.web.wraps.FeatureService.get_system_features")
+    @patch("controllers.web.wraps.PassportService")
+    @patch("controllers.web.wraps.extract_webapp_passport")
+    @patch("controllers.web.wraps.db")
+    def test_disabled_site_raises_bad_request(
+        self,
+        mock_db: MagicMock,
+        mock_extract: MagicMock,
+        mock_passport_cls: MagicMock,
+        mock_features: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_extract.return_value = "jwt-token"
+        mock_passport_cls.return_value.verify.return_value = {
+            "app_code": "code1",
+            "app_id": "app-1",
+            "end_user_id": "eu-1",
+        }
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+
+        app_model = SimpleNamespace(id="app-1", enable_site=False)
+
+        session_mock = MagicMock()
+        # scalar calls: app_model, site (code found), then end_user
+        session_mock.scalar.side_effect = [app_model, SimpleNamespace(code="code1"), None]
+        session_ctx = MagicMock()
+        session_ctx.__enter__ = MagicMock(return_value=session_mock)
+        session_ctx.__exit__ = MagicMock(return_value=False)
+        mock_db.engine = "engine"
+
+        with patch("controllers.web.wraps.Session", return_value=session_ctx):
+            with app.test_request_context("/", headers={"X-App-Code": "code1"}):
+                with pytest.raises(BadRequest, match="Site is disabled"):
+                    decode_jwt_token()
+
+    @patch("controllers.web.wraps.FeatureService.get_system_features")
+    @patch("controllers.web.wraps.PassportService")
+    @patch("controllers.web.wraps.extract_webapp_passport")
+    @patch("controllers.web.wraps.db")
+    def test_missing_end_user_raises_not_found(
+        self,
+        mock_db: MagicMock,
+        mock_extract: MagicMock,
+        mock_passport_cls: MagicMock,
+        mock_features: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_extract.return_value = "jwt-token"
+        mock_passport_cls.return_value.verify.return_value = {
+            "app_code": "code1",
+            "app_id": "app-1",
+            "end_user_id": "eu-1",
+        }
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+
+        app_model = SimpleNamespace(id="app-1", enable_site=True)
+        site = SimpleNamespace(code="code1")
+
+        session_mock = MagicMock()
+        session_mock.scalar.side_effect = [app_model, site, None]  # end_user is None
+        session_ctx = MagicMock()
+        session_ctx.__enter__ = MagicMock(return_value=session_mock)
+        session_ctx.__exit__ = MagicMock(return_value=False)
+        mock_db.engine = "engine"
+
+        with patch("controllers.web.wraps.Session", return_value=session_ctx):
+            with app.test_request_context("/", headers={"X-App-Code": "code1"}):
+                with pytest.raises(NotFound):
+                    decode_jwt_token()
+
+    @patch("controllers.web.wraps.FeatureService.get_system_features")
+    @patch("controllers.web.wraps.PassportService")
+    @patch("controllers.web.wraps.extract_webapp_passport")
+    @patch("controllers.web.wraps.db")
+    def test_user_id_mismatch_raises_unauthorized(
+        self,
+        mock_db: MagicMock,
+        mock_extract: MagicMock,
+        mock_passport_cls: MagicMock,
+        mock_features: MagicMock,
+        app: Flask,
+    ) -> None:
+        mock_extract.return_value = "jwt-token"
+        mock_passport_cls.return_value.verify.return_value = {
+            "app_code": "code1",
+            "app_id": "app-1",
+            "end_user_id": "eu-1",
+        }
+        mock_features.return_value = SimpleNamespace(webapp_auth=SimpleNamespace(enabled=False))
+
+        app_model = SimpleNamespace(id="app-1", enable_site=True)
+        site = SimpleNamespace(code="code1")
+        end_user = SimpleNamespace(id="eu-1", session_id="sess-1")
+
+        session_mock = MagicMock()
+        session_mock.scalar.side_effect = [app_model, site, end_user]
+        session_ctx = MagicMock()
+        session_ctx.__enter__ = MagicMock(return_value=session_mock)
+        session_ctx.__exit__ = MagicMock(return_value=False)
+        mock_db.engine = "engine"
+
+        with patch("controllers.web.wraps.Session", return_value=session_ctx):
+            with app.test_request_context("/", headers={"X-App-Code": "code1"}):
+                with pytest.raises(Unauthorized, match="expired"):
+                    decode_jwt_token(user_id="different-user")

api/tests/unit_tests/core/workflow/nodes/knowledge_retrieval/test_knowledge_retrieval_node.py

@@ -8,7 +8,9 @@ from core.app.entities.app_invoke_entities import InvokeFrom, UserFrom
 from dify_graph.enums import WorkflowNodeExecutionStatus
 from dify_graph.model_runtime.entities.llm_entities import LLMUsage
 from dify_graph.nodes.knowledge_retrieval.entities import (
+    Condition,
     KnowledgeRetrievalNodeData,
+    MetadataFilteringCondition,
     MultipleRetrievalConfig,
     RerankingModelConfig,
     SingleRetrievalConfig,
@@ -593,3 +595,106 @@ class TestFetchDatasetRetriever:
 
         # Assert
         assert version == "1"
+
+    def test_resolve_metadata_filtering_conditions_templates(
+        self,
+        mock_graph_init_params,
+        mock_graph_runtime_state,
+        mock_rag_retrieval,
+    ):
+        """_resolve_metadata_filtering_conditions should expand {{#...#}} and keep numbers/None unchanged."""
+        # Arrange
+        node_id = str(uuid.uuid4())
+        config = {
+            "id": node_id,
+            "data": {
+                "title": "Knowledge Retrieval",
+                "type": "knowledge-retrieval",
+                "dataset_ids": [str(uuid.uuid4())],
+                "retrieval_mode": "multiple",
+            },
+        }
+        # Variable in pool used by template
+        mock_graph_runtime_state.variable_pool.add(["start", "query"], StringSegment(value="readme"))
+
+        node = KnowledgeRetrievalNode(
+            id=node_id,
+            config=config,
+            graph_init_params=mock_graph_init_params,
+            graph_runtime_state=mock_graph_runtime_state,
+            rag_retrieval=mock_rag_retrieval,
+        )
+
+        conditions = MetadataFilteringCondition(
+            logical_operator="and",
+            conditions=[
+                Condition(name="document_name", comparison_operator="is", value="{{#start.query#}}"),
+                Condition(name="tags", comparison_operator="in", value=["x", "{{#start.query#}}"]),
+                Condition(name="year", comparison_operator="=", value=2025),
+            ],
+        )
+
+        # Act
+        resolved = node._resolve_metadata_filtering_conditions(conditions)
+
+        # Assert
+        assert resolved.logical_operator == "and"
+        assert resolved.conditions[0].value == "readme"
+        assert isinstance(resolved.conditions[1].value, list)
+        assert resolved.conditions[1].value[1] == "readme"
+        assert resolved.conditions[2].value == 2025
+
+    def test_fetch_passes_resolved_metadata_conditions(
+        self,
+        mock_graph_init_params,
+        mock_graph_runtime_state,
+        mock_rag_retrieval,
+    ):
+        """_fetch_dataset_retriever should pass resolved metadata conditions into request."""
+        # Arrange
+        query = "hi"
+        variables = {"query": query}
+        mock_graph_runtime_state.variable_pool.add(["start", "q"], StringSegment(value="readme"))
+
+        node_data = KnowledgeRetrievalNodeData(
+            title="Knowledge Retrieval",
+            type="knowledge-retrieval",
+            dataset_ids=[str(uuid.uuid4())],
+            retrieval_mode="multiple",
+            multiple_retrieval_config=MultipleRetrievalConfig(
+                top_k=4,
+                score_threshold=0.0,
+                reranking_mode="reranking_model",
+                reranking_enable=True,
+                reranking_model=RerankingModelConfig(provider="cohere", model="rerank-v2"),
+            ),
+            metadata_filtering_mode="manual",
+            metadata_filtering_conditions=MetadataFilteringCondition(
+                logical_operator="and",
+                conditions=[
+                    Condition(name="document_name", comparison_operator="is", value="{{#start.q#}}"),
+                ],
+            ),
+        )
+
+        node_id = str(uuid.uuid4())
+        config = {"id": node_id, "data": node_data.model_dump()}
+        node = KnowledgeRetrievalNode(
+            id=node_id,
+            config=config,
+            graph_init_params=mock_graph_init_params,
+            graph_runtime_state=mock_graph_runtime_state,
+            rag_retrieval=mock_rag_retrieval,
+        )
+
+        mock_rag_retrieval.knowledge_retrieval.return_value = []
+        mock_rag_retrieval.llm_usage = LLMUsage.empty_usage()
+
+        # Act
+        node._fetch_dataset_retriever(node_data=node_data, variables=variables)
+
+        # Assert the passed request has resolved value
+        call_args = mock_rag_retrieval.knowledge_retrieval.call_args
+        request = call_args[1]["request"]
+        assert request.metadata_filtering_conditions is not None
+        assert request.metadata_filtering_conditions.conditions[0].value == "readme"

api/tests/unit_tests/core/workflow/nodes/test_document_extractor_node.py

@@ -16,6 +16,7 @@ from dify_graph.nodes.document_extractor.node import (
     _extract_text_from_excel,
     _extract_text_from_pdf,
     _extract_text_from_plain_text,
+    _normalize_docx_zip,
 )
 from dify_graph.variables import ArrayFileSegment
 from dify_graph.variables.segments import ArrayStringSegment
@@ -86,6 +87,38 @@ def test_run_invalid_variable_type(document_extractor_node, mock_graph_runtime_s
     assert "is not an ArrayFileSegment" in result.error
 
 
+def test_run_empty_file_list_returns_succeeded(document_extractor_node, mock_graph_runtime_state):
+    """Empty file list should return SUCCEEDED with empty documents and ArrayStringSegment([])."""
+    document_extractor_node.graph_runtime_state = mock_graph_runtime_state
+
+    # Provide an actual ArrayFileSegment with an empty list
+    mock_graph_runtime_state.variable_pool.get.return_value = ArrayFileSegment(value=[])
+
+    result = document_extractor_node._run()
+
+    assert isinstance(result, NodeRunResult)
+    assert result.status == WorkflowNodeExecutionStatus.SUCCEEDED, result.error
+    assert result.process_data.get("documents") == []
+    assert result.outputs["text"] == ArrayStringSegment(value=[])
+
+
+def test_run_none_only_file_list_returns_succeeded(document_extractor_node, mock_graph_runtime_state):
+    """A file list containing only None (e.g., [None]) should be filtered to [] and succeed."""
+    document_extractor_node.graph_runtime_state = mock_graph_runtime_state
+
+    # Use a Mock to bypass type validation for None entries in the list
+    afs = Mock(spec=ArrayFileSegment)
+    afs.value = [None]
+    mock_graph_runtime_state.variable_pool.get.return_value = afs
+
+    result = document_extractor_node._run()
+
+    assert isinstance(result, NodeRunResult)
+    assert result.status == WorkflowNodeExecutionStatus.SUCCEEDED, result.error
+    assert result.process_data.get("documents") == []
+    assert result.outputs["text"] == ArrayStringSegment(value=[])
+
+
 @pytest.mark.parametrize(
     ("mime_type", "file_content", "expected_text", "transfer_method", "extension"),
     [
@@ -385,3 +418,58 @@ def test_extract_text_from_excel_numeric_type_column(mock_excel_file):
     expected_manual = "| 1.0 | 1.1 |\n| --- | --- |\n| Test | Test |\n\n"
 
     assert expected_manual == result
+
+
+def _make_docx_zip(use_backslash: bool) -> bytes:
+    """Helper to build a minimal in-memory DOCX zip.
+
+    When use_backslash=True the ZIP entry names use backslash separators
+    (as produced by Evernote on Windows), otherwise forward slashes are used.
+    """
+    import zipfile
+
+    sep = "\\" if use_backslash else "/"
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr("[Content_Types].xml", b"<Types/>")
+        zf.writestr(f"_rels{sep}.rels", b"<Relationships/>")
+        zf.writestr(f"word{sep}document.xml", b"<w:document/>")
+        zf.writestr(f"word{sep}_rels{sep}document.xml.rels", b"<Relationships/>")
+    return buf.getvalue()
+
+
+def test_normalize_docx_zip_replaces_backslashes():
+    """ZIP entries with backslash separators must be rewritten to forward slashes."""
+    import zipfile
+
+    malformed = _make_docx_zip(use_backslash=True)
+    fixed = _normalize_docx_zip(malformed)
+
+    with zipfile.ZipFile(io.BytesIO(fixed)) as zf:
+        names = zf.namelist()
+
+    assert "word/document.xml" in names
+    assert "word/_rels/document.xml.rels" in names
+    # No entry should contain a backslash after normalization
+    assert all("\\" not in name for name in names)
+
+
+def test_normalize_docx_zip_leaves_forward_slash_unchanged():
+    """ZIP entries that already use forward slashes must not be modified."""
+    import zipfile
+
+    normal = _make_docx_zip(use_backslash=False)
+    fixed = _normalize_docx_zip(normal)
+
+    with zipfile.ZipFile(io.BytesIO(fixed)) as zf:
+        names = zf.namelist()
+
+    assert "word/document.xml" in names
+    assert "word/_rels/document.xml.rels" in names
+
+
+def test_normalize_docx_zip_returns_original_on_bad_zip():
+    """Non-zip bytes must be returned as-is without raising."""
+    garbage = b"not a zip file at all"
+    result = _normalize_docx_zip(garbage)
+    assert result == garbage

api/tests/unit_tests/services/test_messages_clean_service.py

@@ -554,11 +554,9 @@ class TestMessagesCleanServiceFromDays:
             MessagesCleanService.from_days(policy=policy, days=-1)
 
         # Act
-        with patch("services.retention.conversation.messages_clean_service.datetime", autospec=True) as mock_datetime:
+        with patch("services.retention.conversation.messages_clean_service.naive_utc_now") as mock_now:
             fixed_now = datetime.datetime(2024, 6, 15, 14, 0, 0)
-            mock_datetime.datetime.now.return_value = fixed_now
-            mock_datetime.timedelta = datetime.timedelta
-
+            mock_now.return_value = fixed_now
             service = MessagesCleanService.from_days(policy=policy, days=0)
 
         # Assert
@@ -586,11 +584,9 @@ class TestMessagesCleanServiceFromDays:
         dry_run = True
 
         # Act
-        with patch("services.retention.conversation.messages_clean_service.datetime", autospec=True) as mock_datetime:
+        with patch("services.retention.conversation.messages_clean_service.naive_utc_now") as mock_now:
             fixed_now = datetime.datetime(2024, 6, 15, 10, 30, 0)
-            mock_datetime.datetime.now.return_value = fixed_now
-            mock_datetime.timedelta = datetime.timedelta
-
+            mock_now.return_value = fixed_now
             service = MessagesCleanService.from_days(
                 policy=policy,
                 days=days,
@@ -613,11 +609,9 @@ class TestMessagesCleanServiceFromDays:
         policy = BillingDisabledPolicy()
 
         # Act
-        with patch("services.retention.conversation.messages_clean_service.datetime", autospec=True) as mock_datetime:
+        with patch("services.retention.conversation.messages_clean_service.naive_utc_now") as mock_now:
             fixed_now = datetime.datetime(2024, 6, 15, 10, 30, 0)
-            mock_datetime.datetime.now.return_value = fixed_now
-            mock_datetime.timedelta = datetime.timedelta
-
+            mock_now.return_value = fixed_now
             service = MessagesCleanService.from_days(policy=policy)
 
         # Assert

api/tests/unit_tests/services/workflow/test_workflow_draft_variable_service.py

@@ -25,7 +25,6 @@ from services.workflow_draft_variable_service import (
     DraftVariableSaver,
     VariableResetError,
     WorkflowDraftVariableService,
-    _model_to_insertion_dict,
 )
 
 
@@ -476,41 +475,3 @@ class TestWorkflowDraftVariableService:
         assert node_var.visible == True
         assert node_var.editable == True
         assert node_var.node_execution_id == "exec-id"
-
-
-class TestModelToInsertionDict:
-    """Reproduce two production errors in _model_to_insertion_dict / _new()."""
-
-    def test_visible_and_is_default_value_always_present(self):
-        """Problem 1: _new() did not set visible/is_default_value, causing
-        inconsistent dict keys across rows in multi-row INSERT and missing
-        is_default_value in the insertion dict entirely.
-        """
-        conv_var = WorkflowDraftVariable.new_conversation_variable(
-            app_id="app-1",
-            name="counter",
-            value=StringSegment(value="0"),
-        )
-        # _new() should explicitly set these fields so they are not None
-        assert conv_var.visible is not None
-        assert conv_var.is_default_value is not None
-
-        d = _model_to_insertion_dict(conv_var)
-        # visible must appear in every row's dict
-        assert "visible" in d
-        # is_default_value must always be present
-        assert "is_default_value" in d
-
-    def test_description_passthrough(self):
-        """_model_to_insertion_dict passes description as-is;
-        length validation is enforced earlier in build_conversation_variable_from_mapping.
-        """
-        desc = "a" * 200
-        conv_var = WorkflowDraftVariable.new_conversation_variable(
-            app_id="app-1",
-            name="counter",
-            value=StringSegment(value="0"),
-            description=desc,
-        )
-        d = _model_to_insertion_dict(conv_var)
-        assert d["description"] == desc

scripts/stress-test/common/config_helper.py

@@ -6,6 +6,13 @@ from typing import Any
 
 
 class ConfigHelper:
+    _LEGACY_SECTION_MAP = {
+        "admin_config": "admin",
+        "token_config": "auth",
+        "app_config": "app",
+        "api_key_config": "api_key",
+    }
+
     """Helper class for reading and writing configuration files."""
 
     def __init__(self, base_dir: Path | None = None):
@@ -50,14 +57,8 @@ class ConfigHelper:
             Dictionary containing config data, or None if file doesn't exist
         """
         # Provide backward compatibility for old config names
-        if filename in ["admin_config", "token_config", "app_config", "api_key_config"]:
-            section_map = {
-                "admin_config": "admin",
-                "token_config": "auth",
-                "app_config": "app",
-                "api_key_config": "api_key",
-            }
-            return self.get_state_section(section_map[filename])
+        if filename in self._LEGACY_SECTION_MAP:
+            return self.get_state_section(self._LEGACY_SECTION_MAP[filename])
 
         config_path = self.get_config_path(filename)
 
@@ -85,14 +86,11 @@ class ConfigHelper:
             True if successful, False otherwise
         """
         # Provide backward compatibility for old config names
-        if filename in ["admin_config", "token_config", "app_config", "api_key_config"]:
-            section_map = {
-                "admin_config": "admin",
-                "token_config": "auth",
-                "app_config": "app",
-                "api_key_config": "api_key",
-            }
-            return self.update_state_section(section_map[filename], data)
+        if filename in self._LEGACY_SECTION_MAP:
+            return self.update_state_section(
+                self._LEGACY_SECTION_MAP[filename],
+                data,
+            )
 
         self.ensure_config_dir()
         config_path = self.get_config_path(filename)

web/AGENTS.md

@@ -2,6 +2,12 @@
 
 - Refer to the `./docs/test.md` and `./docs/lint.md` for detailed frontend workflow instructions.
 
+## Overlay Components (Mandatory)
+
+- `./docs/overlay-migration.md` is the source of truth for overlay-related work.
+- In new or modified code, use only overlay primitives from `@/app/components/base/ui/*`.
+- Do not introduce deprecated overlay imports from `@/app/components/base/*`; when touching legacy callers, prefer migrating them and keep the allowlist shrinking (never expanding).
+
 ## Automated Test Generation
 
 - Use `./docs/test.md` as the canonical instruction set for generating frontend automated tests.

web/app/components/base/ui/context-menu/__tests__/index.spec.tsx

@@ -0,0 +1,257 @@
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuLinkItem,
+  ContextMenuSeparator,
+  ContextMenuSub,
+  ContextMenuSubContent,
+  ContextMenuSubTrigger,
+  ContextMenuTrigger,
+} from '../index'
+
+describe('context-menu wrapper', () => {
+  describe('ContextMenuContent', () => {
+    it('should position content at bottom-start with default placement when props are omitted', () => {
+      render(
+        <ContextMenu open>
+          <ContextMenuTrigger aria-label="context trigger">Open</ContextMenuTrigger>
+          <ContextMenuContent positionerProps={{ 'role': 'group', 'aria-label': 'content positioner' }}>
+            <ContextMenuItem>Content action</ContextMenuItem>
+          </ContextMenuContent>
+        </ContextMenu>,
+      )
+
+      const positioner = screen.getByRole('group', { name: 'content positioner' })
+      const popup = screen.getByRole('menu')
+      expect(positioner).toHaveAttribute('data-side', 'bottom')
+      expect(positioner).toHaveAttribute('data-align', 'start')
+      expect(within(popup).getByRole('menuitem', { name: 'Content action' })).toBeInTheDocument()
+    })
+
+    it('should apply custom placement when custom positioning props are provided', () => {
+      render(
+        <ContextMenu open>
+          <ContextMenuTrigger aria-label="context trigger">Open</ContextMenuTrigger>
+          <ContextMenuContent
+            placement="top-end"
+            sideOffset={12}
+            alignOffset={-3}
+            positionerProps={{ 'role': 'group', 'aria-label': 'custom content positioner' }}
+          >
+            <ContextMenuItem>Custom content</ContextMenuItem>
+          </ContextMenuContent>
+        </ContextMenu>,
+      )
+
+      const positioner = screen.getByRole('group', { name: 'custom content positioner' })
+      const popup = screen.getByRole('menu')
+      expect(positioner).toHaveAttribute('data-side', 'top')
+      expect(positioner).toHaveAttribute('data-align', 'end')
+      expect(within(popup).getByRole('menuitem', { name: 'Custom content' })).toBeInTheDocument()
+    })
+
+    it('should forward passthrough attributes and handlers when positionerProps and popupProps are provided', () => {
+      const handlePositionerMouseEnter = vi.fn()
+      const handlePopupClick = vi.fn()
+
+      render(
+        <ContextMenu open>
+          <ContextMenuTrigger aria-label="context trigger">Open</ContextMenuTrigger>
+          <ContextMenuContent
+            positionerProps={{
+              'role': 'group',
+              'aria-label': 'context content positioner',
+              'id': 'context-content-positioner',
+              'onMouseEnter': handlePositionerMouseEnter,
+            }}
+            popupProps={{
+              role: 'menu',
+              id: 'context-content-popup',
+              onClick: handlePopupClick,
+            }}
+          >
+            <ContextMenuItem>Passthrough content</ContextMenuItem>
+          </ContextMenuContent>
+        </ContextMenu>,
+      )
+
+      const positioner = screen.getByRole('group', { name: 'context content positioner' })
+      const popup = screen.getByRole('menu')
+      fireEvent.mouseEnter(positioner)
+      fireEvent.click(popup)
+      expect(positioner).toHaveAttribute('id', 'context-content-positioner')
+      expect(popup).toHaveAttribute('id', 'context-content-popup')
+      expect(handlePositionerMouseEnter).toHaveBeenCalledTimes(1)
+      expect(handlePopupClick).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  describe('ContextMenuSubContent', () => {
+    it('should position sub-content at right-start with default placement when props are omitted', () => {
+      render(
+        <ContextMenu open>
+          <ContextMenuTrigger aria-label="context trigger">Open</ContextMenuTrigger>
+          <ContextMenuContent>
+            <ContextMenuSub open>
+              <ContextMenuSubTrigger>More actions</ContextMenuSubTrigger>
+              <ContextMenuSubContent positionerProps={{ 'role': 'group', 'aria-label': 'sub positioner' }}>
+                <ContextMenuItem>Sub action</ContextMenuItem>
+              </ContextMenuSubContent>
+            </ContextMenuSub>
+          </ContextMenuContent>
+        </ContextMenu>,
+      )
+
+      const positioner = screen.getByRole('group', { name: 'sub positioner' })
+      expect(positioner).toHaveAttribute('data-side', 'right')
+      expect(positioner).toHaveAttribute('data-align', 'start')
+      expect(screen.getByRole('menuitem', { name: 'Sub action' })).toBeInTheDocument()
+    })
+  })
+
+  describe('destructive prop behavior', () => {
+    it.each([true, false])('should remain interactive and not leak destructive prop on item when destructive is %s', (destructive) => {
+      const handleClick = vi.fn()
+
+      render(
+        <ContextMenu open>
+          <ContextMenuTrigger aria-label="context trigger">Open</ContextMenuTrigger>
+          <ContextMenuContent>
+            <ContextMenuItem
+              destructive={destructive}
+              aria-label="menu action"
+              id={`context-item-${String(destructive)}`}
+              onClick={handleClick}
+            >
+              Item label
+            </ContextMenuItem>
+          </ContextMenuContent>
+        </ContextMenu>,
+      )
+
+      const item = screen.getByRole('menuitem', { name: 'menu action' })
+      fireEvent.click(item)
+      expect(item).toHaveAttribute('id', `context-item-${String(destructive)}`)
+      expect(item).not.toHaveAttribute('destructive')
+      expect(handleClick).toHaveBeenCalledTimes(1)
+    })
+
+    it.each([true, false])('should remain interactive and not leak destructive prop on submenu trigger when destructive is %s', (destructive) => {
+      const handleClick = vi.fn()
+
+      render(
+        <ContextMenu open>
+          <ContextMenuTrigger aria-label="context trigger">Open</ContextMenuTrigger>
+          <ContextMenuContent>
+            <ContextMenuSub open>
+              <ContextMenuSubTrigger
+                destructive={destructive}
+                aria-label="submenu action"
+                id={`context-sub-${String(destructive)}`}
+                onClick={handleClick}
+              >
+                Trigger item
+              </ContextMenuSubTrigger>
+            </ContextMenuSub>
+          </ContextMenuContent>
+        </ContextMenu>,
+      )
+
+      const trigger = screen.getByRole('menuitem', { name: 'submenu action' })
+      fireEvent.click(trigger)
+      expect(trigger).toHaveAttribute('id', `context-sub-${String(destructive)}`)
+      expect(trigger).not.toHaveAttribute('destructive')
+      expect(handleClick).toHaveBeenCalledTimes(1)
+    })
+
+    it.each([true, false])('should remain interactive and not leak destructive prop on link item when destructive is %s', (destructive) => {
+      render(
+        <ContextMenu open>
+          <ContextMenuTrigger aria-label="context trigger">Open</ContextMenuTrigger>
+          <ContextMenuContent>
+            <ContextMenuLinkItem
+              destructive={destructive}
+              href="https://example.com/docs"
+              aria-label="context docs link"
+              id={`context-link-${String(destructive)}`}
+              target="_blank"
+              rel="noopener noreferrer"
+            >
+              Docs
+            </ContextMenuLinkItem>
+          </ContextMenuContent>
+        </ContextMenu>,
+      )
+
+      const link = screen.getByRole('menuitem', { name: 'context docs link' })
+      expect(link.tagName.toLowerCase()).toBe('a')
+      expect(link).toHaveAttribute('id', `context-link-${String(destructive)}`)
+      expect(link).not.toHaveAttribute('destructive')
+    })
+  })
+
+  describe('ContextMenuLinkItem close behavior', () => {
+    it('should keep link semantics and not leak closeOnClick prop when closeOnClick is false', () => {
+      render(
+        <ContextMenu open>
+          <ContextMenuTrigger aria-label="context trigger">Open</ContextMenuTrigger>
+          <ContextMenuContent>
+            <ContextMenuLinkItem
+              href="https://example.com/docs"
+              closeOnClick={false}
+              aria-label="docs link"
+            >
+              Docs
+            </ContextMenuLinkItem>
+          </ContextMenuContent>
+        </ContextMenu>,
+      )
+
+      const link = screen.getByRole('menuitem', { name: 'docs link' })
+      expect(link.tagName.toLowerCase()).toBe('a')
+      expect(link).toHaveAttribute('href', 'https://example.com/docs')
+      expect(link).not.toHaveAttribute('closeOnClick')
+    })
+  })
+
+  describe('ContextMenuTrigger interaction', () => {
+    it('should open menu when right-clicking trigger area', () => {
+      render(
+        <ContextMenu>
+          <ContextMenuTrigger aria-label="context trigger area">
+            Trigger area
+          </ContextMenuTrigger>
+          <ContextMenuContent>
+            <ContextMenuItem>Open on right click</ContextMenuItem>
+          </ContextMenuContent>
+        </ContextMenu>,
+      )
+
+      const trigger = screen.getByLabelText('context trigger area')
+      fireEvent.contextMenu(trigger)
+      expect(screen.getByRole('menuitem', { name: 'Open on right click' })).toBeInTheDocument()
+    })
+  })
+
+  describe('ContextMenuSeparator', () => {
+    it('should render separator and keep surrounding rows when separator is between items', () => {
+      render(
+        <ContextMenu open>
+          <ContextMenuTrigger aria-label="context trigger">Open</ContextMenuTrigger>
+          <ContextMenuContent>
+            <ContextMenuItem>First action</ContextMenuItem>
+            <ContextMenuSeparator />
+            <ContextMenuItem>Second action</ContextMenuItem>
+          </ContextMenuContent>
+        </ContextMenu>,
+      )
+
+      expect(screen.getByRole('menuitem', { name: 'First action' })).toBeInTheDocument()
+      expect(screen.getByRole('menuitem', { name: 'Second action' })).toBeInTheDocument()
+      expect(screen.getAllByRole('separator')).toHaveLength(1)
+    })
+  })
+})

web/app/components/base/ui/context-menu/index.stories.tsx

@@ -0,0 +1,215 @@
+import type { Meta, StoryObj } from '@storybook/nextjs-vite'
+import { useState } from 'react'
+import {
+  ContextMenu,
+  ContextMenuCheckboxItem,
+  ContextMenuCheckboxItemIndicator,
+  ContextMenuContent,
+  ContextMenuGroup,
+  ContextMenuGroupLabel,
+  ContextMenuItem,
+  ContextMenuLinkItem,
+  ContextMenuRadioGroup,
+  ContextMenuRadioItem,
+  ContextMenuRadioItemIndicator,
+  ContextMenuSeparator,
+  ContextMenuSub,
+  ContextMenuSubContent,
+  ContextMenuSubTrigger,
+  ContextMenuTrigger,
+} from '.'
+
+const TriggerArea = ({ label = 'Right-click inside this area' }: { label?: string }) => (
+  <ContextMenuTrigger
+    aria-label="context menu trigger area"
+    render={<button type="button" className="flex h-44 w-80 select-none items-center justify-center rounded-xl border border-divider-subtle bg-background-default-subtle px-6 text-center text-sm text-text-tertiary" />}
+  >
+    {label}
+  </ContextMenuTrigger>
+)
+
+const meta = {
+  title: 'Base/Navigation/ContextMenu',
+  component: ContextMenu,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'Compound context menu built on Base UI ContextMenu. Open by right-clicking the trigger area.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof ContextMenu>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  render: () => (
+    <ContextMenu>
+      <TriggerArea />
+      <ContextMenuContent>
+        <ContextMenuItem>Edit</ContextMenuItem>
+        <ContextMenuItem>Duplicate</ContextMenuItem>
+        <ContextMenuItem>Archive</ContextMenuItem>
+      </ContextMenuContent>
+    </ContextMenu>
+  ),
+}
+
+export const WithSubmenu: Story = {
+  render: () => (
+    <ContextMenu>
+      <TriggerArea />
+      <ContextMenuContent>
+        <ContextMenuItem>Copy</ContextMenuItem>
+        <ContextMenuItem>Paste</ContextMenuItem>
+        <ContextMenuSeparator />
+        <ContextMenuSub>
+          <ContextMenuSubTrigger>Share</ContextMenuSubTrigger>
+          <ContextMenuSubContent>
+            <ContextMenuItem>Email</ContextMenuItem>
+            <ContextMenuItem>Slack</ContextMenuItem>
+            <ContextMenuItem>Copy link</ContextMenuItem>
+          </ContextMenuSubContent>
+        </ContextMenuSub>
+      </ContextMenuContent>
+    </ContextMenu>
+  ),
+}
+
+export const WithGroupLabel: Story = {
+  render: () => (
+    <ContextMenu>
+      <TriggerArea />
+      <ContextMenuContent>
+        <ContextMenuGroup>
+          <ContextMenuGroupLabel>Actions</ContextMenuGroupLabel>
+          <ContextMenuItem>Rename</ContextMenuItem>
+          <ContextMenuItem>Duplicate</ContextMenuItem>
+        </ContextMenuGroup>
+        <ContextMenuSeparator />
+        <ContextMenuGroup>
+          <ContextMenuGroupLabel>Danger Zone</ContextMenuGroupLabel>
+          <ContextMenuItem destructive>Delete</ContextMenuItem>
+        </ContextMenuGroup>
+      </ContextMenuContent>
+    </ContextMenu>
+  ),
+}
+
+const WithRadioItemsDemo = () => {
+  const [value, setValue] = useState('comfortable')
+
+  return (
+    <ContextMenu>
+      <TriggerArea label={`Right-click to set density: ${value}`} />
+      <ContextMenuContent>
+        <ContextMenuRadioGroup value={value} onValueChange={setValue}>
+          <ContextMenuRadioItem value="compact">
+            Compact
+            <ContextMenuRadioItemIndicator />
+          </ContextMenuRadioItem>
+          <ContextMenuRadioItem value="comfortable">
+            Comfortable
+            <ContextMenuRadioItemIndicator />
+          </ContextMenuRadioItem>
+          <ContextMenuRadioItem value="spacious">
+            Spacious
+            <ContextMenuRadioItemIndicator />
+          </ContextMenuRadioItem>
+        </ContextMenuRadioGroup>
+      </ContextMenuContent>
+    </ContextMenu>
+  )
+}
+
+export const WithRadioItems: Story = {
+  render: () => <WithRadioItemsDemo />,
+}
+
+const WithCheckboxItemsDemo = () => {
+  const [showToolbar, setShowToolbar] = useState(true)
+  const [showSidebar, setShowSidebar] = useState(false)
+  const [showStatusBar, setShowStatusBar] = useState(true)
+
+  return (
+    <ContextMenu>
+      <TriggerArea label="Right-click to configure panel visibility" />
+      <ContextMenuContent>
+        <ContextMenuCheckboxItem checked={showToolbar} onCheckedChange={setShowToolbar}>
+          Toolbar
+          <ContextMenuCheckboxItemIndicator />
+        </ContextMenuCheckboxItem>
+        <ContextMenuCheckboxItem checked={showSidebar} onCheckedChange={setShowSidebar}>
+          Sidebar
+          <ContextMenuCheckboxItemIndicator />
+        </ContextMenuCheckboxItem>
+        <ContextMenuCheckboxItem checked={showStatusBar} onCheckedChange={setShowStatusBar}>
+          Status bar
+          <ContextMenuCheckboxItemIndicator />
+        </ContextMenuCheckboxItem>
+      </ContextMenuContent>
+    </ContextMenu>
+  )
+}
+
+export const WithCheckboxItems: Story = {
+  render: () => <WithCheckboxItemsDemo />,
+}
+
+export const WithLinkItems: Story = {
+  render: () => (
+    <ContextMenu>
+      <TriggerArea label="Right-click to open links" />
+      <ContextMenuContent>
+        <ContextMenuLinkItem href="https://docs.dify.ai" rel="noopener noreferrer" target="_blank">
+          Dify Docs
+        </ContextMenuLinkItem>
+        <ContextMenuLinkItem href="https://roadmap.dify.ai" rel="noopener noreferrer" target="_blank">
+          Product Roadmap
+        </ContextMenuLinkItem>
+        <ContextMenuSeparator />
+        <ContextMenuLinkItem destructive href="https://example.com/delete" rel="noopener noreferrer" target="_blank">
+          Dangerous External Action
+        </ContextMenuLinkItem>
+      </ContextMenuContent>
+    </ContextMenu>
+  ),
+}
+
+export const Complex: Story = {
+  render: () => (
+    <ContextMenu>
+      <TriggerArea label="Right-click to inspect all menu capabilities" />
+      <ContextMenuContent>
+        <ContextMenuItem>
+          <span aria-hidden className="i-ri-pencil-line size-4 shrink-0 text-text-tertiary" />
+          Rename
+        </ContextMenuItem>
+        <ContextMenuItem>
+          <span aria-hidden className="i-ri-file-copy-line size-4 shrink-0 text-text-tertiary" />
+          Duplicate
+        </ContextMenuItem>
+        <ContextMenuSeparator />
+        <ContextMenuSub>
+          <ContextMenuSubTrigger>
+            <span aria-hidden className="i-ri-share-line size-4 shrink-0 text-text-tertiary" />
+            Share
+          </ContextMenuSubTrigger>
+          <ContextMenuSubContent>
+            <ContextMenuItem>Email</ContextMenuItem>
+            <ContextMenuItem>Slack</ContextMenuItem>
+            <ContextMenuItem>Copy Link</ContextMenuItem>
+          </ContextMenuSubContent>
+        </ContextMenuSub>
+        <ContextMenuSeparator />
+        <ContextMenuItem destructive>
+          <span aria-hidden className="i-ri-delete-bin-line size-4 shrink-0" />
+          Delete
+        </ContextMenuItem>
+      </ContextMenuContent>
+    </ContextMenu>
+  ),
+}

web/app/components/base/ui/context-menu/index.tsx

@@ -0,0 +1,302 @@
+'use client'
+
+import type { Placement } from '@/app/components/base/ui/placement'
+import { ContextMenu as BaseContextMenu } from '@base-ui/react/context-menu'
+import * as React from 'react'
+import {
+  menuBackdropClassName,
+  menuGroupLabelClassName,
+  menuIndicatorClassName,
+  menuPopupAnimationClassName,
+  menuPopupBaseClassName,
+  menuRowClassName,
+  menuSeparatorClassName,
+} from '@/app/components/base/ui/menu-shared'
+import { parsePlacement } from '@/app/components/base/ui/placement'
+import { cn } from '@/utils/classnames'
+
+export const ContextMenu = BaseContextMenu.Root
+export const ContextMenuTrigger = BaseContextMenu.Trigger
+export const ContextMenuPortal = BaseContextMenu.Portal
+export const ContextMenuBackdrop = BaseContextMenu.Backdrop
+export const ContextMenuSub = BaseContextMenu.SubmenuRoot
+export const ContextMenuGroup = BaseContextMenu.Group
+export const ContextMenuRadioGroup = BaseContextMenu.RadioGroup
+
+type ContextMenuContentProps = {
+  children: React.ReactNode
+  placement?: Placement
+  sideOffset?: number
+  alignOffset?: number
+  className?: string
+  popupClassName?: string
+  positionerProps?: Omit<
+    React.ComponentPropsWithoutRef<typeof BaseContextMenu.Positioner>,
+    'children' | 'className' | 'side' | 'align' | 'sideOffset' | 'alignOffset'
+  >
+  popupProps?: Omit<
+    React.ComponentPropsWithoutRef<typeof BaseContextMenu.Popup>,
+    'children' | 'className'
+  >
+}
+
+type ContextMenuPopupRenderProps = Required<Pick<ContextMenuContentProps, 'children'>> & {
+  placement: Placement
+  sideOffset: number
+  alignOffset: number
+  className?: string
+  popupClassName?: string
+  positionerProps?: ContextMenuContentProps['positionerProps']
+  popupProps?: ContextMenuContentProps['popupProps']
+  withBackdrop?: boolean
+}
+
+function renderContextMenuPopup({
+  children,
+  placement,
+  sideOffset,
+  alignOffset,
+  className,
+  popupClassName,
+  positionerProps,
+  popupProps,
+  withBackdrop = false,
+}: ContextMenuPopupRenderProps) {
+  const { side, align } = parsePlacement(placement)
+
+  return (
+    <BaseContextMenu.Portal>
+      {withBackdrop && (
+        <BaseContextMenu.Backdrop className={menuBackdropClassName} />
+      )}
+      <BaseContextMenu.Positioner
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        alignOffset={alignOffset}
+        className={cn('z-50 outline-none', className)}
+        {...positionerProps}
+      >
+        <BaseContextMenu.Popup
+          className={cn(
+            menuPopupBaseClassName,
+            menuPopupAnimationClassName,
+            popupClassName,
+          )}
+          {...popupProps}
+        >
+          {children}
+        </BaseContextMenu.Popup>
+      </BaseContextMenu.Positioner>
+    </BaseContextMenu.Portal>
+  )
+}
+
+export function ContextMenuContent({
+  children,
+  placement = 'bottom-start',
+  sideOffset = 0,
+  alignOffset = 0,
+  className,
+  popupClassName,
+  positionerProps,
+  popupProps,
+}: ContextMenuContentProps) {
+  return renderContextMenuPopup({
+    children,
+    placement,
+    sideOffset,
+    alignOffset,
+    className,
+    popupClassName,
+    positionerProps,
+    popupProps,
+    withBackdrop: true,
+  })
+}
+
+type ContextMenuItemProps = React.ComponentPropsWithoutRef<typeof BaseContextMenu.Item> & {
+  destructive?: boolean
+}
+
+export function ContextMenuItem({
+  className,
+  destructive,
+  ...props
+}: ContextMenuItemProps) {
+  return (
+    <BaseContextMenu.Item
+      className={cn(menuRowClassName, destructive && 'text-text-destructive', className)}
+      {...props}
+    />
+  )
+}
+
+type ContextMenuLinkItemProps = React.ComponentPropsWithoutRef<typeof BaseContextMenu.LinkItem> & {
+  destructive?: boolean
+}
+
+export function ContextMenuLinkItem({
+  className,
+  destructive,
+  closeOnClick = true,
+  ...props
+}: ContextMenuLinkItemProps) {
+  return (
+    <BaseContextMenu.LinkItem
+      className={cn(menuRowClassName, destructive && 'text-text-destructive', className)}
+      closeOnClick={closeOnClick}
+      {...props}
+    />
+  )
+}
+
+export function ContextMenuRadioItem({
+  className,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof BaseContextMenu.RadioItem>) {
+  return (
+    <BaseContextMenu.RadioItem
+      className={cn(menuRowClassName, className)}
+      {...props}
+    />
+  )
+}
+
+export function ContextMenuCheckboxItem({
+  className,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof BaseContextMenu.CheckboxItem>) {
+  return (
+    <BaseContextMenu.CheckboxItem
+      className={cn(menuRowClassName, className)}
+      {...props}
+    />
+  )
+}
+
+type ContextMenuIndicatorProps = Omit<React.ComponentPropsWithoutRef<'span'>, 'children'> & {
+  children?: React.ReactNode
+}
+
+export function ContextMenuItemIndicator({
+  className,
+  children,
+  ...props
+}: ContextMenuIndicatorProps) {
+  return (
+    <span
+      aria-hidden
+      className={cn(menuIndicatorClassName, className)}
+      {...props}
+    >
+      {children ?? <span aria-hidden className="i-ri-check-line h-4 w-4" />}
+    </span>
+  )
+}
+
+export function ContextMenuCheckboxItemIndicator({
+  className,
+  ...props
+}: Omit<React.ComponentPropsWithoutRef<typeof BaseContextMenu.CheckboxItemIndicator>, 'children'>) {
+  return (
+    <BaseContextMenu.CheckboxItemIndicator
+      className={cn(menuIndicatorClassName, className)}
+      {...props}
+    >
+      <span aria-hidden className="i-ri-check-line h-4 w-4" />
+    </BaseContextMenu.CheckboxItemIndicator>
+  )
+}
+
+export function ContextMenuRadioItemIndicator({
+  className,
+  ...props
+}: Omit<React.ComponentPropsWithoutRef<typeof BaseContextMenu.RadioItemIndicator>, 'children'>) {
+  return (
+    <BaseContextMenu.RadioItemIndicator
+      className={cn(menuIndicatorClassName, className)}
+      {...props}
+    >
+      <span aria-hidden className="i-ri-check-line h-4 w-4" />
+    </BaseContextMenu.RadioItemIndicator>
+  )
+}
+
+type ContextMenuSubTriggerProps = React.ComponentPropsWithoutRef<typeof BaseContextMenu.SubmenuTrigger> & {
+  destructive?: boolean
+}
+
+export function ContextMenuSubTrigger({
+  className,
+  destructive,
+  children,
+  ...props
+}: ContextMenuSubTriggerProps) {
+  return (
+    <BaseContextMenu.SubmenuTrigger
+      className={cn(menuRowClassName, destructive && 'text-text-destructive', className)}
+      {...props}
+    >
+      {children}
+      <span aria-hidden className="i-ri-arrow-right-s-line ml-auto size-4 shrink-0 text-text-tertiary" />
+    </BaseContextMenu.SubmenuTrigger>
+  )
+}
+
+type ContextMenuSubContentProps = {
+  children: React.ReactNode
+  placement?: Placement
+  sideOffset?: number
+  alignOffset?: number
+  className?: string
+  popupClassName?: string
+  positionerProps?: ContextMenuContentProps['positionerProps']
+  popupProps?: ContextMenuContentProps['popupProps']
+}
+
+export function ContextMenuSubContent({
+  children,
+  placement = 'right-start',
+  sideOffset = 4,
+  alignOffset = 0,
+  className,
+  popupClassName,
+  positionerProps,
+  popupProps,
+}: ContextMenuSubContentProps) {
+  return renderContextMenuPopup({
+    children,
+    placement,
+    sideOffset,
+    alignOffset,
+    className,
+    popupClassName,
+    positionerProps,
+    popupProps,
+  })
+}
+
+export function ContextMenuGroupLabel({
+  className,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof BaseContextMenu.GroupLabel>) {
+  return (
+    <BaseContextMenu.GroupLabel
+      className={cn(menuGroupLabelClassName, className)}
+      {...props}
+    />
+  )
+}
+
+export function ContextMenuSeparator({
+  className,
+  ...props
+}: React.ComponentPropsWithoutRef<typeof BaseContextMenu.Separator>) {
+  return (
+    <BaseContextMenu.Separator
+      className={cn(menuSeparatorClassName, className)}
+      {...props}
+    />
+  )
+}

web/app/components/base/ui/dropdown-menu/__tests__/index.spec.tsx

@@ -1,13 +1,12 @@
-import { Menu } from '@base-ui/react/menu'
+import type { ComponentPropsWithoutRef, ReactNode } from 'react'
 import { fireEvent, render, screen, within } from '@testing-library/react'
+import Link from 'next/link'
 import { describe, expect, it, vi } from 'vitest'
 import {
   DropdownMenu,
   DropdownMenuContent,
-  DropdownMenuGroup,
   DropdownMenuItem,
-  DropdownMenuPortal,
-  DropdownMenuRadioGroup,
+  DropdownMenuLinkItem,
   DropdownMenuSeparator,
   DropdownMenuSub,
   DropdownMenuSubContent,
@@ -15,18 +14,22 @@ import {
   DropdownMenuTrigger,
 } from '../index'
 
-describe('dropdown-menu wrapper', () => {
-  describe('alias exports', () => {
-    it('should map direct aliases to the corresponding Menu primitive when importing menu roots', () => {
-      expect(DropdownMenu).toBe(Menu.Root)
-      expect(DropdownMenuPortal).toBe(Menu.Portal)
-      expect(DropdownMenuTrigger).toBe(Menu.Trigger)
-      expect(DropdownMenuSub).toBe(Menu.SubmenuRoot)
-      expect(DropdownMenuGroup).toBe(Menu.Group)
-      expect(DropdownMenuRadioGroup).toBe(Menu.RadioGroup)
-    })
-  })
+vi.mock('next/link', () => ({
+  default: ({
+    href,
+    children,
+    ...props
+  }: {
+    href: string
+    children?: ReactNode
+  } & Omit<ComponentPropsWithoutRef<'a'>, 'href'>) => (
+    <a href={href} {...props}>
+      {children}
+    </a>
+  ),
+}))
 
+describe('dropdown-menu wrapper', () => {
   describe('DropdownMenuContent', () => {
     it('should position content at bottom-end with default placement when props are omitted', () => {
       render(
@@ -250,6 +253,99 @@ describe('dropdown-menu wrapper', () => {
     })
   })
 
+  describe('DropdownMenuLinkItem', () => {
+    it('should render as anchor and keep href/target attributes when link props are provided', () => {
+      render(
+        <DropdownMenu open>
+          <DropdownMenuTrigger aria-label="menu trigger">Open</DropdownMenuTrigger>
+          <DropdownMenuContent>
+            <DropdownMenuLinkItem href="https://example.com/docs" target="_blank" rel="noopener noreferrer">
+              Docs
+            </DropdownMenuLinkItem>
+          </DropdownMenuContent>
+        </DropdownMenu>,
+      )
+
+      const link = screen.getByRole('menuitem', { name: 'Docs' })
+      expect(link.tagName.toLowerCase()).toBe('a')
+      expect(link).toHaveAttribute('href', 'https://example.com/docs')
+      expect(link).toHaveAttribute('target', '_blank')
+      expect(link).toHaveAttribute('rel', 'noopener noreferrer')
+    })
+
+    it('should keep link semantics and not leak closeOnClick prop when closeOnClick is false', () => {
+      render(
+        <DropdownMenu open>
+          <DropdownMenuTrigger aria-label="menu trigger">Open</DropdownMenuTrigger>
+          <DropdownMenuContent>
+            <DropdownMenuLinkItem
+              href="https://example.com/docs"
+              closeOnClick={false}
+              aria-label="docs link"
+            >
+              Docs
+            </DropdownMenuLinkItem>
+          </DropdownMenuContent>
+        </DropdownMenu>,
+      )
+
+      const link = screen.getByRole('menuitem', { name: 'docs link' })
+      expect(link.tagName.toLowerCase()).toBe('a')
+      expect(link).toHaveAttribute('href', 'https://example.com/docs')
+      expect(link).not.toHaveAttribute('closeOnClick')
+    })
+
+    it('should preserve link semantics when render prop uses a custom link component', () => {
+      render(
+        <DropdownMenu open>
+          <DropdownMenuTrigger aria-label="menu trigger">Open</DropdownMenuTrigger>
+          <DropdownMenuContent>
+            <DropdownMenuLinkItem
+              render={<Link href="/account" />}
+              aria-label="account link"
+            >
+              Account settings
+            </DropdownMenuLinkItem>
+          </DropdownMenuContent>
+        </DropdownMenu>,
+      )
+
+      const link = screen.getByRole('menuitem', { name: 'account link' })
+      expect(link.tagName.toLowerCase()).toBe('a')
+      expect(link).toHaveAttribute('href', '/account')
+      expect(link).toHaveTextContent('Account settings')
+    })
+
+    it.each([true, false])('should remain interactive and not leak destructive prop when destructive is %s', (destructive) => {
+      const handleClick = vi.fn()
+
+      render(
+        <DropdownMenu open>
+          <DropdownMenuTrigger aria-label="menu trigger">Open</DropdownMenuTrigger>
+          <DropdownMenuContent>
+            <DropdownMenuLinkItem
+              destructive={destructive}
+              href="https://example.com/docs"
+              aria-label="docs link"
+              id={`menu-link-${String(destructive)}`}
+              onClick={handleClick}
+            >
+              Docs
+            </DropdownMenuLinkItem>
+          </DropdownMenuContent>
+        </DropdownMenu>,
+      )
+
+      const link = screen.getByRole('menuitem', { name: 'docs link' })
+      fireEvent.click(link)
+
+      expect(link.tagName.toLowerCase()).toBe('a')
+      expect(link).toHaveAttribute('id', `menu-link-${String(destructive)}`)
+      expect(link).not.toHaveAttribute('destructive')
+      expect(handleClick).toHaveBeenCalledTimes(1)
+    })
+  })
+
   describe('DropdownMenuSeparator', () => {
     it('should forward passthrough props and handlers when separator props are provided', () => {
       const handleMouseEnter = vi.fn()

web/app/components/base/ui/dropdown-menu/index.stories.tsx

@@ -8,6 +8,7 @@ import {
   DropdownMenuGroup,
   DropdownMenuGroupLabel,
   DropdownMenuItem,
+  DropdownMenuLinkItem,
   DropdownMenuRadioGroup,
   DropdownMenuRadioItem,
   DropdownMenuRadioItemIndicator,
@@ -234,6 +235,22 @@ export const WithIcons: Story = {
   ),
 }
 
+export const WithLinkItems: Story = {
+  render: () => (
+    <DropdownMenu>
+      <TriggerButton label="Open links" />
+      <DropdownMenuContent>
+        <DropdownMenuLinkItem href="https://docs.dify.ai" rel="noopener noreferrer" target="_blank">
+          Dify Docs
+        </DropdownMenuLinkItem>
+        <DropdownMenuLinkItem href="https://roadmap.dify.ai" rel="noopener noreferrer" target="_blank">
+          Product Roadmap
+        </DropdownMenuLinkItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  ),
+}
+
 const ComplexDemo = () => {
   const [sortOrder, setSortOrder] = useState('newest')
   const [showArchived, setShowArchived] = useState(false)

web/app/components/base/ui/dropdown-menu/index.tsx

@@ -3,6 +3,14 @@
 import type { Placement } from '@/app/components/base/ui/placement'
 import { Menu } from '@base-ui/react/menu'
 import * as React from 'react'
+import {
+  menuGroupLabelClassName,
+  menuIndicatorClassName,
+  menuPopupAnimationClassName,
+  menuPopupBaseClassName,
+  menuRowClassName,
+  menuSeparatorClassName,
+} from '@/app/components/base/ui/menu-shared'
 import { parsePlacement } from '@/app/components/base/ui/placement'
 import { cn } from '@/utils/classnames'
 
@@ -13,20 +21,13 @@ export const DropdownMenuSub = Menu.SubmenuRoot
 export const DropdownMenuGroup = Menu.Group
 export const DropdownMenuRadioGroup = Menu.RadioGroup
 
-const menuRowBaseClassName = 'mx-1 flex h-8 cursor-pointer select-none items-center gap-1 rounded-lg px-2 outline-none'
-const menuRowStateClassName = 'data-[highlighted]:bg-state-base-hover data-[disabled]:cursor-not-allowed data-[disabled]:opacity-30'
-
 export function DropdownMenuRadioItem({
   className,
   ...props
 }: React.ComponentPropsWithoutRef<typeof Menu.RadioItem>) {
   return (
     <Menu.RadioItem
-      className={cn(
-        menuRowBaseClassName,
-        menuRowStateClassName,
-        className,
-      )}
+      className={cn(menuRowClassName, className)}
       {...props}
     />
   )
@@ -38,10 +39,7 @@ export function DropdownMenuRadioItemIndicator({
 }: Omit<React.ComponentPropsWithoutRef<typeof Menu.RadioItemIndicator>, 'children'>) {
   return (
     <Menu.RadioItemIndicator
-      className={cn(
-        'ml-auto flex shrink-0 items-center text-text-accent',
-        className,
-      )}
+      className={cn(menuIndicatorClassName, className)}
       {...props}
     >
       <span aria-hidden className="i-ri-check-line h-4 w-4" />
@@ -55,11 +53,7 @@ export function DropdownMenuCheckboxItem({
 }: React.ComponentPropsWithoutRef<typeof Menu.CheckboxItem>) {
   return (
     <Menu.CheckboxItem
-      className={cn(
-        menuRowBaseClassName,
-        menuRowStateClassName,
-        className,
-      )}
+      className={cn(menuRowClassName, className)}
       {...props}
     />
   )
@@ -71,10 +65,7 @@ export function DropdownMenuCheckboxItemIndicator({
 }: Omit<React.ComponentPropsWithoutRef<typeof Menu.CheckboxItemIndicator>, 'children'>) {
   return (
     <Menu.CheckboxItemIndicator
-      className={cn(
-        'ml-auto flex shrink-0 items-center text-text-accent',
-        className,
-      )}
+      className={cn(menuIndicatorClassName, className)}
       {...props}
     >
       <span aria-hidden className="i-ri-check-line h-4 w-4" />
@@ -88,10 +79,7 @@ export function DropdownMenuGroupLabel({
 }: React.ComponentPropsWithoutRef<typeof Menu.GroupLabel>) {
   return (
     <Menu.GroupLabel
-      className={cn(
-        'px-3 pb-0.5 pt-1 text-text-tertiary system-xs-medium-uppercase',
-        className,
-      )}
+      className={cn(menuGroupLabelClassName, className)}
       {...props}
     />
   )
@@ -148,8 +136,8 @@ function renderDropdownMenuPopup({
       >
         <Menu.Popup
           className={cn(
-            'max-h-[var(--available-height)] overflow-y-auto overflow-x-hidden rounded-xl border-[0.5px] border-components-panel-border bg-components-panel-bg-blur py-1 text-sm text-text-secondary shadow-lg backdrop-blur-[5px]',
-            'origin-[var(--transform-origin)] transition-[transform,scale,opacity] data-[ending-style]:scale-95 data-[starting-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none',
+            menuPopupBaseClassName,
+            menuPopupAnimationClassName,
             popupClassName,
           )}
           {...popupProps}
@@ -195,12 +183,7 @@ export function DropdownMenuSubTrigger({
 }: DropdownMenuSubTriggerProps) {
   return (
     <Menu.SubmenuTrigger
-      className={cn(
-        menuRowBaseClassName,
-        menuRowStateClassName,
-        destructive && 'text-text-destructive',
-        className,
-      )}
+      className={cn(menuRowClassName, destructive && 'text-text-destructive', className)}
       {...props}
     >
       {children}
@@ -253,12 +236,26 @@ export function DropdownMenuItem({
 }: DropdownMenuItemProps) {
   return (
     <Menu.Item
-      className={cn(
-        menuRowBaseClassName,
-        menuRowStateClassName,
-        destructive && 'text-text-destructive',
-        className,
-      )}
+      className={cn(menuRowClassName, destructive && 'text-text-destructive', className)}
+      {...props}
+    />
+  )
+}
+
+type DropdownMenuLinkItemProps = React.ComponentPropsWithoutRef<typeof Menu.LinkItem> & {
+  destructive?: boolean
+}
+
+export function DropdownMenuLinkItem({
+  className,
+  destructive,
+  closeOnClick = true,
+  ...props
+}: DropdownMenuLinkItemProps) {
+  return (
+    <Menu.LinkItem
+      className={cn(menuRowClassName, destructive && 'text-text-destructive', className)}
+      closeOnClick={closeOnClick}
       {...props}
     />
   )
@@ -270,7 +267,7 @@ export function DropdownMenuSeparator({
 }: React.ComponentPropsWithoutRef<typeof Menu.Separator>) {
   return (
     <Menu.Separator
-      className={cn('my-1 h-px bg-divider-subtle', className)}
+      className={cn(menuSeparatorClassName, className)}
       {...props}
     />
   )

web/app/components/base/ui/menu-shared.ts

@@ -0,0 +1,7 @@
+export const menuRowClassName = 'mx-1 flex h-8 cursor-pointer select-none items-center gap-1 rounded-lg px-2 outline-none data-[highlighted]:bg-state-base-hover data-[disabled]:cursor-not-allowed data-[disabled]:opacity-30'
+export const menuIndicatorClassName = 'ml-auto flex shrink-0 items-center text-text-accent'
+export const menuGroupLabelClassName = 'px-3 pb-0.5 pt-1 text-text-tertiary system-xs-medium-uppercase'
+export const menuSeparatorClassName = 'my-1 h-px bg-divider-subtle'
+export const menuPopupBaseClassName = 'max-h-[var(--available-height)] overflow-y-auto overflow-x-hidden rounded-xl border-[0.5px] border-components-panel-border bg-components-panel-bg-blur py-1 text-sm text-text-secondary shadow-lg outline-none focus:outline-none focus-visible:outline-none backdrop-blur-[5px]'
+export const menuPopupAnimationClassName = 'origin-[var(--transform-origin)] transition-[transform,scale,opacity] data-[ending-style]:scale-95 data-[starting-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none'
+export const menuBackdropClassName = 'fixed inset-0 z-50 bg-transparent transition-opacity duration-150 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none'

web/app/components/header/account-dropdown/compliance.tsx

@@ -184,7 +184,7 @@ export default function Compliance() {
       <DropdownMenuSubContent
         popupClassName="w-[337px] divide-y divide-divider-subtle !bg-components-panel-bg-blur !py-0 backdrop-blur-sm"
       >
-        <DropdownMenuGroup className="p-1">
+        <DropdownMenuGroup className="py-1">
           <ComplianceDocRowItem
             icon={<Soc2 aria-hidden className="size-7 shrink-0" />}
             label={t('compliance.soc2Type1', { ns: 'common' })}

web/app/components/header/account-dropdown/index.tsx

@@ -9,7 +9,7 @@ import { resetUser } from '@/app/components/base/amplitude/utils'
 import Avatar from '@/app/components/base/avatar'
 import PremiumBadge from '@/app/components/base/premium-badge'
 import ThemeSwitcher from '@/app/components/base/theme-switcher'
-import { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger } from '@/app/components/base/ui/dropdown-menu'
+import { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLinkItem, DropdownMenuSeparator, DropdownMenuTrigger } from '@/app/components/base/ui/dropdown-menu'
 import { ACCOUNT_SETTING_TAB } from '@/app/components/header/account-setting/constants'
 import { IS_CLOUD_EDITION } from '@/config'
 import { useAppContext } from '@/context/app-context'
@@ -41,12 +41,12 @@ function AccountMenuRouteItem({
   trailing,
 }: AccountMenuRouteItemProps) {
   return (
-    <DropdownMenuItem
+    <DropdownMenuLinkItem
       className="justify-between"
       render={<Link href={href} />}
     >
       <MenuItemContent iconClassName={iconClassName} label={label} trailing={trailing} />
-    </DropdownMenuItem>
+    </DropdownMenuLinkItem>
   )
 }
 
@@ -64,12 +64,14 @@ function AccountMenuExternalItem({
   trailing,
 }: AccountMenuExternalItemProps) {
   return (
-    <DropdownMenuItem
+    <DropdownMenuLinkItem
       className="justify-between"
-      render={<a href={href} rel="noopener noreferrer" target="_blank" />}
+      href={href}
+      rel="noopener noreferrer"
+      target="_blank"
     >
       <MenuItemContent iconClassName={iconClassName} label={label} trailing={trailing} />
-    </DropdownMenuItem>
+    </DropdownMenuLinkItem>
   )
 }
 
@@ -101,7 +103,7 @@ type AccountMenuSectionProps = {
 }
 
 function AccountMenuSection({ children }: AccountMenuSectionProps) {
-  return <DropdownMenuGroup className="p-1">{children}</DropdownMenuGroup>
+  return <DropdownMenuGroup className="py-1">{children}</DropdownMenuGroup>
 }
 
 export default function AppSelector() {
@@ -144,8 +146,8 @@ export default function AppSelector() {
           sideOffset={6}
           popupClassName="w-60 max-w-80 !bg-components-panel-bg-blur !py-0 backdrop-blur-sm"
         >
-          <DropdownMenuGroup className="px-1 py-1">
-            <div className="flex flex-nowrap items-center py-2 pl-3 pr-2">
+          <DropdownMenuGroup className="py-1">
+            <div className="mx-1 flex flex-nowrap items-center py-2 pl-3 pr-2">
               <div className="grow">
                 <div className="break-all text-text-primary system-md-medium">
                   {userProfile.name}

web/app/components/header/account-dropdown/support.tsx

@@ -1,5 +1,5 @@
 import { useTranslation } from 'react-i18next'
-import { DropdownMenuGroup, DropdownMenuItem, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger } from '@/app/components/base/ui/dropdown-menu'
+import { DropdownMenuGroup, DropdownMenuItem, DropdownMenuLinkItem, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger } from '@/app/components/base/ui/dropdown-menu'
 import { toggleZendeskWindow } from '@/app/components/base/zendesk/utils'
 import { Plan } from '@/app/components/billing/type'
 import { SUPPORT_EMAIL_ADDRESS, ZENDESK_WIDGET_KEY } from '@/config'
@@ -31,7 +31,7 @@ export default function Support({ closeAccountDropdown }: SupportProps) {
       <DropdownMenuSubContent
         popupClassName="w-[216px] divide-y divide-divider-subtle !bg-components-panel-bg-blur !py-0 backdrop-blur-sm"
       >
-        <DropdownMenuGroup className="p-1">
+        <DropdownMenuGroup className="py-1">
           {hasDedicatedChannel && hasZendeskWidget && (
             <DropdownMenuItem
               className="justify-between"
@@ -47,37 +47,43 @@ export default function Support({ closeAccountDropdown }: SupportProps) {
             </DropdownMenuItem>
           )}
           {hasDedicatedChannel && !hasZendeskWidget && (
-            <DropdownMenuItem
+            <DropdownMenuLinkItem
               className="justify-between"
-              render={<a href={mailToSupport(userProfile.email, plan.type, langGeniusVersionInfo?.current_version, SUPPORT_EMAIL_ADDRESS)} rel="noopener noreferrer" target="_blank" />}
+              href={mailToSupport(userProfile.email, plan.type, langGeniusVersionInfo?.current_version, SUPPORT_EMAIL_ADDRESS)}
+              rel="noopener noreferrer"
+              target="_blank"
             >
               <MenuItemContent
                 iconClassName="i-ri-mail-send-line"
                 label={t('userProfile.emailSupport', { ns: 'common' })}
                 trailing={<ExternalLinkIndicator />}
               />
-            </DropdownMenuItem>
+            </DropdownMenuLinkItem>
           )}
-          <DropdownMenuItem
+          <DropdownMenuLinkItem
             className="justify-between"
-            render={<a href="https://forum.dify.ai/" rel="noopener noreferrer" target="_blank" />}
+            href="https://forum.dify.ai/"
+            rel="noopener noreferrer"
+            target="_blank"
           >
             <MenuItemContent
               iconClassName="i-ri-discuss-line"
               label={t('userProfile.forum', { ns: 'common' })}
               trailing={<ExternalLinkIndicator />}
             />
-          </DropdownMenuItem>
-          <DropdownMenuItem
+          </DropdownMenuLinkItem>
+          <DropdownMenuLinkItem
             className="justify-between"
-            render={<a href="https://discord.gg/5AEfbxcd9k" rel="noopener noreferrer" target="_blank" />}
+            href="https://discord.gg/5AEfbxcd9k"
+            rel="noopener noreferrer"
+            target="_blank"
           >
             <MenuItemContent
               iconClassName="i-ri-discord-line"
               label={t('userProfile.community', { ns: 'common' })}
               trailing={<ExternalLinkIndicator />}
             />
-          </DropdownMenuItem>
+          </DropdownMenuLinkItem>
         </DropdownMenuGroup>
       </DropdownMenuSubContent>
     </DropdownMenuSub>

web/app/components/workflow/block-selector/tool/action-item.tsx

@@ -111,11 +111,11 @@ const ToolItem: FC<Props> = ({
           })
         }}
       >
-        <div className={cn('system-sm-medium h-8 truncate border-l-2 border-divider-subtle pl-4 leading-8 text-text-secondary')}>
+        <div className={cn('truncate border-l-2 border-divider-subtle py-2 pl-4 text-text-secondary system-sm-medium')}>
           <span className={cn(disabled && 'opacity-30')}>{payload.label[language]}</span>
         </div>
         {isAdded && (
-          <div className="system-xs-regular mr-4 text-text-tertiary">{t('addToolModal.added', { ns: 'tools' })}</div>
+          <div className="mr-4 text-text-tertiary system-xs-regular">{t('addToolModal.added', { ns: 'tools' })}</div>
         )}
       </div>
     </Tooltip>

web/app/components/workflow/block-selector/trigger-plugin/action-item.tsx

@@ -77,11 +77,11 @@ const TriggerPluginActionItem: FC<Props> = ({
           })
         }}
       >
-        <div className={cn('system-sm-medium h-8 truncate border-l-2 border-divider-subtle pl-4 leading-8 text-text-secondary')}>
+        <div className={cn('truncate border-l-2 border-divider-subtle py-2 pl-4 text-text-secondary system-sm-medium')}>
           <span className={cn(disabled && 'opacity-30')}>{payload.label[language]}</span>
         </div>
         {isAdded && (
-          <div className="system-xs-regular mr-4 text-text-tertiary">{t('addToolModal.added', { ns: 'tools' })}</div>
+          <div className="mr-4 text-text-tertiary system-xs-regular">{t('addToolModal.added', { ns: 'tools' })}</div>
         )}
       </div>
     </Tooltip>

web/app/components/workflow/hooks/use-nodes-interactions.ts

@@ -1422,21 +1422,136 @@ export const useNodesInteractions = () => {
         extent: currentNode.extent,
         zIndex: currentNode.zIndex,
       })
-      const nodesConnectedSourceOrTargetHandleIdsMap
-        = getNodesConnectedSourceOrTargetHandleIdsMap(
-          connectedEdges.map(edge => ({ type: 'remove', edge })),
-          nodes,
-        )
-      const newNodes = produce(nodes, (draft) => {
+      const parentNode = nodes.find(node => node.id === currentNode.parentId)
+      const newNodeIsInIteration
+        = !!parentNode && parentNode.data.type === BlockEnum.Iteration
+      const newNodeIsInLoop
+        = !!parentNode && parentNode.data.type === BlockEnum.Loop
+      const outgoingEdges = connectedEdges.filter(
+        edge => edge.source === currentNodeId,
+      )
+      const normalizedSourceHandle = sourceHandle || 'source'
+      const outgoingHandles = new Set(
+        outgoingEdges.map(edge => edge.sourceHandle || 'source'),
+      )
+      const branchSourceHandle = currentNode.data._targetBranches?.[0]?.id
+      let outgoingHandleToPreserve = normalizedSourceHandle
+      if (!outgoingHandles.has(outgoingHandleToPreserve)) {
+        if (branchSourceHandle && outgoingHandles.has(branchSourceHandle))
+          outgoingHandleToPreserve = branchSourceHandle
+        else if (outgoingHandles.has('source'))
+          outgoingHandleToPreserve = 'source'
+        else
+          outgoingHandleToPreserve = outgoingEdges[0]?.sourceHandle || 'source'
+      }
+      const outgoingEdgesToPreserve = outgoingEdges.filter(
+        edge => (edge.sourceHandle || 'source') === outgoingHandleToPreserve,
+      )
+      const outgoingEdgeIds = new Set(
+        outgoingEdgesToPreserve.map(edge => edge.id),
+      )
+      const newNodeSourceHandle = newCurrentNode.data._targetBranches?.[0]?.id || 'source'
+      const reconnectedEdges = connectedEdges.reduce<Edge[]>(
+        (acc, edge) => {
+          if (outgoingEdgeIds.has(edge.id)) {
+            const originalTargetNode = nodes.find(
+              node => node.id === edge.target,
+            )
+            const targetNodeForEdge
+              = originalTargetNode && originalTargetNode.id !== currentNodeId
+                ? originalTargetNode
+                : newCurrentNode
+            if (!targetNodeForEdge)
+              return acc
+
+            const targetHandle = edge.targetHandle || 'target'
+            const targetParentNode
+              = targetNodeForEdge.id === newCurrentNode.id
+                ? parentNode || null
+                : nodes.find(node => node.id === targetNodeForEdge.parentId)
+                  || null
+            const isInIteration
+              = !!targetParentNode
+                && targetParentNode.data.type === BlockEnum.Iteration
+            const isInLoop
+              = !!targetParentNode
+                && targetParentNode.data.type === BlockEnum.Loop
+
+            acc.push({
+              ...edge,
+              id: `${newCurrentNode.id}-${newNodeSourceHandle}-${targetNodeForEdge.id}-${targetHandle}`,
+              source: newCurrentNode.id,
+              sourceHandle: newNodeSourceHandle,
+              target: targetNodeForEdge.id,
+              targetHandle,
+              type: CUSTOM_EDGE,
+              data: {
+                ...(edge.data || {}),
+                sourceType: newCurrentNode.data.type,
+                targetType: targetNodeForEdge.data.type,
+                isInIteration,
+                iteration_id: isInIteration
+                  ? targetNodeForEdge.parentId
+                  : undefined,
+                isInLoop,
+                loop_id: isInLoop ? targetNodeForEdge.parentId : undefined,
+                _connectedNodeIsSelected: false,
+              },
+              zIndex: targetNodeForEdge.parentId
+                ? isInIteration
+                  ? ITERATION_CHILDREN_Z_INDEX
+                  : LOOP_CHILDREN_Z_INDEX
+                : 0,
+            })
+          }
+
+          if (
+            edge.target === currentNodeId
+            && edge.source !== currentNodeId
+            && !outgoingEdgeIds.has(edge.id)
+          ) {
+            const sourceNode = nodes.find(node => node.id === edge.source)
+            if (!sourceNode)
+              return acc
+
+            const targetHandle = edge.targetHandle || 'target'
+            const sourceHandle = edge.sourceHandle || 'source'
+
+            acc.push({
+              ...edge,
+              id: `${sourceNode.id}-${sourceHandle}-${newCurrentNode.id}-${targetHandle}`,
+              source: sourceNode.id,
+              sourceHandle,
+              target: newCurrentNode.id,
+              targetHandle,
+              type: CUSTOM_EDGE,
+              data: {
+                ...(edge.data || {}),
+                sourceType: sourceNode.data.type,
+                targetType: newCurrentNode.data.type,
+                isInIteration: newNodeIsInIteration,
+                iteration_id: newNodeIsInIteration
+                  ? newCurrentNode.parentId
+                  : undefined,
+                isInLoop: newNodeIsInLoop,
+                loop_id: newNodeIsInLoop ? newCurrentNode.parentId : undefined,
+                _connectedNodeIsSelected: false,
+              },
+              zIndex: newCurrentNode.parentId
+                ? newNodeIsInIteration
+                  ? ITERATION_CHILDREN_Z_INDEX
+                  : LOOP_CHILDREN_Z_INDEX
+                : 0,
+            })
+          }
+
+          return acc
+        },
+        [],
+      )
+      const nodesWithNewNode = produce(nodes, (draft) => {
         draft.forEach((node) => {
           node.data.selected = false
-
-          if (nodesConnectedSourceOrTargetHandleIdsMap[node.id]) {
-            node.data = {
-              ...node.data,
-              ...nodesConnectedSourceOrTargetHandleIdsMap[node.id],
-            }
-          }
         })
         const index = draft.findIndex(node => node.id === currentNodeId)
 
@@ -1446,18 +1561,32 @@ export const useNodesInteractions = () => {
         if (newLoopStartNode)
           draft.push(newLoopStartNode)
       })
-      setNodes(newNodes)
-      const newEdges = produce(edges, (draft) => {
-        const filtered = draft.filter(
-          edge =>
-            !connectedEdges.find(
-              connectedEdge => connectedEdge.id === edge.id,
-            ),
+      const nodesConnectedSourceOrTargetHandleIdsMap
+        = getNodesConnectedSourceOrTargetHandleIdsMap(
+          [
+            ...connectedEdges.map(edge => ({ type: 'remove', edge })),
+            ...reconnectedEdges.map(edge => ({ type: 'add', edge })),
+          ],
+          nodesWithNewNode,
         )
-
-        return filtered
+      const newNodes = produce(nodesWithNewNode, (draft) => {
+        draft.forEach((node) => {
+          if (nodesConnectedSourceOrTargetHandleIdsMap[node.id]) {
+            node.data = {
+              ...node.data,
+              ...nodesConnectedSourceOrTargetHandleIdsMap[node.id],
+            }
+          }
+        })
       })
-      setEdges(newEdges)
+      setNodes(newNodes)
+      const remainingEdges = edges.filter(
+        edge =>
+          !connectedEdges.find(
+            connectedEdge => connectedEdge.id === edge.id,
+          ),
+      )
+      setEdges([...remainingEdges, ...reconnectedEdges])
       if (nodeType === BlockEnum.TriggerWebhook) {
         handleSyncWorkflowDraft(true, true, {
           onSuccess: () => autoGenerateWebhookUrl(newCurrentNode.id),
@@ -1606,6 +1735,7 @@ export const useNodesInteractions = () => {
       const offsetX = currentPosition.x - x
       const offsetY = currentPosition.y - y
       let idMapping: Record<string, string> = {}
+      const pastedNodesMap: Record<string, Node> = {}
       const parentChildrenToAppend: { parentId: string, childId: string, childType: BlockEnum }[] = []
       clipboardElements.forEach((nodeToPaste, index) => {
         const nodeType = nodeToPaste.data.type
@@ -1665,7 +1795,21 @@ export const useNodesInteractions = () => {
           newLoopStartNode!.parentId = newNode.id;
           (newNode.data as LoopNodeType).start_node_id = newLoopStartNode!.id
 
-          newChildren = handleNodeLoopChildrenCopy(nodeToPaste.id, newNode.id)
+          const oldLoopStartNode = nodes.find(
+            n =>
+              n.parentId === nodeToPaste.id
+              && n.type === CUSTOM_LOOP_START_NODE,
+          )
+          idMapping[oldLoopStartNode!.id] = newLoopStartNode!.id
+
+          const { copyChildren, newIdMapping }
+            = handleNodeLoopChildrenCopy(
+              nodeToPaste.id,
+              newNode.id,
+              idMapping,
+            )
+          newChildren = copyChildren
+          idMapping = newIdMapping
           newChildren.forEach((child) => {
             newNode.data._children?.push({
               nodeId: child.id,
@@ -1710,18 +1854,31 @@ export const useNodesInteractions = () => {
           }
         }
 
+        idMapping[nodeToPaste.id] = newNode.id
         nodesToPaste.push(newNode)
+        pastedNodesMap[newNode.id] = newNode
 
-        if (newChildren.length)
+        if (newChildren.length) {
+          newChildren.forEach((child) => {
+            pastedNodesMap[child.id] = child
+          })
           nodesToPaste.push(...newChildren)
+        }
       })
 
-      // only handle edge when paste nested block
+      // Rebuild edges where both endpoints are part of the pasted set.
       edges.forEach((edge) => {
         const sourceId = idMapping[edge.source]
         const targetId = idMapping[edge.target]
 
         if (sourceId && targetId) {
+          const sourceNode = pastedNodesMap[sourceId]
+          const targetNode = pastedNodesMap[targetId]
+          const parentNode = sourceNode?.parentId && sourceNode.parentId === targetNode?.parentId
+            ? pastedNodesMap[sourceNode.parentId] ?? nodes.find(n => n.id === sourceNode.parentId)
+            : null
+          const isInIteration = parentNode?.data.type === BlockEnum.Iteration
+          const isInLoop = parentNode?.data.type === BlockEnum.Loop
           const newEdge: Edge = {
             ...edge,
             id: `${sourceId}-${edge.sourceHandle}-${targetId}-${edge.targetHandle}`,
@@ -1729,8 +1886,19 @@ export const useNodesInteractions = () => {
             target: targetId,
             data: {
               ...edge.data,
+              isInIteration,
+              iteration_id: isInIteration ? parentNode?.id : undefined,
+              isInLoop,
+              loop_id: isInLoop ? parentNode?.id : undefined,
               _connectedNodeIsSelected: false,
             },
+            zIndex: parentNode
+              ? isInIteration
+                ? ITERATION_CHILDREN_Z_INDEX
+                : isInLoop
+                  ? LOOP_CHILDREN_Z_INDEX
+                  : 0
+              : 0,
           }
           edgesToPaste.push(newEdge)
         }

web/app/components/workflow/nodes/loop/use-interactions.ts

@@ -108,12 +108,13 @@ export const useNodeLoopInteractions = () => {
       handleNodeLoopRerender(parentId)
   }, [store, handleNodeLoopRerender])
 
-  const handleNodeLoopChildrenCopy = useCallback((nodeId: string, newNodeId: string) => {
+  const handleNodeLoopChildrenCopy = useCallback((nodeId: string, newNodeId: string, idMapping: Record<string, string>) => {
     const { getNodes } = store.getState()
     const nodes = getNodes()
     const childrenNodes = nodes.filter(n => n.parentId === nodeId && n.type !== CUSTOM_LOOP_START_NODE)
+    const newIdMapping = { ...idMapping }
 
-    return childrenNodes.map((child, index) => {
+    const copyChildren = childrenNodes.map((child, index) => {
       const childNodeType = child.data.type as BlockEnum
       const { defaultValue } = nodesMetaDataMap![childNodeType]
       const nodesWithSameType = nodes.filter(node => node.data.type === childNodeType)
@@ -139,8 +140,14 @@ export const useNodeLoopInteractions = () => {
         zIndex: LOOP_CHILDREN_Z_INDEX,
       })
       newNode.id = `${newNodeId}${newNode.id + index}`
+      newIdMapping[child.id] = newNode.id
       return newNode
     })
+
+    return {
+      copyChildren,
+      newIdMapping,
+    }
   }, [store, nodesMetaDataMap])
 
   return {

web/app/components/workflow/panel/chat-variable-panel/components/variable-modal.tsx

@@ -231,8 +231,6 @@ const ChatVariableModal = ({
     }
   }
 
-  const MAX_DESCRIPTION_LENGTH = 255
-
   const handleSave = () => {
     if (!checkVariableName(name))
       return
@@ -243,8 +241,6 @@ const ChatVariableModal = ({
     //   return notify({ type: 'error', message: 'value can not be empty' })
     if (type === ChatVarType.Object && objectValue.some(item => !item.key && !!item.value))
       return notify({ type: 'error', message: 'object key can not be empty' })
-    if (description.length > MAX_DESCRIPTION_LENGTH)
-      return notify({ type: 'error', message: t('chatVariable.modal.descriptionTooLong', { ns: 'workflow', maxLength: MAX_DESCRIPTION_LENGTH }) })
 
     onSave({
       id: chatVar ? chatVar.id : uuid4(),
@@ -277,7 +273,7 @@ const ChatVariableModal = ({
     <div
       className={cn('flex h-full w-[360px] flex-col rounded-2xl border-[0.5px] border-components-panel-border bg-components-panel-bg shadow-2xl', type === ChatVarType.Object && 'w-[480px]')}
     >
-      <div className="mb-3 flex shrink-0 items-center justify-between p-4 pb-0 text-text-primary system-xl-semibold">
+      <div className="system-xl-semibold mb-3 flex shrink-0 items-center justify-between p-4 pb-0 text-text-primary">
         {!chatVar ? t('chatVariable.modal.title', { ns: 'workflow' }) : t('chatVariable.modal.editTitle', { ns: 'workflow' })}
         <div className="flex items-center">
           <div
@@ -291,7 +287,7 @@ const ChatVariableModal = ({
       <div className="max-h-[480px] overflow-y-auto px-4 py-2">
         {/* name */}
         <div className="mb-4">
-          <div className="mb-1 flex h-6 items-center text-text-secondary system-sm-semibold">{t('chatVariable.modal.name', { ns: 'workflow' })}</div>
+          <div className="system-sm-semibold mb-1 flex h-6 items-center text-text-secondary">{t('chatVariable.modal.name', { ns: 'workflow' })}</div>
           <div className="flex">
             <Input
               placeholder={t('chatVariable.modal.namePlaceholder', { ns: 'workflow' }) || ''}
@@ -304,7 +300,7 @@ const ChatVariableModal = ({
         </div>
         {/* type */}
         <div className="mb-4">
-          <div className="mb-1 flex h-6 items-center text-text-secondary system-sm-semibold">{t('chatVariable.modal.type', { ns: 'workflow' })}</div>
+          <div className="system-sm-semibold mb-1 flex h-6 items-center text-text-secondary">{t('chatVariable.modal.type', { ns: 'workflow' })}</div>
           <div className="flex">
             <VariableTypeSelector
               value={type}
@@ -316,7 +312,7 @@ const ChatVariableModal = ({
         </div>
         {/* default value */}
         <div className="mb-4">
-          <div className="mb-1 flex h-6 items-center justify-between text-text-secondary system-sm-semibold">
+          <div className="system-sm-semibold mb-1 flex h-6 items-center justify-between text-text-secondary">
             <div>{t('chatVariable.modal.value', { ns: 'workflow' })}</div>
             {(type === ChatVarType.ArrayString || type === ChatVarType.ArrayNumber || type === ChatVarType.ArrayBoolean) && (
               <Button
@@ -345,7 +341,7 @@ const ChatVariableModal = ({
             {type === ChatVarType.String && (
               // Input will remove \n\r, so use Textarea just like description area
               <textarea
-                className="block h-20 w-full resize-none appearance-none rounded-lg border border-transparent bg-components-input-bg-normal p-2 text-components-input-text-filled caret-primary-600 outline-none system-sm-regular placeholder:text-components-input-text-placeholder placeholder:system-sm-regular hover:border-components-input-border-hover hover:bg-components-input-bg-hover focus:border-components-input-border-active focus:bg-components-input-bg-active focus:shadow-xs"
+                className="system-sm-regular placeholder:system-sm-regular block h-20 w-full resize-none appearance-none rounded-lg border border-transparent bg-components-input-bg-normal p-2 text-components-input-text-filled caret-primary-600 outline-none placeholder:text-components-input-text-placeholder hover:border-components-input-border-hover hover:bg-components-input-bg-hover focus:border-components-input-border-active focus:bg-components-input-bg-active focus:shadow-xs"
                 value={value}
                 placeholder={t('chatVariable.modal.valuePlaceholder', { ns: 'workflow' }) || ''}
                 onChange={e => setValue(e.target.value)}
@@ -408,20 +404,15 @@ const ChatVariableModal = ({
         </div>
         {/* description */}
         <div className="">
-          <div className="mb-1 flex h-6 items-center text-text-secondary system-sm-semibold">{t('chatVariable.modal.description', { ns: 'workflow' })}</div>
+          <div className="system-sm-semibold mb-1 flex h-6 items-center text-text-secondary">{t('chatVariable.modal.description', { ns: 'workflow' })}</div>
           <div className="flex">
             <textarea
-              className="block h-20 w-full resize-none appearance-none rounded-lg border border-transparent bg-components-input-bg-normal p-2 text-components-input-text-filled caret-primary-600 outline-none system-sm-regular placeholder:text-components-input-text-placeholder placeholder:system-sm-regular hover:border-components-input-border-hover hover:bg-components-input-bg-hover focus:border-components-input-border-active focus:bg-components-input-bg-active focus:shadow-xs"
+              className="system-sm-regular placeholder:system-sm-regular block h-20 w-full resize-none appearance-none rounded-lg border border-transparent bg-components-input-bg-normal p-2 text-components-input-text-filled caret-primary-600 outline-none placeholder:text-components-input-text-placeholder hover:border-components-input-border-hover hover:bg-components-input-bg-hover focus:border-components-input-border-active focus:bg-components-input-bg-active focus:shadow-xs"
               value={description}
               placeholder={t('chatVariable.modal.descriptionPlaceholder', { ns: 'workflow' }) || ''}
               onChange={e => setDescription(e.target.value)}
             />
           </div>
-          <div className={cn('mt-1 text-right system-xs-regular', description.length > MAX_DESCRIPTION_LENGTH ? 'text-text-destructive' : 'text-text-quaternary')}>
-            {description.length}
-            /
-            {MAX_DESCRIPTION_LENGTH}
-          </div>
         </div>
       </div>
       <div className="flex flex-row-reverse rounded-b-2xl p-4 pt-2">

web/docs/overlay-migration.md

@@ -16,6 +16,7 @@ This document tracks the migration away from legacy overlay APIs.
 - Replacement primitives:
   - `@/app/components/base/ui/tooltip`
   - `@/app/components/base/ui/dropdown-menu`
+  - `@/app/components/base/ui/context-menu`
   - `@/app/components/base/ui/popover`
   - `@/app/components/base/ui/dialog`
   - `@/app/components/base/ui/alert-dialog`

web/eslint-suppressions.json

@@ -6554,9 +6554,6 @@
   "app/components/workflow/block-selector/tool/action-item.tsx": {
     "no-restricted-imports": {
       "count": 1
-    },
-    "tailwindcss/enforce-consistent-class-order": {
-      "count": 2
     }
   },
   "app/components/workflow/block-selector/tool/tool-list-flat-view/list.tsx": {
@@ -6576,9 +6573,6 @@
     "no-restricted-imports": {
       "count": 1
     },
-    "tailwindcss/enforce-consistent-class-order": {
-      "count": 2
-    },
     "ts/no-explicit-any": {
       "count": 1
     }

web/i18n/en-US/workflow.json

@@ -90,7 +90,6 @@
   "chatVariable.modal.arrayValue": "Value",
   "chatVariable.modal.description": "Description",
   "chatVariable.modal.descriptionPlaceholder": "Describe the variable",
-  "chatVariable.modal.descriptionTooLong": "Description must be {{maxLength}} characters or less",
   "chatVariable.modal.editInForm": "Edit in Form",
   "chatVariable.modal.editInJSON": "Edit in JSON",
   "chatVariable.modal.editTitle": "Edit Conversation Variable",

web/i18n/zh-Hans/workflow.json

@@ -90,7 +90,6 @@
   "chatVariable.modal.arrayValue": "值",
   "chatVariable.modal.description": "描述",
   "chatVariable.modal.descriptionPlaceholder": "变量的描述",
-  "chatVariable.modal.descriptionTooLong": "描述不能超过 {{maxLength}} 个字符",
   "chatVariable.modal.editInForm": "在表单中编辑",
   "chatVariable.modal.editInJSON": "在 JSON 中编辑",
   "chatVariable.modal.editTitle": "编辑会话变量",

web/package.json

@@ -69,13 +69,13 @@
     "@formatjs/intl-localematcher": "0.5.10",
     "@headlessui/react": "2.2.1",
     "@heroicons/react": "2.2.0",
-    "@lexical/code": "0.38.2",
-    "@lexical/link": "0.38.2",
-    "@lexical/list": "0.38.2",
-    "@lexical/react": "0.38.2",
-    "@lexical/selection": "0.38.2",
-    "@lexical/text": "0.38.2",
-    "@lexical/utils": "0.39.0",
+    "@lexical/code": "0.41.0",
+    "@lexical/link": "0.41.0",
+    "@lexical/list": "0.41.0",
+    "@lexical/react": "0.41.0",
+    "@lexical/selection": "0.41.0",
+    "@lexical/text": "0.41.0",
+    "@lexical/utils": "0.41.0",
     "@monaco-editor/react": "4.7.0",
     "@octokit/core": "6.1.6",
     "@octokit/request-error": "6.1.8",
@@ -122,7 +122,7 @@
     "katex": "0.16.25",
     "ky": "1.12.0",
     "lamejs": "1.2.1",
-    "lexical": "0.38.2",
+    "lexical": "0.41.0",
     "mermaid": "11.11.0",
     "mime": "4.1.0",
     "mitt": "3.0.1",
@@ -216,7 +216,7 @@
     "@vitejs/plugin-react": "5.1.4",
     "@vitejs/plugin-rsc": "0.5.21",
     "@vitest/coverage-v8": "4.0.18",
-    "agentation": "2.2.1",
+    "agentation": "2.3.0",
     "autoprefixer": "10.4.21",
     "code-inspector-plugin": "1.4.2",
     "cross-env": "10.1.0",
@@ -243,7 +243,7 @@
     "tsx": "4.21.0",
     "typescript": "5.9.3",
     "uglify-js": "3.19.3",
-    "vinext": "https://pkg.pr.new/hyoban/vinext@556a6d6",
+    "vinext": "https://pkg.pr.new/vinext@1a2fd61",
     "vite": "8.0.0-beta.16",
     "vite-plugin-inspect": "11.3.3",
     "vite-tsconfig-paths": "6.1.1",
@@ -252,6 +252,7 @@
   },
   "pnpm": {
     "overrides": {
+      "@lexical/code": "npm:lexical-code-no-prism@0.41.0",
       "@monaco-editor/loader": "1.5.0",
       "@nolyfill/safe-buffer": "npm:safe-buffer@^5.2.1",
       "@stylistic/eslint-plugin": "https://pkg.pr.new/@stylistic/eslint-plugin@258f9d8",

web/pnpm-lock.yaml

@@ -5,6 +5,7 @@ settings:
   excludeLinksFromLockfile: false
 
 overrides:
+  '@lexical/code': npm:lexical-code-no-prism@0.41.0
   '@monaco-editor/loader': 1.5.0
   '@nolyfill/safe-buffer': npm:safe-buffer@^5.2.1
   '@stylistic/eslint-plugin': https://pkg.pr.new/@stylistic/eslint-plugin@258f9d8
@@ -79,26 +80,26 @@ importers:
         specifier: 2.2.0
         version: 2.2.0(react@19.2.4)
       '@lexical/code':
-        specifier: 0.38.2
-        version: 0.38.2
+        specifier: npm:lexical-code-no-prism@0.41.0
+        version: lexical-code-no-prism@0.41.0(@lexical/utils@0.41.0)(lexical@0.41.0)
       '@lexical/link':
-        specifier: 0.38.2
-        version: 0.38.2
+        specifier: 0.41.0
+        version: 0.41.0
       '@lexical/list':
-        specifier: 0.38.2
-        version: 0.38.2
+        specifier: 0.41.0
+        version: 0.41.0
       '@lexical/react':
-        specifier: 0.38.2
-        version: 0.38.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(yjs@13.6.29)
+        specifier: 0.41.0
+        version: 0.41.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(yjs@13.6.29)
       '@lexical/selection':
-        specifier: 0.38.2
-        version: 0.38.2
+        specifier: 0.41.0
+        version: 0.41.0
       '@lexical/text':
-        specifier: 0.38.2
-        version: 0.38.2
+        specifier: 0.41.0
+        version: 0.41.0
       '@lexical/utils':
-        specifier: 0.39.0
-        version: 0.39.0
+        specifier: 0.41.0
+        version: 0.41.0
       '@monaco-editor/react':
         specifier: 4.7.0
         version: 4.7.0(monaco-editor@0.55.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -238,8 +239,8 @@ importers:
         specifier: 1.2.1
         version: 1.2.1
       lexical:
-        specifier: 0.38.2
-        version: 0.38.2
+        specifier: 0.41.0
+        version: 0.41.0
       mermaid:
         specifier: 11.11.0
         version: 11.11.0
@@ -515,8 +516,8 @@ importers:
         specifier: 4.0.18
         version: 4.0.18(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       agentation:
-        specifier: 2.2.1
-        version: 2.2.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+        specifier: 2.3.0
+        version: 2.3.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       autoprefixer:
         specifier: 10.4.21
         version: 10.4.21(postcss@8.5.6)
@@ -596,8 +597,8 @@ importers:
         specifier: 3.19.3
         version: 3.19.3
       vinext:
-        specifier: https://pkg.pr.new/hyoban/vinext@556a6d6
-        version: https://pkg.pr.new/hyoban/vinext@556a6d6(next@16.1.5(@babel/core@7.28.6)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
+        specifier: https://pkg.pr.new/vinext@1a2fd61
+        version: https://pkg.pr.new/vinext@1a2fd61(next@16.1.5(@babel/core@7.28.6)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
       vite:
         specifier: 8.0.0-beta.16
         version: 8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
@@ -1682,98 +1683,74 @@ packages:
   '@jridgewell/trace-mapping@0.3.31':
     resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
 
-  '@lexical/clipboard@0.38.2':
-    resolution: {integrity: sha512-dDShUplCu8/o6BB9ousr3uFZ9bltR+HtleF/Tl8FXFNPpZ4AXhbLKUoJuucRuIr+zqT7RxEv/3M6pk/HEoE6NQ==}
+  '@lexical/clipboard@0.41.0':
+    resolution: {integrity: sha512-Ex5lPkb4NBBX1DCPzOAIeHBJFH1bJcmATjREaqpnTfxCbuOeQkt44wchezUA0oDl+iAxNZ3+pLLWiUju9icoSA==}
 
-  '@lexical/clipboard@0.39.0':
-    resolution: {integrity: sha512-ylrHy8M+I5EH4utwqivslugqQhvgLTz9VEJdrb2RjbhKQEXwMcqKCRWh6cRfkYx64onE2YQE0nRIdzHhExEpLQ==}
-
-  '@lexical/code@0.38.2':
-    resolution: {integrity: sha512-wpqgbmPsfi/+8SYP0zI2kml09fGPRhzO5litR9DIbbSGvcbawMbRNcKLO81DaTbsJRnBJiQvbBBBJAwZKRqgBw==}
-
-  '@lexical/devtools-core@0.38.2':
-    resolution: {integrity: sha512-hlN0q7taHNzG47xKynQLCAFEPOL8l6IP79C2M18/FE1+htqNP35q4rWhYhsptGlKo4me4PtiME7mskvr7T4yqA==}
+  '@lexical/devtools-core@0.41.0':
+    resolution: {integrity: sha512-FzJtluBhBc8bKS11TUZe72KoZN/hnzIyiiM0SPJAsPwGpoXuM01jqpXQGybWf/1bWB+bmmhOae7O4Nywi/Csuw==}
     peerDependencies:
       react: '>=17.x'
       react-dom: '>=17.x'
 
-  '@lexical/dragon@0.38.2':
-    resolution: {integrity: sha512-riOhgo+l4oN50RnLGhcqeUokVlMZRc+NDrxRNs2lyKSUdC4vAhAmAVUHDqYPyb4K4ZSw4ebZ3j8hI2zO4O3BbA==}
+  '@lexical/dragon@0.41.0':
+    resolution: {integrity: sha512-gBEqkk8Q6ZPruvDaRcOdF1EK9suCVBODzOCcR+EnoJTaTjfDkCM7pkPAm4w90Wa1wCZEtFHvCfas+jU9MDSumg==}
 
-  '@lexical/extension@0.38.2':
-    resolution: {integrity: sha512-qbUNxEVjAC0kxp7hEMTzktj0/51SyJoIJWK6Gm790b4yNBq82fEPkksfuLkRg9VQUteD0RT1Nkjy8pho8nNamw==}
+  '@lexical/extension@0.41.0':
+    resolution: {integrity: sha512-sF4SPiP72yXvIGchmmIZ7Yg2XZTxNLOpFEIIzdqG7X/1fa1Ham9P/T7VbrblWpF6Ei5LJtK9JgNVB0hb4l3o1g==}
 
-  '@lexical/extension@0.39.0':
-    resolution: {integrity: sha512-mp/WcF8E53FWPiUHgHQz382J7u7C4+cELYNkC00dKaymf8NhS6M65Y8tyDikNGNUcLXSzaluwK0HkiKjTYGhVQ==}
+  '@lexical/hashtag@0.41.0':
+    resolution: {integrity: sha512-tFWM74RW4KU0E/sj2aowfWl26vmLUTp331CgVESnhQKcZBfT40KJYd57HEqBDTfQKn4MUhylQCCA0hbpw6EeFQ==}
 
-  '@lexical/hashtag@0.38.2':
-    resolution: {integrity: sha512-jNI4Pv+plth39bjOeeQegMypkjDmoMWBMZtV0lCynBpkkPFlfMnyL9uzW/IxkZnX8LXWSw5mbWk07nqOUNTCrA==}
+  '@lexical/history@0.41.0':
+    resolution: {integrity: sha512-kGoVWsiOn62+RMjRolRa+NXZl8jFwxav6GNDiHH8yzivtoaH8n1SwUfLJELXCzeqzs81HySqD4q30VLJVTGoDg==}
 
-  '@lexical/history@0.38.2':
-    resolution: {integrity: sha512-QWPwoVDMe/oJ0+TFhy78TDi7TWU/8bcDRFUNk1nWgbq7+2m+5MMoj90LmOFwakQHnCVovgba2qj+atZrab1dsQ==}
+  '@lexical/html@0.41.0':
+    resolution: {integrity: sha512-3RyZy+H/IDKz2D66rNN/NqYx87xVFrngfEbyu1OWtbY963RUFnopiVHCQvsge/8kT04QSZ7U/DzjVFqeNS6clg==}
 
-  '@lexical/html@0.38.2':
-    resolution: {integrity: sha512-pC5AV+07bmHistRwgG3NJzBMlIzSdxYO6rJU4eBNzyR4becdiLsI4iuv+aY7PhfSv+SCs7QJ9oc4i5caq48Pkg==}
+  '@lexical/link@0.41.0':
+    resolution: {integrity: sha512-Rjtx5cGWAkKcnacncbVsZ1TqRnUB2Wm4eEVKpaAEG41+kHgqghzM2P+UGT15yROroxJu8KvAC9ISiYFiU4XE1w==}
 
-  '@lexical/html@0.39.0':
-    resolution: {integrity: sha512-7VLWP5DpzBg3kKctpNK6PbhymKAtU6NAnKieopCfCIWlMW+EqpldteiIXGqSqrMRK0JWTmF1gKgr9nnQyOOsXw==}
+  '@lexical/list@0.41.0':
+    resolution: {integrity: sha512-RXvB+xcbzVoQLGRDOBRCacztG7V+bI95tdoTwl8pz5xvgPtAaRnkZWMDP+yMNzMJZsqEChdtpxbf0NgtMkun6g==}
 
-  '@lexical/link@0.38.2':
-    resolution: {integrity: sha512-UOKTyYqrdCR9+7GmH6ZVqJTmqYefKGMUHMGljyGks+OjOGZAQs78S1QgcPEqltDy+SSdPSYK7wAo6gjxZfEq9g==}
+  '@lexical/mark@0.41.0':
+    resolution: {integrity: sha512-UO5WVs9uJAYIKHSlYh4Z1gHrBBchTOi21UCYBIZ7eAs4suK84hPzD+3/LAX5CB7ZltL6ke5Sly3FOwNXv/wfpA==}
 
-  '@lexical/list@0.38.2':
-    resolution: {integrity: sha512-OQm9TzatlMrDZGxMxbozZEHzMJhKxAbH1TOnOGyFfzpfjbnFK2y8oLeVsfQZfZRmiqQS4Qc/rpFnRP2Ax5dsbA==}
+  '@lexical/markdown@0.41.0':
+    resolution: {integrity: sha512-bzI73JMXpjGFhqUWNV6KqfjWcgAWzwFT+J3RHtbCF5rysC8HLldBYojOgAAtPfXqfxyv2mDzsY7SoJ75s9uHZA==}
 
-  '@lexical/list@0.39.0':
-    resolution: {integrity: sha512-mxgSxUrakTCHtC+gF30BChQBJTsCMiMgfC2H5VvhcFwXMgsKE/aK9+a+C/sSvvzCmPXqzYsuAcGkJcrY3e5xlw==}
+  '@lexical/offset@0.41.0':
+    resolution: {integrity: sha512-2RHBXZqC8gm3X9C0AyRb0M8w7zJu5dKiasrif+jSKzsxPjAUeF1m95OtIOsWs1XLNUgASOSUqGovDZxKJslZfA==}
 
-  '@lexical/mark@0.38.2':
-    resolution: {integrity: sha512-U+8KGwc3cP5DxSs15HfkP2YZJDs5wMbWQAwpGqep9bKphgxUgjPViKhdi+PxIt2QEzk7WcoZWUsK1d2ty/vSmg==}
+  '@lexical/overflow@0.41.0':
+    resolution: {integrity: sha512-Iy6ZiJip8X14EBYt1zKPOrXyQ4eG9JLBEoPoSVBTiSbVd+lYicdUvaOThT0k0/qeVTN9nqTaEltBjm56IrVKCQ==}
 
-  '@lexical/markdown@0.38.2':
-    resolution: {integrity: sha512-ykQJ9KUpCs1+Ak6ZhQMP6Slai4/CxfLEGg/rSHNVGbcd7OaH/ICtZN5jOmIe9ExfXMWy1o8PyMu+oAM3+AWFgA==}
+  '@lexical/plain-text@0.41.0':
+    resolution: {integrity: sha512-HIsGgmFUYRUNNyvckun33UQfU7LRzDlxymHUq67+Bxd5bXqdZOrStEKJXuDX+LuLh/GXZbaWNbDLqwLBObfbQg==}
 
-  '@lexical/offset@0.38.2':
-    resolution: {integrity: sha512-uDky2palcY+gE6WTv6q2umm2ioTUnVqcaWlEcchP6A310rI08n6rbpmkaLSIh3mT2GJQN2QcN2x0ct5BQmKIpA==}
-
-  '@lexical/overflow@0.38.2':
-    resolution: {integrity: sha512-f6vkTf+YZF0EuKvUK3goh4jrnF+Z0koiNMO+7rhSMLooc5IlD/4XXix4ZLiIktUWq4BhO84b82qtrO+6oPUxtw==}
-
-  '@lexical/plain-text@0.38.2':
-    resolution: {integrity: sha512-xRYNHJJFCbaQgr0uErW8Im2Phv1nWHIT4VSoAlBYqLuVGZBD4p61dqheBwqXWlGGJFk+MY5C5URLiMicgpol7A==}
-
-  '@lexical/react@0.38.2':
-    resolution: {integrity: sha512-M3z3MkWyw3Msg4Hojr5TnO4TzL71NVPVNGoavESjdgJbTdv1ezcQqjE4feq+qs7H9jytZeuK8wsEOJfSPmNd8w==}
+  '@lexical/react@0.41.0':
+    resolution: {integrity: sha512-7+GUdZUm6sofWm+zdsWAs6cFBwKNsvsHezZTrf6k8jrZxL461ZQmbz/16b4DvjCGL9r5P1fR7md9/LCmk8TiCg==}
     peerDependencies:
       react: '>=17.x'
       react-dom: '>=17.x'
 
-  '@lexical/rich-text@0.38.2':
-    resolution: {integrity: sha512-eFjeOT7YnDZYpty7Zlwlct0UxUSaYu53uLYG+Prs3NoKzsfEK7e7nYsy/BbQFfk5HoM1pYuYxFR2iIX62+YHGw==}
+  '@lexical/rich-text@0.41.0':
+    resolution: {integrity: sha512-yUcr7ZaaVTZNi8bow4CK1M8jy2qyyls1Vr+5dVjwBclVShOL/F/nFyzBOSb6RtXXRbd3Ahuk9fEleppX/RNIdw==}
 
-  '@lexical/selection@0.38.2':
-    resolution: {integrity: sha512-eMFiWlBH6bEX9U9sMJ6PXPxVXTrihQfFeiIlWLuTpEIDF2HRz7Uo1KFRC/yN6q0DQaj7d9NZYA6Mei5DoQuz5w==}
+  '@lexical/selection@0.41.0':
+    resolution: {integrity: sha512-1s7/kNyRzcv5uaTwsUL28NpiisqTf5xZ1zNukLsCN1xY+TWbv9RE9OxIv+748wMm4pxNczQe/UbIBODkbeknLw==}
 
-  '@lexical/selection@0.39.0':
-    resolution: {integrity: sha512-j0cgNuTKDCdf/4MzRnAUwEqG6C/WQp18k2WKmX5KIVZJlhnGIJmlgSBrxjo8AuZ16DIHxTm2XNB4cUDCgZNuPA==}
+  '@lexical/table@0.41.0':
+    resolution: {integrity: sha512-d3SPThBAr+oZ8O74TXU0iXM3rLbrAVC7/HcOnSAq7/AhWQW8yMutT51JQGN+0fMLP9kqoWSAojNtkdvzXfU/+A==}
 
-  '@lexical/table@0.38.2':
-    resolution: {integrity: sha512-uu0i7yz0nbClmHOO5ZFsinRJE6vQnFz2YPblYHAlNigiBedhqMwSv5bedrzDq8nTTHwych3mC63tcyKIrM+I1g==}
+  '@lexical/text@0.41.0':
+    resolution: {integrity: sha512-gGA+Anc7ck110EXo4KVKtq6Ui3M7Vz3OpGJ4QE6zJHWW8nV5h273koUGSutAMeoZgRVb6t01Izh3ORoFt/j1CA==}
 
-  '@lexical/table@0.39.0':
-    resolution: {integrity: sha512-1eH11kV4bJ0fufCYl8DpE19kHwqUI8Ev5CZwivfAtC3ntwyNkeEpjCc0pqeYYIWN/4rTZ5jgB3IJV4FntyfCzw==}
+  '@lexical/utils@0.41.0':
+    resolution: {integrity: sha512-Wlsokr5NQCq83D+7kxZ9qs5yQ3dU3Qaf2M+uXxLRoPoDaXqW8xTWZq1+ZFoEzsHzx06QoPa4Vu/40BZR91uQPg==}
 
-  '@lexical/text@0.38.2':
-    resolution: {integrity: sha512-+juZxUugtC4T37aE3P0l4I9tsWbogDUnTI/mgYk4Ht9g+gLJnhQkzSA8chIyfTxbj5i0A8yWrUUSw+/xA7lKUQ==}
-
-  '@lexical/utils@0.38.2':
-    resolution: {integrity: sha512-y+3rw15r4oAWIEXicUdNjfk8018dbKl7dWHqGHVEtqzAYefnEYdfD2FJ5KOTXfeoYfxi8yOW7FvzS4NZDi8Bfw==}
-
-  '@lexical/utils@0.39.0':
-    resolution: {integrity: sha512-8YChidpMJpwQc4nex29FKUeuZzC++QCS/Jt46lPuy1GS/BZQoPHFKQ5hyVvM9QVhc5CEs4WGNoaCZvZIVN8bQw==}
-
-  '@lexical/yjs@0.38.2':
-    resolution: {integrity: sha512-fg6ZHNrVQmy1AAxaTs8HrFbeNTJCaCoEDPi6pqypHQU3QVfqr4nq0L0EcHU/TRlR1CeduEPvZZIjUUxWTZ0u8g==}
+  '@lexical/yjs@0.41.0':
+    resolution: {integrity: sha512-PaKTxSbVC4fpqUjQ7vUL9RkNF1PjL8TFl5jRe03PqoPYpE33buf3VXX6+cOUEfv9+uknSqLCPHoBS/4jN3a97w==}
     peerDependencies:
       yjs: '>=13.5.22'
 
@@ -3705,8 +3682,8 @@ packages:
     resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
     engines: {node: '>= 14'}
 
-  agentation@2.2.1:
-    resolution: {integrity: sha512-yV9P1DggI7M3SRaRwLwt+xqE5lXqg5l8xtqCr8KzEkbnH8Wa6eRATU97uKnD7cC8FrsJP62Mmw0Xf5Xi5KV50Q==}
+  agentation@2.3.0:
+    resolution: {integrity: sha512-uGcDel78I5UAVSiWnsNv0pHj+ieuHyZ4GCsL6kqEralKeIW32869JlwfsKoy5S71jseyrI6O5duU+AacJs+CmQ==}
     peerDependencies:
       react: '>=18.0.0'
       react-dom: '>=18.0.0'
@@ -5632,11 +5609,14 @@ packages:
     resolution: {integrity: sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==}
     engines: {node: '>= 0.8.0'}
 
-  lexical@0.38.2:
-    resolution: {integrity: sha512-JJmfsG3c4gwBHzUGffbV7ifMNkKAWMCnYE3xJl87gty7hjyV5f3xq7eqTjP5HFYvO4XpjJvvWO2/djHp5S10tw==}
+  lexical-code-no-prism@0.41.0:
+    resolution: {integrity: sha512-cFgCC/VMXjch58iod4TIhBHb1bx7Da8IdduUwltua581dhLmugcaFnUvgC0naBaPeYVuirA6cuDsyOdPgEEDLA==}
+    peerDependencies:
+      '@lexical/utils': '>=0.28.0'
+      lexical: '>=0.28.0'
 
-  lexical@0.39.0:
-    resolution: {integrity: sha512-lpLv7MEJH5QDujEDlYqettL3ATVtNYjqyimzqgrm0RvCm3AO9WXSdsgTxuN7IAZRu88xkxCDeYubeUf4mNZVdg==}
+  lexical@0.41.0:
+    resolution: {integrity: sha512-pNIm5+n+hVnJHB9gYPDYsIO5Y59dNaDU9rJmPPsfqQhP2ojKFnUoPbcRnrI9FJLXB14sSumcY8LUw7Sq70TZqA==}
 
   lib0@0.2.117:
     resolution: {integrity: sha512-DeXj9X5xDCjgKLU/7RR+/HQEVzuuEUiwldwOGsHK/sfAfELGWEyTcf0x+uOvCvK3O2zPmZePXWL85vtia6GyZw==}
@@ -7524,8 +7504,8 @@ packages:
   vfile@6.0.3:
     resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==}
 
-  vinext@https://pkg.pr.new/hyoban/vinext@556a6d6:
-    resolution: {tarball: https://pkg.pr.new/hyoban/vinext@556a6d6}
+  vinext@https://pkg.pr.new/vinext@1a2fd61:
+    resolution: {integrity: sha512-5Q2iQExi1QQ/EpNcJ7TA6U9o4+kxJyaM/Ocobostt9IHqod6TOzhOx+ZSfmZr7eEVZq2joaIGY6Jl3dZ1dGNjg==, tarball: https://pkg.pr.new/vinext@1a2fd61}
     version: 0.0.5
     engines: {node: '>=22'}
     hasBin: true
@@ -9119,210 +9099,157 @@ snapshots:
       '@jridgewell/resolve-uri': 3.1.2
       '@jridgewell/sourcemap-codec': 1.5.5
 
-  '@lexical/clipboard@0.38.2':
+  '@lexical/clipboard@0.41.0':
     dependencies:
-      '@lexical/html': 0.38.2
-      '@lexical/list': 0.38.2
-      '@lexical/selection': 0.38.2
-      '@lexical/utils': 0.38.2
-      lexical: 0.38.2
+      '@lexical/html': 0.41.0
+      '@lexical/list': 0.41.0
+      '@lexical/selection': 0.41.0
+      '@lexical/utils': 0.41.0
+      lexical: 0.41.0
 
-  '@lexical/clipboard@0.39.0':
+  '@lexical/devtools-core@0.41.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
     dependencies:
-      '@lexical/html': 0.39.0
-      '@lexical/list': 0.39.0
-      '@lexical/selection': 0.39.0
-      '@lexical/utils': 0.39.0
-      lexical: 0.39.0
-
-  '@lexical/code@0.38.2':
-    dependencies:
-      '@lexical/utils': 0.38.2
-      lexical: 0.38.2
-      prismjs: 1.30.0
-
-  '@lexical/devtools-core@0.38.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
-    dependencies:
-      '@lexical/html': 0.38.2
-      '@lexical/link': 0.38.2
-      '@lexical/mark': 0.38.2
-      '@lexical/table': 0.38.2
-      '@lexical/utils': 0.38.2
-      lexical: 0.38.2
+      '@lexical/html': 0.41.0
+      '@lexical/link': 0.41.0
+      '@lexical/mark': 0.41.0
+      '@lexical/table': 0.41.0
+      '@lexical/utils': 0.41.0
+      lexical: 0.41.0
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
 
-  '@lexical/dragon@0.38.2':
+  '@lexical/dragon@0.41.0':
     dependencies:
-      '@lexical/extension': 0.38.2
-      lexical: 0.38.2
+      '@lexical/extension': 0.41.0
+      lexical: 0.41.0
 
-  '@lexical/extension@0.38.2':
+  '@lexical/extension@0.41.0':
     dependencies:
-      '@lexical/utils': 0.38.2
+      '@lexical/utils': 0.41.0
       '@preact/signals-core': 1.12.2
-      lexical: 0.38.2
+      lexical: 0.41.0
 
-  '@lexical/extension@0.39.0':
+  '@lexical/hashtag@0.41.0':
     dependencies:
-      '@lexical/utils': 0.39.0
-      '@preact/signals-core': 1.12.2
-      lexical: 0.39.0
+      '@lexical/text': 0.41.0
+      '@lexical/utils': 0.41.0
+      lexical: 0.41.0
 
-  '@lexical/hashtag@0.38.2':
+  '@lexical/history@0.41.0':
     dependencies:
-      '@lexical/text': 0.38.2
-      '@lexical/utils': 0.38.2
-      lexical: 0.38.2
+      '@lexical/extension': 0.41.0
+      '@lexical/utils': 0.41.0
+      lexical: 0.41.0
 
-  '@lexical/history@0.38.2':
+  '@lexical/html@0.41.0':
     dependencies:
-      '@lexical/extension': 0.38.2
-      '@lexical/utils': 0.38.2
-      lexical: 0.38.2
+      '@lexical/selection': 0.41.0
+      '@lexical/utils': 0.41.0
+      lexical: 0.41.0
 
-  '@lexical/html@0.38.2':
+  '@lexical/link@0.41.0':
     dependencies:
-      '@lexical/selection': 0.38.2
-      '@lexical/utils': 0.38.2
-      lexical: 0.38.2
+      '@lexical/extension': 0.41.0
+      '@lexical/utils': 0.41.0
+      lexical: 0.41.0
 
-  '@lexical/html@0.39.0':
+  '@lexical/list@0.41.0':
     dependencies:
-      '@lexical/selection': 0.39.0
-      '@lexical/utils': 0.39.0
-      lexical: 0.39.0
+      '@lexical/extension': 0.41.0
+      '@lexical/selection': 0.41.0
+      '@lexical/utils': 0.41.0
+      lexical: 0.41.0
 
-  '@lexical/link@0.38.2':
+  '@lexical/mark@0.41.0':
     dependencies:
-      '@lexical/extension': 0.38.2
-      '@lexical/utils': 0.38.2
-      lexical: 0.38.2
+      '@lexical/utils': 0.41.0
+      lexical: 0.41.0
 
-  '@lexical/list@0.38.2':
+  '@lexical/markdown@0.41.0':
     dependencies:
-      '@lexical/extension': 0.38.2
-      '@lexical/selection': 0.38.2
-      '@lexical/utils': 0.38.2
-      lexical: 0.38.2
+      '@lexical/code': lexical-code-no-prism@0.41.0(@lexical/utils@0.41.0)(lexical@0.41.0)
+      '@lexical/link': 0.41.0
+      '@lexical/list': 0.41.0
+      '@lexical/rich-text': 0.41.0
+      '@lexical/text': 0.41.0
+      '@lexical/utils': 0.41.0
+      lexical: 0.41.0
 
-  '@lexical/list@0.39.0':
+  '@lexical/offset@0.41.0':
     dependencies:
-      '@lexical/extension': 0.39.0
-      '@lexical/selection': 0.39.0
-      '@lexical/utils': 0.39.0
-      lexical: 0.39.0
+      lexical: 0.41.0
 
-  '@lexical/mark@0.38.2':
+  '@lexical/overflow@0.41.0':
     dependencies:
-      '@lexical/utils': 0.38.2
-      lexical: 0.38.2
+      lexical: 0.41.0
 
-  '@lexical/markdown@0.38.2':
+  '@lexical/plain-text@0.41.0':
     dependencies:
-      '@lexical/code': 0.38.2
-      '@lexical/link': 0.38.2
-      '@lexical/list': 0.38.2
-      '@lexical/rich-text': 0.38.2
-      '@lexical/text': 0.38.2
-      '@lexical/utils': 0.38.2
-      lexical: 0.38.2
+      '@lexical/clipboard': 0.41.0
+      '@lexical/dragon': 0.41.0
+      '@lexical/selection': 0.41.0
+      '@lexical/utils': 0.41.0
+      lexical: 0.41.0
 
-  '@lexical/offset@0.38.2':
-    dependencies:
-      lexical: 0.38.2
-
-  '@lexical/overflow@0.38.2':
-    dependencies:
-      lexical: 0.38.2
-
-  '@lexical/plain-text@0.38.2':
-    dependencies:
-      '@lexical/clipboard': 0.38.2
-      '@lexical/dragon': 0.38.2
-      '@lexical/selection': 0.38.2
-      '@lexical/utils': 0.38.2
-      lexical: 0.38.2
-
-  '@lexical/react@0.38.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(yjs@13.6.29)':
+  '@lexical/react@0.41.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(yjs@13.6.29)':
     dependencies:
       '@floating-ui/react': 0.27.16(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
-      '@lexical/devtools-core': 0.38.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
-      '@lexical/dragon': 0.38.2
-      '@lexical/extension': 0.38.2
-      '@lexical/hashtag': 0.38.2
-      '@lexical/history': 0.38.2
-      '@lexical/link': 0.38.2
-      '@lexical/list': 0.38.2
-      '@lexical/mark': 0.38.2
-      '@lexical/markdown': 0.38.2
-      '@lexical/overflow': 0.38.2
-      '@lexical/plain-text': 0.38.2
-      '@lexical/rich-text': 0.38.2
-      '@lexical/table': 0.38.2
-      '@lexical/text': 0.38.2
-      '@lexical/utils': 0.38.2
-      '@lexical/yjs': 0.38.2(yjs@13.6.29)
-      lexical: 0.38.2
+      '@lexical/devtools-core': 0.41.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@lexical/dragon': 0.41.0
+      '@lexical/extension': 0.41.0
+      '@lexical/hashtag': 0.41.0
+      '@lexical/history': 0.41.0
+      '@lexical/link': 0.41.0
+      '@lexical/list': 0.41.0
+      '@lexical/mark': 0.41.0
+      '@lexical/markdown': 0.41.0
+      '@lexical/overflow': 0.41.0
+      '@lexical/plain-text': 0.41.0
+      '@lexical/rich-text': 0.41.0
+      '@lexical/table': 0.41.0
+      '@lexical/text': 0.41.0
+      '@lexical/utils': 0.41.0
+      '@lexical/yjs': 0.41.0(yjs@13.6.29)
+      lexical: 0.41.0
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
       react-error-boundary: 6.1.0(react@19.2.4)
     transitivePeerDependencies:
       - yjs
 
-  '@lexical/rich-text@0.38.2':
+  '@lexical/rich-text@0.41.0':
     dependencies:
-      '@lexical/clipboard': 0.38.2
-      '@lexical/dragon': 0.38.2
-      '@lexical/selection': 0.38.2
-      '@lexical/utils': 0.38.2
-      lexical: 0.38.2
+      '@lexical/clipboard': 0.41.0
+      '@lexical/dragon': 0.41.0
+      '@lexical/selection': 0.41.0
+      '@lexical/utils': 0.41.0
+      lexical: 0.41.0
 
-  '@lexical/selection@0.38.2':
+  '@lexical/selection@0.41.0':
     dependencies:
-      lexical: 0.38.2
+      lexical: 0.41.0
 
-  '@lexical/selection@0.39.0':
+  '@lexical/table@0.41.0':
     dependencies:
-      lexical: 0.39.0
+      '@lexical/clipboard': 0.41.0
+      '@lexical/extension': 0.41.0
+      '@lexical/utils': 0.41.0
+      lexical: 0.41.0
 
-  '@lexical/table@0.38.2':
+  '@lexical/text@0.41.0':
     dependencies:
-      '@lexical/clipboard': 0.38.2
-      '@lexical/extension': 0.38.2
-      '@lexical/utils': 0.38.2
-      lexical: 0.38.2
+      lexical: 0.41.0
 
-  '@lexical/table@0.39.0':
+  '@lexical/utils@0.41.0':
     dependencies:
-      '@lexical/clipboard': 0.39.0
-      '@lexical/extension': 0.39.0
-      '@lexical/utils': 0.39.0
-      lexical: 0.39.0
+      '@lexical/selection': 0.41.0
+      lexical: 0.41.0
 
-  '@lexical/text@0.38.2':
+  '@lexical/yjs@0.41.0(yjs@13.6.29)':
     dependencies:
-      lexical: 0.38.2
-
-  '@lexical/utils@0.38.2':
-    dependencies:
-      '@lexical/list': 0.38.2
-      '@lexical/selection': 0.38.2
-      '@lexical/table': 0.38.2
-      lexical: 0.38.2
-
-  '@lexical/utils@0.39.0':
-    dependencies:
-      '@lexical/list': 0.39.0
-      '@lexical/selection': 0.39.0
-      '@lexical/table': 0.39.0
-      lexical: 0.39.0
-
-  '@lexical/yjs@0.38.2(yjs@13.6.29)':
-    dependencies:
-      '@lexical/offset': 0.38.2
-      '@lexical/selection': 0.38.2
-      lexical: 0.38.2
+      '@lexical/offset': 0.41.0
+      '@lexical/selection': 0.41.0
+      lexical: 0.41.0
       yjs: 13.6.29
 
   '@mdx-js/loader@3.1.1(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))':
@@ -11372,7 +11299,7 @@ snapshots:
 
   agent-base@7.1.4: {}
 
-  agentation@2.2.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
+  agentation@2.3.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
     optionalDependencies:
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
@@ -13529,9 +13456,12 @@ snapshots:
       prelude-ls: 1.2.1
       type-check: 0.4.0
 
-  lexical@0.38.2: {}
+  lexical-code-no-prism@0.41.0(@lexical/utils@0.41.0)(lexical@0.41.0):
+    dependencies:
+      '@lexical/utils': 0.41.0
+      lexical: 0.41.0
 
-  lexical@0.39.0: {}
+  lexical@0.41.0: {}
 
   lib0@0.2.117:
     dependencies:
@@ -15884,10 +15814,11 @@ snapshots:
       '@types/unist': 3.0.3
       vfile-message: 4.0.3
 
-  vinext@https://pkg.pr.new/hyoban/vinext@556a6d6(next@16.1.5(@babel/core@7.28.6)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3)):
+  vinext@https://pkg.pr.new/vinext@1a2fd61(next@16.1.5(@babel/core@7.28.6)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3)):
     dependencies:
       '@unpic/react': 1.0.2(next@16.1.5(@babel/core@7.28.6)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@vercel/og': 0.8.6
+      '@vitejs/plugin-react': 5.1.4(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       '@vitejs/plugin-rsc': 0.5.21(react-dom@19.2.4(react@19.2.4))(react-server-dom-webpack@19.2.4(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3)))(react@19.2.4)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       magic-string: 0.30.21
       react: 19.2.4

web/vite.config.ts

@@ -46,7 +46,6 @@ export default defineConfig(({ mode }) => {
               injectTarget: browserInitializerInjectTarget,
               projectRoot,
             }),
-            react(),
             vinext(),
             customI18nHmrPlugin({ injectTarget: browserInitializerInjectTarget }),
             // reactGrabOpenFilePlugin({
@@ -65,13 +64,6 @@ export default defineConfig(({ mode }) => {
       ? {
           optimizeDeps: {
             exclude: ['nuqs'],
-            // Make Prism in lexical works
-            // https://github.com/vitejs/rolldown-vite/issues/396
-            rolldownOptions: {
-              output: {
-                strictExecutionOrder: true,
-              },
-            },
           },
           server: {
             port: 3000,
@@ -80,15 +72,6 @@ export default defineConfig(({ mode }) => {
             // SyntaxError: Named export not found. The requested module is a CommonJS module, which may not support all module.exports as named exports
             noExternal: ['emoji-mart'],
           },
-          // Make Prism in lexical works
-          // https://github.com/vitejs/rolldown-vite/issues/396
-          build: {
-            rolldownOptions: {
-              output: {
-                strictExecutionOrder: true,
-              },
-            },
-          },
         }
       : {}),
 

web/vitest.setup.ts

@@ -80,6 +80,16 @@ if (typeof globalThis.IntersectionObserver === 'undefined') {
 if (typeof Element !== 'undefined' && !Element.prototype.scrollIntoView)
   Element.prototype.scrollIntoView = function () { /* noop */ }
 
+// Mock DOMRect.fromRect for tests (not available in jsdom)
+if (typeof DOMRect !== 'undefined' && typeof (DOMRect as typeof DOMRect & { fromRect?: unknown }).fromRect !== 'function') {
+  (DOMRect as typeof DOMRect & { fromRect: (rect?: DOMRectInit) => DOMRect }).fromRect = (rect = {}) => new DOMRect(
+    rect.x ?? 0,
+    rect.y ?? 0,
+    rect.width ?? 0,
+    rect.height ?? 0,
+  )
+}
+
 afterEach(async () => {
   // Wrap cleanup in act() to flush pending React scheduler work
   // This prevents "window is not defined" errors from React 19's scheduler