feat: Inject "Start" node for snippet before running the whole snippet workflow.

# Conflicts:
#	api/controllers/console/snippets/payloads.py
#	api/controllers/console/snippets/snippet_workflow.py
#	api/services/snippet_service.py

api/configs/feature/__init__.py

@@ -265,6 +265,11 @@ class PluginConfig(BaseSettings):
         default=60 * 60,
     )
 
+    PLUGIN_MAX_FILE_SIZE: PositiveInt = Field(
+        description="Maximum allowed size (bytes) for plugin-generated files",
+        default=50 * 1024 * 1024,
+    )
+
 
 class MarketplaceConfig(BaseSettings):
     """

api/configs/middleware/vdb/oceanbase_config.py

@@ -1,3 +1,5 @@
+from typing import Literal
+
 from pydantic import Field, PositiveInt
 from pydantic_settings import BaseSettings
 
@@ -49,3 +51,43 @@ class OceanBaseVectorConfig(BaseSettings):
         ),
         default="ik",
     )
+
+    OCEANBASE_VECTOR_BATCH_SIZE: PositiveInt = Field(
+        description="Number of documents to insert per batch",
+        default=100,
+    )
+
+    OCEANBASE_VECTOR_METRIC_TYPE: Literal["l2", "cosine", "inner_product"] = Field(
+        description="Distance metric type for vector index: l2, cosine, or inner_product",
+        default="l2",
+    )
+
+    OCEANBASE_HNSW_M: PositiveInt = Field(
+        description="HNSW M parameter (max number of connections per node)",
+        default=16,
+    )
+
+    OCEANBASE_HNSW_EF_CONSTRUCTION: PositiveInt = Field(
+        description="HNSW efConstruction parameter (index build-time search width)",
+        default=256,
+    )
+
+    OCEANBASE_HNSW_EF_SEARCH: int = Field(
+        description="HNSW efSearch parameter (query-time search width, -1 uses server default)",
+        default=-1,
+    )
+
+    OCEANBASE_VECTOR_POOL_SIZE: PositiveInt = Field(
+        description="SQLAlchemy connection pool size",
+        default=5,
+    )
+
+    OCEANBASE_VECTOR_MAX_OVERFLOW: int = Field(
+        description="SQLAlchemy connection pool max overflow connections",
+        default=10,
+    )
+
+    OCEANBASE_HNSW_REFRESH_THRESHOLD: int = Field(
+        description="Minimum number of inserted documents to trigger an automatic HNSW index refresh (0 to disable)",
+        default=1000,
+    )

api/controllers/console/__init__.py

@@ -116,6 +116,12 @@ from .explore import (
     trial,
 )
 
+# Import evaluation controllers
+from .evaluation import evaluation
+
+# Import snippet controllers
+from .snippets import snippet_workflow
+
 # Import tag controllers
 from .tag import tags
 
@@ -129,6 +135,7 @@ from .workspace import (
     model_providers,
     models,
     plugin,
+    snippets,
     tool_providers,
     trigger_providers,
     workspace,
@@ -166,6 +173,7 @@ __all__ = [
     "datasource_content_preview",
     "email_register",
     "endpoint",
+    "evaluation",
     "extension",
     "external",
     "feature",
@@ -199,6 +207,8 @@ __all__ = [
     "saved_message",
     "setup",
     "site",
+    "snippet_workflow",
+    "snippets",
     "spec",
     "statistic",
     "tags",

api/controllers/console/evaluation/__init__.py

@@ -0,0 +1 @@
+# Evaluation controller module

api/controllers/console/evaluation/evaluation.py

@@ -0,0 +1,320 @@
+import logging
+from collections.abc import Callable
+from functools import wraps
+from typing import ParamSpec, TypeVar, Union
+from urllib.parse import quote
+
+from flask import Response, request
+from flask_restx import Resource, fields
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+from werkzeug.exceptions import NotFound
+
+from controllers.common.schema import register_schema_models
+from controllers.console import console_ns
+from controllers.console.wraps import (
+    account_initialization_required,
+    edit_permission_required,
+    setup_required,
+)
+from core.file import helpers as file_helpers
+from extensions.ext_database import db
+from libs.helper import TimestampField
+from libs.login import current_account_with_tenant, login_required
+from models import App
+from models.model import UploadFile
+from models.snippet import CustomizedSnippet
+from services.evaluation_service import EvaluationService
+
+logger = logging.getLogger(__name__)
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+# Valid evaluation target types
+EVALUATE_TARGET_TYPES = {"app", "snippets"}
+
+
+class VersionQuery(BaseModel):
+    """Query parameters for version endpoint."""
+
+    version: str
+
+
+register_schema_models(
+    console_ns,
+    VersionQuery,
+)
+
+
+# Response field definitions
+file_info_fields = {
+    "id": fields.String,
+    "name": fields.String,
+}
+
+evaluation_log_fields = {
+    "created_at": TimestampField,
+    "created_by": fields.String,
+    "test_file": fields.Nested(
+        console_ns.model(
+            "EvaluationTestFile",
+            file_info_fields,
+        )
+    ),
+    "result_file": fields.Nested(
+        console_ns.model(
+            "EvaluationResultFile",
+            file_info_fields,
+        ),
+        allow_null=True,
+    ),
+    "version": fields.String,
+}
+
+evaluation_log_list_model = console_ns.model(
+    "EvaluationLogList",
+    {
+        "data": fields.List(fields.Nested(console_ns.model("EvaluationLog", evaluation_log_fields))),
+    },
+)
+
+customized_matrix_fields = {
+    "evaluation_workflow_id": fields.String,
+    "input_fields": fields.Raw,
+    "output_fields": fields.Raw,
+}
+
+condition_fields = {
+    "name": fields.List(fields.String),
+    "comparison_operator": fields.String,
+    "value": fields.String,
+}
+
+judgement_conditions_fields = {
+    "logical_operator": fields.String,
+    "conditions": fields.List(fields.Nested(console_ns.model("EvaluationCondition", condition_fields))),
+}
+
+evaluation_detail_fields = {
+    "evaluation_model": fields.String,
+    "evaluation_model_provider": fields.String,
+    "customized_matrix": fields.Nested(
+        console_ns.model("EvaluationCustomizedMatrix", customized_matrix_fields),
+        allow_null=True,
+    ),
+    "judgement_conditions": fields.Nested(
+        console_ns.model("EvaluationJudgementConditions", judgement_conditions_fields),
+        allow_null=True,
+    ),
+}
+
+evaluation_detail_model = console_ns.model("EvaluationDetail", evaluation_detail_fields)
+
+
+def get_evaluation_target(view_func: Callable[P, R]):
+    """
+    Decorator to resolve polymorphic evaluation target (app or snippet).
+
+    Validates the target_type parameter and fetches the corresponding
+    model (App or CustomizedSnippet) with tenant isolation.
+    """
+
+    @wraps(view_func)
+    def decorated_view(*args: P.args, **kwargs: P.kwargs):
+        target_type = kwargs.get("evaluate_target_type")
+        target_id = kwargs.get("evaluate_target_id")
+
+        if target_type not in EVALUATE_TARGET_TYPES:
+            raise NotFound(f"Invalid evaluation target type: {target_type}")
+
+        _, current_tenant_id = current_account_with_tenant()
+
+        target_id = str(target_id)
+
+        # Remove path parameters
+        del kwargs["evaluate_target_type"]
+        del kwargs["evaluate_target_id"]
+
+        target: Union[App, CustomizedSnippet] | None = None
+
+        if target_type == "app":
+            target = (
+                db.session.query(App).where(App.id == target_id, App.tenant_id == current_tenant_id).first()
+            )
+        elif target_type == "snippets":
+            target = (
+                db.session.query(CustomizedSnippet)
+                .where(CustomizedSnippet.id == target_id, CustomizedSnippet.tenant_id == current_tenant_id)
+                .first()
+            )
+
+        if not target:
+            raise NotFound(f"{str(target_type)} not found")
+
+        kwargs["target"] = target
+        kwargs["target_type"] = target_type
+
+        return view_func(*args, **kwargs)
+
+    return decorated_view
+
+
+@console_ns.route("/<string:evaluate_target_type>/<uuid:evaluate_target_id>/dataset-template/download")
+class EvaluationDatasetTemplateDownloadApi(Resource):
+    @console_ns.doc("download_evaluation_dataset_template")
+    @console_ns.response(200, "Template file streamed as XLSX attachment")
+    @console_ns.response(400, "Invalid target type or excluded app mode")
+    @console_ns.response(404, "Target not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_evaluation_target
+    @edit_permission_required
+    def post(self, target: Union[App, CustomizedSnippet], target_type: str):
+        """
+        Download evaluation dataset template.
+
+        Generates an XLSX template based on the target's input parameters
+        and streams it directly as a file attachment.
+        """
+        try:
+            xlsx_content, filename = EvaluationService.generate_dataset_template(
+                target=target,
+                target_type=target_type,
+            )
+        except ValueError as e:
+            return {"message": str(e)}, 400
+
+        encoded_filename = quote(filename)
+        response = Response(
+            xlsx_content,
+            mimetype="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        )
+        response.headers["Content-Disposition"] = f"attachment; filename*=UTF-8''{encoded_filename}"
+        response.headers["Content-Length"] = str(len(xlsx_content))
+        return response
+
+
+@console_ns.route("/<string:evaluate_target_type>/<uuid:evaluate_target_id>/evaluation")
+class EvaluationDetailApi(Resource):
+    @console_ns.doc("get_evaluation_detail")
+    @console_ns.response(200, "Evaluation details retrieved successfully", evaluation_detail_model)
+    @console_ns.response(404, "Target not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_evaluation_target
+    def get(self, target: Union[App, CustomizedSnippet], target_type: str):
+        """
+        Get evaluation details for the target.
+
+        Returns evaluation configuration including model settings,
+        customized matrix, and judgement conditions.
+        """
+        # TODO: Implement actual evaluation detail retrieval
+        # This is a placeholder implementation
+        return {
+            "evaluation_model": None,
+            "evaluation_model_provider": None,
+            "customized_matrix": None,
+            "judgement_conditions": None,
+        }
+
+
+@console_ns.route("/<string:evaluate_target_type>/<uuid:evaluate_target_id>/evaluation/logs")
+class EvaluationLogsApi(Resource):
+    @console_ns.doc("get_evaluation_logs")
+    @console_ns.response(200, "Evaluation logs retrieved successfully", evaluation_log_list_model)
+    @console_ns.response(404, "Target not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_evaluation_target
+    def get(self, target: Union[App, CustomizedSnippet], target_type: str):
+        """
+        Get offline evaluation logs for the target.
+
+        Returns a list of evaluation runs with test files,
+        result files, and version information.
+        """
+        # TODO: Implement actual evaluation logs retrieval
+        # This is a placeholder implementation
+        return {
+            "data": [],
+        }
+
+
+@console_ns.route("/<string:evaluate_target_type>/<uuid:evaluate_target_id>/evaluation/files/<uuid:file_id>")
+class EvaluationFileDownloadApi(Resource):
+    @console_ns.doc("download_evaluation_file")
+    @console_ns.response(200, "File download URL generated successfully")
+    @console_ns.response(404, "Target or file not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_evaluation_target
+    def get(self, target: Union[App, CustomizedSnippet], target_type: str, file_id: str):
+        """
+        Download evaluation test file or result file.
+
+        Looks up the specified file, verifies it belongs to the same tenant,
+        and returns file info and download URL.
+        """
+        file_id = str(file_id)
+        _, current_tenant_id = current_account_with_tenant()
+
+        with Session(db.engine, expire_on_commit=False) as session:
+            stmt = select(UploadFile).where(
+                UploadFile.id == file_id,
+                UploadFile.tenant_id == current_tenant_id,
+            )
+            upload_file = session.execute(stmt).scalar_one_or_none()
+
+        if not upload_file:
+            raise NotFound("File not found")
+
+        download_url = file_helpers.get_signed_file_url(upload_file_id=upload_file.id, as_attachment=True)
+
+        return {
+            "id": upload_file.id,
+            "name": upload_file.name,
+            "size": upload_file.size,
+            "extension": upload_file.extension,
+            "mime_type": upload_file.mime_type,
+            "created_at": int(upload_file.created_at.timestamp()) if upload_file.created_at else None,
+            "download_url": download_url,
+        }
+
+
+@console_ns.route("/<string:evaluate_target_type>/<uuid:evaluate_target_id>/evaluation/version")
+class EvaluationVersionApi(Resource):
+    @console_ns.doc("get_evaluation_version_detail")
+    @console_ns.expect(console_ns.models.get(VersionQuery.__name__))
+    @console_ns.response(200, "Version details retrieved successfully")
+    @console_ns.response(404, "Target or version not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_evaluation_target
+    def get(self, target: Union[App, CustomizedSnippet], target_type: str):
+        """
+        Get evaluation target version details.
+
+        Returns the workflow graph for the specified version.
+        """
+        version = request.args.get("version")
+
+        if not version:
+            return {"message": "version parameter is required"}, 400
+
+        # TODO: Implement actual version detail retrieval
+        # For now, return the current graph if available
+        graph = {}
+        if target_type == "snippets" and isinstance(target, CustomizedSnippet):
+            graph = target.graph_dict
+
+        return {
+            "graph": graph,
+        }

api/controllers/console/snippets/payloads.py

@@ -0,0 +1,102 @@
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class SnippetListQuery(BaseModel):
+    """Query parameters for listing snippets."""
+
+    page: int = Field(default=1, ge=1, le=99999)
+    limit: int = Field(default=20, ge=1, le=100)
+    keyword: str | None = None
+
+
+class IconInfo(BaseModel):
+    """Icon information model."""
+
+    icon: str | None = None
+    icon_type: Literal["emoji", "image"] | None = None
+    icon_background: str | None = None
+    icon_url: str | None = None
+
+
+class InputFieldDefinition(BaseModel):
+    """Input field definition for snippet parameters."""
+
+    default: str | None = None
+    hint: bool | None = None
+    label: str | None = None
+    max_length: int | None = None
+    options: list[str] | None = None
+    placeholder: str | None = None
+    required: bool | None = None
+    type: str | None = None  # e.g., "text-input"
+
+
+class CreateSnippetPayload(BaseModel):
+    """Payload for creating a new snippet."""
+
+    name: str = Field(..., min_length=1, max_length=255)
+    description: str | None = Field(default=None, max_length=2000)
+    type: Literal["node", "group"] = "node"
+    icon_info: IconInfo | None = None
+    graph: dict[str, Any] | None = None
+    input_fields: list[InputFieldDefinition] | None = Field(default_factory=list)
+
+
+class UpdateSnippetPayload(BaseModel):
+    """Payload for updating a snippet."""
+
+    name: str | None = Field(default=None, min_length=1, max_length=255)
+    description: str | None = Field(default=None, max_length=2000)
+    icon_info: IconInfo | None = None
+
+
+class SnippetDraftSyncPayload(BaseModel):
+    """Payload for syncing snippet draft workflow."""
+
+    graph: dict[str, Any]
+    hash: str | None = None
+    environment_variables: list[dict[str, Any]] | None = None
+    conversation_variables: list[dict[str, Any]] | None = None
+    input_variables: list[dict[str, Any]] | None = None
+
+
+class WorkflowRunQuery(BaseModel):
+    """Query parameters for workflow runs."""
+
+    last_id: str | None = None
+    limit: int = Field(default=20, ge=1, le=100)
+
+
+class SnippetDraftRunPayload(BaseModel):
+    """Payload for running snippet draft workflow."""
+
+    inputs: dict[str, Any]
+    files: list[dict[str, Any]] | None = None
+
+
+class SnippetDraftNodeRunPayload(BaseModel):
+    """Payload for running a single node in snippet draft workflow."""
+
+    inputs: dict[str, Any]
+    query: str = ""
+    files: list[dict[str, Any]] | None = None
+
+
+class SnippetIterationNodeRunPayload(BaseModel):
+    """Payload for running an iteration node in snippet draft workflow."""
+
+    inputs: dict[str, Any] | None = None
+
+
+class SnippetLoopNodeRunPayload(BaseModel):
+    """Payload for running a loop node in snippet draft workflow."""
+
+    inputs: dict[str, Any] | None = None
+
+
+class PublishWorkflowPayload(BaseModel):
+    """Payload for publishing snippet workflow."""
+
+    knowledge_base_setting: dict[str, Any] | None = None

api/controllers/console/snippets/snippet_workflow.py

@@ -0,0 +1,540 @@
+import logging
+from collections.abc import Callable
+from functools import wraps
+from typing import ParamSpec, TypeVar
+
+from flask import request
+from flask_restx import Resource, marshal_with
+from sqlalchemy.orm import Session
+from werkzeug.exceptions import InternalServerError, NotFound
+
+from controllers.common.schema import register_schema_models
+from controllers.console import console_ns
+from controllers.console.app.error import DraftWorkflowNotExist, DraftWorkflowNotSync
+from controllers.console.app.workflow import workflow_model
+from controllers.console.app.workflow_run import (
+    workflow_run_detail_model,
+    workflow_run_node_execution_list_model,
+    workflow_run_node_execution_model,
+    workflow_run_pagination_model,
+)
+from controllers.console.snippets.payloads import (
+    PublishWorkflowPayload,
+    SnippetDraftNodeRunPayload,
+    SnippetDraftRunPayload,
+    SnippetDraftSyncPayload,
+    SnippetIterationNodeRunPayload,
+    SnippetLoopNodeRunPayload,
+    WorkflowRunQuery,
+)
+from controllers.console.wraps import (
+    account_initialization_required,
+    edit_permission_required,
+    setup_required,
+)
+from core.app.apps.base_app_queue_manager import AppQueueManager
+from core.app.entities.app_invoke_entities import InvokeFrom
+from core.workflow.graph_engine.manager import GraphEngineManager
+from extensions.ext_database import db
+from factories import variable_factory
+from libs import helper
+from libs.helper import TimestampField
+from libs.login import current_account_with_tenant, login_required
+from models.snippet import CustomizedSnippet
+from services.errors.app import WorkflowHashNotEqualError
+from services.snippet_generate_service import SnippetGenerateService
+from services.snippet_service import SnippetService
+
+logger = logging.getLogger(__name__)
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+# Register Pydantic models with Swagger
+register_schema_models(
+    console_ns,
+    SnippetDraftSyncPayload,
+    SnippetDraftNodeRunPayload,
+    SnippetDraftRunPayload,
+    SnippetIterationNodeRunPayload,
+    SnippetLoopNodeRunPayload,
+    WorkflowRunQuery,
+    PublishWorkflowPayload,
+)
+
+
+class SnippetNotFoundError(Exception):
+    """Snippet not found error."""
+
+    pass
+
+
+def get_snippet(view_func: Callable[P, R]):
+    """Decorator to fetch and validate snippet access."""
+
+    @wraps(view_func)
+    def decorated_view(*args: P.args, **kwargs: P.kwargs):
+        if not kwargs.get("snippet_id"):
+            raise ValueError("missing snippet_id in path parameters")
+
+        _, current_tenant_id = current_account_with_tenant()
+
+        snippet_id = str(kwargs.get("snippet_id"))
+        del kwargs["snippet_id"]
+
+        snippet = SnippetService.get_snippet_by_id(
+            snippet_id=snippet_id,
+            tenant_id=current_tenant_id,
+        )
+
+        if not snippet:
+            raise NotFound("Snippet not found")
+
+        kwargs["snippet"] = snippet
+
+        return view_func(*args, **kwargs)
+
+    return decorated_view
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft")
+class SnippetDraftWorkflowApi(Resource):
+    @console_ns.doc("get_snippet_draft_workflow")
+    @console_ns.response(200, "Draft workflow retrieved successfully", workflow_model)
+    @console_ns.response(404, "Snippet or draft workflow not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    @marshal_with(workflow_model)
+    def get(self, snippet: CustomizedSnippet):
+        """Get draft workflow for snippet."""
+        snippet_service = SnippetService()
+        workflow = snippet_service.get_draft_workflow(snippet=snippet)
+
+        if not workflow:
+            raise DraftWorkflowNotExist()
+
+        return workflow
+
+    @console_ns.doc("sync_snippet_draft_workflow")
+    @console_ns.expect(console_ns.models.get(SnippetDraftSyncPayload.__name__))
+    @console_ns.response(200, "Draft workflow synced successfully")
+    @console_ns.response(400, "Hash mismatch")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet):
+        """Sync draft workflow for snippet."""
+        current_user, _ = current_account_with_tenant()
+
+        payload = SnippetDraftSyncPayload.model_validate(console_ns.payload or {})
+
+        try:
+            environment_variables_list = payload.environment_variables or []
+            environment_variables = [
+                variable_factory.build_environment_variable_from_mapping(obj) for obj in environment_variables_list
+            ]
+            conversation_variables_list = payload.conversation_variables or []
+            conversation_variables = [
+                variable_factory.build_conversation_variable_from_mapping(obj) for obj in conversation_variables_list
+            ]
+            snippet_service = SnippetService()
+            workflow = snippet_service.sync_draft_workflow(
+                snippet=snippet,
+                graph=payload.graph,
+                unique_hash=payload.hash,
+                account=current_user,
+                environment_variables=environment_variables,
+                conversation_variables=conversation_variables,
+                input_variables=payload.input_variables,
+            )
+        except WorkflowHashNotEqualError:
+            raise DraftWorkflowNotSync()
+
+        return {
+            "result": "success",
+            "hash": workflow.unique_hash,
+            "updated_at": TimestampField().format(workflow.updated_at or workflow.created_at),
+        }
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/config")
+class SnippetDraftConfigApi(Resource):
+    @console_ns.doc("get_snippet_draft_config")
+    @console_ns.response(200, "Draft config retrieved successfully")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def get(self, snippet: CustomizedSnippet):
+        """Get snippet draft workflow configuration limits."""
+        return {
+            "parallel_depth_limit": 3,
+        }
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/publish")
+class SnippetPublishedWorkflowApi(Resource):
+    @console_ns.doc("get_snippet_published_workflow")
+    @console_ns.response(200, "Published workflow retrieved successfully", workflow_model)
+    @console_ns.response(404, "Snippet not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    @marshal_with(workflow_model)
+    def get(self, snippet: CustomizedSnippet):
+        """Get published workflow for snippet."""
+        if not snippet.is_published:
+            return None
+
+        snippet_service = SnippetService()
+        workflow = snippet_service.get_published_workflow(snippet=snippet)
+
+        return workflow
+
+    @console_ns.doc("publish_snippet_workflow")
+    @console_ns.expect(console_ns.models.get(PublishWorkflowPayload.__name__))
+    @console_ns.response(200, "Workflow published successfully")
+    @console_ns.response(400, "No draft workflow found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet):
+        """Publish snippet workflow."""
+        current_user, _ = current_account_with_tenant()
+        snippet_service = SnippetService()
+
+        with Session(db.engine) as session:
+            snippet = session.merge(snippet)
+            try:
+                workflow = snippet_service.publish_workflow(
+                    session=session,
+                    snippet=snippet,
+                    account=current_user,
+                )
+                workflow_created_at = TimestampField().format(workflow.created_at)
+                session.commit()
+            except ValueError as e:
+                return {"message": str(e)}, 400
+
+        return {
+            "result": "success",
+            "created_at": workflow_created_at,
+        }
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/default-workflow-block-configs")
+class SnippetDefaultBlockConfigsApi(Resource):
+    @console_ns.doc("get_snippet_default_block_configs")
+    @console_ns.response(200, "Default block configs retrieved successfully")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def get(self, snippet: CustomizedSnippet):
+        """Get default block configurations for snippet workflow."""
+        snippet_service = SnippetService()
+        return snippet_service.get_default_block_configs()
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflow-runs")
+class SnippetWorkflowRunsApi(Resource):
+    @console_ns.doc("list_snippet_workflow_runs")
+    @console_ns.response(200, "Workflow runs retrieved successfully", workflow_run_pagination_model)
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @marshal_with(workflow_run_pagination_model)
+    def get(self, snippet: CustomizedSnippet):
+        """List workflow runs for snippet."""
+        query = WorkflowRunQuery.model_validate(
+            {
+                "last_id": request.args.get("last_id"),
+                "limit": request.args.get("limit", type=int, default=20),
+            }
+        )
+        args = {
+            "last_id": query.last_id,
+            "limit": query.limit,
+        }
+
+        snippet_service = SnippetService()
+        result = snippet_service.get_snippet_workflow_runs(snippet=snippet, args=args)
+
+        return result
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflow-runs/<uuid:run_id>")
+class SnippetWorkflowRunDetailApi(Resource):
+    @console_ns.doc("get_snippet_workflow_run_detail")
+    @console_ns.response(200, "Workflow run detail retrieved successfully", workflow_run_detail_model)
+    @console_ns.response(404, "Workflow run not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @marshal_with(workflow_run_detail_model)
+    def get(self, snippet: CustomizedSnippet, run_id):
+        """Get workflow run detail for snippet."""
+        run_id = str(run_id)
+
+        snippet_service = SnippetService()
+        workflow_run = snippet_service.get_snippet_workflow_run(snippet=snippet, run_id=run_id)
+
+        if not workflow_run:
+            raise NotFound("Workflow run not found")
+
+        return workflow_run
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflow-runs/<uuid:run_id>/node-executions")
+class SnippetWorkflowRunNodeExecutionsApi(Resource):
+    @console_ns.doc("list_snippet_workflow_run_node_executions")
+    @console_ns.response(200, "Node executions retrieved successfully", workflow_run_node_execution_list_model)
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @marshal_with(workflow_run_node_execution_list_model)
+    def get(self, snippet: CustomizedSnippet, run_id):
+        """List node executions for a workflow run."""
+        run_id = str(run_id)
+
+        snippet_service = SnippetService()
+        node_executions = snippet_service.get_snippet_workflow_run_node_executions(
+            snippet=snippet,
+            run_id=run_id,
+        )
+
+        return {"data": node_executions}
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/nodes/<string:node_id>/run")
+class SnippetDraftNodeRunApi(Resource):
+    @console_ns.doc("run_snippet_draft_node")
+    @console_ns.doc(description="Run a single node in snippet draft workflow (single-step debugging)")
+    @console_ns.doc(params={"snippet_id": "Snippet ID", "node_id": "Node ID"})
+    @console_ns.expect(console_ns.models.get(SnippetDraftNodeRunPayload.__name__))
+    @console_ns.response(200, "Node run completed successfully", workflow_run_node_execution_model)
+    @console_ns.response(404, "Snippet or draft workflow not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @marshal_with(workflow_run_node_execution_model)
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet, node_id: str):
+        """
+        Run a single node in snippet draft workflow.
+
+        Executes a specific node with provided inputs for single-step debugging.
+        Returns the node execution result including status, outputs, and timing.
+        """
+        current_user, _ = current_account_with_tenant()
+        payload = SnippetDraftNodeRunPayload.model_validate(console_ns.payload or {})
+
+        user_inputs = payload.inputs
+
+        # Get draft workflow for file parsing
+        snippet_service = SnippetService()
+        draft_workflow = snippet_service.get_draft_workflow(snippet=snippet)
+        if not draft_workflow:
+            raise NotFound("Draft workflow not found")
+
+        files = SnippetGenerateService.parse_files(draft_workflow, payload.files)
+
+        workflow_node_execution = SnippetGenerateService.run_draft_node(
+            snippet=snippet,
+            node_id=node_id,
+            user_inputs=user_inputs,
+            account=current_user,
+            query=payload.query,
+            files=files,
+        )
+
+        return workflow_node_execution
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/nodes/<string:node_id>/last-run")
+class SnippetDraftNodeLastRunApi(Resource):
+    @console_ns.doc("get_snippet_draft_node_last_run")
+    @console_ns.doc(description="Get last run result for a node in snippet draft workflow")
+    @console_ns.doc(params={"snippet_id": "Snippet ID", "node_id": "Node ID"})
+    @console_ns.response(200, "Node last run retrieved successfully", workflow_run_node_execution_model)
+    @console_ns.response(404, "Snippet, draft workflow, or node last run not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @marshal_with(workflow_run_node_execution_model)
+    def get(self, snippet: CustomizedSnippet, node_id: str):
+        """
+        Get the last run result for a specific node in snippet draft workflow.
+
+        Returns the most recent execution record for the given node,
+        including status, inputs, outputs, and timing information.
+        """
+        snippet_service = SnippetService()
+        draft_workflow = snippet_service.get_draft_workflow(snippet=snippet)
+        if not draft_workflow:
+            raise NotFound("Draft workflow not found")
+
+        node_exec = snippet_service.get_snippet_node_last_run(
+            snippet=snippet,
+            workflow=draft_workflow,
+            node_id=node_id,
+        )
+        if node_exec is None:
+            raise NotFound("Node last run not found")
+
+        return node_exec
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/iteration/nodes/<string:node_id>/run")
+class SnippetDraftRunIterationNodeApi(Resource):
+    @console_ns.doc("run_snippet_draft_iteration_node")
+    @console_ns.doc(description="Run draft workflow iteration node for snippet")
+    @console_ns.doc(params={"snippet_id": "Snippet ID", "node_id": "Node ID"})
+    @console_ns.expect(console_ns.models.get(SnippetIterationNodeRunPayload.__name__))
+    @console_ns.response(200, "Iteration node run started successfully (SSE stream)")
+    @console_ns.response(404, "Snippet or draft workflow not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet, node_id: str):
+        """
+        Run a draft workflow iteration node for snippet.
+
+        Iteration nodes execute their internal sub-graph multiple times over an input list.
+        Returns an SSE event stream with iteration progress and results.
+        """
+        current_user, _ = current_account_with_tenant()
+        args = SnippetIterationNodeRunPayload.model_validate(console_ns.payload or {}).model_dump(exclude_none=True)
+
+        try:
+            response = SnippetGenerateService.generate_single_iteration(
+                snippet=snippet, user=current_user, node_id=node_id, args=args, streaming=True
+            )
+
+            return helper.compact_generate_response(response)
+        except ValueError as e:
+            raise e
+        except Exception:
+            logger.exception("internal server error.")
+            raise InternalServerError()
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/loop/nodes/<string:node_id>/run")
+class SnippetDraftRunLoopNodeApi(Resource):
+    @console_ns.doc("run_snippet_draft_loop_node")
+    @console_ns.doc(description="Run draft workflow loop node for snippet")
+    @console_ns.doc(params={"snippet_id": "Snippet ID", "node_id": "Node ID"})
+    @console_ns.expect(console_ns.models.get(SnippetLoopNodeRunPayload.__name__))
+    @console_ns.response(200, "Loop node run started successfully (SSE stream)")
+    @console_ns.response(404, "Snippet or draft workflow not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet, node_id: str):
+        """
+        Run a draft workflow loop node for snippet.
+
+        Loop nodes execute their internal sub-graph repeatedly until a condition is met.
+        Returns an SSE event stream with loop progress and results.
+        """
+        current_user, _ = current_account_with_tenant()
+        args = SnippetLoopNodeRunPayload.model_validate(console_ns.payload or {})
+
+        try:
+            response = SnippetGenerateService.generate_single_loop(
+                snippet=snippet, user=current_user, node_id=node_id, args=args, streaming=True
+            )
+
+            return helper.compact_generate_response(response)
+        except ValueError as e:
+            raise e
+        except Exception:
+            logger.exception("internal server error.")
+            raise InternalServerError()
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflows/draft/run")
+class SnippetDraftWorkflowRunApi(Resource):
+    @console_ns.doc("run_snippet_draft_workflow")
+    @console_ns.expect(console_ns.models.get(SnippetDraftRunPayload.__name__))
+    @console_ns.response(200, "Draft workflow run started successfully (SSE stream)")
+    @console_ns.response(404, "Snippet or draft workflow not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet):
+        """
+        Run draft workflow for snippet.
+
+        Executes the snippet's draft workflow with the provided inputs
+        and returns an SSE event stream with execution progress and results.
+        """
+        current_user, _ = current_account_with_tenant()
+
+        payload = SnippetDraftRunPayload.model_validate(console_ns.payload or {})
+        args = payload.model_dump(exclude_none=True)
+
+        try:
+            response = SnippetGenerateService.generate(
+                snippet=snippet,
+                user=current_user,
+                args=args,
+                invoke_from=InvokeFrom.DEBUGGER,
+                streaming=True,
+            )
+
+            return helper.compact_generate_response(response)
+        except ValueError as e:
+            raise e
+        except Exception:
+            logger.exception("internal server error.")
+            raise InternalServerError()
+
+
+@console_ns.route("/snippets/<uuid:snippet_id>/workflow-runs/tasks/<string:task_id>/stop")
+class SnippetWorkflowTaskStopApi(Resource):
+    @console_ns.doc("stop_snippet_workflow_task")
+    @console_ns.response(200, "Task stopped successfully")
+    @console_ns.response(404, "Snippet not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_snippet
+    @edit_permission_required
+    def post(self, snippet: CustomizedSnippet, task_id: str):
+        """
+        Stop a running snippet workflow task.
+
+        Uses both the legacy stop flag mechanism and the graph engine
+        command channel for backward compatibility.
+        """
+        # Stop using both mechanisms for backward compatibility
+        # Legacy stop flag mechanism (without user check)
+        AppQueueManager.set_stop_flag_no_user_check(task_id)
+
+        # New graph engine command channel mechanism
+        GraphEngineManager.send_stop_command(task_id)
+
+        return {"result": "success"}

api/controllers/console/workspace/snippets.py

@@ -0,0 +1,202 @@
+import logging
+
+from flask import request
+from flask_restx import Resource, marshal, marshal_with
+from sqlalchemy.orm import Session
+from werkzeug.exceptions import NotFound
+
+from controllers.common.schema import register_schema_models
+from controllers.console import console_ns
+from controllers.console.snippets.payloads import (
+    CreateSnippetPayload,
+    SnippetListQuery,
+    UpdateSnippetPayload,
+)
+from controllers.console.wraps import (
+    account_initialization_required,
+    edit_permission_required,
+    setup_required,
+)
+from extensions.ext_database import db
+from fields.snippet_fields import snippet_fields, snippet_list_fields, snippet_pagination_fields
+from libs.login import current_account_with_tenant, login_required
+from models.snippet import SnippetType
+from services.snippet_service import SnippetService
+
+logger = logging.getLogger(__name__)
+
+# Register Pydantic models with Swagger
+register_schema_models(
+    console_ns,
+    SnippetListQuery,
+    CreateSnippetPayload,
+    UpdateSnippetPayload,
+)
+
+# Create namespace models for marshaling
+snippet_model = console_ns.model("Snippet", snippet_fields)
+snippet_list_model = console_ns.model("SnippetList", snippet_list_fields)
+snippet_pagination_model = console_ns.model("SnippetPagination", snippet_pagination_fields)
+
+
+@console_ns.route("/workspaces/current/customized-snippets")
+class CustomizedSnippetsApi(Resource):
+    @console_ns.doc("list_customized_snippets")
+    @console_ns.expect(console_ns.models.get(SnippetListQuery.__name__))
+    @console_ns.response(200, "Snippets retrieved successfully", snippet_pagination_model)
+    @setup_required
+    @login_required
+    @account_initialization_required
+    def get(self):
+        """List customized snippets with pagination and search."""
+        _, current_tenant_id = current_account_with_tenant()
+
+        query_params = request.args.to_dict()
+        query = SnippetListQuery.model_validate(query_params)
+
+        snippets, total, has_more = SnippetService.get_snippets(
+            tenant_id=current_tenant_id,
+            page=query.page,
+            limit=query.limit,
+            keyword=query.keyword,
+        )
+
+        return {
+            "data": marshal(snippets, snippet_list_fields),
+            "page": query.page,
+            "limit": query.limit,
+            "total": total,
+            "has_more": has_more,
+        }, 200
+
+    @console_ns.doc("create_customized_snippet")
+    @console_ns.expect(console_ns.models.get(CreateSnippetPayload.__name__))
+    @console_ns.response(201, "Snippet created successfully", snippet_model)
+    @console_ns.response(400, "Invalid request or name already exists")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    def post(self):
+        """Create a new customized snippet."""
+        current_user, current_tenant_id = current_account_with_tenant()
+
+        payload = CreateSnippetPayload.model_validate(console_ns.payload or {})
+
+        try:
+            snippet_type = SnippetType(payload.type)
+        except ValueError:
+            snippet_type = SnippetType.NODE
+
+        try:
+            snippet = SnippetService.create_snippet(
+                tenant_id=current_tenant_id,
+                name=payload.name,
+                description=payload.description,
+                snippet_type=snippet_type,
+                icon_info=payload.icon_info.model_dump() if payload.icon_info else None,
+                graph=payload.graph,
+                input_fields=[f.model_dump() for f in payload.input_fields] if payload.input_fields else None,
+                account=current_user,
+            )
+        except ValueError as e:
+            return {"message": str(e)}, 400
+
+        return marshal(snippet, snippet_fields), 201
+
+
+@console_ns.route("/workspaces/current/customized-snippets/<uuid:snippet_id>")
+class CustomizedSnippetDetailApi(Resource):
+    @console_ns.doc("get_customized_snippet")
+    @console_ns.response(200, "Snippet retrieved successfully", snippet_model)
+    @console_ns.response(404, "Snippet not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    def get(self, snippet_id: str):
+        """Get customized snippet details."""
+        _, current_tenant_id = current_account_with_tenant()
+
+        snippet = SnippetService.get_snippet_by_id(
+            snippet_id=str(snippet_id),
+            tenant_id=current_tenant_id,
+        )
+
+        if not snippet:
+            raise NotFound("Snippet not found")
+
+        return marshal(snippet, snippet_fields), 200
+
+    @console_ns.doc("update_customized_snippet")
+    @console_ns.expect(console_ns.models.get(UpdateSnippetPayload.__name__))
+    @console_ns.response(200, "Snippet updated successfully", snippet_model)
+    @console_ns.response(400, "Invalid request or name already exists")
+    @console_ns.response(404, "Snippet not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    def patch(self, snippet_id: str):
+        """Update customized snippet."""
+        current_user, current_tenant_id = current_account_with_tenant()
+
+        snippet = SnippetService.get_snippet_by_id(
+            snippet_id=str(snippet_id),
+            tenant_id=current_tenant_id,
+        )
+
+        if not snippet:
+            raise NotFound("Snippet not found")
+
+        payload = UpdateSnippetPayload.model_validate(console_ns.payload or {})
+        update_data = payload.model_dump(exclude_unset=True)
+
+        if "icon_info" in update_data and update_data["icon_info"] is not None:
+            update_data["icon_info"] = payload.icon_info.model_dump() if payload.icon_info else None
+
+        if not update_data:
+            return {"message": "No valid fields to update"}, 400
+
+        try:
+            with Session(db.engine, expire_on_commit=False) as session:
+                snippet = session.merge(snippet)
+                snippet = SnippetService.update_snippet(
+                    session=session,
+                    snippet=snippet,
+                    account_id=current_user.id,
+                    data=update_data,
+                )
+                session.commit()
+        except ValueError as e:
+            return {"message": str(e)}, 400
+
+        return marshal(snippet, snippet_fields), 200
+
+    @console_ns.doc("delete_customized_snippet")
+    @console_ns.response(204, "Snippet deleted successfully")
+    @console_ns.response(404, "Snippet not found")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    def delete(self, snippet_id: str):
+        """Delete customized snippet."""
+        _, current_tenant_id = current_account_with_tenant()
+
+        snippet = SnippetService.get_snippet_by_id(
+            snippet_id=str(snippet_id),
+            tenant_id=current_tenant_id,
+        )
+
+        if not snippet:
+            raise NotFound("Snippet not found")
+
+        with Session(db.engine) as session:
+            snippet = session.merge(snippet)
+            SnippetService.delete_snippet(
+                session=session,
+                snippet=snippet,
+            )
+            session.commit()
+
+        return "", 204

api/core/plugin/impl/tool.py

@@ -3,6 +3,8 @@ from typing import Any
 
 from pydantic import BaseModel
 
+from configs import dify_config
+
 # from core.plugin.entities.plugin import GenericProviderID, ToolProviderID
 from core.plugin.entities.plugin_daemon import CredentialType, PluginBasicBooleanResponse, PluginToolProviderEntity
 from core.plugin.impl.base import BasePluginClient
@@ -122,7 +124,7 @@ class PluginToolManager(BasePluginClient):
             },
         )
 
-        return merge_blob_chunks(response)
+        return merge_blob_chunks(response, max_file_size=dify_config.PLUGIN_MAX_FILE_SIZE)
 
     def validate_provider_credentials(
         self, tenant_id: str, user_id: str, provider: str, credentials: dict[str, Any]

api/core/rag/datasource/vdb/oceanbase/oceanbase_vector.py

@@ -1,12 +1,13 @@
 import json
 import logging
-import math
-from typing import Any
+import re
+from typing import Any, Literal
 
 from pydantic import BaseModel, model_validator
-from pyobvector import VECTOR, ObVecClient, l2_distance  # type: ignore
+from pyobvector import VECTOR, ObVecClient, cosine_distance, inner_product, l2_distance  # type: ignore
 from sqlalchemy import JSON, Column, String
 from sqlalchemy.dialects.mysql import LONGTEXT
+from sqlalchemy.exc import SQLAlchemyError
 
 from configs import dify_config
 from core.rag.datasource.vdb.vector_base import BaseVector
@@ -19,10 +20,14 @@ from models.dataset import Dataset
 
 logger = logging.getLogger(__name__)
 
-DEFAULT_OCEANBASE_HNSW_BUILD_PARAM = {"M": 16, "efConstruction": 256}
-DEFAULT_OCEANBASE_HNSW_SEARCH_PARAM = {"efSearch": 64}
 OCEANBASE_SUPPORTED_VECTOR_INDEX_TYPE = "HNSW"
-DEFAULT_OCEANBASE_VECTOR_METRIC_TYPE = "l2"
+_VALID_TABLE_NAME_RE = re.compile(r"^[a-zA-Z0-9_]+$")
+
+_DISTANCE_FUNC_MAP = {
+    "l2": l2_distance,
+    "cosine": cosine_distance,
+    "inner_product": inner_product,
+}
 
 
 class OceanBaseVectorConfig(BaseModel):
@@ -32,6 +37,14 @@ class OceanBaseVectorConfig(BaseModel):
     password: str
     database: str
     enable_hybrid_search: bool = False
+    batch_size: int = 100
+    metric_type: Literal["l2", "cosine", "inner_product"] = "l2"
+    hnsw_m: int = 16
+    hnsw_ef_construction: int = 256
+    hnsw_ef_search: int = -1
+    pool_size: int = 5
+    max_overflow: int = 10
+    hnsw_refresh_threshold: int = 1000
 
     @model_validator(mode="before")
     @classmethod
@@ -49,14 +62,23 @@ class OceanBaseVectorConfig(BaseModel):
 
 class OceanBaseVector(BaseVector):
     def __init__(self, collection_name: str, config: OceanBaseVectorConfig):
+        if not _VALID_TABLE_NAME_RE.match(collection_name):
+            raise ValueError(
+                f"Invalid collection name '{collection_name}': "
+                "only alphanumeric characters and underscores are allowed."
+            )
         super().__init__(collection_name)
         self._config = config
-        self._hnsw_ef_search = -1
+        self._hnsw_ef_search = self._config.hnsw_ef_search
         self._client = ObVecClient(
             uri=f"{self._config.host}:{self._config.port}",
             user=self._config.user,
             password=self._config.password,
             db_name=self._config.database,
+            pool_size=self._config.pool_size,
+            max_overflow=self._config.max_overflow,
+            pool_recycle=3600,
+            pool_pre_ping=True,
         )
         self._fields: list[str] = []  # List of fields in the collection
         if self._client.check_table_exists(collection_name):
@@ -136,8 +158,8 @@ class OceanBaseVector(BaseVector):
                 field_name="vector",
                 index_type=OCEANBASE_SUPPORTED_VECTOR_INDEX_TYPE,
                 index_name="vector_index",
-                metric_type=DEFAULT_OCEANBASE_VECTOR_METRIC_TYPE,
-                params=DEFAULT_OCEANBASE_HNSW_BUILD_PARAM,
+                metric_type=self._config.metric_type,
+                params={"M": self._config.hnsw_m, "efConstruction": self._config.hnsw_ef_construction},
             )
 
             self._client.create_table_with_index_params(
@@ -178,6 +200,17 @@ class OceanBaseVector(BaseVector):
             else:
                 logger.debug("DEBUG: Hybrid search is NOT enabled for '%s'", self._collection_name)
 
+            try:
+                self._client.perform_raw_text_sql(
+                    f"CREATE INDEX IF NOT EXISTS idx_metadata_doc_id ON `{self._collection_name}` "
+                    f"((CAST(metadata->>'$.document_id' AS CHAR(64))))"
+                )
+            except SQLAlchemyError:
+                logger.warning(
+                    "Failed to create metadata functional index on '%s'; metadata queries may be slow without it.",
+                    self._collection_name,
+                )
+
             self._client.refresh_metadata([self._collection_name])
             self._load_collection_fields()
             redis_client.set(collection_exist_cache_key, 1, ex=3600)
@@ -205,24 +238,49 @@ class OceanBaseVector(BaseVector):
 
     def add_texts(self, documents: list[Document], embeddings: list[list[float]], **kwargs):
         ids = self._get_uuids(documents)
-        for id, doc, emb in zip(ids, documents, embeddings):
+        batch_size = self._config.batch_size
+        total = len(documents)
+
+        all_data = [
+            {
+                "id": doc_id,
+                "vector": emb,
+                "text": doc.page_content,
+                "metadata": doc.metadata,
+            }
+            for doc_id, doc, emb in zip(ids, documents, embeddings)
+        ]
+
+        for start in range(0, total, batch_size):
+            batch = all_data[start : start + batch_size]
             try:
                 self._client.insert(
                     table_name=self._collection_name,
-                    data={
-                        "id": id,
-                        "vector": emb,
-                        "text": doc.page_content,
-                        "metadata": doc.metadata,
-                    },
+                    data=batch,
                 )
             except Exception as e:
                 logger.exception(
-                    "Failed to insert document with id '%s' in collection '%s'",
-                    id,
+                    "Failed to insert batch [%d:%d] into collection '%s'",
+                    start,
+                    start + len(batch),
+                    self._collection_name,
+                )
+                raise Exception(
+                    f"Failed to insert batch [{start}:{start + len(batch)}] into collection '{self._collection_name}'"
+                ) from e
+
+        if self._config.hnsw_refresh_threshold > 0 and total >= self._config.hnsw_refresh_threshold:
+            try:
+                self._client.refresh_index(
+                    table_name=self._collection_name,
+                    index_name="vector_index",
+                )
+            except SQLAlchemyError:
+                logger.warning(
+                    "Failed to refresh HNSW index after inserting %d documents into '%s'",
+                    total,
                     self._collection_name,
                 )
-                raise Exception(f"Failed to insert document with id '{id}'") from e
 
     def text_exists(self, id: str) -> bool:
         try:
@@ -412,7 +470,7 @@ class OceanBaseVector(BaseVector):
                 vec_column_name="vector",
                 vec_data=query_vector,
                 topk=topk,
-                distance_func=l2_distance,
+                distance_func=self._get_distance_func(),
                 output_column_names=["text", "metadata"],
                 with_dist=True,
                 where_clause=_where_clause,
@@ -424,14 +482,31 @@ class OceanBaseVector(BaseVector):
             )
             raise Exception(f"Vector search failed for collection '{self._collection_name}'") from e
 
-        # Convert distance to score and prepare results for processing
         results = []
         for _text, metadata_str, distance in cur:
-            score = 1 - distance / math.sqrt(2)
+            score = self._distance_to_score(distance)
             results.append((_text, metadata_str, score))
 
         return self._process_search_results(results, score_threshold=score_threshold)
 
+    def _get_distance_func(self):
+        func = _DISTANCE_FUNC_MAP.get(self._config.metric_type)
+        if func is None:
+            raise ValueError(
+                f"Unsupported metric_type '{self._config.metric_type}'. Supported: {', '.join(_DISTANCE_FUNC_MAP)}"
+            )
+        return func
+
+    def _distance_to_score(self, distance: float) -> float:
+        metric = self._config.metric_type
+        if metric == "l2":
+            return 1.0 / (1.0 + distance)
+        elif metric == "cosine":
+            return 1.0 - distance
+        elif metric == "inner_product":
+            return -distance
+        raise ValueError(f"Unsupported metric_type '{metric}'")
+
     def delete(self):
         try:
             self._client.drop_table_if_exist(self._collection_name)
@@ -464,5 +539,13 @@ class OceanBaseVectorFactory(AbstractVectorFactory):
                 password=(dify_config.OCEANBASE_VECTOR_PASSWORD or ""),
                 database=dify_config.OCEANBASE_VECTOR_DATABASE or "",
                 enable_hybrid_search=dify_config.OCEANBASE_ENABLE_HYBRID_SEARCH or False,
+                batch_size=dify_config.OCEANBASE_VECTOR_BATCH_SIZE,
+                metric_type=dify_config.OCEANBASE_VECTOR_METRIC_TYPE,
+                hnsw_m=dify_config.OCEANBASE_HNSW_M,
+                hnsw_ef_construction=dify_config.OCEANBASE_HNSW_EF_CONSTRUCTION,
+                hnsw_ef_search=dify_config.OCEANBASE_HNSW_EF_SEARCH,
+                pool_size=dify_config.OCEANBASE_VECTOR_POOL_SIZE,
+                max_overflow=dify_config.OCEANBASE_VECTOR_MAX_OVERFLOW,
+                hnsw_refresh_threshold=dify_config.OCEANBASE_HNSW_REFRESH_THRESHOLD,
             ),
         )

api/fields/snippet_fields.py

@@ -0,0 +1,45 @@
+from flask_restx import fields
+
+from fields.member_fields import simple_account_fields
+from libs.helper import TimestampField
+
+# Snippet list item fields (lightweight for list display)
+snippet_list_fields = {
+    "id": fields.String,
+    "name": fields.String,
+    "description": fields.String,
+    "type": fields.String,
+    "version": fields.Integer,
+    "use_count": fields.Integer,
+    "is_published": fields.Boolean,
+    "icon_info": fields.Raw,
+    "created_at": TimestampField,
+    "updated_at": TimestampField,
+}
+
+# Full snippet fields (includes creator info and graph data)
+snippet_fields = {
+    "id": fields.String,
+    "name": fields.String,
+    "description": fields.String,
+    "type": fields.String,
+    "version": fields.Integer,
+    "use_count": fields.Integer,
+    "is_published": fields.Boolean,
+    "icon_info": fields.Raw,
+    "graph": fields.Raw(attribute="graph_dict"),
+    "input_fields": fields.Raw(attribute="input_fields_list"),
+    "created_by": fields.Nested(simple_account_fields, attribute="created_by_account", allow_null=True),
+    "created_at": TimestampField,
+    "updated_by": fields.Nested(simple_account_fields, attribute="updated_by_account", allow_null=True),
+    "updated_at": TimestampField,
+}
+
+# Pagination response fields
+snippet_pagination_fields = {
+    "data": fields.List(fields.Nested(snippet_list_fields)),
+    "page": fields.Integer,
+    "limit": fields.Integer,
+    "total": fields.Integer,
+    "has_more": fields.Boolean,
+}

api/migrations/versions/2026_01_29_1200-1c05e80d2380_add_customized_snippets_table.py

@@ -0,0 +1,83 @@
+"""add_customized_snippets_table
+
+Revision ID: 1c05e80d2380
+Revises: 788d3099ae3a
+Create Date: 2026-01-29 12:00:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+import models as models
+
+
+def _is_pg(conn):
+    return conn.dialect.name == "postgresql"
+
+
+# revision identifiers, used by Alembic.
+revision = "1c05e80d2380"
+down_revision = "788d3099ae3a"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    conn = op.get_bind()
+
+    if _is_pg(conn):
+        op.create_table(
+            "customized_snippets",
+            sa.Column("id", models.types.StringUUID(), server_default=sa.text("uuidv7()"), nullable=False),
+            sa.Column("tenant_id", models.types.StringUUID(), nullable=False),
+            sa.Column("name", sa.String(length=255), nullable=False),
+            sa.Column("description", sa.Text(), nullable=True),
+            sa.Column("type", sa.String(length=50), server_default=sa.text("'node'"), nullable=False),
+            sa.Column("workflow_id", models.types.StringUUID(), nullable=True),
+            sa.Column("is_published", sa.Boolean(), server_default=sa.text("false"), nullable=False),
+            sa.Column("version", sa.Integer(), server_default=sa.text("1"), nullable=False),
+            sa.Column("use_count", sa.Integer(), server_default=sa.text("0"), nullable=False),
+            sa.Column("icon_info", postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+            sa.Column("graph", sa.Text(), nullable=True),
+            sa.Column("input_fields", sa.Text(), nullable=True),
+            sa.Column("created_by", models.types.StringUUID(), nullable=True),
+            sa.Column("created_at", sa.DateTime(), server_default=sa.text("CURRENT_TIMESTAMP"), nullable=False),
+            sa.Column("updated_by", models.types.StringUUID(), nullable=True),
+            sa.Column("updated_at", sa.DateTime(), server_default=sa.text("CURRENT_TIMESTAMP"), nullable=False),
+            sa.PrimaryKeyConstraint("id", name="customized_snippet_pkey"),
+            sa.UniqueConstraint("tenant_id", "name", name="customized_snippet_tenant_name_key"),
+        )
+    else:
+        op.create_table(
+            "customized_snippets",
+            sa.Column("id", models.types.StringUUID(), nullable=False),
+            sa.Column("tenant_id", models.types.StringUUID(), nullable=False),
+            sa.Column("name", sa.String(length=255), nullable=False),
+            sa.Column("description", models.types.LongText(), nullable=True),
+            sa.Column("type", sa.String(length=50), server_default=sa.text("'node'"), nullable=False),
+            sa.Column("workflow_id", models.types.StringUUID(), nullable=True),
+            sa.Column("is_published", sa.Boolean(), server_default=sa.text("false"), nullable=False),
+            sa.Column("version", sa.Integer(), server_default=sa.text("1"), nullable=False),
+            sa.Column("use_count", sa.Integer(), server_default=sa.text("0"), nullable=False),
+            sa.Column("icon_info", models.types.AdjustedJSON(astext_type=sa.Text()), nullable=True),
+            sa.Column("graph", models.types.LongText(), nullable=True),
+            sa.Column("input_fields", models.types.LongText(), nullable=True),
+            sa.Column("created_by", models.types.StringUUID(), nullable=True),
+            sa.Column("created_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+            sa.Column("updated_by", models.types.StringUUID(), nullable=True),
+            sa.Column("updated_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+            sa.PrimaryKeyConstraint("id", name="customized_snippet_pkey"),
+            sa.UniqueConstraint("tenant_id", "name", name="customized_snippet_tenant_name_key"),
+        )
+
+    with op.batch_alter_table("customized_snippets", schema=None) as batch_op:
+        batch_op.create_index("customized_snippet_tenant_idx", ["tenant_id"], unique=False)
+
+
+def downgrade():
+    with op.batch_alter_table("customized_snippets", schema=None) as batch_op:
+        batch_op.drop_index("customized_snippet_tenant_idx")
+
+    op.drop_table("customized_snippets")

api/models/__init__.py

@@ -81,6 +81,7 @@ from .provider import (
     TenantDefaultModel,
     TenantPreferredModelProvider,
 )
+from .snippet import CustomizedSnippet, SnippetType
 from .source import DataSourceApiKeyAuthBinding, DataSourceOauthBinding
 from .task import CeleryTask, CeleryTaskSet
 from .tools import (
@@ -140,6 +141,7 @@ __all__ = [
     "Conversation",
     "ConversationVariable",
     "CreatorUserRole",
+    "CustomizedSnippet",
     "DataSourceApiKeyAuthBinding",
     "DataSourceOauthBinding",
     "Dataset",
@@ -184,6 +186,7 @@ __all__ = [
     "RecommendedApp",
     "SavedMessage",
     "Site",
+    "SnippetType",
     "Tag",
     "TagBinding",
     "Tenant",

api/models/snippet.py

@@ -0,0 +1,101 @@
+import json
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+import sqlalchemy as sa
+from sqlalchemy import DateTime, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from libs.uuid_utils import uuidv7
+
+from .account import Account
+from .base import Base
+from .engine import db
+from .types import AdjustedJSON, LongText, StringUUID
+
+
+class SnippetType(StrEnum):
+    """Snippet Type Enum"""
+
+    NODE = "node"
+    GROUP = "group"
+
+
+class CustomizedSnippet(Base):
+    """
+    Customized Snippet Model
+
+    Stores reusable workflow components (nodes or node groups) that can be
+    shared across applications within a workspace.
+    """
+
+    __tablename__ = "customized_snippets"
+    __table_args__ = (
+        sa.PrimaryKeyConstraint("id", name="customized_snippet_pkey"),
+        sa.Index("customized_snippet_tenant_idx", "tenant_id"),
+        sa.UniqueConstraint("tenant_id", "name", name="customized_snippet_tenant_name_key"),
+    )
+
+    id: Mapped[str] = mapped_column(StringUUID, default=lambda: str(uuidv7()))
+    tenant_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(LongText, nullable=True)
+    type: Mapped[str] = mapped_column(String(50), nullable=False, server_default=sa.text("'node'"))
+
+    # Workflow reference for published version
+    workflow_id: Mapped[str | None] = mapped_column(StringUUID, nullable=True)
+
+    # State flags
+    is_published: Mapped[bool] = mapped_column(sa.Boolean, nullable=False, server_default=sa.text("false"))
+    version: Mapped[int] = mapped_column(sa.Integer, nullable=False, server_default=sa.text("1"))
+    use_count: Mapped[int] = mapped_column(sa.Integer, nullable=False, server_default=sa.text("0"))
+
+    # Visual customization
+    icon_info: Mapped[dict | None] = mapped_column(AdjustedJSON, nullable=True)
+
+    # Snippet configuration (stored as JSON text)
+    input_fields: Mapped[str | None] = mapped_column(LongText, nullable=True)
+
+    # Audit fields
+    created_by: Mapped[str | None] = mapped_column(StringUUID, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False, server_default=func.current_timestamp())
+    updated_by: Mapped[str | None] = mapped_column(StringUUID, nullable=True)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, nullable=False, server_default=func.current_timestamp(), onupdate=func.current_timestamp()
+    )
+
+    @property
+    def graph_dict(self) -> dict[str, Any]:
+        """Get graph from associated workflow."""
+        if self.workflow_id:
+            from .workflow import Workflow
+
+            workflow = db.session.get(Workflow, self.workflow_id)
+            if workflow:
+                return json.loads(workflow.graph) if workflow.graph else {}
+        return {}
+
+    @property
+    def input_fields_list(self) -> list[dict[str, Any]]:
+        """Parse input_fields JSON to list."""
+        return json.loads(self.input_fields) if self.input_fields else []
+
+    @property
+    def created_by_account(self) -> Account | None:
+        """Get the account that created this snippet."""
+        if self.created_by:
+            return db.session.get(Account, self.created_by)
+        return None
+
+    @property
+    def updated_by_account(self) -> Account | None:
+        """Get the account that last updated this snippet."""
+        if self.updated_by:
+            return db.session.get(Account, self.updated_by)
+        return None
+
+    @property
+    def version_str(self) -> str:
+        """Get version as string for API response."""
+        return str(self.version)

api/models/workflow.py

@@ -67,6 +67,7 @@ class WorkflowType(StrEnum):
     WORKFLOW = "workflow"
     CHAT = "chat"
     RAG_PIPELINE = "rag-pipeline"
+    SNIPPET = "snippet"
 
     @classmethod
     def value_of(cls, value: str) -> "WorkflowType":

api/pyproject.toml

@@ -67,7 +67,7 @@ dependencies = [
     "pycryptodome==3.23.0",
     "pydantic~=2.11.4",
     "pydantic-extra-types~=2.10.3",
-    "pydantic-settings~=2.11.0",
+    "pydantic-settings~=2.12.0",
     "pyjwt~=2.10.1",
     "pypdfium2==5.2.0",
     "python-docx~=1.1.0",

api/services/evaluation_service.py

@@ -0,0 +1,178 @@
+import io
+import logging
+from typing import Union
+
+from openpyxl import Workbook
+from openpyxl.styles import Alignment, Border, Font, PatternFill, Side
+from openpyxl.utils import get_column_letter
+
+from models.model import App, AppMode
+from models.snippet import CustomizedSnippet
+from services.snippet_service import SnippetService
+from services.workflow_service import WorkflowService
+
+logger = logging.getLogger(__name__)
+
+
+class EvaluationService:
+    """
+    Service for evaluation-related operations.
+
+    Provides functionality to generate evaluation dataset templates
+    based on App or Snippet input parameters.
+    """
+
+    # Excluded app modes that don't support evaluation templates
+    EXCLUDED_APP_MODES = {AppMode.RAG_PIPELINE}
+
+    @classmethod
+    def generate_dataset_template(
+        cls,
+        target: Union[App, CustomizedSnippet],
+        target_type: str,
+    ) -> tuple[bytes, str]:
+        """
+        Generate evaluation dataset template as XLSX bytes.
+
+        Creates an XLSX file with headers based on the evaluation target's input parameters.
+        The first column is index, followed by input parameter columns.
+
+        :param target: App or CustomizedSnippet instance
+        :param target_type: Target type string ("app" or "snippet")
+        :return: Tuple of (xlsx_content_bytes, filename)
+        :raises ValueError: If target type is not supported or app mode is excluded
+        """
+        # Validate target type
+        if target_type == "app":
+            if not isinstance(target, App):
+                raise ValueError("Invalid target: expected App instance")
+            if AppMode.value_of(target.mode) in cls.EXCLUDED_APP_MODES:
+                raise ValueError(f"App mode '{target.mode}' does not support evaluation templates")
+            input_fields = cls._get_app_input_fields(target)
+        elif target_type == "snippet":
+            if not isinstance(target, CustomizedSnippet):
+                raise ValueError("Invalid target: expected CustomizedSnippet instance")
+            input_fields = cls._get_snippet_input_fields(target)
+        else:
+            raise ValueError(f"Unsupported target type: {target_type}")
+
+        # Generate XLSX template
+        xlsx_content = cls._generate_xlsx_template(input_fields, target.name)
+
+        # Build filename
+        truncated_name = target.name[:10] + "..." if len(target.name) > 10 else target.name
+        filename = f"{truncated_name}-evaluation-dataset.xlsx"
+
+        return xlsx_content, filename
+
+    @classmethod
+    def _get_app_input_fields(cls, app: App) -> list[dict]:
+        """
+        Get input fields from App's workflow.
+
+        :param app: App instance
+        :return: List of input field definitions
+        """
+        workflow_service = WorkflowService()
+        workflow = workflow_service.get_published_workflow(app_model=app)
+        if not workflow:
+            workflow = workflow_service.get_draft_workflow(app_model=app)
+
+        if not workflow:
+            return []
+
+        # Get user input form from workflow
+        user_input_form = workflow.user_input_form()
+        return user_input_form
+
+    @classmethod
+    def _get_snippet_input_fields(cls, snippet: CustomizedSnippet) -> list[dict]:
+        """
+        Get input fields from Snippet.
+
+        Tries to get from snippet's own input_fields first,
+        then falls back to workflow's user_input_form.
+
+        :param snippet: CustomizedSnippet instance
+        :return: List of input field definitions
+        """
+        # Try snippet's own input_fields first
+        input_fields = snippet.input_fields_list
+        if input_fields:
+            return input_fields
+
+        # Fallback to workflow's user_input_form
+        snippet_service = SnippetService()
+        workflow = snippet_service.get_published_workflow(snippet=snippet)
+        if not workflow:
+            workflow = snippet_service.get_draft_workflow(snippet=snippet)
+
+        if workflow:
+            return workflow.user_input_form()
+
+        return []
+
+    @classmethod
+    def _generate_xlsx_template(cls, input_fields: list[dict], target_name: str) -> bytes:
+        """
+        Generate XLSX template file content.
+
+        Creates a workbook with:
+        - First row as header row with "index" and input field names
+        - Styled header with background color and borders
+        - Empty data rows ready for user input
+
+        :param input_fields: List of input field definitions
+        :param target_name: Name of the target (for sheet name)
+        :return: XLSX file content as bytes
+        """
+        wb = Workbook()
+        ws = wb.active
+
+        sheet_name = "Evaluation Dataset"
+        ws.title = sheet_name
+
+        header_font = Font(bold=True, color="FFFFFF")
+        header_fill = PatternFill(start_color="4472C4", end_color="4472C4", fill_type="solid")
+        header_alignment = Alignment(horizontal="center", vertical="center")
+        thin_border = Border(
+            left=Side(style="thin"),
+            right=Side(style="thin"),
+            top=Side(style="thin"),
+            bottom=Side(style="thin"),
+        )
+
+        # Build header row
+        headers = ["index"]
+
+        for field in input_fields:
+            field_label = field.get("label") or field.get("variable")
+            headers.append(field_label)
+
+        # Write header row
+        for col_idx, header in enumerate(headers, start=1):
+            cell = ws.cell(row=1, column=col_idx, value=header)
+            cell.font = header_font
+            cell.fill = header_fill
+            cell.alignment = header_alignment
+            cell.border = thin_border
+
+        # Set column widths
+        ws.column_dimensions["A"].width = 10  # index column
+        for col_idx in range(2, len(headers) + 1):
+            ws.column_dimensions[get_column_letter(col_idx)].width = 20
+
+        # Add one empty row with row number for user reference
+        for col_idx in range(1, len(headers) + 1):
+            cell = ws.cell(row=2, column=col_idx, value="")
+            cell.border = thin_border
+            if col_idx == 1:
+                cell.value = 1
+                cell.alignment = Alignment(horizontal="center")
+
+        # Save to bytes
+        output = io.BytesIO()
+        wb.save(output)
+        output.seek(0)
+
+        return output.getvalue()

api/services/metadata_service.py

@@ -220,8 +220,8 @@ class MetadataService:
                     doc_metadata[BuiltInField.source] = MetadataDataSource[document.data_source_type]
                 document.doc_metadata = doc_metadata
                 db.session.add(document)
-                db.session.commit()
-                # deal metadata binding
+
+                # deal metadata binding (in the same transaction as the doc_metadata update)
                 if not operation.partial_update:
                     db.session.query(DatasetMetadataBinding).filter_by(document_id=operation.document_id).delete()
 
@@ -247,7 +247,9 @@ class MetadataService:
                     db.session.add(dataset_metadata_binding)
                 db.session.commit()
             except Exception:
+                db.session.rollback()
                 logger.exception("Update documents metadata failed")
+                raise
             finally:
                 redis_client.delete(lock_key)
 

api/services/snippet_generate_service.py

@@ -0,0 +1,374 @@
+"""
+Service for generating snippet workflow executions.
+
+Uses an adapter pattern to bridge CustomizedSnippet with the App-based
+WorkflowAppGenerator. The adapter (_SnippetAsApp) provides the minimal App-like
+interface needed by the generator, avoiding modifications to core workflow
+infrastructure.
+
+Key invariants:
+- Snippets always run as WORKFLOW mode (not CHAT or ADVANCED_CHAT).
+- The adapter maps snippet.id to app_id in workflow execution records.
+- Snippet debugging has no rate limiting (max_active_requests = 0).
+
+Supported execution modes:
+- Full workflow run (generate): Runs the entire draft workflow as SSE stream.
+- Single node run (run_draft_node): Synchronous single-step debugging for regular nodes.
+- Single iteration run (generate_single_iteration): SSE stream for iteration container nodes.
+- Single loop run (generate_single_loop): SSE stream for loop container nodes.
+"""
+
+import json
+import logging
+from collections.abc import Generator, Mapping, Sequence
+from typing import Any, Union
+
+from sqlalchemy.orm import make_transient
+
+from core.app.app_config.features.file_upload.manager import FileUploadConfigManager
+from core.app.apps.workflow.app_generator import WorkflowAppGenerator
+from core.app.entities.app_invoke_entities import InvokeFrom
+from core.file.models import File
+from factories import file_factory
+from models import Account
+from models.model import AppMode, EndUser
+from models.snippet import CustomizedSnippet
+from models.workflow import Workflow, WorkflowNodeExecutionModel
+from services.snippet_service import SnippetService
+from services.workflow_service import WorkflowService
+
+logger = logging.getLogger(__name__)
+
+
+class _SnippetAsApp:
+    """
+    Minimal adapter that wraps a CustomizedSnippet to satisfy the App-like
+    interface required by WorkflowAppGenerator, WorkflowAppConfigManager,
+    and WorkflowService.run_draft_workflow_node.
+
+    Used properties:
+    - id: maps to snippet.id (stored as app_id in workflows table)
+    - tenant_id: maps to snippet.tenant_id
+    - mode: hardcoded to AppMode.WORKFLOW since snippets always run as workflows
+    - max_active_requests: defaults to 0 (no limit) for snippet debugging
+    - app_model_config_id: None (snippets don't have app model configs)
+    """
+
+    id: str
+    tenant_id: str
+    mode: str
+    max_active_requests: int
+    app_model_config_id: str | None
+
+    def __init__(self, snippet: CustomizedSnippet) -> None:
+        self.id = snippet.id
+        self.tenant_id = snippet.tenant_id
+        self.mode = AppMode.WORKFLOW.value
+        self.max_active_requests = 0
+        self.app_model_config_id = None
+
+
+class SnippetGenerateService:
+    """
+    Service for running snippet workflow executions.
+
+    Adapts CustomizedSnippet to work with the existing App-based
+    WorkflowAppGenerator infrastructure, avoiding duplication of the
+    complex workflow execution pipeline.
+    """
+
+    # Specific ID for the injected virtual Start node so it can be recognised
+    _VIRTUAL_START_NODE_ID = "__snippet_virtual_start__"
+
+    @classmethod
+    def generate(
+        cls,
+        snippet: CustomizedSnippet,
+        user: Union[Account, EndUser],
+        args: Mapping[str, Any],
+        invoke_from: InvokeFrom,
+        streaming: bool = True,
+    ) -> Union[Mapping[str, Any], Generator[Mapping[str, Any] | str, None, None]]:
+        """
+        Run a snippet's draft workflow.
+
+        Retrieves the draft workflow, adapts the snippet to an App-like proxy,
+        then delegates execution to WorkflowAppGenerator.
+
+        If the workflow graph has no Start node, a virtual Start node is injected
+        in-memory so that:
+        1. Graph validation passes (root node must have execution_type=ROOT).
+        2. User inputs are processed into the variable pool by the StartNode logic.
+
+        :param snippet: CustomizedSnippet instance
+        :param user: Account or EndUser initiating the run
+        :param args: Workflow inputs (must include "inputs" key)
+        :param invoke_from: Source of invocation (typically DEBUGGER)
+        :param streaming: Whether to stream the response
+        :return: Blocking response mapping or SSE streaming generator
+        :raises ValueError: If the snippet has no draft workflow
+        """
+        snippet_service = SnippetService()
+        workflow = snippet_service.get_draft_workflow(snippet=snippet)
+        if not workflow:
+            raise ValueError("Workflow not initialized")
+
+        # Inject a virtual Start node when the graph doesn't have one.
+        workflow = cls._ensure_start_node(workflow, snippet)
+
+        # Adapt snippet to App-like interface for WorkflowAppGenerator
+        app_proxy = _SnippetAsApp(snippet)
+
+        return WorkflowAppGenerator.convert_to_event_stream(
+            WorkflowAppGenerator().generate(
+                app_model=app_proxy,  # type: ignore[arg-type]
+                workflow=workflow,
+                user=user,
+                args=args,
+                invoke_from=invoke_from,
+                streaming=streaming,
+                call_depth=0,
+            )
+        )
+
+    @classmethod
+    def _ensure_start_node(cls, workflow: Workflow, snippet: CustomizedSnippet) -> Workflow:
+        """
+        Return *workflow* with a Start node.
+
+        If the graph already contains a Start node, the original workflow is
+        returned unchanged.  Otherwise a virtual Start node is injected and the
+        workflow object is detached from the SQLAlchemy session so the in-memory
+        change is never flushed to the database.
+        """
+        graph_dict = workflow.graph_dict
+        nodes: list[dict[str, Any]] = graph_dict.get("nodes", [])
+
+        has_start = any(node.get("data", {}).get("type") == "start" for node in nodes)
+        if has_start:
+            return workflow
+
+        modified_graph = cls._inject_virtual_start_node(
+            graph_dict=graph_dict,
+            input_fields=snippet.input_fields_list,
+        )
+
+        # Detach from session to prevent accidental DB persistence of the
+        # modified graph.  All attributes remain accessible for read.
+        make_transient(workflow)
+        workflow.graph = json.dumps(modified_graph)
+        return workflow
+
+    @classmethod
+    def _inject_virtual_start_node(
+        cls,
+        graph_dict: Mapping[str, Any],
+        input_fields: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """
+        Build a new graph dict with a virtual Start node prepended.
+
+        The virtual Start node is wired to every existing node that has no
+        incoming edges (i.e. the current root candidates).  This guarantees:
+
+        :param graph_dict: Original graph configuration.
+        :param input_fields: Snippet input field definitions from
+            ``CustomizedSnippet.input_fields_list``.
+        :return: New graph dict containing the virtual Start node and edges.
+        """
+        nodes: list[dict[str, Any]] = list(graph_dict.get("nodes", []))
+        edges: list[dict[str, Any]] = list(graph_dict.get("edges", []))
+
+        # Identify nodes with no incoming edges.
+        nodes_with_incoming: set[str] = set()
+        for edge in edges:
+            target = edge.get("target")
+            if isinstance(target, str):
+                nodes_with_incoming.add(target)
+        root_candidate_ids = [n["id"] for n in nodes if n["id"] not in nodes_with_incoming]
+
+        # Build Start node ``variables`` from snippet input fields.
+        start_variables: list[dict[str, Any]] = []
+        for field in input_fields:
+            var: dict[str, Any] = {
+                "variable": field.get("variable", ""),
+                "label": field.get("label", field.get("variable", "")),
+                "type": field.get("type", "text-input"),
+                "required": field.get("required", False),
+                "options": field.get("options", []),
+            }
+            if field.get("max_length") is not None:
+                var["max_length"] = field["max_length"]
+            start_variables.append(var)
+
+        virtual_start_node: dict[str, Any] = {
+            "id": cls._VIRTUAL_START_NODE_ID,
+            "data": {
+                "type": "start",
+                "title": "Start",
+                "variables": start_variables,
+            },
+        }
+
+        # Create edges from virtual Start to each root candidate.
+        new_edges: list[dict[str, Any]] = [
+            {
+                "source": cls._VIRTUAL_START_NODE_ID,
+                "sourceHandle": "source",
+                "target": root_id,
+                "targetHandle": "target",
+            }
+            for root_id in root_candidate_ids
+        ]
+
+        return {
+            **graph_dict,
+            "nodes": [virtual_start_node, *nodes],
+            "edges": [*edges, *new_edges],
+        }
+
+    @classmethod
+    def run_draft_node(
+        cls,
+        snippet: CustomizedSnippet,
+        node_id: str,
+        user_inputs: Mapping[str, Any],
+        account: Account,
+        query: str = "",
+        files: Sequence[File] | None = None,
+    ) -> WorkflowNodeExecutionModel:
+        """
+        Run a single node in a snippet's draft workflow (single-step debugging).
+
+        Retrieves the draft workflow, adapts the snippet to an App-like proxy,
+        parses file inputs, then delegates to WorkflowService.run_draft_workflow_node.
+
+        :param snippet: CustomizedSnippet instance
+        :param node_id: ID of the node to run
+        :param user_inputs: User input values for the node
+        :param account: Account initiating the run
+        :param query: Optional query string
+        :param files: Optional parsed file objects
+        :return: WorkflowNodeExecutionModel with execution results
+        :raises ValueError: If the snippet has no draft workflow
+        """
+        snippet_service = SnippetService()
+        draft_workflow = snippet_service.get_draft_workflow(snippet=snippet)
+        if not draft_workflow:
+            raise ValueError("Workflow not initialized")
+
+        app_proxy = _SnippetAsApp(snippet)
+
+        workflow_service = WorkflowService()
+        return workflow_service.run_draft_workflow_node(
+            app_model=app_proxy,  # type: ignore[arg-type]
+            draft_workflow=draft_workflow,
+            node_id=node_id,
+            user_inputs=user_inputs,
+            account=account,
+            query=query,
+            files=files,
+        )
+
+    @classmethod
+    def generate_single_iteration(
+        cls,
+        snippet: CustomizedSnippet,
+        user: Union[Account, EndUser],
+        node_id: str,
+        args: Mapping[str, Any],
+        streaming: bool = True,
+    ) -> Union[Mapping[str, Any], Generator[Mapping[str, Any] | str, None, None]]:
+        """
+        Run a single iteration node in a snippet's draft workflow.
+
+        Iteration nodes are container nodes that execute their sub-graph multiple
+        times, producing many events. Therefore, this uses the full WorkflowAppGenerator
+        pipeline with SSE streaming (unlike regular single-step node run).
+
+        :param snippet: CustomizedSnippet instance
+        :param user: Account or EndUser initiating the run
+        :param node_id: ID of the iteration node to run
+        :param args: Dict containing 'inputs' key with iteration input data
+        :param streaming: Whether to stream the response (should be True)
+        :return: SSE streaming generator
+        :raises ValueError: If the snippet has no draft workflow
+        """
+        snippet_service = SnippetService()
+        workflow = snippet_service.get_draft_workflow(snippet=snippet)
+        if not workflow:
+            raise ValueError("Workflow not initialized")
+
+        app_proxy = _SnippetAsApp(snippet)
+
+        return WorkflowAppGenerator.convert_to_event_stream(
+            WorkflowAppGenerator().single_iteration_generate(
+                app_model=app_proxy,  # type: ignore[arg-type]
+                workflow=workflow,
+                node_id=node_id,
+                user=user,
+                args=args,
+                streaming=streaming,
+            )
+        )
+
+    @classmethod
+    def generate_single_loop(
+        cls,
+        snippet: CustomizedSnippet,
+        user: Union[Account, EndUser],
+        node_id: str,
+        args: Any,
+        streaming: bool = True,
+    ) -> Union[Mapping[str, Any], Generator[Mapping[str, Any] | str, None, None]]:
+        """
+        Run a single loop node in a snippet's draft workflow.
+
+        Loop nodes are container nodes that execute their sub-graph repeatedly,
+        producing many events. Therefore, this uses the full WorkflowAppGenerator
+        pipeline with SSE streaming (unlike regular single-step node run).
+
+        :param snippet: CustomizedSnippet instance
+        :param user: Account or EndUser initiating the run
+        :param node_id: ID of the loop node to run
+        :param args: Pydantic model with 'inputs' attribute containing loop input data
+        :param streaming: Whether to stream the response (should be True)
+        :return: SSE streaming generator
+        :raises ValueError: If the snippet has no draft workflow
+        """
+        snippet_service = SnippetService()
+        workflow = snippet_service.get_draft_workflow(snippet=snippet)
+        if not workflow:
+            raise ValueError("Workflow not initialized")
+
+        app_proxy = _SnippetAsApp(snippet)
+
+        return WorkflowAppGenerator.convert_to_event_stream(
+            WorkflowAppGenerator().single_loop_generate(
+                app_model=app_proxy,  # type: ignore[arg-type]
+                workflow=workflow,
+                node_id=node_id,
+                user=user,
+                args=args,  # type: ignore[arg-type]
+                streaming=streaming,
+            )
+        )
+
+    @staticmethod
+    def parse_files(workflow: Workflow, files: list[dict] | None = None) -> Sequence[File]:
+        """
+        Parse file mappings into File objects based on workflow configuration.
+
+        :param workflow: Workflow instance for file upload config
+        :param files: Raw file mapping dicts
+        :return: Parsed File objects
+        """
+        files = files or []
+        file_extra_config = FileUploadConfigManager.convert(workflow.features_dict, is_vision=False)
+        if file_extra_config is None:
+            return []
+        return file_factory.build_from_mappings(
+            mappings=files,
+            tenant_id=workflow.tenant_id,
+            config=file_extra_config,
+        )

api/services/snippet_service.py

@@ -0,0 +1,566 @@
+import json
+import logging
+from collections.abc import Mapping, Sequence
+from datetime import UTC, datetime
+from typing import Any
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session, sessionmaker
+
+from core.variables.variables import VariableBase
+from core.workflow.enums import NodeType
+from core.workflow.nodes.node_mapping import LATEST_VERSION, NODE_TYPE_CLASSES_MAPPING
+from extensions.ext_database import db
+from libs.infinite_scroll_pagination import InfiniteScrollPagination
+from models import Account
+from models.enums import WorkflowRunTriggeredFrom
+from models.snippet import CustomizedSnippet, SnippetType
+from models.workflow import (
+    Workflow,
+    WorkflowNodeExecutionModel,
+    WorkflowRun,
+    WorkflowType,
+)
+from repositories.factory import DifyAPIRepositoryFactory
+from services.errors.app import WorkflowHashNotEqualError
+
+logger = logging.getLogger(__name__)
+
+
+class SnippetService:
+    """Service for managing customized snippets."""
+
+    def __init__(self, session_maker: sessionmaker | None = None):
+        """Initialize SnippetService with repository dependencies."""
+        if session_maker is None:
+            session_maker = sessionmaker(bind=db.engine, expire_on_commit=False)
+        self._node_execution_service_repo = DifyAPIRepositoryFactory.create_api_workflow_node_execution_repository(
+            session_maker
+        )
+        self._workflow_run_repo = DifyAPIRepositoryFactory.create_api_workflow_run_repository(session_maker)
+
+    # --- CRUD Operations ---
+
+    @staticmethod
+    def get_snippets(
+        *,
+        tenant_id: str,
+        page: int = 1,
+        limit: int = 20,
+        keyword: str | None = None,
+    ) -> tuple[Sequence[CustomizedSnippet], int, bool]:
+        """
+        Get paginated list of snippets with optional search.
+
+        :param tenant_id: Tenant ID
+        :param page: Page number (1-indexed)
+        :param limit: Number of items per page
+        :param keyword: Optional search keyword for name/description
+        :return: Tuple of (snippets list, total count, has_more flag)
+        """
+        stmt = (
+            select(CustomizedSnippet)
+            .where(CustomizedSnippet.tenant_id == tenant_id)
+            .order_by(CustomizedSnippet.created_at.desc())
+        )
+
+        if keyword:
+            stmt = stmt.where(
+                CustomizedSnippet.name.ilike(f"%{keyword}%") | CustomizedSnippet.description.ilike(f"%{keyword}%")
+            )
+
+        # Get total count
+        count_stmt = select(func.count()).select_from(stmt.subquery())
+        total = db.session.scalar(count_stmt) or 0
+
+        # Apply pagination
+        stmt = stmt.limit(limit + 1).offset((page - 1) * limit)
+        snippets = list(db.session.scalars(stmt).all())
+
+        has_more = len(snippets) > limit
+        if has_more:
+            snippets = snippets[:-1]
+
+        return snippets, total, has_more
+
+    @staticmethod
+    def get_snippet_by_id(
+        *,
+        snippet_id: str,
+        tenant_id: str,
+    ) -> CustomizedSnippet | None:
+        """
+        Get snippet by ID with tenant isolation.
+
+        :param snippet_id: Snippet ID
+        :param tenant_id: Tenant ID
+        :return: CustomizedSnippet or None
+        """
+        return (
+            db.session.query(CustomizedSnippet)
+            .where(
+                CustomizedSnippet.id == snippet_id,
+                CustomizedSnippet.tenant_id == tenant_id,
+            )
+            .first()
+        )
+
+    @staticmethod
+    def create_snippet(
+        *,
+        tenant_id: str,
+        name: str,
+        description: str | None,
+        snippet_type: SnippetType,
+        icon_info: dict | None,
+        graph: dict | None,
+        input_fields: list[dict] | None,
+        account: Account,
+    ) -> CustomizedSnippet:
+        """
+        Create a new snippet.
+
+        :param tenant_id: Tenant ID
+        :param name: Snippet name (must be unique per tenant)
+        :param description: Snippet description
+        :param snippet_type: Type of snippet (node or group)
+        :param icon_info: Icon information
+        :param graph: Workflow graph structure
+        :param input_fields: Input field definitions
+        :param account: Creator account
+        :return: Created CustomizedSnippet
+        :raises ValueError: If name already exists
+        """
+        # Check if name already exists for this tenant
+        existing = (
+            db.session.query(CustomizedSnippet)
+            .where(
+                CustomizedSnippet.tenant_id == tenant_id,
+                CustomizedSnippet.name == name,
+            )
+            .first()
+        )
+        if existing:
+            raise ValueError(f"Snippet with name '{name}' already exists")
+
+        snippet = CustomizedSnippet(
+            tenant_id=tenant_id,
+            name=name,
+            description=description or "",
+            type=snippet_type.value,
+            icon_info=icon_info,
+            graph=json.dumps(graph) if graph else None,
+            input_fields=json.dumps(input_fields) if input_fields else None,
+            created_by=account.id,
+        )
+
+        db.session.add(snippet)
+        db.session.commit()
+
+        return snippet
+
+    @staticmethod
+    def update_snippet(
+        *,
+        session: Session,
+        snippet: CustomizedSnippet,
+        account_id: str,
+        data: dict,
+    ) -> CustomizedSnippet:
+        """
+        Update snippet attributes.
+
+        :param session: Database session
+        :param snippet: Snippet to update
+        :param account_id: ID of account making the update
+        :param data: Dictionary of fields to update
+        :return: Updated CustomizedSnippet
+        """
+        if "name" in data:
+            # Check if new name already exists for this tenant
+            existing = (
+                session.query(CustomizedSnippet)
+                .where(
+                    CustomizedSnippet.tenant_id == snippet.tenant_id,
+                    CustomizedSnippet.name == data["name"],
+                    CustomizedSnippet.id != snippet.id,
+                )
+                .first()
+            )
+            if existing:
+                raise ValueError(f"Snippet with name '{data['name']}' already exists")
+            snippet.name = data["name"]
+
+        if "description" in data:
+            snippet.description = data["description"]
+
+        if "icon_info" in data:
+            snippet.icon_info = data["icon_info"]
+
+        snippet.updated_by = account_id
+        snippet.updated_at = datetime.now(UTC).replace(tzinfo=None)
+
+        session.add(snippet)
+        return snippet
+
+    @staticmethod
+    def delete_snippet(
+        *,
+        session: Session,
+        snippet: CustomizedSnippet,
+    ) -> bool:
+        """
+        Delete a snippet.
+
+        :param session: Database session
+        :param snippet: Snippet to delete
+        :return: True if deleted successfully
+        """
+        session.delete(snippet)
+        return True
+
+    # --- Workflow Operations ---
+
+    def get_draft_workflow(self, snippet: CustomizedSnippet) -> Workflow | None:
+        """
+        Get draft workflow for snippet.
+
+        :param snippet: CustomizedSnippet instance
+        :return: Draft Workflow or None
+        """
+        workflow = (
+            db.session.query(Workflow)
+            .where(
+                Workflow.tenant_id == snippet.tenant_id,
+                Workflow.app_id == snippet.id,
+                Workflow.type == WorkflowType.SNIPPET.value,
+                Workflow.version == "draft",
+            )
+            .first()
+        )
+        return workflow
+
+    def get_published_workflow(self, snippet: CustomizedSnippet) -> Workflow | None:
+        """
+        Get published workflow for snippet.
+
+        :param snippet: CustomizedSnippet instance
+        :return: Published Workflow or None
+        """
+        if not snippet.workflow_id:
+            return None
+
+        workflow = (
+            db.session.query(Workflow)
+            .where(
+                Workflow.tenant_id == snippet.tenant_id,
+                Workflow.app_id == snippet.id,
+                Workflow.type == WorkflowType.SNIPPET.value,
+                Workflow.id == snippet.workflow_id,
+            )
+            .first()
+        )
+        return workflow
+
+    def sync_draft_workflow(
+        self,
+        *,
+        snippet: CustomizedSnippet,
+        graph: dict,
+        unique_hash: str | None,
+        account: Account,
+        environment_variables: Sequence[VariableBase],
+        conversation_variables: Sequence[VariableBase],
+        input_variables: list[dict] | None = None,
+    ) -> Workflow:
+        """
+        Sync draft workflow for snippet.
+
+        :param snippet: CustomizedSnippet instance
+        :param graph: Workflow graph configuration
+        :param unique_hash: Hash for conflict detection
+        :param account: Account making the change
+        :param environment_variables: Environment variables
+        :param conversation_variables: Conversation variables
+        :param input_variables: Input variables for snippet
+        :return: Synced Workflow
+        :raises WorkflowHashNotEqualError: If hash mismatch
+        """
+        workflow = self.get_draft_workflow(snippet=snippet)
+
+        if workflow and workflow.unique_hash != unique_hash:
+            raise WorkflowHashNotEqualError()
+
+        # Create draft workflow if not found
+        if not workflow:
+            workflow = Workflow(
+                tenant_id=snippet.tenant_id,
+                app_id=snippet.id,
+                features="{}",
+                type=WorkflowType.SNIPPET.value,
+                version="draft",
+                graph=json.dumps(graph),
+                created_by=account.id,
+                environment_variables=environment_variables,
+                conversation_variables=conversation_variables,
+            )
+            db.session.add(workflow)
+            db.session.flush()
+        else:
+            # Update existing draft workflow
+            workflow.graph = json.dumps(graph)
+            workflow.updated_by = account.id
+            workflow.updated_at = datetime.now(UTC).replace(tzinfo=None)
+            workflow.environment_variables = environment_variables
+            workflow.conversation_variables = conversation_variables
+
+        # Update snippet's input_fields if provided
+        if input_variables is not None:
+            snippet.input_fields = json.dumps(input_variables)
+            snippet.updated_by = account.id
+            snippet.updated_at = datetime.now(UTC).replace(tzinfo=None)
+
+        db.session.commit()
+        return workflow
+
+    def publish_workflow(
+        self,
+        *,
+        session: Session,
+        snippet: CustomizedSnippet,
+        account: Account,
+    ) -> Workflow:
+        """
+        Publish the draft workflow as a new version.
+
+        :param session: Database session
+        :param snippet: CustomizedSnippet instance
+        :param account: Account making the change
+        :return: Published Workflow
+        :raises ValueError: If no draft workflow exists
+        """
+        draft_workflow_stmt = select(Workflow).where(
+            Workflow.tenant_id == snippet.tenant_id,
+            Workflow.app_id == snippet.id,
+            Workflow.type == WorkflowType.SNIPPET.value,
+            Workflow.version == "draft",
+        )
+        draft_workflow = session.scalar(draft_workflow_stmt)
+        if not draft_workflow:
+            raise ValueError("No valid workflow found.")
+
+        # Create new published workflow
+        workflow = Workflow.new(
+            tenant_id=snippet.tenant_id,
+            app_id=snippet.id,
+            type=draft_workflow.type,
+            version=str(datetime.now(UTC).replace(tzinfo=None)),
+            graph=draft_workflow.graph,
+            features=draft_workflow.features,
+            created_by=account.id,
+            environment_variables=draft_workflow.environment_variables,
+            conversation_variables=draft_workflow.conversation_variables,
+            marked_name="",
+            marked_comment="",
+        )
+        session.add(workflow)
+
+        # Update snippet version
+        snippet.version += 1
+        snippet.is_published = True
+        snippet.workflow_id = workflow.id
+        snippet.updated_by = account.id
+        session.add(snippet)
+
+        return workflow
+
+    def get_all_published_workflows(
+        self,
+        *,
+        session: Session,
+        snippet: CustomizedSnippet,
+        page: int,
+        limit: int,
+    ) -> tuple[Sequence[Workflow], bool]:
+        """
+        Get all published workflow versions for snippet.
+
+        :param session: Database session
+        :param snippet: CustomizedSnippet instance
+        :param page: Page number
+        :param limit: Items per page
+        :return: Tuple of (workflows list, has_more flag)
+        """
+        if not snippet.workflow_id:
+            return [], False
+
+        stmt = (
+            select(Workflow)
+            .where(
+                Workflow.app_id == snippet.id,
+                Workflow.type == WorkflowType.SNIPPET.value,
+                Workflow.version != "draft",
+            )
+            .order_by(Workflow.version.desc())
+            .limit(limit + 1)
+            .offset((page - 1) * limit)
+        )
+
+        workflows = list(session.scalars(stmt).all())
+        has_more = len(workflows) > limit
+        if has_more:
+            workflows = workflows[:-1]
+
+        return workflows, has_more
+
+    # --- Default Block Configs ---
+
+    def get_default_block_configs(self) -> list[dict]:
+        """
+        Get default block configurations for all node types.
+
+        :return: List of default configurations
+        """
+        default_block_configs: list[dict[str, Any]] = []
+        for node_class_mapping in NODE_TYPE_CLASSES_MAPPING.values():
+            node_class = node_class_mapping[LATEST_VERSION]
+            default_config = node_class.get_default_config()
+            if default_config:
+                default_block_configs.append(dict(default_config))
+
+        return default_block_configs
+
+    def get_default_block_config(self, node_type: str, filters: dict | None = None) -> Mapping[str, object] | None:
+        """
+        Get default config for specific node type.
+
+        :param node_type: Node type string
+        :param filters: Optional filters
+        :return: Default configuration or None
+        """
+        node_type_enum = NodeType(node_type)
+
+        if node_type_enum not in NODE_TYPE_CLASSES_MAPPING:
+            return None
+
+        node_class = NODE_TYPE_CLASSES_MAPPING[node_type_enum][LATEST_VERSION]
+        default_config = node_class.get_default_config(filters=filters)
+        if not default_config:
+            return None
+
+        return default_config
+
+    # --- Workflow Run Operations ---
+
+    def get_snippet_workflow_runs(
+        self,
+        *,
+        snippet: CustomizedSnippet,
+        args: dict,
+    ) -> InfiniteScrollPagination:
+        """
+        Get paginated workflow runs for snippet.
+
+        :param snippet: CustomizedSnippet instance
+        :param args: Request arguments (last_id, limit)
+        :return: InfiniteScrollPagination result
+        """
+        limit = int(args.get("limit", 20))
+        last_id = args.get("last_id")
+
+        triggered_from_values = [
+            WorkflowRunTriggeredFrom.DEBUGGING,
+        ]
+
+        return self._workflow_run_repo.get_paginated_workflow_runs(
+            tenant_id=snippet.tenant_id,
+            app_id=snippet.id,
+            triggered_from=triggered_from_values,
+            limit=limit,
+            last_id=last_id,
+        )
+
+    def get_snippet_workflow_run(
+        self,
+        *,
+        snippet: CustomizedSnippet,
+        run_id: str,
+    ) -> WorkflowRun | None:
+        """
+        Get workflow run details.
+
+        :param snippet: CustomizedSnippet instance
+        :param run_id: Workflow run ID
+        :return: WorkflowRun or None
+        """
+        return self._workflow_run_repo.get_workflow_run_by_id(
+            tenant_id=snippet.tenant_id,
+            app_id=snippet.id,
+            run_id=run_id,
+        )
+
+    def get_snippet_workflow_run_node_executions(
+        self,
+        *,
+        snippet: CustomizedSnippet,
+        run_id: str,
+    ) -> Sequence[WorkflowNodeExecutionModel]:
+        """
+        Get workflow run node execution list.
+
+        :param snippet: CustomizedSnippet instance
+        :param run_id: Workflow run ID
+        :return: List of WorkflowNodeExecutionModel
+        """
+        workflow_run = self.get_snippet_workflow_run(snippet=snippet, run_id=run_id)
+        if not workflow_run:
+            return []
+
+        node_executions = self._node_execution_service_repo.get_executions_by_workflow_run(
+            tenant_id=snippet.tenant_id,
+            app_id=snippet.id,
+            workflow_run_id=workflow_run.id,
+        )
+
+        return node_executions
+
+    # --- Node Execution Operations ---
+
+    def get_snippet_node_last_run(
+        self,
+        *,
+        snippet: CustomizedSnippet,
+        workflow: Workflow,
+        node_id: str,
+    ) -> WorkflowNodeExecutionModel | None:
+        """
+        Get the most recent execution for a specific node in a snippet workflow.
+
+        :param snippet: CustomizedSnippet instance
+        :param workflow: Workflow instance
+        :param node_id: Node identifier
+        :return: WorkflowNodeExecutionModel or None
+        """
+        return self._node_execution_service_repo.get_node_last_execution(
+            tenant_id=snippet.tenant_id,
+            app_id=snippet.id,
+            workflow_id=workflow.id,
+            node_id=node_id,
+        )
+
+    # --- Use Count ---
+
+    @staticmethod
+    def increment_use_count(
+        *,
+        session: Session,
+        snippet: CustomizedSnippet,
+    ) -> None:
+        """
+        Increment the use_count when snippet is used.
+
+        :param session: Database session
+        :param snippet: CustomizedSnippet instance
+        """
+        snippet.use_count += 1
+        session.add(snippet)

api/tests/integration_tests/vdb/oceanbase/bench_oceanbase.py

@@ -0,0 +1,241 @@
+"""
+Benchmark: OceanBase vector store — old (single-row) vs new (batch) insertion,
+metadata query with/without functional index, and vector search across metrics.
+
+Usage:
+    uv run --project api python -m tests.integration_tests.vdb.oceanbase.bench_oceanbase
+"""
+
+import json
+import random
+import statistics
+import time
+import uuid
+
+from pyobvector import VECTOR, ObVecClient, cosine_distance, inner_product, l2_distance
+from sqlalchemy import JSON, Column, String, text
+from sqlalchemy.dialects.mysql import LONGTEXT
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+HOST = "127.0.0.1"
+PORT = 2881
+USER = "root@test"
+PASSWORD = "difyai123456"
+DATABASE = "test"
+
+VEC_DIM = 1536
+HNSW_BUILD = {"M": 16, "efConstruction": 256}
+DISTANCE_FUNCS = {"l2": l2_distance, "cosine": cosine_distance, "inner_product": inner_product}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+def _make_client(**extra):
+    return ObVecClient(
+        uri=f"{HOST}:{PORT}",
+        user=USER,
+        password=PASSWORD,
+        db_name=DATABASE,
+        **extra,
+    )
+
+
+def _rand_vec():
+    return [random.uniform(-1, 1) for _ in range(VEC_DIM)]  # noqa: S311
+
+
+def _drop(client, table):
+    client.drop_table_if_exist(table)
+
+
+def _create_table(client, table, metric="l2"):
+    cols = [
+        Column("id", String(36), primary_key=True, autoincrement=False),
+        Column("vector", VECTOR(VEC_DIM)),
+        Column("text", LONGTEXT),
+        Column("metadata", JSON),
+    ]
+    vidx = client.prepare_index_params()
+    vidx.add_index(
+        field_name="vector",
+        index_type="HNSW",
+        index_name="vector_index",
+        metric_type=metric,
+        params=HNSW_BUILD,
+    )
+    client.create_table_with_index_params(table_name=table, columns=cols, vidxs=vidx)
+    client.refresh_metadata([table])
+
+
+def _gen_rows(n):
+    doc_id = str(uuid.uuid4())
+    rows = []
+    for _ in range(n):
+        rows.append(
+            {
+                "id": str(uuid.uuid4()),
+                "vector": _rand_vec(),
+                "text": f"benchmark text {uuid.uuid4().hex[:12]}",
+                "metadata": json.dumps({"document_id": doc_id, "dataset_id": str(uuid.uuid4())}),
+            }
+        )
+    return rows, doc_id
+
+
+# ---------------------------------------------------------------------------
+# Benchmark: Insertion
+# ---------------------------------------------------------------------------
+def bench_insert_single(client, table, rows):
+    """Old approach: one INSERT per row."""
+    t0 = time.perf_counter()
+    for row in rows:
+        client.insert(table_name=table, data=row)
+    return time.perf_counter() - t0
+
+
+def bench_insert_batch(client, table, rows, batch_size=100):
+    """New approach: batch INSERT."""
+    t0 = time.perf_counter()
+    for start in range(0, len(rows), batch_size):
+        batch = rows[start : start + batch_size]
+        client.insert(table_name=table, data=batch)
+    return time.perf_counter() - t0
+
+
+# ---------------------------------------------------------------------------
+# Benchmark: Metadata query
+# ---------------------------------------------------------------------------
+def bench_metadata_query(client, table, doc_id, with_index=False):
+    """Query by metadata->>'$.document_id' with/without functional index."""
+    if with_index:
+        try:
+            client.perform_raw_text_sql(f"CREATE INDEX idx_metadata_doc_id ON `{table}` ((metadata->>'$.document_id'))")
+        except Exception:
+            pass  # already exists
+
+    sql = text(f"SELECT id FROM `{table}` WHERE metadata->>'$.document_id' = :val")
+    times = []
+    with client.engine.connect() as conn:
+        for _ in range(10):
+            t0 = time.perf_counter()
+            result = conn.execute(sql, {"val": doc_id})
+            _ = result.fetchall()
+            times.append(time.perf_counter() - t0)
+    return times
+
+
+# ---------------------------------------------------------------------------
+# Benchmark: Vector search
+# ---------------------------------------------------------------------------
+def bench_vector_search(client, table, metric, topk=10, n_queries=20):
+    dist_func = DISTANCE_FUNCS[metric]
+    times = []
+    for _ in range(n_queries):
+        q = _rand_vec()
+        t0 = time.perf_counter()
+        cur = client.ann_search(
+            table_name=table,
+            vec_column_name="vector",
+            vec_data=q,
+            topk=topk,
+            distance_func=dist_func,
+            output_column_names=["text", "metadata"],
+            with_dist=True,
+        )
+        _ = list(cur)
+        times.append(time.perf_counter() - t0)
+    return times
+
+
+def _fmt(times):
+    """Format list of durations as 'mean ± stdev'."""
+    m = statistics.mean(times) * 1000
+    s = statistics.stdev(times) * 1000 if len(times) > 1 else 0
+    return f"{m:.1f} ± {s:.1f} ms"
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+def main():
+    client = _make_client()
+    client_pooled = _make_client(pool_size=5, max_overflow=10, pool_recycle=3600, pool_pre_ping=True)
+
+    print("=" * 70)
+    print("OceanBase Vector Store — Performance Benchmark")
+    print(f"  Endpoint : {HOST}:{PORT}")
+    print(f"  Vec dim  : {VEC_DIM}")
+    print("=" * 70)
+
+    # ------------------------------------------------------------------
+    # 1. Insertion benchmark
+    # ------------------------------------------------------------------
+    for n_docs in [100, 500, 1000]:
+        rows, doc_id = _gen_rows(n_docs)
+        tbl_single = f"bench_single_{n_docs}"
+        tbl_batch = f"bench_batch_{n_docs}"
+
+        _drop(client, tbl_single)
+        _drop(client, tbl_batch)
+        _create_table(client, tbl_single)
+        _create_table(client, tbl_batch)
+
+        t_single = bench_insert_single(client, tbl_single, rows)
+        t_batch = bench_insert_batch(client_pooled, tbl_batch, rows, batch_size=100)
+
+        speedup = t_single / t_batch if t_batch > 0 else float("inf")
+        print(f"\n[Insert {n_docs} docs]")
+        print(f"  Single-row : {t_single:.2f}s")
+        print(f"  Batch(100) : {t_batch:.2f}s")
+        print(f"  Speedup    : {speedup:.1f}x")
+
+    # ------------------------------------------------------------------
+    # 2. Metadata query benchmark (use the 1000-doc batch table)
+    # ------------------------------------------------------------------
+    tbl_meta = "bench_batch_1000"
+    rows_1000, doc_id_1000 = _gen_rows(1000)
+    # The table already has 1000 rows from step 1; use that doc_id
+    # Re-query doc_id from one of the rows we inserted
+    with client.engine.connect() as conn:
+        res = conn.execute(text(f"SELECT metadata->>'$.document_id' FROM `{tbl_meta}` LIMIT 1"))
+        doc_id_1000 = res.fetchone()[0]
+
+    print("\n[Metadata filter query — 1000 rows, by document_id]")
+    times_no_idx = bench_metadata_query(client, tbl_meta, doc_id_1000, with_index=False)
+    print(f"  Without index : {_fmt(times_no_idx)}")
+    times_with_idx = bench_metadata_query(client, tbl_meta, doc_id_1000, with_index=True)
+    print(f"  With index    : {_fmt(times_with_idx)}")
+
+    # ------------------------------------------------------------------
+    # 3. Vector search benchmark — across metrics
+    # ------------------------------------------------------------------
+    print("\n[Vector search — top-10, 20 queries each, on 1000 rows]")
+
+    for metric in ["l2", "cosine", "inner_product"]:
+        tbl_vs = f"bench_vs_{metric}"
+        _drop(client_pooled, tbl_vs)
+        _create_table(client_pooled, tbl_vs, metric=metric)
+        # Insert 1000 rows
+        rows_vs, _ = _gen_rows(1000)
+        bench_insert_batch(client_pooled, tbl_vs, rows_vs, batch_size=100)
+        times = bench_vector_search(client_pooled, tbl_vs, metric, topk=10, n_queries=20)
+        print(f"  {metric:15s}: {_fmt(times)}")
+        _drop(client_pooled, tbl_vs)
+
+    # ------------------------------------------------------------------
+    # Cleanup
+    # ------------------------------------------------------------------
+    for n in [100, 500, 1000]:
+        _drop(client, f"bench_single_{n}")
+        _drop(client, f"bench_batch_{n}")
+
+    print("\n" + "=" * 70)
+    print("Benchmark complete.")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

api/tests/integration_tests/vdb/oceanbase/test_oceanbase.py

@@ -21,6 +21,7 @@ def oceanbase_vector():
             database="test",
             password="difyai123456",
             enable_hybrid_search=True,
+            batch_size=10,
         ),
     )
 

api/tests/test_containers_integration_tests/services/test_metadata_service.py

@@ -914,9 +914,6 @@ class TestMetadataService:
         metadata_args = MetadataArgs(type="string", name="test_metadata")
         metadata = MetadataService.create_metadata(dataset.id, metadata_args)
 
-        # Mock DocumentService.get_document to return None (document not found)
-        mock_external_service_dependencies["document_service"].get_document.return_value = None
-
         # Create metadata operation data
         from services.entities.knowledge_entities.knowledge_entities import (
             DocumentMetadataOperation,
@@ -926,16 +923,17 @@ class TestMetadataService:
 
         metadata_detail = MetadataDetail(id=metadata.id, name=metadata.name, value="test_value")
 
-        operation = DocumentMetadataOperation(document_id="non-existent-document-id", metadata_list=[metadata_detail])
+        # Use a valid UUID format that does not exist in the database
+        operation = DocumentMetadataOperation(
+            document_id="00000000-0000-0000-0000-000000000000", metadata_list=[metadata_detail]
+        )
 
         operation_data = MetadataOperationData(operation_data=[operation])
 
-        # Act: Execute the method under test
-        # The method should handle the error gracefully and continue
-        MetadataService.update_documents_metadata(dataset, operation_data)
-
-        # Assert: Verify the method completes without raising exceptions
-        # The main functionality (error handling) is verified
+        # Act & Assert: The method should raise ValueError("Document not found.")
+        # because the exception is now re-raised after rollback
+        with pytest.raises(ValueError, match="Document not found"):
+            MetadataService.update_documents_metadata(dataset, operation_data)
 
     def test_knowledge_base_metadata_lock_check_dataset_id(
         self, db_session_with_containers, mock_external_service_dependencies

api/tests/unit_tests/services/test_metadata_partial_update.py

@@ -1,6 +1,8 @@
 import unittest
 from unittest.mock import MagicMock, patch
 
+import pytest
+
 from models.dataset import Dataset, Document
 from services.entities.knowledge_entities.knowledge_entities import (
     DocumentMetadataOperation,
@@ -148,6 +150,38 @@ class TestMetadataPartialUpdate(unittest.TestCase):
         # If it were added, there would be 2 calls. If skipped, 1 call.
         assert mock_db.session.add.call_count == 1
 
+    @patch("services.metadata_service.db")
+    @patch("services.metadata_service.DocumentService")
+    @patch("services.metadata_service.current_account_with_tenant")
+    @patch("services.metadata_service.redis_client")
+    def test_rollback_called_on_commit_failure(self, mock_redis, mock_current_account, mock_document_service, mock_db):
+        """When db.session.commit() raises, rollback must be called and the exception must propagate."""
+        # Setup mocks
+        mock_redis.get.return_value = None
+        mock_document_service.get_document.return_value = self.document
+        mock_current_account.return_value = (MagicMock(id="user_id"), "tenant_id")
+        mock_db.session.query.return_value.filter_by.return_value.first.return_value = None
+
+        # Make commit raise an exception
+        mock_db.session.commit.side_effect = RuntimeError("database connection lost")
+
+        operation = DocumentMetadataOperation(
+            document_id="doc_id",
+            metadata_list=[MetadataDetail(id="meta_id", name="key", value="value")],
+            partial_update=True,
+        )
+        metadata_args = MetadataOperationData(operation_data=[operation])
+
+        # Act & Assert: the exception must propagate
+        with pytest.raises(RuntimeError, match="database connection lost"):
+            MetadataService.update_documents_metadata(self.dataset, metadata_args)
+
+        # Verify rollback was called
+        mock_db.session.rollback.assert_called_once()
+
+        # Verify the lock key was cleaned up despite the failure
+        mock_redis.delete.assert_called_with("document_metadata_lock_doc_id")
+
 
 if __name__ == "__main__":
     unittest.main()

api/uv.lock

@@ -1635,7 +1635,7 @@ requires-dist = [
     { name = "pycryptodome", specifier = "==3.23.0" },
     { name = "pydantic", specifier = "~=2.11.4" },
     { name = "pydantic-extra-types", specifier = "~=2.10.3" },
-    { name = "pydantic-settings", specifier = "~=2.11.0" },
+    { name = "pydantic-settings", specifier = "~=2.12.0" },
     { name = "pyjwt", specifier = "~=2.10.1" },
     { name = "pypdfium2", specifier = "==5.2.0" },
     { name = "python-docx", specifier = "~=1.1.0" },
@@ -4473,39 +4473,39 @@ wheels = [
 
 [[package]]
 name = "pillow"
-version = "12.0.0"
+version = "12.1.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/5a/b0/cace85a1b0c9775a9f8f5d5423c8261c858760e2466c79b2dd184638b056/pillow-12.0.0.tar.gz", hash = "sha256:87d4f8125c9988bfbed67af47dd7a953e2fc7b0cc1e7800ec6d2080d490bb353", size = 47008828, upload-time = "2025-10-15T18:24:14.008Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/1f/42/5c74462b4fd957fcd7b13b04fb3205ff8349236ea74c7c375766d6c82288/pillow-12.1.1.tar.gz", hash = "sha256:9ad8fa5937ab05218e2b6a4cff30295ad35afd2f83ac592e68c0d871bb0fdbc4", size = 46980264, upload-time = "2026-02-11T04:23:07.146Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/0e/5a/a2f6773b64edb921a756eb0729068acad9fc5208a53f4a349396e9436721/pillow-12.0.0-cp311-cp311-macosx_10_10_x86_64.whl", hash = "sha256:0fd00cac9c03256c8b2ff58f162ebcd2587ad3e1f2e397eab718c47e24d231cc", size = 5289798, upload-time = "2025-10-15T18:21:47.763Z" },
-    { url = "https://files.pythonhosted.org/packages/2e/05/069b1f8a2e4b5a37493da6c5868531c3f77b85e716ad7a590ef87d58730d/pillow-12.0.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:a3475b96f5908b3b16c47533daaa87380c491357d197564e0ba34ae75c0f3257", size = 4650589, upload-time = "2025-10-15T18:21:49.515Z" },
-    { url = "https://files.pythonhosted.org/packages/61/e3/2c820d6e9a36432503ead175ae294f96861b07600a7156154a086ba7111a/pillow-12.0.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:110486b79f2d112cf6add83b28b627e369219388f64ef2f960fef9ebaf54c642", size = 6230472, upload-time = "2025-10-15T18:21:51.052Z" },
-    { url = "https://files.pythonhosted.org/packages/4f/89/63427f51c64209c5e23d4d52071c8d0f21024d3a8a487737caaf614a5795/pillow-12.0.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:5269cc1caeedb67e6f7269a42014f381f45e2e7cd42d834ede3c703a1d915fe3", size = 8033887, upload-time = "2025-10-15T18:21:52.604Z" },
-    { url = "https://files.pythonhosted.org/packages/f6/1b/c9711318d4901093c15840f268ad649459cd81984c9ec9887756cca049a5/pillow-12.0.0-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:aa5129de4e174daccbc59d0a3b6d20eaf24417d59851c07ebb37aeb02947987c", size = 6343964, upload-time = "2025-10-15T18:21:54.619Z" },
-    { url = "https://files.pythonhosted.org/packages/41/1e/db9470f2d030b4995083044cd8738cdd1bf773106819f6d8ba12597d5352/pillow-12.0.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bee2a6db3a7242ea309aa7ee8e2780726fed67ff4e5b40169f2c940e7eb09227", size = 7034756, upload-time = "2025-10-15T18:21:56.151Z" },
-    { url = "https://files.pythonhosted.org/packages/cc/b0/6177a8bdd5ee4ed87cba2de5a3cc1db55ffbbec6176784ce5bb75aa96798/pillow-12.0.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:90387104ee8400a7b4598253b4c406f8958f59fcf983a6cea2b50d59f7d63d0b", size = 6458075, upload-time = "2025-10-15T18:21:57.759Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/5e/61537aa6fa977922c6a03253a0e727e6e4a72381a80d63ad8eec350684f2/pillow-12.0.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:bc91a56697869546d1b8f0a3ff35224557ae7f881050e99f615e0119bf934b4e", size = 7125955, upload-time = "2025-10-15T18:21:59.372Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/3d/d5033539344ee3cbd9a4d69e12e63ca3a44a739eb2d4c8da350a3d38edd7/pillow-12.0.0-cp311-cp311-win32.whl", hash = "sha256:27f95b12453d165099c84f8a8bfdfd46b9e4bda9e0e4b65f0635430027f55739", size = 6298440, upload-time = "2025-10-15T18:22:00.982Z" },
-    { url = "https://files.pythonhosted.org/packages/4d/42/aaca386de5cc8bd8a0254516957c1f265e3521c91515b16e286c662854c4/pillow-12.0.0-cp311-cp311-win_amd64.whl", hash = "sha256:b583dc9070312190192631373c6c8ed277254aa6e6084b74bdd0a6d3b221608e", size = 6999256, upload-time = "2025-10-15T18:22:02.617Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/f1/9197c9c2d5708b785f631a6dfbfa8eb3fb9672837cb92ae9af812c13b4ed/pillow-12.0.0-cp311-cp311-win_arm64.whl", hash = "sha256:759de84a33be3b178a64c8ba28ad5c135900359e85fb662bc6e403ad4407791d", size = 2436025, upload-time = "2025-10-15T18:22:04.598Z" },
-    { url = "https://files.pythonhosted.org/packages/2c/90/4fcce2c22caf044e660a198d740e7fbc14395619e3cb1abad12192c0826c/pillow-12.0.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:53561a4ddc36facb432fae7a9d8afbfaf94795414f5cdc5fc52f28c1dca90371", size = 5249377, upload-time = "2025-10-15T18:22:05.993Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/e0/ed960067543d080691d47d6938ebccbf3976a931c9567ab2fbfab983a5dd/pillow-12.0.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:71db6b4c1653045dacc1585c1b0d184004f0d7e694c7b34ac165ca70c0838082", size = 4650343, upload-time = "2025-10-15T18:22:07.718Z" },
-    { url = "https://files.pythonhosted.org/packages/e7/a1/f81fdeddcb99c044bf7d6faa47e12850f13cee0849537a7d27eeab5534d4/pillow-12.0.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:2fa5f0b6716fc88f11380b88b31fe591a06c6315e955c096c35715788b339e3f", size = 6232981, upload-time = "2025-10-15T18:22:09.287Z" },
-    { url = "https://files.pythonhosted.org/packages/88/e1/9098d3ce341a8750b55b0e00c03f1630d6178f38ac191c81c97a3b047b44/pillow-12.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:82240051c6ca513c616f7f9da06e871f61bfd7805f566275841af15015b8f98d", size = 8041399, upload-time = "2025-10-15T18:22:10.872Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/62/a22e8d3b602ae8cc01446d0c57a54e982737f44b6f2e1e019a925143771d/pillow-12.0.0-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:55f818bd74fe2f11d4d7cbc65880a843c4075e0ac7226bc1a23261dbea531953", size = 6347740, upload-time = "2025-10-15T18:22:12.769Z" },
-    { url = "https://files.pythonhosted.org/packages/4f/87/424511bdcd02c8d7acf9f65caa09f291a519b16bd83c3fb3374b3d4ae951/pillow-12.0.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b87843e225e74576437fd5b6a4c2205d422754f84a06942cfaf1dc32243e45a8", size = 7040201, upload-time = "2025-10-15T18:22:14.813Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/4d/435c8ac688c54d11755aedfdd9f29c9eeddf68d150fe42d1d3dbd2365149/pillow-12.0.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:c607c90ba67533e1b2355b821fef6764d1dd2cbe26b8c1005ae84f7aea25ff79", size = 6462334, upload-time = "2025-10-15T18:22:16.375Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/f2/ad34167a8059a59b8ad10bc5c72d4d9b35acc6b7c0877af8ac885b5f2044/pillow-12.0.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:21f241bdd5080a15bc86d3466a9f6074a9c2c2b314100dd896ac81ee6db2f1ba", size = 7134162, upload-time = "2025-10-15T18:22:17.996Z" },
-    { url = "https://files.pythonhosted.org/packages/0c/b1/a7391df6adacf0a5c2cf6ac1cf1fcc1369e7d439d28f637a847f8803beb3/pillow-12.0.0-cp312-cp312-win32.whl", hash = "sha256:dd333073e0cacdc3089525c7df7d39b211bcdf31fc2824e49d01c6b6187b07d0", size = 6298769, upload-time = "2025-10-15T18:22:19.923Z" },
-    { url = "https://files.pythonhosted.org/packages/a2/0b/d87733741526541c909bbf159e338dcace4f982daac6e5a8d6be225ca32d/pillow-12.0.0-cp312-cp312-win_amd64.whl", hash = "sha256:9fe611163f6303d1619bbcb653540a4d60f9e55e622d60a3108be0d5b441017a", size = 7001107, upload-time = "2025-10-15T18:22:21.644Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/96/aaa61ce33cc98421fb6088af2a03be4157b1e7e0e87087c888e2370a7f45/pillow-12.0.0-cp312-cp312-win_arm64.whl", hash = "sha256:7dfb439562f234f7d57b1ac6bc8fe7f838a4bd49c79230e0f6a1da93e82f1fad", size = 2436012, upload-time = "2025-10-15T18:22:23.621Z" },
-    { url = "https://files.pythonhosted.org/packages/1d/b3/582327e6c9f86d037b63beebe981425d6811104cb443e8193824ef1a2f27/pillow-12.0.0-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:b22bd8c974942477156be55a768f7aa37c46904c175be4e158b6a86e3a6b7ca8", size = 5215068, upload-time = "2025-10-15T18:23:59.594Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/d6/67748211d119f3b6540baf90f92fae73ae51d5217b171b0e8b5f7e5d558f/pillow-12.0.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:805ebf596939e48dbb2e4922a1d3852cfc25c38160751ce02da93058b48d252a", size = 4614994, upload-time = "2025-10-15T18:24:01.669Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/e1/f8281e5d844c41872b273b9f2c34a4bf64ca08905668c8ae730eedc7c9fa/pillow-12.0.0-pp311-pypy311_pp73-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:cae81479f77420d217def5f54b5b9d279804d17e982e0f2fa19b1d1e14ab5197", size = 5246639, upload-time = "2025-10-15T18:24:03.403Z" },
-    { url = "https://files.pythonhosted.org/packages/94/5a/0d8ab8ffe8a102ff5df60d0de5af309015163bf710c7bb3e8311dd3b3ad0/pillow-12.0.0-pp311-pypy311_pp73-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:aeaefa96c768fc66818730b952a862235d68825c178f1b3ffd4efd7ad2edcb7c", size = 6986839, upload-time = "2025-10-15T18:24:05.344Z" },
-    { url = "https://files.pythonhosted.org/packages/20/2e/3434380e8110b76cd9eb00a363c484b050f949b4bbe84ba770bb8508a02c/pillow-12.0.0-pp311-pypy311_pp73-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:09f2d0abef9e4e2f349305a4f8cc784a8a6c2f58a8c4892eea13b10a943bd26e", size = 5313505, upload-time = "2025-10-15T18:24:07.137Z" },
-    { url = "https://files.pythonhosted.org/packages/57/ca/5a9d38900d9d74785141d6580950fe705de68af735ff6e727cb911b64740/pillow-12.0.0-pp311-pypy311_pp73-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bdee52571a343d721fb2eb3b090a82d959ff37fc631e3f70422e0c2e029f3e76", size = 5963654, upload-time = "2025-10-15T18:24:09.579Z" },
-    { url = "https://files.pythonhosted.org/packages/95/7e/f896623c3c635a90537ac093c6a618ebe1a90d87206e42309cb5d98a1b9e/pillow-12.0.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:b290fd8aa38422444d4b50d579de197557f182ef1068b75f5aa8558638b8d0a5", size = 6997850, upload-time = "2025-10-15T18:24:11.495Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/46/5da1ec4a5171ee7bf1a0efa064aba70ba3d6e0788ce3f5acd1375d23c8c0/pillow-12.1.1-cp311-cp311-macosx_10_10_x86_64.whl", hash = "sha256:e879bb6cd5c73848ef3b2b48b8af9ff08c5b71ecda8048b7dd22d8a33f60be32", size = 5304084, upload-time = "2026-02-11T04:20:27.501Z" },
+    { url = "https://files.pythonhosted.org/packages/78/93/a29e9bc02d1cf557a834da780ceccd54e02421627200696fcf805ebdc3fb/pillow-12.1.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:365b10bb9417dd4498c0e3b128018c4a624dc11c7b97d8cc54effe3b096f4c38", size = 4657866, upload-time = "2026-02-11T04:20:29.827Z" },
+    { url = "https://files.pythonhosted.org/packages/13/84/583a4558d492a179d31e4aae32eadce94b9acf49c0337c4ce0b70e0a01f2/pillow-12.1.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:d4ce8e329c93845720cd2014659ca67eac35f6433fd3050393d85f3ecef0dad5", size = 6232148, upload-time = "2026-02-11T04:20:31.329Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/e2/53c43334bbbb2d3b938978532fbda8e62bb6e0b23a26ce8592f36bcc4987/pillow-12.1.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:fc354a04072b765eccf2204f588a7a532c9511e8b9c7f900e1b64e3e33487090", size = 8038007, upload-time = "2026-02-11T04:20:34.225Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/a6/3d0e79c8a9d58150dd98e199d7c1c56861027f3829a3a60b3c2784190180/pillow-12.1.1-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7e7976bf1910a8116b523b9f9f58bf410f3e8aa330cd9a2bb2953f9266ab49af", size = 6345418, upload-time = "2026-02-11T04:20:35.858Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/c8/46dfeac5825e600579157eea177be43e2f7ff4a99da9d0d0a49533509ac5/pillow-12.1.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:597bd9c8419bc7c6af5604e55847789b69123bbe25d65cc6ad3012b4f3c98d8b", size = 7034590, upload-time = "2026-02-11T04:20:37.91Z" },
+    { url = "https://files.pythonhosted.org/packages/af/bf/e6f65d3db8a8bbfeaf9e13cc0417813f6319863a73de934f14b2229ada18/pillow-12.1.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:2c1fc0f2ca5f96a3c8407e41cca26a16e46b21060fe6d5b099d2cb01412222f5", size = 6458655, upload-time = "2026-02-11T04:20:39.496Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/c2/66091f3f34a25894ca129362e510b956ef26f8fb67a0e6417bc5744e56f1/pillow-12.1.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:578510d88c6229d735855e1f278aa305270438d36a05031dfaae5067cc8eb04d", size = 7159286, upload-time = "2026-02-11T04:20:41.139Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/5a/24bc8eb526a22f957d0cec6243146744966d40857e3d8deb68f7902ca6c1/pillow-12.1.1-cp311-cp311-win32.whl", hash = "sha256:7311c0a0dcadb89b36b7025dfd8326ecfa36964e29913074d47382706e516a7c", size = 6328663, upload-time = "2026-02-11T04:20:43.184Z" },
+    { url = "https://files.pythonhosted.org/packages/31/03/bef822e4f2d8f9d7448c133d0a18185d3cce3e70472774fffefe8b0ed562/pillow-12.1.1-cp311-cp311-win_amd64.whl", hash = "sha256:fbfa2a7c10cc2623f412753cddf391c7f971c52ca40a3f65dc5039b2939e8563", size = 7031448, upload-time = "2026-02-11T04:20:44.696Z" },
+    { url = "https://files.pythonhosted.org/packages/49/70/f76296f53610bd17b2e7d31728b8b7825e3ac3b5b3688b51f52eab7c0818/pillow-12.1.1-cp311-cp311-win_arm64.whl", hash = "sha256:b81b5e3511211631b3f672a595e3221252c90af017e399056d0faabb9538aa80", size = 2453651, upload-time = "2026-02-11T04:20:46.243Z" },
+    { url = "https://files.pythonhosted.org/packages/07/d3/8df65da0d4df36b094351dce696f2989bec731d4f10e743b1c5f4da4d3bf/pillow-12.1.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:ab323b787d6e18b3d91a72fc99b1a2c28651e4358749842b8f8dfacd28ef2052", size = 5262803, upload-time = "2026-02-11T04:20:47.653Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/71/5026395b290ff404b836e636f51d7297e6c83beceaa87c592718747e670f/pillow-12.1.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:adebb5bee0f0af4909c30db0d890c773d1a92ffe83da908e2e9e720f8edf3984", size = 4657601, upload-time = "2026-02-11T04:20:49.328Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/2e/1001613d941c67442f745aff0f7cc66dd8df9a9c084eb497e6a543ee6f7e/pillow-12.1.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:bb66b7cc26f50977108790e2456b7921e773f23db5630261102233eb355a3b79", size = 6234995, upload-time = "2026-02-11T04:20:51.032Z" },
+    { url = "https://files.pythonhosted.org/packages/07/26/246ab11455b2549b9233dbd44d358d033a2f780fa9007b61a913c5b2d24e/pillow-12.1.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:aee2810642b2898bb187ced9b349e95d2a7272930796e022efaf12e99dccd293", size = 8045012, upload-time = "2026-02-11T04:20:52.882Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/8b/07587069c27be7535ac1fe33874e32de118fbd34e2a73b7f83436a88368c/pillow-12.1.1-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a0b1cd6232e2b618adcc54d9882e4e662a089d5768cd188f7c245b4c8c44a397", size = 6349638, upload-time = "2026-02-11T04:20:54.444Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/79/6df7b2ee763d619cda2fb4fea498e5f79d984dae304d45a8999b80d6cf5c/pillow-12.1.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7aac39bcf8d4770d089588a2e1dd111cbaa42df5a94be3114222057d68336bd0", size = 7041540, upload-time = "2026-02-11T04:20:55.97Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/5e/2ba19e7e7236d7529f4d873bdaf317a318896bac289abebd4bb00ef247f0/pillow-12.1.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:ab174cd7d29a62dd139c44bf74b698039328f45cb03b4596c43473a46656b2f3", size = 6462613, upload-time = "2026-02-11T04:20:57.542Z" },
+    { url = "https://files.pythonhosted.org/packages/03/03/31216ec124bb5c3dacd74ce8efff4cc7f52643653bad4825f8f08c697743/pillow-12.1.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:339ffdcb7cbeaa08221cd401d517d4b1fe7a9ed5d400e4a8039719238620ca35", size = 7166745, upload-time = "2026-02-11T04:20:59.196Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/e7/7c4552d80052337eb28653b617eafdef39adfb137c49dd7e831b8dc13bc5/pillow-12.1.1-cp312-cp312-win32.whl", hash = "sha256:5d1f9575a12bed9e9eedd9a4972834b08c97a352bd17955ccdebfeca5913fa0a", size = 6328823, upload-time = "2026-02-11T04:21:01.385Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/17/688626d192d7261bbbf98846fc98995726bddc2c945344b65bec3a29d731/pillow-12.1.1-cp312-cp312-win_amd64.whl", hash = "sha256:21329ec8c96c6e979cd0dfd29406c40c1d52521a90544463057d2aaa937d66a6", size = 7033367, upload-time = "2026-02-11T04:21:03.536Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/fe/a0ef1f73f939b0eca03ee2c108d0043a87468664770612602c63266a43c4/pillow-12.1.1-cp312-cp312-win_arm64.whl", hash = "sha256:af9a332e572978f0218686636610555ae3defd1633597be015ed50289a03c523", size = 2453811, upload-time = "2026-02-11T04:21:05.116Z" },
+    { url = "https://files.pythonhosted.org/packages/56/11/5d43209aa4cb58e0cc80127956ff1796a68b928e6324bbf06ef4db34367b/pillow-12.1.1-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:600fd103672b925fe62ed08e0d874ea34d692474df6f4bf7ebe148b30f89f39f", size = 5228606, upload-time = "2026-02-11T04:22:52.106Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/d5/3b005b4e4fda6698b371fa6c21b097d4707585d7db99e98d9b0b87ac612a/pillow-12.1.1-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:665e1b916b043cef294bc54d47bf02d87e13f769bc4bc5fa225a24b3a6c5aca9", size = 4622321, upload-time = "2026-02-11T04:22:53.827Z" },
+    { url = "https://files.pythonhosted.org/packages/df/36/ed3ea2d594356fd8037e5a01f6156c74bc8d92dbb0fa60746cc96cabb6e8/pillow-12.1.1-pp311-pypy311_pp73-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:495c302af3aad1ca67420ddd5c7bd480c8867ad173528767d906428057a11f0e", size = 5247579, upload-time = "2026-02-11T04:22:56.094Z" },
+    { url = "https://files.pythonhosted.org/packages/54/9a/9cc3e029683cf6d20ae5085da0dafc63148e3252c2f13328e553aaa13cfb/pillow-12.1.1-pp311-pypy311_pp73-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:8fd420ef0c52c88b5a035a0886f367748c72147b2b8f384c9d12656678dfdfa9", size = 6989094, upload-time = "2026-02-11T04:22:58.288Z" },
+    { url = "https://files.pythonhosted.org/packages/00/98/fc53ab36da80b88df0967896b6c4b4cd948a0dc5aa40a754266aa3ae48b3/pillow-12.1.1-pp311-pypy311_pp73-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f975aa7ef9684ce7e2c18a3aa8f8e2106ce1e46b94ab713d156b2898811651d3", size = 5313850, upload-time = "2026-02-11T04:23:00.554Z" },
+    { url = "https://files.pythonhosted.org/packages/30/02/00fa585abfd9fe9d73e5f6e554dc36cc2b842898cbfc46d70353dae227f8/pillow-12.1.1-pp311-pypy311_pp73-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8089c852a56c2966cf18835db62d9b34fef7ba74c726ad943928d494fa7f4735", size = 5963343, upload-time = "2026-02-11T04:23:02.934Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/26/c56ce33ca856e358d27fda9676c055395abddb82c35ac0f593877ed4562e/pillow-12.1.1-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:cb9bb857b2d057c6dfc72ac5f3b44836924ba15721882ef103cecb40d002d80e", size = 7029880, upload-time = "2026-02-11T04:23:04.783Z" },
 ]
 
 [[package]]
@@ -4900,16 +4900,16 @@ wheels = [
 
 [[package]]
 name = "pydantic-settings"
-version = "2.11.0"
+version = "2.12.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "pydantic" },
     { name = "python-dotenv" },
     { name = "typing-inspection" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/20/c5/dbbc27b814c71676593d1c3f718e6cd7d4f00652cefa24b75f7aa3efb25e/pydantic_settings-2.11.0.tar.gz", hash = "sha256:d0e87a1c7d33593beb7194adb8470fc426e95ba02af83a0f23474a04c9a08180", size = 188394, upload-time = "2025-09-24T14:19:11.764Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/43/4b/ac7e0aae12027748076d72a8764ff1c9d82ca75a7a52622e67ed3f765c54/pydantic_settings-2.12.0.tar.gz", hash = "sha256:005538ef951e3c2a68e1c08b292b5f2e71490def8589d4221b95dab00dafcfd0", size = 194184, upload-time = "2025-11-10T14:25:47.013Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/83/d6/887a1ff844e64aa823fb4905978d882a633cfe295c32eacad582b78a7d8b/pydantic_settings-2.11.0-py3-none-any.whl", hash = "sha256:fe2cea3413b9530d10f3a5875adffb17ada5c1e1bab0b2885546d7310415207c", size = 48608, upload-time = "2025-09-24T14:19:10.015Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/60/5d4751ba3f4a40a6891f24eec885f51afd78d208498268c734e256fb13c4/pydantic_settings-2.12.0-py3-none-any.whl", hash = "sha256:fddb9fd99a5b18da837b29710391e945b1e30c135477f484084ee513adb93809", size = 51880, upload-time = "2025-11-10T14:25:45.546Z" },
 ]
 
 [[package]]

web/__tests__/apps/app-card-operations-flow.test.tsx

@@ -0,0 +1,462 @@
+/**
+ * Integration test: App Card Operations Flow
+ *
+ * Tests the end-to-end user flows for app card operations:
+ *   - Editing app info
+ *   - Duplicating an app
+ *   - Deleting an app
+ *   - Exporting app DSL
+ *   - Navigation on card click
+ *   - Access mode icons
+ */
+import type { App } from '@/types/app'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import AppCard from '@/app/components/apps/app-card'
+import { AccessMode } from '@/models/access-control'
+import { deleteApp, exportAppConfig, updateAppInfo } from '@/service/apps'
+import { AppModeEnum } from '@/types/app'
+
+let mockIsCurrentWorkspaceEditor = true
+let mockSystemFeatures = {
+  branding: { enabled: false },
+  webapp_auth: { enabled: false },
+}
+
+const mockRouterPush = vi.fn()
+const mockNotify = vi.fn()
+const mockOnPlanInfoChanged = vi.fn()
+
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({
+    push: mockRouterPush,
+  }),
+}))
+
+// Mock headless UI Popover so it renders content without transition
+vi.mock('@headlessui/react', async () => {
+  const actual = await vi.importActual<typeof import('@headlessui/react')>('@headlessui/react')
+  return {
+    ...actual,
+    Popover: ({ children, className }: { children: ((bag: { open: boolean }) => React.ReactNode) | React.ReactNode, className?: string }) => (
+      <div className={className} data-testid="popover-wrapper">
+        {typeof children === 'function' ? children({ open: true }) : children}
+      </div>
+    ),
+    PopoverButton: ({ children, className, ref: _ref, ...rest }: Record<string, unknown>) => (
+      <button className={className as string} {...rest}>{children as React.ReactNode}</button>
+    ),
+    PopoverPanel: ({ children, className }: { children: ((bag: { close: () => void }) => React.ReactNode) | React.ReactNode, className?: string }) => (
+      <div className={className}>
+        {typeof children === 'function' ? children({ close: vi.fn() }) : children}
+      </div>
+    ),
+    Transition: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  }
+})
+
+vi.mock('next/dynamic', () => ({
+  default: (loader: () => Promise<{ default: React.ComponentType }>) => {
+    let Component: React.ComponentType<Record<string, unknown>> | null = null
+    loader().then((mod) => {
+      Component = mod.default as React.ComponentType<Record<string, unknown>>
+    }).catch(() => {})
+    const Wrapper = (props: Record<string, unknown>) => {
+      if (Component)
+        return <Component {...props} />
+      return null
+    }
+    Wrapper.displayName = 'DynamicWrapper'
+    return Wrapper
+  },
+}))
+
+vi.mock('@/context/app-context', () => ({
+  useAppContext: () => ({
+    isCurrentWorkspaceEditor: mockIsCurrentWorkspaceEditor,
+  }),
+}))
+
+vi.mock('@/context/global-public-context', () => ({
+  useGlobalPublicStore: (selector?: (state: Record<string, unknown>) => unknown) => {
+    const state = { systemFeatures: mockSystemFeatures }
+    if (typeof selector === 'function')
+      return selector(state)
+    return mockSystemFeatures
+  },
+}))
+
+vi.mock('@/context/provider-context', () => ({
+  useProviderContext: () => ({
+    onPlanInfoChanged: mockOnPlanInfoChanged,
+  }),
+}))
+
+// Mock the ToastContext used via useContext from use-context-selector
+vi.mock('use-context-selector', async () => {
+  const actual = await vi.importActual<typeof import('use-context-selector')>('use-context-selector')
+  return {
+    ...actual,
+    useContext: () => ({ notify: mockNotify }),
+  }
+})
+
+vi.mock('@/app/components/base/tag-management/store', () => ({
+  useStore: (selector: (state: Record<string, unknown>) => unknown) => {
+    const state = {
+      tagList: [],
+      showTagManagementModal: false,
+      setTagList: vi.fn(),
+      setShowTagManagementModal: vi.fn(),
+    }
+    return selector(state)
+  },
+}))
+
+vi.mock('@/service/tag', () => ({
+  fetchTagList: vi.fn().mockResolvedValue([]),
+}))
+
+vi.mock('@/service/apps', () => ({
+  deleteApp: vi.fn().mockResolvedValue({}),
+  updateAppInfo: vi.fn().mockResolvedValue({}),
+  copyApp: vi.fn().mockResolvedValue({ id: 'new-app-id', mode: 'chat' }),
+  exportAppConfig: vi.fn().mockResolvedValue({ data: 'yaml-content' }),
+}))
+
+vi.mock('@/service/explore', () => ({
+  fetchInstalledAppList: vi.fn().mockResolvedValue({ installed_apps: [] }),
+}))
+
+vi.mock('@/service/workflow', () => ({
+  fetchWorkflowDraft: vi.fn().mockResolvedValue({ environment_variables: [] }),
+}))
+
+vi.mock('@/service/access-control', () => ({
+  useGetUserCanAccessApp: () => ({ data: { result: true }, isLoading: false }),
+}))
+
+vi.mock('@/hooks/use-async-window-open', () => ({
+  useAsyncWindowOpen: () => vi.fn(),
+}))
+
+// Mock modals loaded via next/dynamic
+vi.mock('@/app/components/explore/create-app-modal', () => ({
+  default: ({ show, onConfirm, onHide, appName }: Record<string, unknown>) => {
+    if (!show)
+      return null
+    return (
+      <div data-testid="edit-app-modal">
+        <span data-testid="modal-app-name">{appName as string}</span>
+        <button
+          data-testid="confirm-edit"
+          onClick={() => (onConfirm as (data: Record<string, unknown>) => void)({
+            name: 'Updated App Name',
+            icon_type: 'emoji',
+            icon: '🔥',
+            icon_background: '#fff',
+            description: 'Updated description',
+          })}
+        >
+          Confirm
+        </button>
+        <button data-testid="cancel-edit" onClick={onHide as () => void}>Cancel</button>
+      </div>
+    )
+  },
+}))
+
+vi.mock('@/app/components/app/duplicate-modal', () => ({
+  default: ({ show, onConfirm, onHide }: Record<string, unknown>) => {
+    if (!show)
+      return null
+    return (
+      <div data-testid="duplicate-app-modal">
+        <button
+          data-testid="confirm-duplicate"
+          onClick={() => (onConfirm as (data: Record<string, unknown>) => void)({
+            name: 'Copied App',
+            icon_type: 'emoji',
+            icon: '📋',
+            icon_background: '#fff',
+          })}
+        >
+          Confirm Duplicate
+        </button>
+        <button data-testid="cancel-duplicate" onClick={onHide as () => void}>Cancel</button>
+      </div>
+    )
+  },
+}))
+
+vi.mock('@/app/components/app/switch-app-modal', () => ({
+  default: ({ show, onClose, onSuccess }: Record<string, unknown>) => {
+    if (!show)
+      return null
+    return (
+      <div data-testid="switch-app-modal">
+        <button data-testid="confirm-switch" onClick={onSuccess as () => void}>Confirm Switch</button>
+        <button data-testid="cancel-switch" onClick={onClose as () => void}>Cancel</button>
+      </div>
+    )
+  },
+}))
+
+vi.mock('@/app/components/base/confirm', () => ({
+  default: ({ isShow, onConfirm, onCancel, title }: Record<string, unknown>) => {
+    if (!isShow)
+      return null
+    return (
+      <div data-testid="confirm-delete-modal">
+        <span>{title as string}</span>
+        <button data-testid="confirm-delete" onClick={onConfirm as () => void}>Delete</button>
+        <button data-testid="cancel-delete" onClick={onCancel as () => void}>Cancel</button>
+      </div>
+    )
+  },
+}))
+
+vi.mock('@/app/components/workflow/dsl-export-confirm-modal', () => ({
+  default: ({ onConfirm, onClose }: Record<string, unknown>) => (
+    <div data-testid="dsl-export-confirm-modal">
+      <button data-testid="export-include" onClick={() => (onConfirm as (include: boolean) => void)(true)}>Include</button>
+      <button data-testid="export-close" onClick={onClose as () => void}>Close</button>
+    </div>
+  ),
+}))
+
+vi.mock('@/app/components/app/app-access-control', () => ({
+  default: ({ onConfirm, onClose }: Record<string, unknown>) => (
+    <div data-testid="access-control-modal">
+      <button data-testid="confirm-access" onClick={onConfirm as () => void}>Confirm</button>
+      <button data-testid="cancel-access" onClick={onClose as () => void}>Cancel</button>
+    </div>
+  ),
+}))
+
+const createMockApp = (overrides: Partial<App> = {}): App => ({
+  id: overrides.id ?? 'app-1',
+  name: overrides.name ?? 'Test Chat App',
+  description: overrides.description ?? 'A chat application',
+  author_name: overrides.author_name ?? 'Test Author',
+  icon_type: overrides.icon_type ?? 'emoji',
+  icon: overrides.icon ?? '🤖',
+  icon_background: overrides.icon_background ?? '#FFEAD5',
+  icon_url: overrides.icon_url ?? null,
+  use_icon_as_answer_icon: overrides.use_icon_as_answer_icon ?? false,
+  mode: overrides.mode ?? AppModeEnum.CHAT,
+  enable_site: overrides.enable_site ?? true,
+  enable_api: overrides.enable_api ?? true,
+  api_rpm: overrides.api_rpm ?? 60,
+  api_rph: overrides.api_rph ?? 3600,
+  is_demo: overrides.is_demo ?? false,
+  model_config: overrides.model_config ?? {} as App['model_config'],
+  app_model_config: overrides.app_model_config ?? {} as App['app_model_config'],
+  created_at: overrides.created_at ?? 1700000000,
+  updated_at: overrides.updated_at ?? 1700001000,
+  site: overrides.site ?? {} as App['site'],
+  api_base_url: overrides.api_base_url ?? 'https://api.example.com',
+  tags: overrides.tags ?? [],
+  access_mode: overrides.access_mode ?? AccessMode.PUBLIC,
+  max_active_requests: overrides.max_active_requests ?? null,
+})
+
+const mockOnRefresh = vi.fn()
+
+const renderAppCard = (app?: Partial<App>) => {
+  return render(<AppCard app={createMockApp(app)} onRefresh={mockOnRefresh} />)
+}
+
+describe('App Card Operations Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockIsCurrentWorkspaceEditor = true
+    mockSystemFeatures = {
+      branding: { enabled: false },
+      webapp_auth: { enabled: false },
+    }
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  describe('Card Rendering', () => {
+    it('should render app name and description', () => {
+      renderAppCard({ name: 'My AI Bot', description: 'An intelligent assistant' })
+
+      expect(screen.getByText('My AI Bot')).toBeInTheDocument()
+      expect(screen.getByText('An intelligent assistant')).toBeInTheDocument()
+    })
+
+    it('should render author name', () => {
+      renderAppCard({ author_name: 'John Doe' })
+
+      expect(screen.getByText('John Doe')).toBeInTheDocument()
+    })
+
+    it('should navigate to app config page when card is clicked', () => {
+      renderAppCard({ id: 'app-123', mode: AppModeEnum.CHAT })
+
+      const card = screen.getByText('Test Chat App').closest('[class*="cursor-pointer"]')
+      if (card)
+        fireEvent.click(card)
+
+      expect(mockRouterPush).toHaveBeenCalledWith('/app/app-123/configuration')
+    })
+
+    it('should navigate to workflow page for workflow apps', () => {
+      renderAppCard({ id: 'app-wf', mode: AppModeEnum.WORKFLOW, name: 'WF App' })
+
+      const card = screen.getByText('WF App').closest('[class*="cursor-pointer"]')
+      if (card)
+        fireEvent.click(card)
+
+      expect(mockRouterPush).toHaveBeenCalledWith('/app/app-wf/workflow')
+    })
+  })
+
+  // -- Delete flow --
+  describe('Delete App Flow', () => {
+    it('should show delete confirmation and call API on confirm', async () => {
+      renderAppCard({ id: 'app-to-delete', name: 'Deletable App' })
+
+      // Find and click the more button (popover trigger)
+      const moreIcons = document.querySelectorAll('svg')
+      const moreFill = Array.from(moreIcons).find(svg => svg.closest('[class*="cursor-pointer"]'))
+
+      if (moreFill) {
+        const btn = moreFill.closest('[class*="cursor-pointer"]')
+        if (btn)
+          fireEvent.click(btn)
+
+        await waitFor(() => {
+          const deleteBtn = screen.queryByText('common.operation.delete')
+          if (deleteBtn)
+            fireEvent.click(deleteBtn)
+        })
+
+        const confirmBtn = screen.queryByTestId('confirm-delete')
+        if (confirmBtn) {
+          fireEvent.click(confirmBtn)
+
+          await waitFor(() => {
+            expect(deleteApp).toHaveBeenCalledWith('app-to-delete')
+          })
+        }
+      }
+    })
+  })
+
+  // -- Edit flow --
+  describe('Edit App Flow', () => {
+    it('should open edit modal and call updateAppInfo on confirm', async () => {
+      renderAppCard({ id: 'app-edit', name: 'Editable App' })
+
+      const moreIcons = document.querySelectorAll('svg')
+      const moreFill = Array.from(moreIcons).find(svg => svg.closest('[class*="cursor-pointer"]'))
+
+      if (moreFill) {
+        const btn = moreFill.closest('[class*="cursor-pointer"]')
+        if (btn)
+          fireEvent.click(btn)
+
+        await waitFor(() => {
+          const editBtn = screen.queryByText('app.editApp')
+          if (editBtn)
+            fireEvent.click(editBtn)
+        })
+
+        const confirmEdit = screen.queryByTestId('confirm-edit')
+        if (confirmEdit) {
+          fireEvent.click(confirmEdit)
+
+          await waitFor(() => {
+            expect(updateAppInfo).toHaveBeenCalledWith(
+              expect.objectContaining({
+                appID: 'app-edit',
+                name: 'Updated App Name',
+              }),
+            )
+          })
+        }
+      }
+    })
+  })
+
+  // -- Export flow --
+  describe('Export App Flow', () => {
+    it('should call exportAppConfig for completion apps', async () => {
+      renderAppCard({ id: 'app-export', mode: AppModeEnum.COMPLETION, name: 'Export App' })
+
+      const moreIcons = document.querySelectorAll('svg')
+      const moreFill = Array.from(moreIcons).find(svg => svg.closest('[class*="cursor-pointer"]'))
+
+      if (moreFill) {
+        const btn = moreFill.closest('[class*="cursor-pointer"]')
+        if (btn)
+          fireEvent.click(btn)
+
+        await waitFor(() => {
+          const exportBtn = screen.queryByText('app.export')
+          if (exportBtn)
+            fireEvent.click(exportBtn)
+        })
+
+        await waitFor(() => {
+          expect(exportAppConfig).toHaveBeenCalledWith(
+            expect.objectContaining({ appID: 'app-export' }),
+          )
+        })
+      }
+    })
+  })
+
+  // -- Access mode display --
+  describe('Access Mode Display', () => {
+    it('should not render operations menu for non-editor users', () => {
+      mockIsCurrentWorkspaceEditor = false
+      renderAppCard({ name: 'Readonly App' })
+
+      expect(screen.queryByText('app.editApp')).not.toBeInTheDocument()
+      expect(screen.queryByText('common.operation.delete')).not.toBeInTheDocument()
+    })
+  })
+
+  // -- Switch mode (only for CHAT/COMPLETION) --
+  describe('Switch App Mode', () => {
+    it('should show switch option for chat mode apps', async () => {
+      renderAppCard({ id: 'app-switch', mode: AppModeEnum.CHAT })
+
+      const moreIcons = document.querySelectorAll('svg')
+      const moreFill = Array.from(moreIcons).find(svg => svg.closest('[class*="cursor-pointer"]'))
+
+      if (moreFill) {
+        const btn = moreFill.closest('[class*="cursor-pointer"]')
+        if (btn)
+          fireEvent.click(btn)
+
+        await waitFor(() => {
+          expect(screen.queryByText('app.switch')).toBeInTheDocument()
+        })
+      }
+    })
+
+    it('should not show switch option for workflow apps', async () => {
+      renderAppCard({ id: 'app-wf', mode: AppModeEnum.WORKFLOW, name: 'WF App' })
+
+      const moreIcons = document.querySelectorAll('svg')
+      const moreFill = Array.from(moreIcons).find(svg => svg.closest('[class*="cursor-pointer"]'))
+
+      if (moreFill) {
+        const btn = moreFill.closest('[class*="cursor-pointer"]')
+        if (btn)
+          fireEvent.click(btn)
+
+        await waitFor(() => {
+          expect(screen.queryByText('app.switch')).not.toBeInTheDocument()
+        })
+      }
+    })
+  })
+})

web/__tests__/apps/app-list-browsing-flow.test.tsx

@@ -0,0 +1,442 @@
+/**
+ * Integration test: App List Browsing Flow
+ *
+ * Tests the end-to-end user flow of browsing, filtering, searching,
+ * and tab switching in the apps list page.
+ *
+ * Covers: List, Empty, Footer, AppCardSkeleton, useAppsQueryState, NewAppCard
+ */
+import type { AppListResponse } from '@/models/app'
+import type { App } from '@/types/app'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import List from '@/app/components/apps/list'
+import { AccessMode } from '@/models/access-control'
+import { AppModeEnum } from '@/types/app'
+
+let mockIsCurrentWorkspaceEditor = true
+let mockIsCurrentWorkspaceDatasetOperator = false
+let mockIsLoadingCurrentWorkspace = false
+
+let mockSystemFeatures = {
+  branding: { enabled: false },
+  webapp_auth: { enabled: false },
+}
+
+let mockPages: AppListResponse[] = []
+let mockIsLoading = false
+let mockIsFetching = false
+let mockIsFetchingNextPage = false
+let mockHasNextPage = false
+let mockError: Error | null = null
+const mockRefetch = vi.fn()
+const mockFetchNextPage = vi.fn()
+
+let mockShowTagManagementModal = false
+
+const mockRouterPush = vi.fn()
+const mockRouterReplace = vi.fn()
+
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({
+    push: mockRouterPush,
+    replace: mockRouterReplace,
+  }),
+  useSearchParams: () => new URLSearchParams(),
+}))
+
+vi.mock('next/dynamic', () => ({
+  default: (_loader: () => Promise<{ default: React.ComponentType }>) => {
+    const LazyComponent = (props: Record<string, unknown>) => {
+      return <div data-testid="dynamic-component" {...props} />
+    }
+    LazyComponent.displayName = 'DynamicComponent'
+    return LazyComponent
+  },
+}))
+
+vi.mock('@/context/app-context', () => ({
+  useAppContext: () => ({
+    isCurrentWorkspaceEditor: mockIsCurrentWorkspaceEditor,
+    isCurrentWorkspaceDatasetOperator: mockIsCurrentWorkspaceDatasetOperator,
+    isLoadingCurrentWorkspace: mockIsLoadingCurrentWorkspace,
+  }),
+}))
+
+vi.mock('@/context/global-public-context', () => ({
+  useGlobalPublicStore: (selector?: (state: Record<string, unknown>) => unknown) => {
+    const state = { systemFeatures: mockSystemFeatures }
+    return selector ? selector(state) : state
+  },
+}))
+
+vi.mock('@/context/provider-context', () => ({
+  useProviderContext: () => ({
+    onPlanInfoChanged: vi.fn(),
+  }),
+}))
+
+vi.mock('@/app/components/base/tag-management/store', () => ({
+  useStore: (selector: (state: Record<string, unknown>) => unknown) => {
+    const state = {
+      tagList: [],
+      showTagManagementModal: mockShowTagManagementModal,
+      setTagList: vi.fn(),
+      setShowTagManagementModal: vi.fn(),
+    }
+    return selector(state)
+  },
+}))
+
+vi.mock('@/service/tag', () => ({
+  fetchTagList: vi.fn().mockResolvedValue([]),
+}))
+
+vi.mock('@/service/use-apps', () => ({
+  useInfiniteAppList: () => ({
+    data: { pages: mockPages },
+    isLoading: mockIsLoading,
+    isFetching: mockIsFetching,
+    isFetchingNextPage: mockIsFetchingNextPage,
+    fetchNextPage: mockFetchNextPage,
+    hasNextPage: mockHasNextPage,
+    error: mockError,
+    refetch: mockRefetch,
+  }),
+}))
+
+vi.mock('@/hooks/use-pay', () => ({
+  CheckModal: () => null,
+}))
+
+vi.mock('ahooks', async () => {
+  const actual = await vi.importActual<typeof import('ahooks')>('ahooks')
+  const React = await vi.importActual<typeof import('react')>('react')
+  return {
+    ...actual,
+    useDebounceFn: (fn: (...args: unknown[]) => void) => {
+      const fnRef = React.useRef(fn)
+      fnRef.current = fn
+      return {
+        run: (...args: unknown[]) => fnRef.current(...args),
+      }
+    },
+  }
+})
+
+const createMockApp = (overrides: Partial<App> = {}): App => ({
+  id: overrides.id ?? 'app-1',
+  name: overrides.name ?? 'My Chat App',
+  description: overrides.description ?? 'A chat application',
+  author_name: overrides.author_name ?? 'Test Author',
+  icon_type: overrides.icon_type ?? 'emoji',
+  icon: overrides.icon ?? '🤖',
+  icon_background: overrides.icon_background ?? '#FFEAD5',
+  icon_url: overrides.icon_url ?? null,
+  use_icon_as_answer_icon: overrides.use_icon_as_answer_icon ?? false,
+  mode: overrides.mode ?? AppModeEnum.CHAT,
+  enable_site: overrides.enable_site ?? true,
+  enable_api: overrides.enable_api ?? true,
+  api_rpm: overrides.api_rpm ?? 60,
+  api_rph: overrides.api_rph ?? 3600,
+  is_demo: overrides.is_demo ?? false,
+  model_config: overrides.model_config ?? {} as App['model_config'],
+  app_model_config: overrides.app_model_config ?? {} as App['app_model_config'],
+  created_at: overrides.created_at ?? 1700000000,
+  updated_at: overrides.updated_at ?? 1700001000,
+  site: overrides.site ?? {} as App['site'],
+  api_base_url: overrides.api_base_url ?? 'https://api.example.com',
+  tags: overrides.tags ?? [],
+  access_mode: overrides.access_mode ?? AccessMode.PUBLIC,
+  max_active_requests: overrides.max_active_requests ?? null,
+})
+
+const createPage = (apps: App[], hasMore = false, page = 1): AppListResponse => ({
+  data: apps,
+  has_more: hasMore,
+  limit: 30,
+  page,
+  total: apps.length,
+})
+
+const renderList = (searchParams?: Record<string, string>) => {
+  return render(
+    <NuqsTestingAdapter searchParams={searchParams}>
+      <List controlRefreshList={0} />
+    </NuqsTestingAdapter>,
+  )
+}
+
+describe('App List Browsing Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockIsCurrentWorkspaceEditor = true
+    mockIsCurrentWorkspaceDatasetOperator = false
+    mockIsLoadingCurrentWorkspace = false
+    mockSystemFeatures = {
+      branding: { enabled: false },
+      webapp_auth: { enabled: false },
+    }
+    mockPages = []
+    mockIsLoading = false
+    mockIsFetching = false
+    mockIsFetchingNextPage = false
+    mockHasNextPage = false
+    mockError = null
+    mockShowTagManagementModal = false
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  describe('Loading and Empty States', () => {
+    it('should show skeleton cards during initial loading', () => {
+      mockIsLoading = true
+      renderList()
+
+      const skeletonCards = document.querySelectorAll('.animate-pulse')
+      expect(skeletonCards.length).toBeGreaterThan(0)
+    })
+
+    it('should show empty state when no apps exist', () => {
+      mockPages = [createPage([])]
+      renderList()
+
+      expect(screen.getByText('app.newApp.noAppsFound')).toBeInTheDocument()
+    })
+
+    it('should transition from loading to content when data loads', () => {
+      mockIsLoading = true
+      const { rerender } = render(
+        <NuqsTestingAdapter>
+          <List controlRefreshList={0} />
+        </NuqsTestingAdapter>,
+      )
+
+      const skeletonCards = document.querySelectorAll('.animate-pulse')
+      expect(skeletonCards.length).toBeGreaterThan(0)
+
+      // Data loads
+      mockIsLoading = false
+      mockPages = [createPage([
+        createMockApp({ id: 'app-1', name: 'Loaded App' }),
+      ])]
+
+      rerender(
+        <NuqsTestingAdapter>
+          <List controlRefreshList={0} />
+        </NuqsTestingAdapter>,
+      )
+
+      expect(screen.getByText('Loaded App')).toBeInTheDocument()
+    })
+  })
+
+  // -- Rendering apps --
+  describe('App List Rendering', () => {
+    it('should render all app cards from the data', () => {
+      mockPages = [createPage([
+        createMockApp({ id: 'app-1', name: 'Chat Bot' }),
+        createMockApp({ id: 'app-2', name: 'Workflow Engine', mode: AppModeEnum.WORKFLOW }),
+        createMockApp({ id: 'app-3', name: 'Completion Tool', mode: AppModeEnum.COMPLETION }),
+      ])]
+
+      renderList()
+
+      expect(screen.getByText('Chat Bot')).toBeInTheDocument()
+      expect(screen.getByText('Workflow Engine')).toBeInTheDocument()
+      expect(screen.getByText('Completion Tool')).toBeInTheDocument()
+    })
+
+    it('should display app descriptions', () => {
+      mockPages = [createPage([
+        createMockApp({ name: 'My App', description: 'A powerful AI assistant' }),
+      ])]
+
+      renderList()
+
+      expect(screen.getByText('A powerful AI assistant')).toBeInTheDocument()
+    })
+
+    it('should show the NewAppCard for workspace editors', () => {
+      mockPages = [createPage([
+        createMockApp({ name: 'Test App' }),
+      ])]
+
+      renderList()
+
+      expect(screen.getByText('app.createApp')).toBeInTheDocument()
+    })
+
+    it('should hide NewAppCard when user is not a workspace editor', () => {
+      mockIsCurrentWorkspaceEditor = false
+      mockPages = [createPage([
+        createMockApp({ name: 'Test App' }),
+      ])]
+
+      renderList()
+
+      expect(screen.queryByText('app.createApp')).not.toBeInTheDocument()
+    })
+  })
+
+  // -- Footer visibility --
+  describe('Footer Visibility', () => {
+    it('should show footer when branding is disabled', () => {
+      mockSystemFeatures = { ...mockSystemFeatures, branding: { enabled: false } }
+      mockPages = [createPage([createMockApp()])]
+
+      renderList()
+
+      expect(screen.getByText('app.join')).toBeInTheDocument()
+      expect(screen.getByText('app.communityIntro')).toBeInTheDocument()
+    })
+
+    it('should hide footer when branding is enabled', () => {
+      mockSystemFeatures = { ...mockSystemFeatures, branding: { enabled: true } }
+      mockPages = [createPage([createMockApp()])]
+
+      renderList()
+
+      expect(screen.queryByText('app.join')).not.toBeInTheDocument()
+    })
+  })
+
+  // -- DSL drag-drop hint --
+  describe('DSL Drag-Drop Hint', () => {
+    it('should show drag-drop hint for workspace editors', () => {
+      mockPages = [createPage([createMockApp()])]
+      renderList()
+
+      expect(screen.getByText('app.newApp.dropDSLToCreateApp')).toBeInTheDocument()
+    })
+
+    it('should hide drag-drop hint for non-editors', () => {
+      mockIsCurrentWorkspaceEditor = false
+      mockPages = [createPage([createMockApp()])]
+      renderList()
+
+      expect(screen.queryByText('app.newApp.dropDSLToCreateApp')).not.toBeInTheDocument()
+    })
+  })
+
+  // -- Tab navigation --
+  describe('Tab Navigation', () => {
+    it('should render all category tabs', () => {
+      mockPages = [createPage([createMockApp()])]
+      renderList()
+
+      expect(screen.getByText('app.types.all')).toBeInTheDocument()
+      expect(screen.getByText('app.types.workflow')).toBeInTheDocument()
+      expect(screen.getByText('app.types.advanced')).toBeInTheDocument()
+      expect(screen.getByText('app.types.chatbot')).toBeInTheDocument()
+      expect(screen.getByText('app.types.agent')).toBeInTheDocument()
+      expect(screen.getByText('app.types.completion')).toBeInTheDocument()
+    })
+  })
+
+  // -- Search --
+  describe('Search Filtering', () => {
+    it('should render search input', () => {
+      mockPages = [createPage([createMockApp()])]
+      renderList()
+
+      const input = document.querySelector('input')
+      expect(input).toBeInTheDocument()
+    })
+
+    it('should allow typing in search input', () => {
+      mockPages = [createPage([createMockApp()])]
+      renderList()
+
+      const input = document.querySelector('input')!
+      fireEvent.change(input, { target: { value: 'test search' } })
+      expect(input.value).toBe('test search')
+    })
+  })
+
+  // -- "Created by me" filter --
+  describe('Created By Me Filter', () => {
+    it('should render the "created by me" checkbox', () => {
+      mockPages = [createPage([createMockApp()])]
+      renderList()
+
+      expect(screen.getByText('app.showMyCreatedAppsOnly')).toBeInTheDocument()
+    })
+
+    it('should toggle the "created by me" filter on click', () => {
+      mockPages = [createPage([createMockApp()])]
+      renderList()
+
+      const checkbox = screen.getByText('app.showMyCreatedAppsOnly')
+      fireEvent.click(checkbox)
+
+      expect(screen.getByText('app.showMyCreatedAppsOnly')).toBeInTheDocument()
+    })
+  })
+
+  // -- Fetching next page skeleton --
+  describe('Pagination Loading', () => {
+    it('should show skeleton when fetching next page', () => {
+      mockPages = [createPage([createMockApp()])]
+      mockIsFetchingNextPage = true
+
+      renderList()
+
+      const skeletonCards = document.querySelectorAll('.animate-pulse')
+      expect(skeletonCards.length).toBeGreaterThan(0)
+    })
+  })
+
+  // -- Dataset operator redirect --
+  describe('Dataset Operator Redirect', () => {
+    it('should redirect dataset operators to /datasets', () => {
+      mockIsCurrentWorkspaceDatasetOperator = true
+      renderList()
+
+      expect(mockRouterReplace).toHaveBeenCalledWith('/datasets')
+    })
+  })
+
+  // -- Multiple pages of data --
+  describe('Multi-page Data', () => {
+    it('should render apps from multiple pages', () => {
+      mockPages = [
+        createPage([
+          createMockApp({ id: 'app-1', name: 'Page One App' }),
+        ], true, 1),
+        createPage([
+          createMockApp({ id: 'app-2', name: 'Page Two App' }),
+        ], false, 2),
+      ]
+
+      renderList()
+
+      expect(screen.getByText('Page One App')).toBeInTheDocument()
+      expect(screen.getByText('Page Two App')).toBeInTheDocument()
+    })
+  })
+
+  // -- controlRefreshList triggers refetch --
+  describe('Refresh List', () => {
+    it('should call refetch when controlRefreshList increments', () => {
+      mockPages = [createPage([createMockApp()])]
+
+      const { rerender } = render(
+        <NuqsTestingAdapter>
+          <List controlRefreshList={0} />
+        </NuqsTestingAdapter>,
+      )
+
+      rerender(
+        <NuqsTestingAdapter>
+          <List controlRefreshList={1} />
+        </NuqsTestingAdapter>,
+      )
+
+      expect(mockRefetch).toHaveBeenCalled()
+    })
+  })
+})

web/__tests__/apps/create-app-flow.test.tsx

@@ -0,0 +1,464 @@
+/**
+ * Integration test: Create App Flow
+ *
+ * Tests the end-to-end user flows for creating new apps:
+ *   - Creating from blank via NewAppCard
+ *   - Creating from template via NewAppCard
+ *   - Creating from DSL import via NewAppCard
+ *   - Apps page top-level state management
+ */
+import type { AppListResponse } from '@/models/app'
+import type { App } from '@/types/app'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import List from '@/app/components/apps/list'
+import { AccessMode } from '@/models/access-control'
+import { AppModeEnum } from '@/types/app'
+
+let mockIsCurrentWorkspaceEditor = true
+let mockIsCurrentWorkspaceDatasetOperator = false
+let mockIsLoadingCurrentWorkspace = false
+let mockSystemFeatures = {
+  branding: { enabled: false },
+  webapp_auth: { enabled: false },
+}
+
+let mockPages: AppListResponse[] = []
+let mockIsLoading = false
+let mockIsFetching = false
+const mockRefetch = vi.fn()
+const mockFetchNextPage = vi.fn()
+let mockShowTagManagementModal = false
+
+const mockRouterPush = vi.fn()
+const mockRouterReplace = vi.fn()
+const mockOnPlanInfoChanged = vi.fn()
+
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({
+    push: mockRouterPush,
+    replace: mockRouterReplace,
+  }),
+  useSearchParams: () => new URLSearchParams(),
+}))
+
+vi.mock('@/context/app-context', () => ({
+  useAppContext: () => ({
+    isCurrentWorkspaceEditor: mockIsCurrentWorkspaceEditor,
+    isCurrentWorkspaceDatasetOperator: mockIsCurrentWorkspaceDatasetOperator,
+    isLoadingCurrentWorkspace: mockIsLoadingCurrentWorkspace,
+  }),
+}))
+
+vi.mock('@/context/global-public-context', () => ({
+  useGlobalPublicStore: (selector?: (state: Record<string, unknown>) => unknown) => {
+    const state = { systemFeatures: mockSystemFeatures }
+    return selector ? selector(state) : state
+  },
+}))
+
+vi.mock('@/context/provider-context', () => ({
+  useProviderContext: () => ({
+    onPlanInfoChanged: mockOnPlanInfoChanged,
+  }),
+}))
+
+vi.mock('@/app/components/base/tag-management/store', () => ({
+  useStore: (selector: (state: Record<string, unknown>) => unknown) => {
+    const state = {
+      tagList: [],
+      showTagManagementModal: mockShowTagManagementModal,
+      setTagList: vi.fn(),
+      setShowTagManagementModal: vi.fn(),
+    }
+    return selector(state)
+  },
+}))
+
+vi.mock('@/service/tag', () => ({
+  fetchTagList: vi.fn().mockResolvedValue([]),
+}))
+
+vi.mock('@/service/use-apps', () => ({
+  useInfiniteAppList: () => ({
+    data: { pages: mockPages },
+    isLoading: mockIsLoading,
+    isFetching: mockIsFetching,
+    isFetchingNextPage: false,
+    fetchNextPage: mockFetchNextPage,
+    hasNextPage: false,
+    error: null,
+    refetch: mockRefetch,
+  }),
+}))
+
+vi.mock('@/hooks/use-pay', () => ({
+  CheckModal: () => null,
+}))
+
+vi.mock('ahooks', async () => {
+  const actual = await vi.importActual<typeof import('ahooks')>('ahooks')
+  const React = await vi.importActual<typeof import('react')>('react')
+  return {
+    ...actual,
+    useDebounceFn: (fn: (...args: unknown[]) => void) => {
+      const fnRef = React.useRef(fn)
+      fnRef.current = fn
+      return {
+        run: (...args: unknown[]) => fnRef.current(...args),
+      }
+    },
+  }
+})
+
+// Mock dynamically loaded modals with test stubs
+vi.mock('next/dynamic', () => ({
+  default: (loader: () => Promise<{ default: React.ComponentType }>) => {
+    let Component: React.ComponentType<Record<string, unknown>> | null = null
+    loader().then((mod) => {
+      Component = mod.default as React.ComponentType<Record<string, unknown>>
+    }).catch(() => {})
+    const Wrapper = (props: Record<string, unknown>) => {
+      if (Component)
+        return <Component {...props} />
+      return null
+    }
+    Wrapper.displayName = 'DynamicWrapper'
+    return Wrapper
+  },
+}))
+
+vi.mock('@/app/components/app/create-app-modal', () => ({
+  default: ({ show, onClose, onSuccess, onCreateFromTemplate }: Record<string, unknown>) => {
+    if (!show)
+      return null
+    return (
+      <div data-testid="create-app-modal">
+        <button data-testid="create-blank-confirm" onClick={onSuccess as () => void}>Create Blank</button>
+        {!!onCreateFromTemplate && (
+          <button data-testid="switch-to-template" onClick={onCreateFromTemplate as () => void}>From Template</button>
+        )}
+        <button data-testid="create-blank-cancel" onClick={onClose as () => void}>Cancel</button>
+      </div>
+    )
+  },
+}))
+
+vi.mock('@/app/components/app/create-app-dialog', () => ({
+  default: ({ show, onClose, onSuccess, onCreateFromBlank }: Record<string, unknown>) => {
+    if (!show)
+      return null
+    return (
+      <div data-testid="template-dialog">
+        <button data-testid="template-confirm" onClick={onSuccess as () => void}>Create from Template</button>
+        {!!onCreateFromBlank && (
+          <button data-testid="switch-to-blank" onClick={onCreateFromBlank as () => void}>From Blank</button>
+        )}
+        <button data-testid="template-cancel" onClick={onClose as () => void}>Cancel</button>
+      </div>
+    )
+  },
+}))
+
+vi.mock('@/app/components/app/create-from-dsl-modal', () => ({
+  default: ({ show, onClose, onSuccess }: Record<string, unknown>) => {
+    if (!show)
+      return null
+    return (
+      <div data-testid="create-from-dsl-modal">
+        <button data-testid="dsl-import-confirm" onClick={onSuccess as () => void}>Import DSL</button>
+        <button data-testid="dsl-import-cancel" onClick={onClose as () => void}>Cancel</button>
+      </div>
+    )
+  },
+  CreateFromDSLModalTab: {
+    FROM_URL: 'from-url',
+    FROM_FILE: 'from-file',
+  },
+}))
+
+const createMockApp = (overrides: Partial<App> = {}): App => ({
+  id: overrides.id ?? 'app-1',
+  name: overrides.name ?? 'Test App',
+  description: overrides.description ?? 'A test app',
+  author_name: overrides.author_name ?? 'Author',
+  icon_type: overrides.icon_type ?? 'emoji',
+  icon: overrides.icon ?? '🤖',
+  icon_background: overrides.icon_background ?? '#FFEAD5',
+  icon_url: overrides.icon_url ?? null,
+  use_icon_as_answer_icon: overrides.use_icon_as_answer_icon ?? false,
+  mode: overrides.mode ?? AppModeEnum.CHAT,
+  enable_site: overrides.enable_site ?? true,
+  enable_api: overrides.enable_api ?? true,
+  api_rpm: overrides.api_rpm ?? 60,
+  api_rph: overrides.api_rph ?? 3600,
+  is_demo: overrides.is_demo ?? false,
+  model_config: overrides.model_config ?? {} as App['model_config'],
+  app_model_config: overrides.app_model_config ?? {} as App['app_model_config'],
+  created_at: overrides.created_at ?? 1700000000,
+  updated_at: overrides.updated_at ?? 1700001000,
+  site: overrides.site ?? {} as App['site'],
+  api_base_url: overrides.api_base_url ?? 'https://api.example.com',
+  tags: overrides.tags ?? [],
+  access_mode: overrides.access_mode ?? AccessMode.PUBLIC,
+  max_active_requests: overrides.max_active_requests ?? null,
+})
+
+const createPage = (apps: App[]): AppListResponse => ({
+  data: apps,
+  has_more: false,
+  limit: 30,
+  page: 1,
+  total: apps.length,
+})
+
+const renderList = () => {
+  return render(
+    <NuqsTestingAdapter>
+      <List controlRefreshList={0} />
+    </NuqsTestingAdapter>,
+  )
+}
+
+describe('Create App Flow', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockIsCurrentWorkspaceEditor = true
+    mockIsCurrentWorkspaceDatasetOperator = false
+    mockIsLoadingCurrentWorkspace = false
+    mockSystemFeatures = {
+      branding: { enabled: false },
+      webapp_auth: { enabled: false },
+    }
+    mockPages = [createPage([createMockApp()])]
+    mockIsLoading = false
+    mockIsFetching = false
+    mockShowTagManagementModal = false
+  })
+
+  describe('NewAppCard Rendering', () => {
+    it('should render the "Create App" card with all options', () => {
+      renderList()
+
+      expect(screen.getByText('app.createApp')).toBeInTheDocument()
+      expect(screen.getByText('app.newApp.startFromBlank')).toBeInTheDocument()
+      expect(screen.getByText('app.newApp.startFromTemplate')).toBeInTheDocument()
+      expect(screen.getByText('app.importDSL')).toBeInTheDocument()
+    })
+
+    it('should not render NewAppCard when user is not an editor', () => {
+      mockIsCurrentWorkspaceEditor = false
+      renderList()
+
+      expect(screen.queryByText('app.createApp')).not.toBeInTheDocument()
+    })
+
+    it('should show loading state when workspace is loading', () => {
+      mockIsLoadingCurrentWorkspace = true
+      renderList()
+
+      // NewAppCard renders but with loading style (pointer-events-none opacity-50)
+      expect(screen.getByText('app.createApp')).toBeInTheDocument()
+    })
+  })
+
+  // -- Create from blank --
+  describe('Create from Blank Flow', () => {
+    it('should open the create app modal when "Start from Blank" is clicked', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.newApp.startFromBlank'))
+
+      await waitFor(() => {
+        expect(screen.getByTestId('create-app-modal')).toBeInTheDocument()
+      })
+    })
+
+    it('should close the create app modal on cancel', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.newApp.startFromBlank'))
+      await waitFor(() => {
+        expect(screen.getByTestId('create-app-modal')).toBeInTheDocument()
+      })
+
+      fireEvent.click(screen.getByTestId('create-blank-cancel'))
+      await waitFor(() => {
+        expect(screen.queryByTestId('create-app-modal')).not.toBeInTheDocument()
+      })
+    })
+
+    it('should call onPlanInfoChanged and refetch on successful creation', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.newApp.startFromBlank'))
+      await waitFor(() => {
+        expect(screen.getByTestId('create-app-modal')).toBeInTheDocument()
+      })
+
+      fireEvent.click(screen.getByTestId('create-blank-confirm'))
+      await waitFor(() => {
+        expect(mockOnPlanInfoChanged).toHaveBeenCalled()
+        expect(mockRefetch).toHaveBeenCalled()
+      })
+    })
+  })
+
+  // -- Create from template --
+  describe('Create from Template Flow', () => {
+    it('should open template dialog when "Start from Template" is clicked', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.newApp.startFromTemplate'))
+
+      await waitFor(() => {
+        expect(screen.getByTestId('template-dialog')).toBeInTheDocument()
+      })
+    })
+
+    it('should allow switching from template to blank modal', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.newApp.startFromTemplate'))
+      await waitFor(() => {
+        expect(screen.getByTestId('template-dialog')).toBeInTheDocument()
+      })
+
+      fireEvent.click(screen.getByTestId('switch-to-blank'))
+      await waitFor(() => {
+        expect(screen.getByTestId('create-app-modal')).toBeInTheDocument()
+        expect(screen.queryByTestId('template-dialog')).not.toBeInTheDocument()
+      })
+    })
+
+    it('should allow switching from blank to template dialog', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.newApp.startFromBlank'))
+      await waitFor(() => {
+        expect(screen.getByTestId('create-app-modal')).toBeInTheDocument()
+      })
+
+      fireEvent.click(screen.getByTestId('switch-to-template'))
+      await waitFor(() => {
+        expect(screen.getByTestId('template-dialog')).toBeInTheDocument()
+        expect(screen.queryByTestId('create-app-modal')).not.toBeInTheDocument()
+      })
+    })
+  })
+
+  // -- Create from DSL import (via NewAppCard button) --
+  describe('Create from DSL Import Flow', () => {
+    it('should open DSL import modal when "Import DSL" is clicked', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.importDSL'))
+
+      await waitFor(() => {
+        expect(screen.getByTestId('create-from-dsl-modal')).toBeInTheDocument()
+      })
+    })
+
+    it('should close DSL import modal on cancel', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.importDSL'))
+      await waitFor(() => {
+        expect(screen.getByTestId('create-from-dsl-modal')).toBeInTheDocument()
+      })
+
+      fireEvent.click(screen.getByTestId('dsl-import-cancel'))
+      await waitFor(() => {
+        expect(screen.queryByTestId('create-from-dsl-modal')).not.toBeInTheDocument()
+      })
+    })
+
+    it('should call onPlanInfoChanged and refetch on successful DSL import', async () => {
+      renderList()
+
+      fireEvent.click(screen.getByText('app.importDSL'))
+      await waitFor(() => {
+        expect(screen.getByTestId('create-from-dsl-modal')).toBeInTheDocument()
+      })
+
+      fireEvent.click(screen.getByTestId('dsl-import-confirm'))
+      await waitFor(() => {
+        expect(mockOnPlanInfoChanged).toHaveBeenCalled()
+        expect(mockRefetch).toHaveBeenCalled()
+      })
+    })
+  })
+
+  // -- DSL drag-and-drop flow (via List component) --
+  describe('DSL Drag-Drop Flow', () => {
+    it('should show drag-drop hint in the list', () => {
+      renderList()
+
+      expect(screen.getByText('app.newApp.dropDSLToCreateApp')).toBeInTheDocument()
+    })
+
+    it('should open create-from-DSL modal when DSL file is dropped', async () => {
+      const { act } = await import('@testing-library/react')
+      renderList()
+
+      const container = document.querySelector('[class*="overflow-y-auto"]')
+      if (container) {
+        const yamlFile = new File(['app: test'], 'app.yaml', { type: 'application/yaml' })
+
+        // Simulate the full drag-drop sequence wrapped in act
+        await act(async () => {
+          const dragEnterEvent = new Event('dragenter', { bubbles: true })
+          Object.defineProperty(dragEnterEvent, 'dataTransfer', {
+            value: { types: ['Files'], files: [] },
+          })
+          Object.defineProperty(dragEnterEvent, 'preventDefault', { value: vi.fn() })
+          Object.defineProperty(dragEnterEvent, 'stopPropagation', { value: vi.fn() })
+          container.dispatchEvent(dragEnterEvent)
+
+          const dropEvent = new Event('drop', { bubbles: true })
+          Object.defineProperty(dropEvent, 'dataTransfer', {
+            value: { files: [yamlFile], types: ['Files'] },
+          })
+          Object.defineProperty(dropEvent, 'preventDefault', { value: vi.fn() })
+          Object.defineProperty(dropEvent, 'stopPropagation', { value: vi.fn() })
+          container.dispatchEvent(dropEvent)
+        })
+
+        await waitFor(() => {
+          const modal = screen.queryByTestId('create-from-dsl-modal')
+          if (modal)
+            expect(modal).toBeInTheDocument()
+        })
+      }
+    })
+  })
+
+  // -- Edge cases --
+  describe('Edge Cases', () => {
+    it('should not show create options when no data and user is editor', () => {
+      mockPages = [createPage([])]
+      renderList()
+
+      // NewAppCard should still be visible even with no apps
+      expect(screen.getByText('app.createApp')).toBeInTheDocument()
+    })
+
+    it('should handle multiple rapid clicks on create buttons without crashing', async () => {
+      renderList()
+
+      // Rapidly click different create options
+      fireEvent.click(screen.getByText('app.newApp.startFromBlank'))
+      fireEvent.click(screen.getByText('app.newApp.startFromTemplate'))
+      fireEvent.click(screen.getByText('app.importDSL'))
+
+      // Should not crash, and some modal should be present
+      await waitFor(() => {
+        const anyModal = screen.queryByTestId('create-app-modal')
+          || screen.queryByTestId('template-dialog')
+          || screen.queryByTestId('create-from-dsl-modal')
+        expect(anyModal).toBeTruthy()
+      })
+    })
+  })
+})

web/__tests__/develop/develop-page-flow.test.tsx

@@ -12,7 +12,6 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import DevelopMain from '@/app/components/develop'
 import { AppModeEnum, Theme } from '@/types/app'
 
-// ---------- fake timers ----------
 beforeEach(() => {
   vi.useFakeTimers({ shouldAdvanceTime: true })
 })
@@ -28,8 +27,6 @@ async function flushUI() {
   })
 }
 
-// ---------- store mock ----------
-
 let storeAppDetail: unknown
 
 vi.mock('@/app/components/app/store', () => ({
@@ -38,8 +35,6 @@ vi.mock('@/app/components/app/store', () => ({
   },
 }))
 
-// ---------- Doc dependencies ----------
-
 vi.mock('@/context/i18n', () => ({
   useLocale: () => 'en-US',
 }))
@@ -48,11 +43,12 @@ vi.mock('@/hooks/use-theme', () => ({
   default: () => ({ theme: Theme.light }),
 }))
 
-vi.mock('@/i18n-config/language', () => ({
-  LanguagesSupported: ['en-US', 'zh-Hans', 'zh-Hant', 'pt-BR', 'es-ES', 'fr-FR', 'de-DE', 'ja-JP'],
-}))
-
-// ---------- SecretKeyModal dependencies ----------
+vi.mock('@/i18n-config/language', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@/i18n-config/language')>()
+  return {
+    ...actual,
+  }
+})
 
 vi.mock('@/context/app-context', () => ({
   useAppContext: () => ({

web/app/components/app/configuration/dataset-config/card-item/index.spec.tsx

@@ -11,7 +11,7 @@ import { RETRIEVE_METHOD } from '@/types/app'
 import Item from './index'
 
 vi.mock('../settings-modal', () => ({
-  default: ({ onSave, onCancel, currentDataset }: any) => (
+  default: ({ onSave, onCancel, currentDataset }: { currentDataset: DataSet, onCancel: () => void, onSave: (newDataset: DataSet) => void }) => (
     <div>
       <div>Mock settings modal</div>
       <button onClick={() => onSave({ ...currentDataset, name: 'Updated dataset' })}>Save changes</button>
@@ -177,7 +177,7 @@ describe('dataset-config/card-item', () => {
       expect(screen.getByRole('dialog')).toBeVisible()
     })
 
-    await user.click(screen.getByText('Save changes'))
+    fireEvent.click(screen.getByText('Save changes'))
 
     await waitFor(() => {
       expect(onSave).toHaveBeenCalledWith(expect.objectContaining({ name: 'Updated dataset' }))

web/app/components/apps/__tests__/app-card.spec.tsx

@@ -1,16 +1,13 @@
 import type { Mock } from 'vitest'
+import type { App } from '@/types/app'
 import { fireEvent, render, screen, waitFor } from '@testing-library/react'
 import * as React from 'react'
 import { AccessMode } from '@/models/access-control'
-// Mock API services - import for direct manipulation
 import * as appsService from '@/service/apps'
-
 import * as exploreService from '@/service/explore'
 import * as workflowService from '@/service/workflow'
 import { AppModeEnum } from '@/types/app'
-
-// Import component after mocks
-import AppCard from './app-card'
+import AppCard from '../app-card'
 
 // Mock next/navigation
 const mockPush = vi.fn()
@@ -24,11 +21,11 @@ vi.mock('next/navigation', () => ({
 // Include createContext for components that use it (like Toast)
 const mockNotify = vi.fn()
 vi.mock('use-context-selector', () => ({
-  createContext: (defaultValue: any) => React.createContext(defaultValue),
+  createContext: <T,>(defaultValue: T) => React.createContext(defaultValue),
   useContext: () => ({
     notify: mockNotify,
   }),
-  useContextSelector: (_context: any, selector: any) => selector({
+  useContextSelector: (_context: unknown, selector: (state: Record<string, unknown>) => unknown) => selector({
     notify: mockNotify,
   }),
 }))
@@ -51,7 +48,7 @@ vi.mock('@/context/provider-context', () => ({
 // Mock global public store - allow dynamic configuration
 let mockWebappAuthEnabled = false
 vi.mock('@/context/global-public-context', () => ({
-  useGlobalPublicStore: (selector: (s: any) => any) => selector({
+  useGlobalPublicStore: (selector: (s: Record<string, unknown>) => unknown) => selector({
     systemFeatures: {
       webapp_auth: { enabled: mockWebappAuthEnabled },
       branding: { enabled: false },
@@ -106,11 +103,11 @@ vi.mock('@/utils/time', () => ({
 
 // Mock dynamic imports
 vi.mock('next/dynamic', () => ({
-  default: (importFn: () => Promise<any>) => {
+  default: (importFn: () => Promise<unknown>) => {
     const fnString = importFn.toString()
 
     if (fnString.includes('create-app-modal') || fnString.includes('explore/create-app-modal')) {
-      return function MockEditAppModal({ show, onHide, onConfirm }: any) {
+      return function MockEditAppModal({ show, onHide, onConfirm }: { show: boolean, onHide: () => void, onConfirm?: (data: Record<string, unknown>) => void }) {
         if (!show)
           return null
         return React.createElement('div', { 'data-testid': 'edit-app-modal' }, React.createElement('button', { 'onClick': onHide, 'data-testid': 'close-edit-modal' }, 'Close'), React.createElement('button', {
@@ -128,7 +125,7 @@ vi.mock('next/dynamic', () => ({
       }
     }
     if (fnString.includes('duplicate-modal')) {
-      return function MockDuplicateAppModal({ show, onHide, onConfirm }: any) {
+      return function MockDuplicateAppModal({ show, onHide, onConfirm }: { show: boolean, onHide: () => void, onConfirm?: (data: Record<string, unknown>) => void }) {
         if (!show)
           return null
         return React.createElement('div', { 'data-testid': 'duplicate-modal' }, React.createElement('button', { 'onClick': onHide, 'data-testid': 'close-duplicate-modal' }, 'Close'), React.createElement('button', {
@@ -143,26 +140,26 @@ vi.mock('next/dynamic', () => ({
       }
     }
     if (fnString.includes('switch-app-modal')) {
-      return function MockSwitchAppModal({ show, onClose, onSuccess }: any) {
+      return function MockSwitchAppModal({ show, onClose, onSuccess }: { show: boolean, onClose: () => void, onSuccess: () => void }) {
         if (!show)
           return null
         return React.createElement('div', { 'data-testid': 'switch-modal' }, React.createElement('button', { 'onClick': onClose, 'data-testid': 'close-switch-modal' }, 'Close'), React.createElement('button', { 'onClick': onSuccess, 'data-testid': 'confirm-switch-modal' }, 'Switch'))
       }
     }
     if (fnString.includes('base/confirm')) {
-      return function MockConfirm({ isShow, onCancel, onConfirm }: any) {
+      return function MockConfirm({ isShow, onCancel, onConfirm }: { isShow: boolean, onCancel: () => void, onConfirm: () => void }) {
         if (!isShow)
           return null
         return React.createElement('div', { 'data-testid': 'confirm-dialog' }, React.createElement('button', { 'onClick': onCancel, 'data-testid': 'cancel-confirm' }, 'Cancel'), React.createElement('button', { 'onClick': onConfirm, 'data-testid': 'confirm-confirm' }, 'Confirm'))
       }
     }
     if (fnString.includes('dsl-export-confirm-modal')) {
-      return function MockDSLExportModal({ onClose, onConfirm }: any) {
+      return function MockDSLExportModal({ onClose, onConfirm }: { onClose?: () => void, onConfirm?: (withSecrets: boolean) => void }) {
         return React.createElement('div', { 'data-testid': 'dsl-export-modal' }, React.createElement('button', { 'onClick': () => onClose?.(), 'data-testid': 'close-dsl-export' }, 'Close'), React.createElement('button', { 'onClick': () => onConfirm?.(true), 'data-testid': 'confirm-dsl-export' }, 'Export with secrets'), React.createElement('button', { 'onClick': () => onConfirm?.(false), 'data-testid': 'confirm-dsl-export-no-secrets' }, 'Export without secrets'))
       }
     }
     if (fnString.includes('app-access-control')) {
-      return function MockAccessControl({ onClose, onConfirm }: any) {
+      return function MockAccessControl({ onClose, onConfirm }: { onClose: () => void, onConfirm: () => void }) {
         return React.createElement('div', { 'data-testid': 'access-control-modal' }, React.createElement('button', { 'onClick': onClose, 'data-testid': 'close-access-control' }, 'Close'), React.createElement('button', { 'onClick': onConfirm, 'data-testid': 'confirm-access-control' }, 'Confirm'))
       }
     }
@@ -172,7 +169,9 @@ vi.mock('next/dynamic', () => ({
 
 // Popover uses @headlessui/react portals - mock for controlled interaction testing
 vi.mock('@/app/components/base/popover', () => {
-  const MockPopover = ({ htmlContent, btnElement, btnClassName }: any) => {
+  type PopoverHtmlContent = React.ReactNode | ((state: { open: boolean, onClose: () => void, onClick: () => void }) => React.ReactNode)
+  type MockPopoverProps = { htmlContent: PopoverHtmlContent, btnElement: React.ReactNode, btnClassName?: string | ((open: boolean) => string) }
+  const MockPopover = ({ htmlContent, btnElement, btnClassName }: MockPopoverProps) => {
     const [isOpen, setIsOpen] = React.useState(false)
     const computedClassName = typeof btnClassName === 'function' ? btnClassName(isOpen) : ''
     return React.createElement('div', { 'data-testid': 'custom-popover', 'className': computedClassName }, React.createElement('div', {
@@ -188,13 +187,13 @@ vi.mock('@/app/components/base/popover', () => {
 
 // Tooltip uses portals - minimal mock preserving popup content as title attribute
 vi.mock('@/app/components/base/tooltip', () => ({
-  default: ({ children, popupContent }: any) => React.createElement('div', { title: popupContent }, children),
+  default: ({ children, popupContent }: { children: React.ReactNode, popupContent: React.ReactNode }) => React.createElement('div', { title: popupContent }, children),
 }))
 
 // TagSelector has API dependency (service/tag) - mock for isolated testing
 vi.mock('@/app/components/base/tag-management/selector', () => ({
-  default: ({ tags }: any) => {
-    return React.createElement('div', { 'aria-label': 'tag-selector' }, tags?.map((tag: any) => React.createElement('span', { key: tag.id }, tag.name)))
+  default: ({ tags }: { tags?: { id: string, name: string }[] }) => {
+    return React.createElement('div', { 'aria-label': 'tag-selector' }, tags?.map((tag: { id: string, name: string }) => React.createElement('span', { key: tag.id }, tag.name)))
   },
 }))
 
@@ -203,11 +202,7 @@ vi.mock('@/app/components/app/type-selector', () => ({
   AppTypeIcon: () => React.createElement('div', { 'data-testid': 'app-type-icon' }),
 }))
 
-// ============================================================================
-// Test Data Factories
-// ============================================================================
-
-const createMockApp = (overrides: Record<string, any> = {}) => ({
+const createMockApp = (overrides: Partial<App> = {}): App => ({
   id: 'test-app-id',
   name: 'Test App',
   description: 'Test app description',
@@ -229,16 +224,8 @@ const createMockApp = (overrides: Record<string, any> = {}) => ({
   api_rpm: 60,
   api_rph: 3600,
   is_demo: false,
-  model_config: {} as any,
-  app_model_config: {} as any,
-  site: {} as any,
-  api_base_url: 'https://api.example.com',
   ...overrides,
-})
-
-// ============================================================================
-// Tests
-// ============================================================================
+} as App)
 
 describe('AppCard', () => {
   const mockApp = createMockApp()
@@ -1171,7 +1158,7 @@ describe('AppCard', () => {
       (exploreService.fetchInstalledAppList as Mock).mockRejectedValueOnce(new Error('API Error'))
 
       // Configure mockOpenAsyncWindow to call the callback and trigger error
-      mockOpenAsyncWindow.mockImplementationOnce(async (callback: () => Promise<string>, options: any) => {
+      mockOpenAsyncWindow.mockImplementationOnce(async (callback: () => Promise<string>, options?: { onError?: (err: unknown) => void }) => {
         try {
           await callback()
         }
@@ -1213,7 +1200,7 @@ describe('AppCard', () => {
       (exploreService.fetchInstalledAppList as Mock).mockResolvedValueOnce({ installed_apps: [] })
 
       // Configure mockOpenAsyncWindow to call the callback and trigger error
-      mockOpenAsyncWindow.mockImplementationOnce(async (callback: () => Promise<string>, options: any) => {
+      mockOpenAsyncWindow.mockImplementationOnce(async (callback: () => Promise<string>, options?: { onError?: (err: unknown) => void }) => {
         try {
           await callback()
         }

web/app/components/apps/__tests__/empty.spec.tsx

@@ -1,6 +1,6 @@
 import { render, screen } from '@testing-library/react'
 import * as React from 'react'
-import Empty from './empty'
+import Empty from '../empty'
 
 describe('Empty', () => {
   beforeEach(() => {
@@ -21,7 +21,6 @@ describe('Empty', () => {
 
     it('should display the no apps found message', () => {
       render(<Empty />)
-      // Use pattern matching for resilient text assertions
       expect(screen.getByText('app.newApp.noAppsFound')).toBeInTheDocument()
     })
   })

web/app/components/apps/__tests__/footer.spec.tsx

@@ -1,6 +1,6 @@
 import { render, screen } from '@testing-library/react'
 import * as React from 'react'
-import Footer from './footer'
+import Footer from '../footer'
 
 describe('Footer', () => {
   beforeEach(() => {
@@ -15,7 +15,6 @@ describe('Footer', () => {
 
     it('should display the community heading', () => {
       render(<Footer />)
-      // Use pattern matching for resilient text assertions
       expect(screen.getByText('app.join')).toBeInTheDocument()
     })
 

web/app/components/apps/__tests__/index.spec.tsx

@@ -3,21 +3,17 @@ import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { render, screen } from '@testing-library/react'
 import * as React from 'react'
 
-// Import after mocks
-import Apps from './index'
+import Apps from '../index'
 
-// Track mock calls
 let documentTitleCalls: string[] = []
 let educationInitCalls: number = 0
 
-// Mock useDocumentTitle hook
 vi.mock('@/hooks/use-document-title', () => ({
   default: (title: string) => {
     documentTitleCalls.push(title)
   },
 }))
 
-// Mock useEducationInit hook
 vi.mock('@/app/education-apply/hooks', () => ({
   useEducationInit: () => {
     educationInitCalls++
@@ -33,8 +29,7 @@ vi.mock('@/hooks/use-import-dsl', () => ({
   }),
 }))
 
-// Mock List component
-vi.mock('./list', () => ({
+vi.mock('../list', () => ({
   default: () => {
     return React.createElement('div', { 'data-testid': 'apps-list' }, 'Apps List')
   },
@@ -100,10 +95,7 @@ describe('Apps', () => {
     it('should render full component tree', () => {
       renderWithClient(<Apps />)
 
-      // Verify container exists
       expect(screen.getByTestId('apps-list')).toBeInTheDocument()
-
-      // Verify hooks were called
       expect(documentTitleCalls.length).toBeGreaterThanOrEqual(1)
       expect(educationInitCalls).toBeGreaterThanOrEqual(1)
     })

web/app/components/apps/__tests__/list.spec.tsx

@@ -1,12 +1,13 @@
+import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
+import type { ReactNode } from 'react'
 import { act, fireEvent, render, screen } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import * as React from 'react'
 import { useStore as useTagStore } from '@/app/components/base/tag-management/store'
 import { AppModeEnum } from '@/types/app'
 
-// Import after mocks
-import List from './list'
+import List from '../list'
 
-// Mock next/navigation
 const mockReplace = vi.fn()
 const mockRouter = { replace: mockReplace }
 vi.mock('next/navigation', () => ({
@@ -14,7 +15,6 @@ vi.mock('next/navigation', () => ({
   useSearchParams: () => new URLSearchParams(''),
 }))
 
-// Mock app context
 const mockIsCurrentWorkspaceEditor = vi.fn(() => true)
 const mockIsCurrentWorkspaceDatasetOperator = vi.fn(() => false)
 vi.mock('@/context/app-context', () => ({
@@ -24,7 +24,6 @@ vi.mock('@/context/app-context', () => ({
   }),
 }))
 
-// Mock global public store
 vi.mock('@/context/global-public-context', () => ({
   useGlobalPublicStore: () => ({
     systemFeatures: {
@@ -33,41 +32,28 @@ vi.mock('@/context/global-public-context', () => ({
   }),
 }))
 
-// Mock custom hooks - allow dynamic query state
 const mockSetQuery = vi.fn()
 const mockQueryState = {
   tagIDs: [] as string[],
   keywords: '',
   isCreatedByMe: false,
 }
-vi.mock('./hooks/use-apps-query-state', () => ({
+vi.mock('../hooks/use-apps-query-state', () => ({
   default: () => ({
     query: mockQueryState,
     setQuery: mockSetQuery,
   }),
 }))
 
-// Store callback for testing DSL file drop
 let mockOnDSLFileDropped: ((file: File) => void) | null = null
 let mockDragging = false
-vi.mock('./hooks/use-dsl-drag-drop', () => ({
+vi.mock('../hooks/use-dsl-drag-drop', () => ({
   useDSLDragDrop: ({ onDSLFileDropped }: { onDSLFileDropped: (file: File) => void }) => {
     mockOnDSLFileDropped = onDSLFileDropped
     return { dragging: mockDragging }
   },
 }))
 
-const mockSetActiveTab = vi.fn()
-vi.mock('nuqs', () => ({
-  useQueryState: () => ['all', mockSetActiveTab],
-  parseAsString: {
-    withDefault: () => ({
-      withOptions: () => ({}),
-    }),
-  },
-}))
-
-// Mock service hooks - use object for mutable state (vi.mock is hoisted)
 const mockRefetch = vi.fn()
 const mockFetchNextPage = vi.fn()
 
@@ -124,47 +110,20 @@ vi.mock('@/service/use-apps', () => ({
   }),
 }))
 
-// Use real tag store - global zustand mock will auto-reset between tests
-
-// Mock tag service to avoid API calls in TagFilter
 vi.mock('@/service/tag', () => ({
   fetchTagList: vi.fn().mockResolvedValue([{ id: 'tag-1', name: 'Test Tag', type: 'app' }]),
 }))
 
-// Store TagFilter onChange callback for testing
-let mockTagFilterOnChange: ((value: string[]) => void) | null = null
-vi.mock('@/app/components/base/tag-management/filter', () => ({
-  default: ({ onChange }: { onChange: (value: string[]) => void }) => {
-    mockTagFilterOnChange = onChange
-    return React.createElement('div', { 'data-testid': 'tag-filter' }, 'common.tag.placeholder')
-  },
-}))
-
-// Mock config
 vi.mock('@/config', () => ({
   NEED_REFRESH_APP_LIST_KEY: 'needRefreshAppList',
 }))
 
-// Mock pay hook
 vi.mock('@/hooks/use-pay', () => ({
   CheckModal: () => null,
 }))
 
-// Mock ahooks - useMount only executes once on mount, not on fn change
-vi.mock('ahooks', () => ({
-  useDebounceFn: (fn: () => void) => ({ run: fn }),
-  useMount: (fn: () => void) => {
-    const fnRef = React.useRef(fn)
-    fnRef.current = fn
-    React.useEffect(() => {
-      fnRef.current()
-    }, [])
-  },
-}))
-
-// Mock dynamic imports
 vi.mock('next/dynamic', () => ({
-  default: (importFn: () => Promise<any>) => {
+  default: (importFn: () => Promise<unknown>) => {
     const fnString = importFn.toString()
 
     if (fnString.includes('tag-management')) {
@@ -173,7 +132,7 @@ vi.mock('next/dynamic', () => ({
       }
     }
     if (fnString.includes('create-from-dsl-modal')) {
-      return function MockCreateFromDSLModal({ show, onClose, onSuccess }: any) {
+      return function MockCreateFromDSLModal({ show, onClose, onSuccess }: { show: boolean, onClose: () => void, onSuccess: () => void }) {
         if (!show)
           return null
         return React.createElement('div', { 'data-testid': 'create-dsl-modal' }, React.createElement('button', { 'onClick': onClose, 'data-testid': 'close-dsl-modal' }, 'Close'), React.createElement('button', { 'onClick': onSuccess, 'data-testid': 'success-dsl-modal' }, 'Success'))
@@ -183,41 +142,34 @@ vi.mock('next/dynamic', () => ({
   },
 }))
 
-/**
- * Mock child components for focused List component testing.
- * These mocks isolate the List component's behavior from its children.
- * Each child component (AppCard, NewAppCard, Empty, Footer) has its own dedicated tests.
- */
-vi.mock('./app-card', () => ({
-  default: ({ app }: any) => {
+vi.mock('../app-card', () => ({
+  default: ({ app }: { app: { id: string, name: string } }) => {
     return React.createElement('div', { 'data-testid': `app-card-${app.id}`, 'role': 'article' }, app.name)
   },
 }))
 
-vi.mock('./new-app-card', () => ({
-  default: React.forwardRef((_props: any, _ref: any) => {
+vi.mock('../new-app-card', () => ({
+  default: React.forwardRef((_props: unknown, _ref: React.ForwardedRef<unknown>) => {
     return React.createElement('div', { 'data-testid': 'new-app-card', 'role': 'button' }, 'New App Card')
   }),
 }))
 
-vi.mock('./empty', () => ({
+vi.mock('../empty', () => ({
   default: () => {
     return React.createElement('div', { 'data-testid': 'empty-state', 'role': 'status' }, 'No apps found')
   },
 }))
 
-vi.mock('./footer', () => ({
+vi.mock('../footer', () => ({
   default: () => {
     return React.createElement('footer', { 'data-testid': 'footer', 'role': 'contentinfo' }, 'Footer')
   },
 }))
 
-// Store IntersectionObserver callback
 let intersectionCallback: IntersectionObserverCallback | null = null
 const mockObserve = vi.fn()
 const mockDisconnect = vi.fn()
 
-// Mock IntersectionObserver
 beforeAll(() => {
   globalThis.IntersectionObserver = class MockIntersectionObserver {
     constructor(callback: IntersectionObserverCallback) {
@@ -234,10 +186,21 @@ beforeAll(() => {
   } as unknown as typeof IntersectionObserver
 })
 
+// Render helper wrapping with NuqsTestingAdapter
+const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
+const renderList = (searchParams = '') => {
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={onUrlUpdate}>
+      {children}
+    </NuqsTestingAdapter>
+  )
+  return render(<List />, { wrapper })
+}
+
 describe('List', () => {
   beforeEach(() => {
     vi.clearAllMocks()
-    // Set up tag store state
+    onUrlUpdate.mockClear()
     useTagStore.setState({
       tagList: [{ id: 'tag-1', name: 'Test Tag', type: 'app', binding_count: 0 }],
       showTagManagementModal: false,
@@ -246,7 +209,6 @@ describe('List', () => {
     mockIsCurrentWorkspaceDatasetOperator.mockReturnValue(false)
     mockDragging = false
     mockOnDSLFileDropped = null
-    mockTagFilterOnChange = null
     mockServiceState.error = null
     mockServiceState.hasNextPage = false
     mockServiceState.isLoading = false
@@ -260,13 +222,12 @@ describe('List', () => {
 
   describe('Rendering', () => {
     it('should render without crashing', () => {
-      render(<List />)
-      // Tab slider renders app type tabs
+      renderList()
       expect(screen.getByText('app.types.all')).toBeInTheDocument()
     })
 
     it('should render tab slider with all app types', () => {
-      render(<List />)
+      renderList()
 
       expect(screen.getByText('app.types.all')).toBeInTheDocument()
       expect(screen.getByText('app.types.workflow')).toBeInTheDocument()
@@ -277,71 +238,74 @@ describe('List', () => {
     })
 
     it('should render search input', () => {
-      render(<List />)
-      // Input component renders a searchbox
+      renderList()
       expect(screen.getByRole('textbox')).toBeInTheDocument()
     })
 
     it('should render tag filter', () => {
-      render(<List />)
-      // Tag filter renders with placeholder text
+      renderList()
       expect(screen.getByText('common.tag.placeholder')).toBeInTheDocument()
     })
 
     it('should render created by me checkbox', () => {
-      render(<List />)
+      renderList()
       expect(screen.getByText('app.showMyCreatedAppsOnly')).toBeInTheDocument()
     })
 
     it('should render app cards when apps exist', () => {
-      render(<List />)
+      renderList()
 
       expect(screen.getByTestId('app-card-app-1')).toBeInTheDocument()
       expect(screen.getByTestId('app-card-app-2')).toBeInTheDocument()
     })
 
     it('should render new app card for editors', () => {
-      render(<List />)
+      renderList()
       expect(screen.getByTestId('new-app-card')).toBeInTheDocument()
     })
 
     it('should render footer when branding is disabled', () => {
-      render(<List />)
+      renderList()
       expect(screen.getByTestId('footer')).toBeInTheDocument()
     })
 
     it('should render drop DSL hint for editors', () => {
-      render(<List />)
+      renderList()
       expect(screen.getByText('app.newApp.dropDSLToCreateApp')).toBeInTheDocument()
     })
   })
 
   describe('Tab Navigation', () => {
-    it('should call setActiveTab when tab is clicked', () => {
-      render(<List />)
+    it('should update URL when workflow tab is clicked', async () => {
+      renderList()
 
       fireEvent.click(screen.getByText('app.types.workflow'))
 
-      expect(mockSetActiveTab).toHaveBeenCalledWith(AppModeEnum.WORKFLOW)
+      await vi.waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const lastCall = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(lastCall.searchParams.get('category')).toBe(AppModeEnum.WORKFLOW)
     })
 
-    it('should call setActiveTab for all tab', () => {
-      render(<List />)
+    it('should update URL when all tab is clicked', async () => {
+      renderList('?category=workflow')
 
       fireEvent.click(screen.getByText('app.types.all'))
 
-      expect(mockSetActiveTab).toHaveBeenCalledWith('all')
+      await vi.waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const lastCall = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      // nuqs removes the default value ('all') from URL params
+      expect(lastCall.searchParams.has('category')).toBe(false)
     })
   })
 
   describe('Search Functionality', () => {
     it('should render search input field', () => {
-      render(<List />)
+      renderList()
       expect(screen.getByRole('textbox')).toBeInTheDocument()
     })
 
     it('should handle search input change', () => {
-      render(<List />)
+      renderList()
 
       const input = screen.getByRole('textbox')
       fireEvent.change(input, { target: { value: 'test search' } })
@@ -349,55 +313,36 @@ describe('List', () => {
       expect(mockSetQuery).toHaveBeenCalled()
     })
 
-    it('should handle search input interaction', () => {
-      render(<List />)
-
-      const input = screen.getByRole('textbox')
-      expect(input).toBeInTheDocument()
-    })
-
     it('should handle search clear button click', () => {
-      // Set initial keywords to make clear button visible
       mockQueryState.keywords = 'existing search'
 
-      render(<List />)
+      renderList()
 
-      // Find and click clear button (Input component uses .group class for clear icon container)
       const clearButton = document.querySelector('.group')
       expect(clearButton).toBeInTheDocument()
       if (clearButton)
         fireEvent.click(clearButton)
 
-      // handleKeywordsChange should be called with empty string
       expect(mockSetQuery).toHaveBeenCalled()
     })
   })
 
   describe('Tag Filter', () => {
     it('should render tag filter component', () => {
-      render(<List />)
-      expect(screen.getByText('common.tag.placeholder')).toBeInTheDocument()
-    })
-
-    it('should render tag filter with placeholder', () => {
-      render(<List />)
-
-      // Tag filter is rendered
+      renderList()
       expect(screen.getByText('common.tag.placeholder')).toBeInTheDocument()
     })
   })
 
   describe('Created By Me Filter', () => {
     it('should render checkbox with correct label', () => {
-      render(<List />)
+      renderList()
       expect(screen.getByText('app.showMyCreatedAppsOnly')).toBeInTheDocument()
     })
 
     it('should handle checkbox change', () => {
-      render(<List />)
+      renderList()
 
-      // Checkbox component uses data-testid="checkbox-{id}"
-      // CheckboxWithLabel doesn't pass testId, so id is undefined
       const checkbox = screen.getByTestId('checkbox-undefined')
       fireEvent.click(checkbox)
 
@@ -409,7 +354,7 @@ describe('List', () => {
     it('should not render new app card for non-editors', () => {
       mockIsCurrentWorkspaceEditor.mockReturnValue(false)
 
-      render(<List />)
+      renderList()
 
       expect(screen.queryByTestId('new-app-card')).not.toBeInTheDocument()
     })
@@ -417,7 +362,7 @@ describe('List', () => {
     it('should not render drop DSL hint for non-editors', () => {
       mockIsCurrentWorkspaceEditor.mockReturnValue(false)
 
-      render(<List />)
+      renderList()
 
       expect(screen.queryByText(/drop dsl file to create app/i)).not.toBeInTheDocument()
     })
@@ -427,7 +372,7 @@ describe('List', () => {
     it('should redirect dataset operators to datasets page', () => {
       mockIsCurrentWorkspaceDatasetOperator.mockReturnValue(true)
 
-      render(<List />)
+      renderList()
 
       expect(mockReplace).toHaveBeenCalledWith('/datasets')
     })
@@ -437,7 +382,7 @@ describe('List', () => {
     it('should call refetch when refresh key is set in localStorage', () => {
       localStorage.setItem('needRefreshAppList', '1')
 
-      render(<List />)
+      renderList()
 
       expect(mockRefetch).toHaveBeenCalled()
       expect(localStorage.getItem('needRefreshAppList')).toBeNull()
@@ -446,22 +391,30 @@ describe('List', () => {
 
   describe('Edge Cases', () => {
     it('should handle multiple renders without issues', () => {
-      const { rerender } = render(<List />)
+      const { rerender } = render(
+        <NuqsTestingAdapter>
+          <List />
+        </NuqsTestingAdapter>,
+      )
       expect(screen.getByText('app.types.all')).toBeInTheDocument()
 
-      rerender(<List />)
+      rerender(
+        <NuqsTestingAdapter>
+          <List />
+        </NuqsTestingAdapter>,
+      )
       expect(screen.getByText('app.types.all')).toBeInTheDocument()
     })
 
     it('should render app cards correctly', () => {
-      render(<List />)
+      renderList()
 
       expect(screen.getByText('Test App 1')).toBeInTheDocument()
       expect(screen.getByText('Test App 2')).toBeInTheDocument()
     })
 
     it('should render with all filter options visible', () => {
-      render(<List />)
+      renderList()
 
       expect(screen.getByRole('textbox')).toBeInTheDocument()
       expect(screen.getByText('common.tag.placeholder')).toBeInTheDocument()
@@ -471,14 +424,20 @@ describe('List', () => {
 
   describe('Dragging State', () => {
     it('should show drop hint when DSL feature is enabled for editors', () => {
-      render(<List />)
+      renderList()
       expect(screen.getByText('app.newApp.dropDSLToCreateApp')).toBeInTheDocument()
     })
+
+    it('should render dragging state overlay when dragging', () => {
+      mockDragging = true
+      const { container } = renderList()
+      expect(container).toBeInTheDocument()
+    })
   })
 
   describe('App Type Tabs', () => {
     it('should render all app type tabs', () => {
-      render(<List />)
+      renderList()
 
       expect(screen.getByText('app.types.all')).toBeInTheDocument()
       expect(screen.getByText('app.types.workflow')).toBeInTheDocument()
@@ -488,8 +447,8 @@ describe('List', () => {
       expect(screen.getByText('app.types.completion')).toBeInTheDocument()
     })
 
-    it('should call setActiveTab for each app type', () => {
-      render(<List />)
+    it('should update URL for each app type tab click', async () => {
+      renderList()
 
       const appTypeTexts = [
         { mode: AppModeEnum.WORKFLOW, text: 'app.types.workflow' },
@@ -499,45 +458,26 @@ describe('List', () => {
         { mode: AppModeEnum.COMPLETION, text: 'app.types.completion' },
       ]
 
-      appTypeTexts.forEach(({ mode, text }) => {
+      for (const { mode, text } of appTypeTexts) {
+        onUrlUpdate.mockClear()
         fireEvent.click(screen.getByText(text))
-        expect(mockSetActiveTab).toHaveBeenCalledWith(mode)
-      })
-    })
-  })
-
-  describe('Search and Filter Integration', () => {
-    it('should display search input with correct attributes', () => {
-      render(<List />)
-
-      const input = screen.getByRole('textbox')
-      expect(input).toBeInTheDocument()
-      expect(input).toHaveAttribute('value', '')
-    })
-
-    it('should have tag filter component', () => {
-      render(<List />)
-
-      expect(screen.getByText('common.tag.placeholder')).toBeInTheDocument()
-    })
-
-    it('should display created by me label', () => {
-      render(<List />)
-
-      expect(screen.getByText('app.showMyCreatedAppsOnly')).toBeInTheDocument()
+        await vi.waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+        const lastCall = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+        expect(lastCall.searchParams.get('category')).toBe(mode)
+      }
     })
   })
 
   describe('App List Display', () => {
     it('should display all app cards from data', () => {
-      render(<List />)
+      renderList()
 
       expect(screen.getByTestId('app-card-app-1')).toBeInTheDocument()
       expect(screen.getByTestId('app-card-app-2')).toBeInTheDocument()
     })
 
     it('should display app names correctly', () => {
-      render(<List />)
+      renderList()
 
       expect(screen.getByText('Test App 1')).toBeInTheDocument()
       expect(screen.getByText('Test App 2')).toBeInTheDocument()
@@ -546,59 +486,27 @@ describe('List', () => {
 
   describe('Footer Visibility', () => {
     it('should render footer when branding is disabled', () => {
-      render(<List />)
-
+      renderList()
       expect(screen.getByTestId('footer')).toBeInTheDocument()
     })
   })
 
-  // --------------------------------------------------------------------------
-  // Additional Coverage Tests
-  // --------------------------------------------------------------------------
-  describe('Additional Coverage', () => {
-    it('should render dragging state overlay when dragging', () => {
-      mockDragging = true
-      const { container } = render(<List />)
-
-      // Component should render successfully with dragging state
-      expect(container).toBeInTheDocument()
-    })
-
-    it('should handle app mode filter in query params', () => {
-      render(<List />)
-
-      const workflowTab = screen.getByText('app.types.workflow')
-      fireEvent.click(workflowTab)
-
-      expect(mockSetActiveTab).toHaveBeenCalledWith(AppModeEnum.WORKFLOW)
-    })
-
-    it('should render new app card for editors', () => {
-      render(<List />)
-
-      expect(screen.getByTestId('new-app-card')).toBeInTheDocument()
-    })
-  })
-
   describe('DSL File Drop', () => {
     it('should handle DSL file drop and show modal', () => {
-      render(<List />)
+      renderList()
 
-      // Simulate DSL file drop via the callback
       const mockFile = new File(['test content'], 'test.yml', { type: 'application/yaml' })
       act(() => {
         if (mockOnDSLFileDropped)
           mockOnDSLFileDropped(mockFile)
       })
 
-      // Modal should be shown
       expect(screen.getByTestId('create-dsl-modal')).toBeInTheDocument()
     })
 
     it('should close DSL modal when onClose is called', () => {
-      render(<List />)
+      renderList()
 
-      // Open modal via DSL file drop
       const mockFile = new File(['test content'], 'test.yml', { type: 'application/yaml' })
       act(() => {
         if (mockOnDSLFileDropped)
@@ -607,16 +515,14 @@ describe('List', () => {
 
       expect(screen.getByTestId('create-dsl-modal')).toBeInTheDocument()
 
-      // Close modal
       fireEvent.click(screen.getByTestId('close-dsl-modal'))
 
       expect(screen.queryByTestId('create-dsl-modal')).not.toBeInTheDocument()
     })
 
     it('should close DSL modal and refetch when onSuccess is called', () => {
-      render(<List />)
+      renderList()
 
-      // Open modal via DSL file drop
       const mockFile = new File(['test content'], 'test.yml', { type: 'application/yaml' })
       act(() => {
         if (mockOnDSLFileDropped)
@@ -625,67 +531,18 @@ describe('List', () => {
 
       expect(screen.getByTestId('create-dsl-modal')).toBeInTheDocument()
 
-      // Click success button
       fireEvent.click(screen.getByTestId('success-dsl-modal'))
 
-      // Modal should be closed and refetch should be called
       expect(screen.queryByTestId('create-dsl-modal')).not.toBeInTheDocument()
       expect(mockRefetch).toHaveBeenCalled()
     })
   })
 
-  describe('Tag Filter Change', () => {
-    it('should handle tag filter value change', () => {
-      vi.useFakeTimers()
-      render(<List />)
-
-      // TagFilter component is rendered
-      expect(screen.getByTestId('tag-filter')).toBeInTheDocument()
-
-      // Trigger tag filter change via captured callback
-      act(() => {
-        if (mockTagFilterOnChange)
-          mockTagFilterOnChange(['tag-1', 'tag-2'])
-      })
-
-      // Advance timers to trigger debounced setTagIDs
-      act(() => {
-        vi.advanceTimersByTime(500)
-      })
-
-      // setQuery should have been called with updated tagIDs
-      expect(mockSetQuery).toHaveBeenCalled()
-
-      vi.useRealTimers()
-    })
-
-    it('should handle empty tag filter selection', () => {
-      vi.useFakeTimers()
-      render(<List />)
-
-      // Trigger tag filter change with empty array
-      act(() => {
-        if (mockTagFilterOnChange)
-          mockTagFilterOnChange([])
-      })
-
-      // Advance timers
-      act(() => {
-        vi.advanceTimersByTime(500)
-      })
-
-      expect(mockSetQuery).toHaveBeenCalled()
-
-      vi.useRealTimers()
-    })
-  })
-
   describe('Infinite Scroll', () => {
     it('should call fetchNextPage when intersection observer triggers', () => {
       mockServiceState.hasNextPage = true
-      render(<List />)
+      renderList()
 
-      // Simulate intersection
       if (intersectionCallback) {
         act(() => {
           intersectionCallback!(
@@ -700,9 +557,8 @@ describe('List', () => {
 
     it('should not call fetchNextPage when not intersecting', () => {
       mockServiceState.hasNextPage = true
-      render(<List />)
+      renderList()
 
-      // Simulate non-intersection
       if (intersectionCallback) {
         act(() => {
           intersectionCallback!(
@@ -718,7 +574,7 @@ describe('List', () => {
     it('should not call fetchNextPage when loading', () => {
       mockServiceState.hasNextPage = true
       mockServiceState.isLoading = true
-      render(<List />)
+      renderList()
 
       if (intersectionCallback) {
         act(() => {
@@ -736,11 +592,8 @@ describe('List', () => {
   describe('Error State', () => {
     it('should handle error state in useEffect', () => {
       mockServiceState.error = new Error('Test error')
-      const { container } = render(<List />)
-
-      // Component should still render
+      const { container } = renderList()
       expect(container).toBeInTheDocument()
-      // Disconnect should be called when there's an error (cleanup)
     })
   })
 })

web/app/components/apps/__tests__/new-app-card.spec.tsx

@@ -1,10 +1,8 @@
 import { fireEvent, render, screen } from '@testing-library/react'
 import * as React from 'react'
 
-// Import after mocks
-import CreateAppCard from './new-app-card'
+import CreateAppCard from '../new-app-card'
 
-// Mock next/navigation
 const mockReplace = vi.fn()
 vi.mock('next/navigation', () => ({
   useRouter: () => ({
@@ -13,7 +11,6 @@ vi.mock('next/navigation', () => ({
   useSearchParams: () => new URLSearchParams(),
 }))
 
-// Mock provider context
 const mockOnPlanInfoChanged = vi.fn()
 vi.mock('@/context/provider-context', () => ({
   useProviderContext: () => ({
@@ -21,37 +18,35 @@ vi.mock('@/context/provider-context', () => ({
   }),
 }))
 
-// Mock next/dynamic to immediately resolve components
 vi.mock('next/dynamic', () => ({
-  default: (importFn: () => Promise<any>) => {
+  default: (importFn: () => Promise<{ default: React.ComponentType }>) => {
     const fnString = importFn.toString()
 
     if (fnString.includes('create-app-modal') && !fnString.includes('create-from-dsl-modal')) {
-      return function MockCreateAppModal({ show, onClose, onSuccess, onCreateFromTemplate }: any) {
+      return function MockCreateAppModal({ show, onClose, onSuccess, onCreateFromTemplate }: Record<string, unknown>) {
         if (!show)
           return null
-        return React.createElement('div', { 'data-testid': 'create-app-modal' }, React.createElement('button', { 'onClick': onClose, 'data-testid': 'close-create-modal' }, 'Close'), React.createElement('button', { 'onClick': onSuccess, 'data-testid': 'success-create-modal' }, 'Success'), React.createElement('button', { 'onClick': onCreateFromTemplate, 'data-testid': 'to-template-modal' }, 'To Template'))
+        return React.createElement('div', { 'data-testid': 'create-app-modal' }, React.createElement('button', { 'onClick': onClose as () => void, 'data-testid': 'close-create-modal' }, 'Close'), React.createElement('button', { 'onClick': onSuccess as () => void, 'data-testid': 'success-create-modal' }, 'Success'), React.createElement('button', { 'onClick': onCreateFromTemplate as () => void, 'data-testid': 'to-template-modal' }, 'To Template'))
       }
     }
     if (fnString.includes('create-app-dialog')) {
-      return function MockCreateAppTemplateDialog({ show, onClose, onSuccess, onCreateFromBlank }: any) {
+      return function MockCreateAppTemplateDialog({ show, onClose, onSuccess, onCreateFromBlank }: Record<string, unknown>) {
         if (!show)
           return null
-        return React.createElement('div', { 'data-testid': 'create-template-dialog' }, React.createElement('button', { 'onClick': onClose, 'data-testid': 'close-template-dialog' }, 'Close'), React.createElement('button', { 'onClick': onSuccess, 'data-testid': 'success-template-dialog' }, 'Success'), React.createElement('button', { 'onClick': onCreateFromBlank, 'data-testid': 'to-blank-modal' }, 'To Blank'))
+        return React.createElement('div', { 'data-testid': 'create-template-dialog' }, React.createElement('button', { 'onClick': onClose as () => void, 'data-testid': 'close-template-dialog' }, 'Close'), React.createElement('button', { 'onClick': onSuccess as () => void, 'data-testid': 'success-template-dialog' }, 'Success'), React.createElement('button', { 'onClick': onCreateFromBlank as () => void, 'data-testid': 'to-blank-modal' }, 'To Blank'))
       }
     }
     if (fnString.includes('create-from-dsl-modal')) {
-      return function MockCreateFromDSLModal({ show, onClose, onSuccess }: any) {
+      return function MockCreateFromDSLModal({ show, onClose, onSuccess }: Record<string, unknown>) {
         if (!show)
           return null
-        return React.createElement('div', { 'data-testid': 'create-dsl-modal' }, React.createElement('button', { 'onClick': onClose, 'data-testid': 'close-dsl-modal' }, 'Close'), React.createElement('button', { 'onClick': onSuccess, 'data-testid': 'success-dsl-modal' }, 'Success'))
+        return React.createElement('div', { 'data-testid': 'create-dsl-modal' }, React.createElement('button', { 'onClick': onClose as () => void, 'data-testid': 'close-dsl-modal' }, 'Close'), React.createElement('button', { 'onClick': onSuccess as () => void, 'data-testid': 'success-dsl-modal' }, 'Success'))
       }
     }
     return () => null
   },
 }))
 
-// Mock CreateFromDSLModalTab enum
 vi.mock('@/app/components/app/create-from-dsl-modal', () => ({
   CreateFromDSLModalTab: {
     FROM_URL: 'from-url',
@@ -68,7 +63,6 @@ describe('CreateAppCard', () => {
   describe('Rendering', () => {
     it('should render without crashing', () => {
       render(<CreateAppCard ref={defaultRef} />)
-      // Use pattern matching for resilient text assertions
       expect(screen.getByText('app.createApp')).toBeInTheDocument()
     })
 
@@ -245,19 +239,15 @@ describe('CreateAppCard', () => {
     it('should handle multiple modal opens/closes', () => {
       render(<CreateAppCard ref={defaultRef} />)
 
-      // Open and close create modal
       fireEvent.click(screen.getByText('app.newApp.startFromBlank'))
       fireEvent.click(screen.getByTestId('close-create-modal'))
 
-      // Open and close template dialog
       fireEvent.click(screen.getByText('app.newApp.startFromTemplate'))
       fireEvent.click(screen.getByTestId('close-template-dialog'))
 
-      // Open and close DSL modal
       fireEvent.click(screen.getByText('app.importDSL'))
       fireEvent.click(screen.getByTestId('close-dsl-modal'))
 
-      // No modals should be visible
       expect(screen.queryByTestId('create-app-modal')).not.toBeInTheDocument()
       expect(screen.queryByTestId('create-template-dialog')).not.toBeInTheDocument()
       expect(screen.queryByTestId('create-dsl-modal')).not.toBeInTheDocument()
@@ -267,7 +257,6 @@ describe('CreateAppCard', () => {
       render(<CreateAppCard ref={defaultRef} />)
 
       fireEvent.click(screen.getByText('app.newApp.startFromBlank'))
-      // This should not throw an error
       expect(() => {
         fireEvent.click(screen.getByTestId('success-create-modal'))
       }).not.toThrow()

web/app/components/apps/hooks/__tests__/use-apps-query-state.spec.tsx

@@ -1,16 +1,8 @@
 import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
 import type { ReactNode } from 'react'
-/**
- * Test suite for useAppsQueryState hook
- *
- * This hook manages app filtering state through URL search parameters, enabling:
- * - Bookmarkable filter states (users can share URLs with specific filters active)
- * - Browser history integration (back/forward buttons work with filters)
- * - Multiple filter types: tagIDs, keywords, isCreatedByMe
- */
 import { act, renderHook, waitFor } from '@testing-library/react'
 import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
-import useAppsQueryState from './use-apps-query-state'
+import useAppsQueryState from '../use-apps-query-state'
 
 const renderWithAdapter = (searchParams = '') => {
   const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
@@ -23,13 +15,11 @@ const renderWithAdapter = (searchParams = '') => {
   return { result, onUrlUpdate }
 }
 
-// Groups scenarios for useAppsQueryState behavior.
 describe('useAppsQueryState', () => {
   beforeEach(() => {
     vi.clearAllMocks()
   })
 
-  // Covers the hook return shape and default values.
   describe('Initialization', () => {
     it('should expose query and setQuery when initialized', () => {
       const { result } = renderWithAdapter()
@@ -47,7 +37,6 @@ describe('useAppsQueryState', () => {
     })
   })
 
-  // Covers parsing of existing URL search params.
   describe('Parsing search params', () => {
     it('should parse tagIDs when URL includes tagIDs', () => {
       const { result } = renderWithAdapter('?tagIDs=tag1;tag2;tag3')
@@ -78,7 +67,6 @@ describe('useAppsQueryState', () => {
     })
   })
 
-  // Covers updates driven by setQuery.
   describe('Updating query state', () => {
     it('should update keywords when setQuery receives keywords', () => {
       const { result } = renderWithAdapter()
@@ -126,7 +114,6 @@ describe('useAppsQueryState', () => {
     })
   })
 
-  // Covers URL updates triggered by query changes.
   describe('URL synchronization', () => {
     it('should sync keywords to URL when keywords change', async () => {
       const { result, onUrlUpdate } = renderWithAdapter()
@@ -202,7 +189,6 @@ describe('useAppsQueryState', () => {
     })
   })
 
-  // Covers decoding and empty values.
   describe('Edge cases', () => {
     it('should treat empty tagIDs as empty list when URL param is empty', () => {
       const { result } = renderWithAdapter('?tagIDs=')
@@ -223,7 +209,6 @@ describe('useAppsQueryState', () => {
     })
   })
 
-  // Covers multi-step updates that mimic real usage.
   describe('Integration scenarios', () => {
     it('should keep accumulated filters when updates are sequential', () => {
       const { result } = renderWithAdapter()

web/app/components/apps/hooks/__tests__/use-dsl-drag-drop.spec.ts

@@ -1,15 +1,6 @@
-/**
- * Test suite for useDSLDragDrop hook
- *
- * This hook provides drag-and-drop functionality for DSL files, enabling:
- * - File drag detection with visual feedback (dragging state)
- * - YAML/YML file filtering (only accepts .yaml and .yml files)
- * - Enable/disable toggle for conditional drag-and-drop
- * - Cleanup on unmount (removes event listeners)
- */
 import type { Mock } from 'vitest'
 import { act, renderHook } from '@testing-library/react'
-import { useDSLDragDrop } from './use-dsl-drag-drop'
+import { useDSLDragDrop } from '../use-dsl-drag-drop'
 
 describe('useDSLDragDrop', () => {
   let container: HTMLDivElement
@@ -26,7 +17,6 @@ describe('useDSLDragDrop', () => {
     document.body.removeChild(container)
   })
 
-  // Helper to create drag events
   const createDragEvent = (type: string, files: File[] = []) => {
     const dataTransfer = {
       types: files.length > 0 ? ['Files'] : [],
@@ -50,7 +40,6 @@ describe('useDSLDragDrop', () => {
     return event
   }
 
-  // Helper to create a mock file
   const createMockFile = (name: string) => {
     return new File(['content'], name, { type: 'application/x-yaml' })
   }
@@ -147,14 +136,12 @@ describe('useDSLDragDrop', () => {
         }),
       )
 
-      // First, enter with files
       const enterEvent = createDragEvent('dragenter', [createMockFile('test.yaml')])
       act(() => {
         container.dispatchEvent(enterEvent)
       })
       expect(result.current.dragging).toBe(true)
 
-      // Then leave with null relatedTarget (leaving container)
       const leaveEvent = createDragEvent('dragleave')
       Object.defineProperty(leaveEvent, 'relatedTarget', {
         value: null,
@@ -180,14 +167,12 @@ describe('useDSLDragDrop', () => {
         }),
       )
 
-      // First, enter with files
       const enterEvent = createDragEvent('dragenter', [createMockFile('test.yaml')])
       act(() => {
         container.dispatchEvent(enterEvent)
       })
       expect(result.current.dragging).toBe(true)
 
-      // Then leave but to a child element
       const leaveEvent = createDragEvent('dragleave')
       Object.defineProperty(leaveEvent, 'relatedTarget', {
         value: childElement,
@@ -290,14 +275,12 @@ describe('useDSLDragDrop', () => {
         }),
       )
 
-      // First, enter with files
       const enterEvent = createDragEvent('dragenter', [createMockFile('test.yaml')])
       act(() => {
         container.dispatchEvent(enterEvent)
       })
       expect(result.current.dragging).toBe(true)
 
-      // Then drop
       const dropEvent = createDragEvent('drop', [createMockFile('test.yaml')])
       act(() => {
         container.dispatchEvent(dropEvent)
@@ -409,14 +392,12 @@ describe('useDSLDragDrop', () => {
         { initialProps: { enabled: true } },
       )
 
-      // Set dragging state
       const enterEvent = createDragEvent('dragenter', [createMockFile('test.yaml')])
       act(() => {
         container.dispatchEvent(enterEvent)
       })
       expect(result.current.dragging).toBe(true)
 
-      // Disable the hook
       rerender({ enabled: false })
       expect(result.current.dragging).toBe(false)
     })

web/app/components/base/agent-log-modal/detail.spec.tsx

@@ -0,0 +1,260 @@
+import type { ComponentProps } from 'react'
+import type { IChatItem } from '@/app/components/base/chat/chat/type'
+import type { AgentLogDetailResponse } from '@/models/log'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { ToastContext } from '@/app/components/base/toast'
+import { fetchAgentLogDetail } from '@/service/log'
+import AgentLogDetail from './detail'
+
+vi.mock('@/service/log', () => ({
+  fetchAgentLogDetail: vi.fn(),
+}))
+
+vi.mock('@/app/components/app/store', () => ({
+  useStore: vi.fn(selector => selector({ appDetail: { id: 'app-id' } })),
+}))
+
+vi.mock('@/app/components/workflow/run/status', () => ({
+  default: ({ status, time, tokens, error }: { status: string, time?: number, tokens?: number, error?: string }) => (
+    <div data-testid="status-panel" data-status={String(status)} data-time={String(time)} data-tokens={String(tokens)}>{error ? <span>{String(error)}</span> : null}</div>
+  ),
+}))
+
+vi.mock('@/app/components/workflow/nodes/_base/components/editor/code-editor', () => ({
+  default: ({ title, value }: { title: React.ReactNode, value: string | object }) => (
+    <div data-testid="code-editor">
+      {title}
+      {typeof value === 'string' ? value : JSON.stringify(value)}
+    </div>
+  ),
+}))
+
+vi.mock('@/hooks/use-timestamp', () => ({
+  default: () => ({ formatTime: (ts: number, fmt: string) => `${ts}-${fmt}` }),
+}))
+
+vi.mock('@/app/components/workflow/block-icon', () => ({
+  default: () => <div data-testid="block-icon" />,
+}))
+
+vi.mock('@/app/components/base/icons/src/vender/line/arrows', () => ({
+  ChevronRight: (props: { className?: string }) => <div data-testid="chevron-right" className={props.className} />,
+}))
+
+const createMockLog = (overrides: Partial<IChatItem> = {}): IChatItem => ({
+  id: 'msg-id',
+  content: 'output content',
+  isAnswer: false,
+  conversationId: 'conv-id',
+  input: 'user input',
+  ...overrides,
+})
+
+const createMockResponse = (overrides: Partial<AgentLogDetailResponse> = {}): AgentLogDetailResponse => ({
+  meta: {
+    status: 'succeeded',
+    executor: 'User',
+    start_time: '2023-01-01',
+    elapsed_time: 1.0,
+    total_tokens: 100,
+    agent_mode: 'function_call',
+    iterations: 1,
+  },
+  iterations: [
+    {
+      created_at: '',
+      files: [],
+      thought: '',
+      tokens: 0,
+      tool_raw: { inputs: '', outputs: '' },
+      tool_calls: [{ tool_name: 'tool1', status: 'success', tool_icon: null, tool_label: { 'en-US': 'Tool 1' } }],
+    },
+  ],
+  files: [],
+  ...overrides,
+})
+
+describe('AgentLogDetail', () => {
+  const notify = vi.fn()
+
+  const renderComponent = (props: Partial<ComponentProps<typeof AgentLogDetail>> = {}) => {
+    const defaultProps: ComponentProps<typeof AgentLogDetail> = {
+      conversationID: 'conv-id',
+      messageID: 'msg-id',
+      log: createMockLog(),
+    }
+    return render(
+      <ToastContext.Provider value={{ notify, close: vi.fn() } as ComponentProps<typeof ToastContext.Provider>['value']}>
+        <AgentLogDetail {...defaultProps} {...props} />
+      </ToastContext.Provider>,
+    )
+  }
+
+  const renderAndWaitForData = async (props: Partial<ComponentProps<typeof AgentLogDetail>> = {}) => {
+    const result = renderComponent(props)
+    await waitFor(() => {
+      expect(screen.queryByRole('status')).not.toBeInTheDocument()
+    })
+    return result
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('Rendering', () => {
+    it('should show loading indicator while fetching data', async () => {
+      vi.mocked(fetchAgentLogDetail).mockReturnValue(new Promise(() => {}))
+
+      renderComponent()
+
+      expect(screen.getByRole('status')).toBeInTheDocument()
+    })
+
+    it('should display result panel after data loads', async () => {
+      vi.mocked(fetchAgentLogDetail).mockResolvedValue(createMockResponse())
+
+      await renderAndWaitForData()
+
+      expect(screen.getByText(/runLog.detail/i)).toBeInTheDocument()
+      expect(screen.getByText(/runLog.tracing/i)).toBeInTheDocument()
+    })
+
+    it('should call fetchAgentLogDetail with correct params', async () => {
+      vi.mocked(fetchAgentLogDetail).mockResolvedValue(createMockResponse())
+
+      await renderAndWaitForData()
+
+      expect(fetchAgentLogDetail).toHaveBeenCalledWith({
+        appID: 'app-id',
+        params: {
+          conversation_id: 'conv-id',
+          message_id: 'msg-id',
+        },
+      })
+    })
+  })
+
+  describe('Props', () => {
+    it('should default to DETAIL tab when activeTab is not provided', async () => {
+      vi.mocked(fetchAgentLogDetail).mockResolvedValue(createMockResponse())
+
+      await renderAndWaitForData()
+
+      const detailTab = screen.getByText(/runLog.detail/i)
+      expect(detailTab.getAttribute('data-active')).toBe('true')
+    })
+
+    it('should show TRACING tab when activeTab is TRACING', async () => {
+      vi.mocked(fetchAgentLogDetail).mockResolvedValue(createMockResponse())
+
+      await renderAndWaitForData({ activeTab: 'TRACING' })
+
+      const tracingTab = screen.getByText(/runLog.tracing/i)
+      expect(tracingTab.getAttribute('data-active')).toBe('true')
+    })
+  })
+
+  describe('User Interactions', () => {
+    it('should switch to TRACING tab when clicked', async () => {
+      vi.mocked(fetchAgentLogDetail).mockResolvedValue(createMockResponse())
+
+      await renderAndWaitForData()
+
+      fireEvent.click(screen.getByText(/runLog.tracing/i))
+
+      await waitFor(() => {
+        const tracingTab = screen.getByText(/runLog.tracing/i)
+        expect(tracingTab.getAttribute('data-active')).toBe('true')
+      })
+
+      const detailTab = screen.getByText(/runLog.detail/i)
+      expect(detailTab.getAttribute('data-active')).toBe('false')
+    })
+
+    it('should switch back to DETAIL tab after switching to TRACING', async () => {
+      vi.mocked(fetchAgentLogDetail).mockResolvedValue(createMockResponse())
+
+      await renderAndWaitForData()
+
+      fireEvent.click(screen.getByText(/runLog.tracing/i))
+
+      await waitFor(() => {
+        expect(screen.getByText(/runLog.tracing/i).getAttribute('data-active')).toBe('true')
+      })
+
+      fireEvent.click(screen.getByText(/runLog.detail/i))
+
+      await waitFor(() => {
+        const detailTab = screen.getByText(/runLog.detail/i)
+        expect(detailTab.getAttribute('data-active')).toBe('true')
+      })
+    })
+  })
+
+  describe('Edge Cases', () => {
+    it('should notify on API error', async () => {
+      vi.mocked(fetchAgentLogDetail).mockRejectedValue(new Error('API Error'))
+
+      renderComponent()
+
+      await waitFor(() => {
+        expect(notify).toHaveBeenCalledWith({
+          type: 'error',
+          message: 'Error: API Error',
+        })
+      })
+    })
+
+    it('should stop loading after API error', async () => {
+      vi.mocked(fetchAgentLogDetail).mockRejectedValue(new Error('Network failure'))
+
+      renderComponent()
+
+      await waitFor(() => {
+        expect(screen.queryByRole('status')).not.toBeInTheDocument()
+      })
+    })
+
+    it('should handle response with empty iterations', async () => {
+      vi.mocked(fetchAgentLogDetail).mockResolvedValue(
+        createMockResponse({ iterations: [] }),
+      )
+
+      await renderAndWaitForData()
+    })
+
+    it('should handle response with multiple iterations and duplicate tools', async () => {
+      const response = createMockResponse({
+        iterations: [
+          {
+            created_at: '',
+            files: [],
+            thought: '',
+            tokens: 0,
+            tool_raw: { inputs: '', outputs: '' },
+            tool_calls: [
+              { tool_name: 'tool1', status: 'success', tool_icon: null, tool_label: { 'en-US': 'Tool 1' } },
+              { tool_name: 'tool2', status: 'success', tool_icon: null, tool_label: { 'en-US': 'Tool 2' } },
+            ],
+          },
+          {
+            created_at: '',
+            files: [],
+            thought: '',
+            tokens: 0,
+            tool_raw: { inputs: '', outputs: '' },
+            tool_calls: [
+              { tool_name: 'tool1', status: 'success', tool_icon: null, tool_label: { 'en-US': 'Tool 1' } },
+            ],
+          },
+        ],
+      })
+      vi.mocked(fetchAgentLogDetail).mockResolvedValue(response)
+
+      await renderAndWaitForData()
+
+      expect(screen.getByText(/runLog.detail/i)).toBeInTheDocument()
+    })
+  })
+})

web/app/components/base/agent-log-modal/detail.tsx

@@ -89,6 +89,7 @@ const AgentLogDetail: FC<AgentLogDetailProps> = ({
             'mr-6 cursor-pointer border-b-2 border-transparent py-3 text-[13px] font-semibold leading-[18px] text-text-tertiary',
             currentTab === 'DETAIL' && '!border-[rgb(21,94,239)] text-text-secondary',
           )}
+          data-active={currentTab === 'DETAIL'}
           onClick={() => switchTab('DETAIL')}
         >
           {t('detail', { ns: 'runLog' })}
@@ -98,6 +99,7 @@ const AgentLogDetail: FC<AgentLogDetailProps> = ({
             'mr-6 cursor-pointer border-b-2 border-transparent py-3 text-[13px] font-semibold leading-[18px] text-text-tertiary',
             currentTab === 'TRACING' && '!border-[rgb(21,94,239)] text-text-secondary',
           )}
+          data-active={currentTab === 'TRACING'}
           onClick={() => switchTab('TRACING')}
         >
           {t('tracing', { ns: 'runLog' })}

web/app/components/base/agent-log-modal/index.spec.tsx

@@ -0,0 +1,142 @@
+import type { IChatItem } from '@/app/components/base/chat/chat/type'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { useClickAway } from 'ahooks'
+import { ToastContext } from '@/app/components/base/toast'
+import { fetchAgentLogDetail } from '@/service/log'
+import AgentLogModal from './index'
+
+vi.mock('@/service/log', () => ({
+  fetchAgentLogDetail: vi.fn(),
+}))
+
+vi.mock('@/app/components/app/store', () => ({
+  useStore: vi.fn(selector => selector({ appDetail: { id: 'app-id' } })),
+}))
+
+vi.mock('@/app/components/workflow/run/status', () => ({
+  default: ({ status, time, tokens, error }: { status: string, time?: number, tokens?: number, error?: string }) => (
+    <div data-testid="status-panel" data-status={String(status)} data-time={String(time)} data-tokens={String(tokens)}>{error ? <span>{String(error)}</span> : null}</div>
+  ),
+}))
+
+vi.mock('@/app/components/workflow/nodes/_base/components/editor/code-editor', () => ({
+  default: ({ title, value }: { title: React.ReactNode, value: string | object }) => (
+    <div data-testid="code-editor">
+      {title}
+      {typeof value === 'string' ? value : JSON.stringify(value)}
+    </div>
+  ),
+}))
+
+vi.mock('@/hooks/use-timestamp', () => ({
+  default: () => ({ formatTime: (ts: number, fmt: string) => `${ts}-${fmt}` }),
+}))
+
+vi.mock('@/app/components/workflow/block-icon', () => ({
+  default: () => <div data-testid="block-icon" />,
+}))
+
+vi.mock('@/app/components/base/icons/src/vender/line/arrows', () => ({
+  ChevronRight: (props: { className?: string }) => <div data-testid="chevron-right" className={props.className} />,
+}))
+
+vi.mock('ahooks', () => ({
+  useClickAway: vi.fn(),
+}))
+
+const mockLog = {
+  id: 'msg-id',
+  conversationId: 'conv-id',
+  content: 'content',
+  isAnswer: false,
+  input: 'test input',
+} as IChatItem
+
+const mockProps = {
+  currentLogItem: mockLog,
+  width: 1000,
+  onCancel: vi.fn(),
+}
+
+describe('AgentLogModal', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(fetchAgentLogDetail).mockResolvedValue({
+      meta: {
+        status: 'succeeded',
+        executor: 'User',
+        start_time: '2023-01-01',
+        elapsed_time: 1.0,
+        total_tokens: 100,
+        agent_mode: 'function_call',
+        iterations: 1,
+      },
+      iterations: [{
+        created_at: '',
+        files: [],
+        thought: '',
+        tokens: 0,
+        tool_raw: { inputs: '', outputs: '' },
+        tool_calls: [{ tool_name: 'tool1', status: 'success', tool_icon: null, tool_label: { 'en-US': 'Tool 1' } }],
+      }],
+      files: [],
+    })
+  })
+
+  it('should return null if no currentLogItem', () => {
+    const { container } = render(<AgentLogModal {...mockProps} currentLogItem={undefined} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('should return null if no conversationId', () => {
+    const { container } = render(<AgentLogModal {...mockProps} currentLogItem={{ id: '1' } as unknown as IChatItem} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('should render correctly when log item is provided', async () => {
+    render(
+      <ToastContext.Provider value={{ notify: vi.fn(), close: vi.fn() } as React.ComponentProps<typeof ToastContext.Provider>['value']}>
+        <AgentLogModal {...mockProps} />
+      </ToastContext.Provider>,
+    )
+
+    expect(screen.getByText('appLog.runDetail.workflowTitle')).toBeInTheDocument()
+
+    await waitFor(() => {
+      expect(screen.getByText(/runLog.detail/i)).toBeInTheDocument()
+    })
+  })
+
+  it('should call onCancel when close button is clicked', () => {
+    vi.mocked(fetchAgentLogDetail).mockReturnValue(new Promise(() => {}))
+
+    render(
+      <ToastContext.Provider value={{ notify: vi.fn(), close: vi.fn() } as React.ComponentProps<typeof ToastContext.Provider>['value']}>
+        <AgentLogModal {...mockProps} />
+      </ToastContext.Provider>,
+    )
+
+    const closeBtn = screen.getByRole('heading', { name: /appLog.runDetail.workflowTitle/i }).nextElementSibling!
+    fireEvent.click(closeBtn)
+
+    expect(mockProps.onCancel).toHaveBeenCalledTimes(1)
+  })
+
+  it('should call onCancel when clicking away', () => {
+    vi.mocked(fetchAgentLogDetail).mockReturnValue(new Promise(() => {}))
+
+    let clickAwayHandler!: (event: Event) => void
+    vi.mocked(useClickAway).mockImplementation((callback) => {
+      clickAwayHandler = callback
+    })
+
+    render(
+      <ToastContext.Provider value={{ notify: vi.fn(), close: vi.fn() } as React.ComponentProps<typeof ToastContext.Provider>['value']}>
+        <AgentLogModal {...mockProps} />
+      </ToastContext.Provider>,
+    )
+    clickAwayHandler(new Event('click'))
+
+    expect(mockProps.onCancel).toHaveBeenCalledTimes(1)
+  })
+})

web/app/components/base/agent-log-modal/iteration.spec.tsx

@@ -0,0 +1,57 @@
+import type { AgentIteration } from '@/models/log'
+import { render, screen } from '@testing-library/react'
+import Iteration from './iteration'
+
+vi.mock('@/app/components/workflow/nodes/_base/components/editor/code-editor', () => ({
+  default: ({ title, value }: { title: React.ReactNode, value: string | object }) => (
+    <div data-testid="code-editor">
+      <div data-testid="code-editor-title">{title}</div>
+      <div data-testid="code-editor-value">{JSON.stringify(value)}</div>
+    </div>
+  ),
+}))
+
+vi.mock('@/app/components/workflow/block-icon', () => ({
+  default: () => <div data-testid="block-icon" />,
+}))
+
+const mockIterationInfo: AgentIteration = {
+  created_at: '2023-01-01',
+  files: [],
+  thought: 'Test thought',
+  tokens: 100,
+  tool_calls: [
+    {
+      status: 'success',
+      tool_name: 'test_tool',
+      tool_label: { en: 'Test Tool' },
+      tool_icon: null,
+    },
+  ],
+  tool_raw: {
+    inputs: '{}',
+    outputs: 'test output',
+  },
+}
+
+describe('Iteration', () => {
+  it('should render final processing when isFinal is true', () => {
+    render(<Iteration iterationInfo={mockIterationInfo} isFinal={true} index={1} />)
+
+    expect(screen.getByText(/appLog.agentLogDetail.finalProcessing/i)).toBeInTheDocument()
+    expect(screen.queryByText(/appLog.agentLogDetail.iteration/i)).not.toBeInTheDocument()
+  })
+
+  it('should render iteration index when isFinal is false', () => {
+    render(<Iteration iterationInfo={mockIterationInfo} isFinal={false} index={2} />)
+
+    expect(screen.getByText(/APPLOG.AGENTLOGDETAIL.ITERATION 2/i)).toBeInTheDocument()
+    expect(screen.queryByText(/appLog.agentLogDetail.finalProcessing/i)).not.toBeInTheDocument()
+  })
+
+  it('should render LLM tool call and subsequent tool calls', () => {
+    render(<Iteration iterationInfo={mockIterationInfo} isFinal={false} index={1} />)
+    expect(screen.getByTitle('LLM')).toBeInTheDocument()
+    expect(screen.getByText('Test Tool')).toBeInTheDocument()
+  })
+})

web/app/components/base/agent-log-modal/result.spec.tsx

@@ -0,0 +1,85 @@
+import { render, screen } from '@testing-library/react'
+import * as React from 'react'
+import ResultPanel from './result'
+
+vi.mock('@/app/components/workflow/nodes/_base/components/editor/code-editor', () => ({
+  default: ({ title, value }: { title: React.ReactNode, value: string | object }) => (
+    <div data-testid="code-editor">
+      <div data-testid="code-editor-title">{title}</div>
+      <div data-testid="code-editor-value">{JSON.stringify(value)}</div>
+    </div>
+  ),
+}))
+
+vi.mock('@/app/components/workflow/run/status', () => ({
+  default: ({ status, time, tokens, error }: { status: string, time?: number, tokens?: number, error?: string }) => (
+    <div data-testid="status-panel">
+      <span>{status}</span>
+      <span>{time}</span>
+      <span>{tokens}</span>
+      <span>{error}</span>
+    </div>
+  ),
+}))
+
+vi.mock('@/hooks/use-timestamp', () => ({
+  default: () => ({
+    formatTime: vi.fn((ts, _format) => `formatted-${ts}`),
+  }),
+}))
+
+const mockProps = {
+  status: 'succeeded',
+  elapsed_time: 1.23456,
+  total_tokens: 150,
+  error: '',
+  inputs: { query: 'input' },
+  outputs: { answer: 'output' },
+  created_by: 'User Name',
+  created_at: '2023-01-01T00:00:00Z',
+  agentMode: 'function_call',
+  tools: ['tool1', 'tool2'],
+  iterations: 3,
+}
+
+describe('ResultPanel', () => {
+  it('should render status panel and code editors', () => {
+    render(<ResultPanel {...mockProps} />)
+
+    expect(screen.getByTestId('status-panel')).toBeInTheDocument()
+
+    const editors = screen.getAllByTestId('code-editor')
+    expect(editors).toHaveLength(2)
+
+    expect(screen.getByText('INPUT')).toBeInTheDocument()
+    expect(screen.getByText('OUTPUT')).toBeInTheDocument()
+    expect(screen.getByText(JSON.stringify(mockProps.inputs))).toBeInTheDocument()
+    expect(screen.getByText(JSON.stringify(mockProps.outputs))).toBeInTheDocument()
+  })
+
+  it('should display correct metadata', () => {
+    render(<ResultPanel {...mockProps} />)
+
+    expect(screen.getByText('User Name')).toBeInTheDocument()
+    expect(screen.getByText('1.235s')).toBeInTheDocument() // toFixed(3)
+    expect(screen.getByText('150 Tokens')).toBeInTheDocument()
+    expect(screen.getByText('appDebug.agent.agentModeType.functionCall')).toBeInTheDocument()
+    expect(screen.getByText('tool1, tool2')).toBeInTheDocument()
+    expect(screen.getByText('3')).toBeInTheDocument()
+
+    // Check formatted time
+    expect(screen.getByText(/formatted-/)).toBeInTheDocument()
+  })
+
+  it('should handle missing created_by and tools', () => {
+    render(<ResultPanel {...mockProps} created_by={undefined} tools={[]} />)
+
+    expect(screen.getByText('N/A')).toBeInTheDocument()
+    expect(screen.getByText('Null')).toBeInTheDocument()
+  })
+
+  it('should display ReACT mode correctly', () => {
+    render(<ResultPanel {...mockProps} agentMode="react" />)
+    expect(screen.getByText('appDebug.agent.agentModeType.ReACT')).toBeInTheDocument()
+  })
+})

web/app/components/base/agent-log-modal/tool-call.spec.tsx

@@ -0,0 +1,126 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import * as React from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { BlockEnum } from '@/app/components/workflow/types'
+import ToolCallItem from './tool-call'
+
+vi.mock('@/app/components/workflow/nodes/_base/components/editor/code-editor', () => ({
+  default: ({ title, value }: { title: React.ReactNode, value: string | object }) => (
+    <div data-testid="code-editor">
+      <div data-testid="code-editor-title">{title}</div>
+      <div data-testid="code-editor-value">{JSON.stringify(value)}</div>
+    </div>
+  ),
+}))
+
+vi.mock('@/app/components/workflow/block-icon', () => ({
+  default: ({ type }: { type: BlockEnum }) => <div data-testid="block-icon" data-type={type} />,
+}))
+
+const mockToolCall = {
+  status: 'success',
+  error: null,
+  tool_name: 'test_tool',
+  tool_label: { en: 'Test Tool Label' },
+  tool_icon: 'icon',
+  time_cost: 1.5,
+  tool_input: { query: 'hello' },
+  tool_output: { result: 'world' },
+}
+
+describe('ToolCallItem', () => {
+  it('should render tool name correctly for LLM', () => {
+    render(<ToolCallItem toolCall={mockToolCall} isLLM={true} />)
+    expect(screen.getByText('LLM')).toBeInTheDocument()
+    expect(screen.getByTestId('block-icon')).toHaveAttribute('data-type', BlockEnum.LLM)
+  })
+
+  it('should render tool name from label for non-LLM', () => {
+    render(<ToolCallItem toolCall={mockToolCall} isLLM={false} />)
+    expect(screen.getByText('Test Tool Label')).toBeInTheDocument()
+    expect(screen.getByTestId('block-icon')).toHaveAttribute('data-type', BlockEnum.Tool)
+  })
+
+  it('should format time correctly', () => {
+    render(<ToolCallItem toolCall={mockToolCall} isLLM={false} />)
+    expect(screen.getByText('1.500 s')).toBeInTheDocument()
+
+    // Test ms format
+    render(<ToolCallItem toolCall={{ ...mockToolCall, time_cost: 0.5 }} isLLM={false} />)
+    expect(screen.getByText('500.000 ms')).toBeInTheDocument()
+
+    // Test minute format
+    render(<ToolCallItem toolCall={{ ...mockToolCall, time_cost: 65 }} isLLM={false} />)
+    expect(screen.getByText('1 m 5.000 s')).toBeInTheDocument()
+  })
+
+  it('should format token count correctly', () => {
+    render(<ToolCallItem toolCall={mockToolCall} isLLM={true} tokens={1200} />)
+    expect(screen.getByText('1.2K tokens')).toBeInTheDocument()
+
+    render(<ToolCallItem toolCall={mockToolCall} isLLM={true} tokens={800} />)
+    expect(screen.getByText('800 tokens')).toBeInTheDocument()
+
+    render(<ToolCallItem toolCall={mockToolCall} isLLM={true} tokens={1200000} />)
+    expect(screen.getByText('1.2M tokens')).toBeInTheDocument()
+  })
+
+  it('should handle collapse/expand', () => {
+    render(<ToolCallItem toolCall={mockToolCall} isLLM={false} />)
+
+    expect(screen.queryByTestId('code-editor')).not.toBeInTheDocument()
+
+    fireEvent.click(screen.getByText(/Test Tool Label/i))
+    expect(screen.getAllByTestId('code-editor')).toHaveLength(2)
+  })
+
+  it('should display error message when status is error', () => {
+    const errorToolCall = {
+      ...mockToolCall,
+      status: 'error',
+      error: 'Something went wrong',
+    }
+    render(<ToolCallItem toolCall={errorToolCall} isLLM={false} />)
+
+    fireEvent.click(screen.getByText(/Test Tool Label/i))
+    expect(screen.getByText('Something went wrong')).toBeInTheDocument()
+  })
+
+  it('should display LLM specific fields when expanded', () => {
+    render(
+      <ToolCallItem
+        toolCall={mockToolCall}
+        isLLM={true}
+        observation="test observation"
+        finalAnswer="test final answer"
+        isFinal={true}
+      />,
+    )
+
+    fireEvent.click(screen.getByText('LLM'))
+
+    const titles = screen.getAllByTestId('code-editor-title')
+    const titleTexts = titles.map(t => t.textContent)
+
+    expect(titleTexts).toContain('INPUT')
+    expect(titleTexts).toContain('OUTPUT')
+    expect(titleTexts).toContain('OBSERVATION')
+    expect(titleTexts).toContain('FINAL ANSWER')
+  })
+
+  it('should display THOUGHT instead of FINAL ANSWER when isFinal is false', () => {
+    render(
+      <ToolCallItem
+        toolCall={mockToolCall}
+        isLLM={true}
+        observation="test observation"
+        finalAnswer="test thought"
+        isFinal={false}
+      />,
+    )
+
+    fireEvent.click(screen.getByText('LLM'))
+    expect(screen.getByText('THOUGHT')).toBeInTheDocument()
+    expect(screen.queryByText('FINAL ANSWER')).not.toBeInTheDocument()
+  })
+})

web/app/components/base/agent-log-modal/tracing.spec.tsx

@@ -0,0 +1,50 @@
+import type { AgentIteration } from '@/models/log'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import TracingPanel from './tracing'
+
+vi.mock('@/app/components/workflow/block-icon', () => ({
+  default: () => <div data-testid="block-icon" />,
+}))
+
+vi.mock('@/app/components/base/icons/src/vender/line/arrows', () => ({
+  ChevronRight: (props: { className?: string }) => <div data-testid="chevron-right" className={props.className} />,
+}))
+
+vi.mock('@/app/components/workflow/nodes/_base/components/editor/code-editor', () => ({
+  default: ({ title, value }: { title: React.ReactNode, value: string | object }) => (
+    <div data-testid="code-editor">
+      {title}
+      {typeof value === 'string' ? value : JSON.stringify(value)}
+    </div>
+  ),
+}))
+
+const createIteration = (thought: string, tokens: number): AgentIteration => ({
+  created_at: '',
+  files: [],
+  thought,
+  tokens,
+  tool_calls: [{ tool_name: 'tool1', status: 'success', tool_icon: null, tool_label: { 'en-US': 'Tool 1' } }],
+  tool_raw: { inputs: '', outputs: '' },
+})
+
+const mockList: AgentIteration[] = [
+  createIteration('Thought 1', 10),
+  createIteration('Thought 2', 20),
+  createIteration('Thought 3', 30),
+]
+
+describe('TracingPanel', () => {
+  it('should render all iterations in the list', () => {
+    render(<TracingPanel list={mockList} />)
+
+    expect(screen.getByText(/finalProcessing/i)).toBeInTheDocument()
+    expect(screen.getAllByText(/ITERATION/i).length).toBe(2)
+  })
+
+  it('should render empty list correctly', () => {
+    const { container } = render(<TracingPanel list={[]} />)
+    expect(container.querySelector('.bg-background-section')?.children.length).toBe(0)
+  })
+})

web/app/components/base/checkbox-list/index.spec.tsx

@@ -0,0 +1,195 @@
+/* eslint-disable next/no-img-element */
+import type { ImgHTMLAttributes } from 'react'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import CheckboxList from '.'
+
+vi.mock('next/image', () => ({
+  default: (props: ImgHTMLAttributes<HTMLImageElement>) => <img {...props} />,
+}))
+
+describe('checkbox list component', () => {
+  const options = [
+    { label: 'Option 1', value: 'option1' },
+    { label: 'Option 2', value: 'option2' },
+    { label: 'Option 3', value: 'option3' },
+    { label: 'Apple', value: 'apple' },
+  ]
+
+  it('renders with title, description and options', () => {
+    render(
+      <CheckboxList
+        title="Test Title"
+        description="Test Description"
+        options={options}
+      />,
+    )
+    expect(screen.getByText('Test Title')).toBeInTheDocument()
+    expect(screen.getByText('Test Description')).toBeInTheDocument()
+    options.forEach((option) => {
+      expect(screen.getByText(option.label)).toBeInTheDocument()
+    })
+  })
+
+  it('filters options by label', async () => {
+    render(<CheckboxList options={options} />)
+
+    const input = screen.getByRole('textbox')
+    await userEvent.type(input, 'app')
+
+    expect(screen.getByText('Apple')).toBeInTheDocument()
+    expect(screen.queryByText('Option 2')).not.toBeInTheDocument()
+    expect(screen.queryByText('Option 3')).not.toBeInTheDocument()
+  })
+
+  it('renders select-all checkbox', () => {
+    render(<CheckboxList options={options} showSelectAll />)
+    const checkboxes = screen.getByTestId('checkbox-selectAll')
+    expect(checkboxes).toBeInTheDocument()
+  })
+
+  it('selects all options when select-all is clicked', async () => {
+    const onChange = vi.fn()
+
+    render(
+      <CheckboxList
+        options={options}
+        value={[]}
+        onChange={onChange}
+        showSelectAll
+      />,
+    )
+
+    const selectAll = screen.getByTestId('checkbox-selectAll')
+    await userEvent.click(selectAll)
+
+    expect(onChange).toHaveBeenCalledWith(['option1', 'option2', 'option3', 'apple'])
+  })
+
+  it('does not select all options when select-all is clicked when disabled', async () => {
+    const onChange = vi.fn()
+
+    render(
+      <CheckboxList
+        options={options}
+        value={[]}
+        disabled
+        showSelectAll
+        onChange={onChange}
+      />,
+    )
+
+    const selectAll = screen.getByTestId('checkbox-selectAll')
+    await userEvent.click(selectAll)
+
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('deselects all options when select-all is clicked', async () => {
+    const onChange = vi.fn()
+
+    render(
+      <CheckboxList
+        options={options}
+        value={['option1', 'option2', 'option3', 'apple']}
+        onChange={onChange}
+        showSelectAll
+      />,
+    )
+
+    const selectAll = screen.getByTestId('checkbox-selectAll')
+    await userEvent.click(selectAll)
+
+    expect(onChange).toHaveBeenCalledWith([])
+  })
+
+  it('selects select-all when all options are clicked', async () => {
+    const onChange = vi.fn()
+
+    render(
+      <CheckboxList
+        options={options}
+        value={['option1', 'option2', 'option3', 'apple']}
+        onChange={onChange}
+        showSelectAll
+      />,
+    )
+
+    const selectAll = screen.getByTestId('checkbox-selectAll')
+    expect(selectAll.querySelector('[data-testid="check-icon-selectAll"]')).toBeInTheDocument()
+  })
+
+  it('hides select-all checkbox when searching', async () => {
+    render(<CheckboxList options={options} />)
+    await userEvent.type(screen.getByRole('textbox'), 'app')
+    expect(screen.queryByTestId('checkbox-selectAll')).not.toBeInTheDocument()
+  })
+
+  it('selects options when checkbox is clicked', async () => {
+    const onChange = vi.fn()
+
+    render(
+      <CheckboxList
+        options={options}
+        value={[]}
+        onChange={onChange}
+        showSelectAll={false}
+      />,
+    )
+
+    const selectOption = screen.getByTestId('checkbox-option1')
+    await userEvent.click(selectOption)
+    expect(onChange).toHaveBeenCalledWith(['option1'])
+  })
+
+  it('deselects options when checkbox is clicked when selected', async () => {
+    const onChange = vi.fn()
+
+    render(
+      <CheckboxList
+        options={options}
+        value={['option1']}
+        onChange={onChange}
+        showSelectAll={false}
+      />,
+    )
+
+    const selectOption = screen.getByTestId('checkbox-option1')
+    await userEvent.click(selectOption)
+    expect(onChange).toHaveBeenCalledWith([])
+  })
+
+  it('does not select options when checkbox is clicked', async () => {
+    const onChange = vi.fn()
+
+    render(
+      <CheckboxList
+        options={options}
+        value={[]}
+        onChange={onChange}
+        disabled
+      />,
+    )
+
+    const selectOption = screen.getByTestId('checkbox-option1')
+    await userEvent.click(selectOption)
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('Reset button works', async () => {
+    const onChange = vi.fn()
+
+    render(
+      <CheckboxList
+        options={options}
+        value={[]}
+        onChange={onChange}
+      />,
+    )
+
+    const input = screen.getByRole('textbox')
+    await userEvent.type(input, 'ban')
+    await userEvent.click(screen.getByText('common.operation.resetKeywords'))
+    expect(input).toHaveValue('')
+  })
+})

web/app/components/base/checkbox-list/index.tsx

@@ -101,12 +101,12 @@ const CheckboxList: FC<CheckboxListProps> = ({
   return (
     <div className={cn('flex w-full flex-col gap-1', containerClassName)}>
       {label && (
-        <div className="system-sm-medium text-text-secondary">
+        <div className="text-text-secondary system-sm-medium">
           {label}
         </div>
       )}
       {description && (
-        <div className="body-xs-regular text-text-tertiary">
+        <div className="text-text-tertiary body-xs-regular">
           {description}
         </div>
       )}
@@ -120,13 +120,14 @@ const CheckboxList: FC<CheckboxListProps> = ({
                 indeterminate={isIndeterminate}
                 onCheck={handleSelectAll}
                 disabled={disabled}
+                id="selectAll"
               />
             )}
             {!searchQuery
               ? (
                   <div className="flex min-w-0 flex-1 items-center gap-1">
                     {title && (
-                      <span className="system-xs-semibold-uppercase truncate leading-5 text-text-secondary">
+                      <span className="truncate leading-5 text-text-secondary system-xs-semibold-uppercase">
                         {title}
                       </span>
                     )}
@@ -138,7 +139,7 @@ const CheckboxList: FC<CheckboxListProps> = ({
                   </div>
                 )
               : (
-                  <div className="system-sm-medium-uppercase flex-1 leading-6 text-text-secondary">
+                  <div className="flex-1 leading-6 text-text-secondary system-sm-medium-uppercase">
                     {
                       filteredOptions.length > 0
                         ? t('operation.searchCount', { ns: 'common', count: filteredOptions.length, content: title })
@@ -168,7 +169,7 @@ const CheckboxList: FC<CheckboxListProps> = ({
                     ? (
                         <div className="flex flex-col items-center justify-center gap-2">
                           <Image alt="search menu" src={SearchMenu} width={32} />
-                          <span className="system-sm-regular text-text-secondary">{t('operation.noSearchResults', { ns: 'common', content: title })}</span>
+                          <span className="text-text-secondary system-sm-regular">{t('operation.noSearchResults', { ns: 'common', content: title })}</span>
                           <Button variant="secondary-accent" size="small" onClick={() => setSearchQuery('')}>{t('operation.resetKeywords', { ns: 'common' })}</Button>
                         </div>
                       )
@@ -198,9 +199,10 @@ const CheckboxList: FC<CheckboxListProps> = ({
                             handleToggleOption(option.value)
                         }}
                         disabled={option.disabled || disabled}
+                        id={option.value}
                       />
                       <div
-                        className="system-sm-medium flex-1 truncate text-text-secondary"
+                        className="flex-1 truncate text-text-secondary system-sm-medium"
                         title={option.label}
                       >
                         {option.label}

web/app/components/base/confirm/index.spec.tsx

@@ -0,0 +1,117 @@
+import { act, fireEvent, render, screen } from '@testing-library/react'
+import Confirm from '.'
+
+vi.mock('react-dom', async () => {
+  const actual = await vi.importActual<typeof import('react-dom')>('react-dom')
+
+  return {
+    ...actual,
+    createPortal: (children: React.ReactNode) => children,
+  }
+})
+
+const onCancel = vi.fn()
+const onConfirm = vi.fn()
+
+describe('Confirm Component', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('Rendering', () => {
+    it('renders confirm correctly', () => {
+      render(<Confirm isShow={true} title="test title" onCancel={onCancel} onConfirm={onConfirm} />)
+      expect(screen.getByText('test title')).toBeInTheDocument()
+    })
+
+    it('does not render on isShow false', () => {
+      const { container } = render(<Confirm isShow={false} title="test title" onCancel={onCancel} onConfirm={onConfirm} />)
+      expect(container.firstChild).toBeNull()
+    })
+
+    it('hides after delay when isShow changes to false', () => {
+      vi.useFakeTimers()
+      const { rerender } = render(<Confirm isShow={true} title="test title" onCancel={onCancel} onConfirm={onConfirm} />)
+      expect(screen.getByText('test title')).toBeInTheDocument()
+
+      rerender(<Confirm isShow={false} title="test title" onCancel={onCancel} onConfirm={onConfirm} />)
+      act(() => {
+        vi.advanceTimersByTime(200)
+      })
+      expect(screen.queryByText('test title')).not.toBeInTheDocument()
+      vi.useRealTimers()
+    })
+
+    it('renders content when provided', () => {
+      render(<Confirm isShow={true} title="title" content="some description" onCancel={onCancel} onConfirm={onConfirm} />)
+      expect(screen.getByText('some description')).toBeInTheDocument()
+    })
+  })
+
+  describe('Props', () => {
+    it('showCancel prop works', () => {
+      render(<Confirm isShow={true} title="test title" onCancel={onCancel} onConfirm={onConfirm} showCancel={false} />)
+      expect(screen.getByRole('button', { name: 'common.operation.confirm' })).toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: 'common.operation.cancel' })).not.toBeInTheDocument()
+    })
+
+    it('showConfirm prop works', () => {
+      render(<Confirm isShow={true} title="test title" onCancel={onCancel} onConfirm={onConfirm} showConfirm={false} />)
+      expect(screen.getByRole('button', { name: 'common.operation.cancel' })).toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: 'common.operation.confirm' })).not.toBeInTheDocument()
+    })
+
+    it('renders custom confirm and cancel text', () => {
+      render(<Confirm isShow={true} title="title" confirmText="Yes" cancelText="No" onCancel={onCancel} onConfirm={onConfirm} />)
+      expect(screen.getByRole('button', { name: 'Yes' })).toBeInTheDocument()
+      expect(screen.getByRole('button', { name: 'No' })).toBeInTheDocument()
+    })
+
+    it('disables confirm button when isDisabled is true', () => {
+      render(<Confirm isShow={true} title="title" isDisabled={true} onCancel={onCancel} onConfirm={onConfirm} />)
+      expect(screen.getByRole('button', { name: 'common.operation.confirm' })).toBeDisabled()
+    })
+  })
+
+  describe('User Interactions', () => {
+    it('clickAway is handled properly', () => {
+      render(<Confirm isShow={true} title="test title" onCancel={onCancel} onConfirm={onConfirm} />)
+      const overlay = screen.getByTestId('confirm-overlay') as HTMLElement
+      expect(overlay).toBeTruthy()
+      fireEvent.mouseDown(overlay)
+      expect(onCancel).toHaveBeenCalledTimes(1)
+    })
+
+    it('overlay click stops propagation', () => {
+      render(<Confirm isShow={true} title="test title" onCancel={onCancel} onConfirm={onConfirm} />)
+      const overlay = screen.getByTestId('confirm-overlay') as HTMLElement
+      const clickEvent = new MouseEvent('click', { bubbles: true, cancelable: true })
+      const preventDefaultSpy = vi.spyOn(clickEvent, 'preventDefault')
+      const stopPropagationSpy = vi.spyOn(clickEvent, 'stopPropagation')
+      overlay.dispatchEvent(clickEvent)
+      expect(preventDefaultSpy).toHaveBeenCalled()
+      expect(stopPropagationSpy).toHaveBeenCalled()
+    })
+
+    it('does not close on click away when maskClosable is false', () => {
+      render(<Confirm isShow={true} title="test title" maskClosable={false} onCancel={onCancel} onConfirm={onConfirm} />)
+      const overlay = screen.getByTestId('confirm-overlay') as HTMLElement
+      fireEvent.mouseDown(overlay)
+      expect(onCancel).not.toHaveBeenCalled()
+    })
+
+    it('escape keyboard event works', () => {
+      render(<Confirm isShow={true} title="test title" onCancel={onCancel} onConfirm={onConfirm} />)
+      fireEvent.keyDown(document, { key: 'Escape' })
+      expect(onCancel).toHaveBeenCalledTimes(1)
+      expect(onConfirm).not.toHaveBeenCalled()
+    })
+
+    it('Enter keyboard event works', () => {
+      render(<Confirm isShow={true} title="test title" onCancel={onCancel} onConfirm={onConfirm} />)
+      fireEvent.keyDown(document, { key: 'Enter' })
+      expect(onConfirm).toHaveBeenCalledTimes(1)
+      expect(onCancel).not.toHaveBeenCalled()
+    })
+  })
+})

web/app/components/base/confirm/index.tsx

@@ -101,6 +101,7 @@ function Confirm({
         e.preventDefault()
         e.stopPropagation()
       }}
+      data-testid="confirm-overlay"
     >
       <div ref={dialogRef} className="relative w-full max-w-[480px] overflow-hidden">
         <div className="shadows-shadow-lg flex max-w-full flex-col items-start rounded-2xl border-[0.5px] border-solid border-components-panel-border bg-components-panel-bg">

web/app/components/base/content-dialog/index.spec.tsx

@@ -0,0 +1,59 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import ContentDialog from './index'
+
+describe('ContentDialog', () => {
+  it('renders children when show is true', async () => {
+    render(
+      <ContentDialog show={true}>
+        <div>Dialog body</div>
+      </ContentDialog>,
+    )
+
+    await screen.findByText('Dialog body')
+    expect(screen.getByText('Dialog body')).toBeInTheDocument()
+
+    const backdrop = document.querySelector('.bg-app-detail-overlay-bg')
+    expect(backdrop).toBeTruthy()
+  })
+
+  it('does not render children when show is false', () => {
+    render(
+      <ContentDialog show={false}>
+        <div>Hidden content</div>
+      </ContentDialog>,
+    )
+
+    expect(screen.queryByText('Hidden content')).toBeNull()
+    expect(document.querySelector('.bg-app-detail-overlay-bg')).toBeNull()
+  })
+
+  it('calls onClose when backdrop is clicked', async () => {
+    const onClose = vi.fn()
+    render(
+      <ContentDialog show={true} onClose={onClose}>
+        <div>Body</div>
+      </ContentDialog>,
+    )
+
+    const user = userEvent.setup()
+    const backdrop = document.querySelector('.bg-app-detail-overlay-bg') as HTMLElement | null
+    expect(backdrop).toBeTruthy()
+
+    await user.click(backdrop!)
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('applies provided className to the content panel', () => {
+    render(
+      <ContentDialog show={true} className="my-panel-class">
+        <div>Panel content</div>
+      </ContentDialog>,
+    )
+
+    const contentPanel = document.querySelector('.bg-app-detail-bg') as HTMLElement | null
+    expect(contentPanel).toBeTruthy()
+    expect(contentPanel?.className).toContain('my-panel-class')
+    expect(screen.getByText('Panel content')).toBeInTheDocument()
+  })
+})

web/app/components/base/copy-feedback/index.spec.tsx

@@ -0,0 +1,93 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import CopyFeedback, { CopyFeedbackNew } from '.'
+
+const mockCopy = vi.fn()
+const mockReset = vi.fn()
+let mockCopied = false
+
+vi.mock('foxact/use-clipboard', () => ({
+  useClipboard: () => ({
+    copy: mockCopy,
+    reset: mockReset,
+    copied: mockCopied,
+  }),
+}))
+
+describe('CopyFeedback', () => {
+  beforeEach(() => {
+    mockCopied = false
+    vi.clearAllMocks()
+  })
+
+  describe('Rendering', () => {
+    it('renders the action button with copy icon', () => {
+      render(<CopyFeedback content="test content" />)
+      expect(screen.getByRole('button')).toBeInTheDocument()
+    })
+
+    it('renders the copied icon when copied is true', () => {
+      mockCopied = true
+      render(<CopyFeedback content="test content" />)
+      expect(screen.getByRole('button')).toBeInTheDocument()
+    })
+  })
+
+  describe('User Interactions', () => {
+    it('calls copy with content when clicked', () => {
+      render(<CopyFeedback content="test content" />)
+      const button = screen.getByRole('button')
+      fireEvent.click(button.firstChild as Element)
+      expect(mockCopy).toHaveBeenCalledWith('test content')
+    })
+
+    it('calls reset on mouse leave', () => {
+      render(<CopyFeedback content="test content" />)
+      const button = screen.getByRole('button')
+      fireEvent.mouseLeave(button.firstChild as Element)
+      expect(mockReset).toHaveBeenCalledTimes(1)
+    })
+  })
+})
+
+describe('CopyFeedbackNew', () => {
+  beforeEach(() => {
+    mockCopied = false
+    vi.clearAllMocks()
+  })
+
+  describe('Rendering', () => {
+    it('renders the component', () => {
+      const { container } = render(<CopyFeedbackNew content="test content" />)
+      expect(container.querySelector('.cursor-pointer')).toBeInTheDocument()
+    })
+
+    it('applies copied CSS class when copied is true', () => {
+      mockCopied = true
+      const { container } = render(<CopyFeedbackNew content="test content" />)
+      const feedbackIcon = container.firstChild?.firstChild as Element
+      expect(feedbackIcon).toHaveClass(/_copied_.*/)
+    })
+
+    it('does not apply copied CSS class when not copied', () => {
+      const { container } = render(<CopyFeedbackNew content="test content" />)
+      const feedbackIcon = container.firstChild?.firstChild as Element
+      expect(feedbackIcon).not.toHaveClass(/_copied_.*/)
+    })
+  })
+
+  describe('User Interactions', () => {
+    it('calls copy with content when clicked', () => {
+      const { container } = render(<CopyFeedbackNew content="test content" />)
+      const clickableArea = container.querySelector('.cursor-pointer')!.firstChild as HTMLElement
+      fireEvent.click(clickableArea)
+      expect(mockCopy).toHaveBeenCalledWith('test content')
+    })
+
+    it('calls reset on mouse leave', () => {
+      const { container } = render(<CopyFeedbackNew content="test content" />)
+      const clickableArea = container.querySelector('.cursor-pointer')!.firstChild as HTMLElement
+      fireEvent.mouseLeave(clickableArea)
+      expect(mockReset).toHaveBeenCalledTimes(1)
+    })
+  })
+})

web/app/components/base/dialog/index.spec.tsx

@@ -0,0 +1,138 @@
+import { act, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import CustomDialog from './index'
+
+describe('CustomDialog Component', () => {
+  const setup = () => userEvent.setup()
+
+  it('should render children and title when show is true', async () => {
+    render(
+      <CustomDialog show={true} title="Modal Title">
+        <div data-testid="dialog-content">Main Content</div>
+      </CustomDialog>,
+    )
+
+    const title = await screen.findByText('Modal Title')
+    const content = screen.getByTestId('dialog-content')
+
+    expect(title).toBeInTheDocument()
+    expect(content).toBeInTheDocument()
+    expect(screen.getByRole('dialog')).toBeInTheDocument()
+  })
+
+  it('should not render anything when show is false', async () => {
+    render(
+      <CustomDialog show={false} title="Hidden Title">
+        <div>Content</div>
+      </CustomDialog>,
+    )
+
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+    expect(screen.queryByText('Hidden Title')).not.toBeInTheDocument()
+  })
+
+  it('should apply the correct semantic tag to title using titleAs', async () => {
+    render(
+      <CustomDialog show={true} title="Semantic Title" titleAs="h1">
+        Content
+      </CustomDialog>,
+    )
+
+    const title = await screen.findByRole('heading', { level: 1 })
+    expect(title).toHaveTextContent('Semantic Title')
+  })
+
+  it('should render the footer only when the prop is provided', async () => {
+    const { rerender } = render(
+      <CustomDialog show={true}>Content</CustomDialog>,
+    )
+
+    await screen.findByRole('dialog')
+    expect(screen.queryByText('Footer Content')).not.toBeInTheDocument()
+
+    rerender(
+      <CustomDialog show={true} footer={<div data-testid="footer-node">Footer Content</div>}>
+        Content
+      </CustomDialog>,
+    )
+
+    expect(await screen.findByTestId('footer-node')).toBeInTheDocument()
+  })
+
+  it('should call onClose when Escape key is pressed', async () => {
+    const user = setup()
+    const onCloseMock = vi.fn()
+
+    render(
+      <CustomDialog show={true} onClose={onCloseMock}>
+        Content
+      </CustomDialog>,
+    )
+
+    await screen.findByRole('dialog')
+
+    await act(async () => {
+      await user.keyboard('{Escape}')
+    })
+
+    expect(onCloseMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('should call onClose when the backdrop is clicked', async () => {
+    const user = setup()
+    const onCloseMock = vi.fn()
+
+    render(
+      <CustomDialog show={true} onClose={onCloseMock}>
+        Content
+      </CustomDialog>,
+    )
+
+    await screen.findByRole('dialog')
+
+    const backdrop = document.querySelector('.bg-background-overlay-backdrop')
+    expect(backdrop).toBeInTheDocument()
+
+    await act(async () => {
+      await user.click(backdrop!)
+    })
+
+    expect(onCloseMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('should apply custom class names to internal elements', async () => {
+    render(
+      <CustomDialog
+        show={true}
+        title="Title"
+        className="custom-panel-container"
+        titleClassName="custom-title-style"
+        bodyClassName="custom-body-style"
+        footer="Footer"
+        footerClassName="custom-footer-style"
+      >
+        <div data-testid="content">Content</div>
+      </CustomDialog>,
+    )
+
+    await screen.findByRole('dialog')
+
+    expect(document.querySelector('.custom-panel-container')).toBeInTheDocument()
+    expect(document.querySelector('.custom-title-style')).toBeInTheDocument()
+    expect(document.querySelector('.custom-body-style')).toBeInTheDocument()
+    expect(document.querySelector('.custom-footer-style')).toBeInTheDocument()
+  })
+
+  it('should maintain accessibility attributes (aria-modal)', async () => {
+    render(
+      <CustomDialog show={true} title="Accessibility Test">
+        <button>Focusable Item</button>
+      </CustomDialog>,
+    )
+
+    const dialog = await screen.findByRole('dialog')
+    // Headless UI should automatically set aria-modal="true"
+    expect(dialog).toHaveAttribute('aria-modal', 'true')
+  })
+})

web/app/components/base/emoji-picker/Inner.spec.tsx

@@ -0,0 +1,169 @@
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import EmojiPickerInner from './Inner'
+
+vi.mock('@emoji-mart/data', () => ({
+  default: {
+    categories: [
+      {
+        id: 'nature',
+        emojis: ['rabbit', 'bear'],
+      },
+      {
+        id: 'food',
+        emojis: ['apple', 'orange'],
+      },
+    ],
+  },
+}))
+
+vi.mock('emoji-mart', () => ({
+  init: vi.fn(),
+}))
+
+vi.mock('@/utils/emoji', () => ({
+  searchEmoji: vi.fn().mockResolvedValue(['dog', 'cat']),
+}))
+
+describe('EmojiPickerInner', () => {
+  const mockOnSelect = vi.fn()
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    // Define the custom element to avoid "Unknown custom element" warnings
+    if (!customElements.get('em-emoji')) {
+      customElements.define('em-emoji', class extends HTMLElement {
+        static get observedAttributes() { return ['id'] }
+      })
+    }
+  })
+
+  describe('Rendering', () => {
+    it('renders initial categories and emojis correctly', () => {
+      render(<EmojiPickerInner onSelect={mockOnSelect} />)
+
+      expect(screen.getByText('nature')).toBeInTheDocument()
+      expect(screen.getByText('food')).toBeInTheDocument()
+      expect(screen.getByPlaceholderText('Search emojis...')).toBeInTheDocument()
+    })
+  })
+
+  describe('User Interactions', () => {
+    it('calls searchEmoji and displays results when typing in search input', async () => {
+      render(<EmojiPickerInner onSelect={mockOnSelect} />)
+      const searchInput = screen.getByPlaceholderText('Search emojis...')
+
+      await act(async () => {
+        fireEvent.change(searchInput, { target: { value: 'anim' } })
+      })
+
+      await waitFor(() => {
+        expect(screen.getByText('Search')).toBeInTheDocument()
+      })
+
+      const searchSection = screen.getByText('Search').parentElement
+      expect(searchSection?.querySelectorAll('em-emoji').length).toBe(2)
+    })
+
+    it('updates selected emoji and calls onSelect when an emoji is clicked', async () => {
+      render(<EmojiPickerInner onSelect={mockOnSelect} />)
+      const emojiContainers = screen.getAllByTestId(/^emoji-container-/)
+
+      await act(async () => {
+        fireEvent.click(emojiContainers[0])
+      })
+
+      expect(mockOnSelect).toHaveBeenCalledWith('rabbit', expect.any(String))
+    })
+
+    it('toggles style colors display when clicking the chevron', async () => {
+      render(<EmojiPickerInner onSelect={mockOnSelect} />)
+
+      expect(screen.queryByText('#FFEAD5')).not.toBeInTheDocument()
+
+      const toggleButton = screen.getByTestId('toggle-colors')
+      expect(toggleButton).toBeInTheDocument()
+
+      await act(async () => {
+        fireEvent.click(toggleButton!)
+      })
+
+      expect(screen.getByText('Choose Style')).toBeInTheDocument()
+      const colorOptions = document.querySelectorAll('[style^="background:"]')
+      expect(colorOptions.length).toBeGreaterThan(0)
+    })
+
+    it('updates background color and calls onSelect when a color is clicked', async () => {
+      render(<EmojiPickerInner onSelect={mockOnSelect} />)
+
+      const toggleButton = screen.getByTestId('toggle-colors')
+      await act(async () => {
+        fireEvent.click(toggleButton!)
+      })
+
+      const emojiContainers = screen.getAllByTestId(/^emoji-container-/)
+      await act(async () => {
+        fireEvent.click(emojiContainers[0])
+      })
+
+      mockOnSelect.mockClear()
+
+      const colorOptions = document.querySelectorAll('[style^="background:"]')
+      await act(async () => {
+        fireEvent.click(colorOptions[1].parentElement!)
+      })
+
+      expect(mockOnSelect).toHaveBeenCalledWith('rabbit', '#E4FBCC')
+    })
+
+    it('updates selected emoji when clicking a search result', async () => {
+      render(<EmojiPickerInner onSelect={mockOnSelect} />)
+      const searchInput = screen.getByPlaceholderText('Search emojis...')
+
+      await act(async () => {
+        fireEvent.change(searchInput, { target: { value: 'anim' } })
+      })
+
+      await screen.findByText('Search')
+
+      const searchEmojis = screen.getAllByTestId(/^emoji-search-result-/)
+      await act(async () => {
+        fireEvent.click(searchEmojis![0])
+      })
+
+      expect(mockOnSelect).toHaveBeenCalledWith('dog', expect.any(String))
+    })
+
+    it('toggles style colors display back and forth', async () => {
+      render(<EmojiPickerInner onSelect={mockOnSelect} />)
+
+      const toggleButton = screen.getByTestId('toggle-colors')
+
+      await act(async () => {
+        fireEvent.click(toggleButton!)
+      })
+      expect(screen.getByText('Choose Style')).toBeInTheDocument()
+
+      await act(async () => {
+        fireEvent.click(screen.getByTestId('toggle-colors')!) // It should be the other icon now
+      })
+      expect(screen.queryByText('#FFEAD5')).not.toBeInTheDocument()
+    })
+
+    it('clears search results when input is cleared', async () => {
+      render(<EmojiPickerInner onSelect={mockOnSelect} />)
+      const searchInput = screen.getByPlaceholderText('Search emojis...')
+
+      await act(async () => {
+        fireEvent.change(searchInput, { target: { value: 'anim' } })
+      })
+
+      await screen.findByText('Search')
+
+      await act(async () => {
+        fireEvent.change(searchInput, { target: { value: '' } })
+      })
+
+      expect(screen.queryByText('Search')).not.toBeInTheDocument()
+    })
+  })
+})

web/app/components/base/emoji-picker/Inner.tsx

@@ -3,8 +3,6 @@ import type { EmojiMartData } from '@emoji-mart/data'
 import type { ChangeEvent, FC } from 'react'
 import data from '@emoji-mart/data'
 import {
-  ChevronDownIcon,
-  ChevronUpIcon,
   MagnifyingGlassIcon,
 } from '@heroicons/react/24/outline'
 import { init } from 'emoji-mart'
@@ -97,7 +95,7 @@ const EmojiPickerInner: FC<IEmojiPickerInnerProps> = ({
         {isSearching && (
           <>
             <div key="category-search" className="flex flex-col">
-              <p className="system-xs-medium-uppercase mb-1 text-text-primary">Search</p>
+              <p className="mb-1 text-text-primary system-xs-medium-uppercase">Search</p>
               <div className="grid h-full w-full grid-cols-8 gap-1">
                 {searchedEmojis.map((emoji: string, index: number) => {
                   return (
@@ -108,7 +106,7 @@ const EmojiPickerInner: FC<IEmojiPickerInnerProps> = ({
                         setSelectedEmoji(emoji)
                       }}
                     >
-                      <div className="flex h-8 w-8 cursor-pointer items-center justify-center rounded-lg p-1 ring-components-input-border-hover ring-offset-1 hover:ring-1">
+                      <div className="flex h-8 w-8 cursor-pointer items-center justify-center rounded-lg p-1 ring-components-input-border-hover ring-offset-1 hover:ring-1" data-testid={`emoji-search-result-${emoji}`}>
                         <em-emoji id={emoji} />
                       </div>
                     </div>
@@ -122,7 +120,7 @@ const EmojiPickerInner: FC<IEmojiPickerInnerProps> = ({
         {categories.map((category, index: number) => {
           return (
             <div key={`category-${index}`} className="flex flex-col">
-              <p className="system-xs-medium-uppercase mb-1 text-text-primary">{category.id}</p>
+              <p className="mb-1 text-text-primary system-xs-medium-uppercase">{category.id}</p>
               <div className="grid h-full w-full grid-cols-8 gap-1">
                 {category.emojis.map((emoji, index: number) => {
                   return (
@@ -133,7 +131,7 @@ const EmojiPickerInner: FC<IEmojiPickerInnerProps> = ({
                         setSelectedEmoji(emoji)
                       }}
                     >
-                      <div className="flex h-8 w-8 cursor-pointer items-center justify-center rounded-lg p-1 ring-components-input-border-hover ring-offset-1 hover:ring-1">
+                      <div className="flex h-8 w-8 cursor-pointer items-center justify-center rounded-lg p-1 ring-components-input-border-hover ring-offset-1 hover:ring-1" data-testid={`emoji-container-${emoji}`}>
                         <em-emoji id={emoji} />
                       </div>
                     </div>
@@ -148,10 +146,10 @@ const EmojiPickerInner: FC<IEmojiPickerInnerProps> = ({
 
       {/* Color Select */}
       <div className={cn('flex items-center justify-between p-3 pb-0')}>
-        <p className="system-xs-medium-uppercase mb-2 text-text-primary">Choose Style</p>
+        <p className="mb-2 text-text-primary system-xs-medium-uppercase">Choose Style</p>
         {showStyleColors
-          ? <ChevronDownIcon className="h-4 w-4 cursor-pointer text-text-quaternary" onClick={() => setShowStyleColors(!showStyleColors)} />
-          : <ChevronUpIcon className="h-4 w-4 cursor-pointer text-text-quaternary" onClick={() => setShowStyleColors(!showStyleColors)} />}
+          ? <span className="i-heroicons-chevron-down h-4 w-4 cursor-pointer text-text-quaternary" onClick={() => setShowStyleColors(!showStyleColors)} data-testid="toggle-colors" />
+          : <span className="i-heroicons-chevron-up h-4 w-4 cursor-pointer text-text-quaternary" onClick={() => setShowStyleColors(!showStyleColors)} data-testid="toggle-colors" />}
       </div>
       {showStyleColors && (
         <div className="grid w-full grid-cols-8 gap-1 px-3">

web/app/components/base/emoji-picker/index.spec.tsx

@@ -0,0 +1,115 @@
+import { act, fireEvent, render, screen } from '@testing-library/react'
+import EmojiPicker from './index'
+
+vi.mock('@emoji-mart/data', () => ({
+  default: {
+    categories: [
+      {
+        id: 'category1',
+        name: 'Category 1',
+        emojis: ['emoji1', 'emoji2'],
+      },
+    ],
+  },
+}))
+
+vi.mock('emoji-mart', () => ({
+  init: vi.fn(),
+  SearchIndex: {
+    search: vi.fn().mockResolvedValue([{ skins: [{ native: '🔍' }] }]),
+  },
+}))
+
+vi.mock('@/utils/emoji', () => ({
+  searchEmoji: vi.fn().mockResolvedValue(['🔍']),
+}))
+
+describe('EmojiPicker', () => {
+  const mockOnSelect = vi.fn()
+  const mockOnClose = vi.fn()
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('Rendering', () => {
+    it('renders nothing when isModal is false', () => {
+      const { container } = render(
+        <EmojiPicker isModal={false} />,
+      )
+      expect(container.firstChild).toBeNull()
+    })
+
+    it('renders modal when isModal is true', async () => {
+      await act(async () => {
+        render(
+          <EmojiPicker isModal={true} />,
+        )
+      })
+      expect(screen.getByPlaceholderText('Search emojis...')).toBeInTheDocument()
+      expect(screen.getByText(/Cancel/i)).toBeInTheDocument()
+      expect(screen.getByText(/OK/i)).toBeInTheDocument()
+    })
+
+    it('OK button is disabled initially', async () => {
+      await act(async () => {
+        render(
+          <EmojiPicker />,
+        )
+      })
+      const okButton = screen.getByText(/OK/i).closest('button')
+      expect(okButton).toBeDisabled()
+    })
+
+    it('applies custom className to modal wrapper', async () => {
+      const customClass = 'custom-wrapper-class'
+      await act(async () => {
+        render(
+          <EmojiPicker className={customClass} />,
+        )
+      })
+      const dialog = screen.getByRole('dialog')
+      expect(dialog).toHaveClass(customClass)
+    })
+  })
+
+  describe('User Interactions', () => {
+    it('calls onSelect with selected emoji and background when OK is clicked', async () => {
+      await act(async () => {
+        render(
+          <EmojiPicker onSelect={mockOnSelect} />,
+        )
+      })
+
+      const emojiWrappers = screen.getAllByTestId(/^emoji-container-/)
+      expect(emojiWrappers.length).toBeGreaterThan(0)
+      await act(async () => {
+        fireEvent.click(emojiWrappers[0])
+      })
+
+      const okButton = screen.getByText(/OK/i)
+      expect(okButton.closest('button')).not.toBeDisabled()
+
+      await act(async () => {
+        fireEvent.click(okButton)
+      })
+
+      expect(mockOnSelect).toHaveBeenCalledWith(expect.any(String), expect.any(String))
+    })
+
+    it('calls onClose when Cancel is clicked', async () => {
+      await act(async () => {
+        render(
+          <EmojiPicker onClose={mockOnClose} />,
+        )
+      })
+
+      const cancelButton = screen.getByText(/Cancel/i)
+      await act(async () => {
+        fireEvent.click(cancelButton)
+      })
+
+      expect(mockOnClose).toHaveBeenCalled()
+    })
+  })
+})

web/app/components/base/file-thumb/image-render.spec.tsx

@@ -0,0 +1,20 @@
+import { render, screen } from '@testing-library/react'
+import ImageRender from './image-render'
+
+describe('ImageRender Component', () => {
+  const mockProps = {
+    sourceUrl: 'https://example.com/image.jpg',
+    name: 'test-image.jpg',
+  }
+
+  describe('Render', () => {
+    it('renders image with correct src and alt', () => {
+      render(<ImageRender {...mockProps} />)
+
+      const img = screen.getByRole('img')
+      expect(img).toBeInTheDocument()
+      expect(img).toHaveAttribute('src', mockProps.sourceUrl)
+      expect(img).toHaveAttribute('alt', mockProps.name)
+    })
+  })
+})

web/app/components/base/file-thumb/index.spec.tsx

@@ -0,0 +1,74 @@
+/* eslint-disable next/no-img-element */
+import type { ImgHTMLAttributes } from 'react'
+import { fireEvent, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import FileThumb from './index'
+
+vi.mock('next/image', () => ({
+  __esModule: true,
+  default: (props: ImgHTMLAttributes<HTMLImageElement>) => <img {...props} />,
+}))
+
+describe('FileThumb Component', () => {
+  const mockImageFile = {
+    name: 'test-image.jpg',
+    mimeType: 'image/jpeg',
+    extension: '.jpg',
+    size: 1024,
+    sourceUrl: 'https://example.com/test-image.jpg',
+  }
+
+  const mockNonImageFile = {
+    name: 'test.pdf',
+    mimeType: 'application/pdf',
+    extension: '.pdf',
+    size: 2048,
+    sourceUrl: 'https://example.com/test.pdf',
+  }
+
+  describe('Render', () => {
+    it('renders image thumbnail correctly', () => {
+      render(<FileThumb file={mockImageFile} />)
+
+      const img = screen.getByAltText(mockImageFile.name)
+      expect(img).toBeInTheDocument()
+      expect(img).toHaveAttribute('src', mockImageFile.sourceUrl)
+    })
+
+    it('renders file type icon for non-image files', () => {
+      const { container } = render(<FileThumb file={mockNonImageFile} />)
+
+      expect(screen.queryByAltText(mockNonImageFile.name)).not.toBeInTheDocument()
+      const svgIcon = container.querySelector('svg')
+      expect(svgIcon).toBeInTheDocument()
+    })
+
+    it('wraps content inside tooltip', async () => {
+      const user = userEvent.setup()
+      render(<FileThumb file={mockImageFile} />)
+
+      const trigger = screen.getByAltText(mockImageFile.name)
+      expect(trigger).toBeInTheDocument()
+
+      await user.hover(trigger)
+
+      const tooltipContent = await screen.findByText(mockImageFile.name)
+      expect(tooltipContent).toBeInTheDocument()
+    })
+  })
+
+  describe('Interaction', () => {
+    it('calls onClick with file when clicked', () => {
+      const onClick = vi.fn()
+
+      render(<FileThumb file={mockImageFile} onClick={onClick} />)
+
+      const clickable = screen.getByAltText(mockImageFile.name).closest('div') as HTMLElement
+
+      fireEvent.click(clickable)
+
+      expect(onClick).toHaveBeenCalledTimes(1)
+      expect(onClick).toHaveBeenCalledWith(mockImageFile)
+    })
+  })
+})

web/app/components/base/file-uploader/store.tsx

@@ -1,11 +1,9 @@
 import type {
   FileEntity,
 } from './types'
-import { isEqual } from 'es-toolkit/predicate'
 import {
   createContext,
   useContext,
-  useEffect,
   useRef,
 } from 'react'
 import {
@@ -57,20 +55,10 @@ export const FileContextProvider = ({
   onChange,
 }: FileProviderProps) => {
   const storeRef = useRef<FileStore | undefined>(undefined)
+
   if (!storeRef.current)
     storeRef.current = createFileStore(value, onChange)
 
-  useEffect(() => {
-    if (!storeRef.current)
-      return
-    if (isEqual(value, storeRef.current.getState().files))
-      return
-
-    storeRef.current.setState({
-      files: value ? [...value] : [],
-    })
-  }, [value])
-
   return (
     <FileContext.Provider value={storeRef.current}>
       {children}

web/app/components/base/fullscreen-modal/index.spec.tsx

@@ -0,0 +1,214 @@
+import { act, fireEvent, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import FullScreenModal from './index'
+
+describe('FullScreenModal Component', () => {
+  it('should not render anything when open is false', () => {
+    render(
+      <FullScreenModal open={false}>
+        <div data-testid="modal-content">Content</div>
+      </FullScreenModal>,
+    )
+    expect(screen.queryByTestId('modal-content')).not.toBeInTheDocument()
+  })
+
+  it('should render content when open is true', async () => {
+    render(
+      <FullScreenModal open={true}>
+        <div data-testid="modal-content">Content</div>
+      </FullScreenModal>,
+    )
+    expect(await screen.findByTestId('modal-content')).toBeInTheDocument()
+  })
+
+  it('should not crash when provided with title and description props', async () => {
+    await act(async () => {
+      render(
+        <FullScreenModal
+          open={true}
+          title="My Title"
+          description="My Description"
+        >
+          Content
+        </FullScreenModal>,
+      )
+    })
+  })
+
+  describe('Props Handling', () => {
+    it('should apply wrapperClassName to the dialog root', async () => {
+      render(
+        <FullScreenModal
+          open={true}
+          wrapperClassName="custom-wrapper-class"
+        >
+          Content
+        </FullScreenModal>,
+      )
+
+      await screen.findByRole('dialog')
+      const element = document.querySelector('.custom-wrapper-class')
+      expect(element).toBeInTheDocument()
+      expect(element).toHaveClass('modal-dialog')
+    })
+
+    it('should apply className to the inner panel', async () => {
+      await act(async () => {
+        render(
+          <FullScreenModal
+            open={true}
+            className="custom-panel-class"
+          >
+            Content
+          </FullScreenModal>,
+        )
+      })
+      const panel = document.querySelector('.custom-panel-class')
+      expect(panel).toBeInTheDocument()
+      expect(panel).toHaveClass('h-full')
+    })
+
+    it('should handle overflowVisible prop', async () => {
+      const { rerender } = await act(async () => {
+        return render(
+          <FullScreenModal
+            open={true}
+            overflowVisible={true}
+            className="target-panel"
+          >
+            Content
+          </FullScreenModal>,
+        )
+      })
+      let panel = document.querySelector('.target-panel')
+      expect(panel).toHaveClass('overflow-visible')
+      expect(panel).not.toHaveClass('overflow-hidden')
+
+      await act(async () => {
+        rerender(
+          <FullScreenModal
+            open={true}
+            overflowVisible={false}
+            className="target-panel"
+          >
+            Content
+          </FullScreenModal>,
+        )
+      })
+      panel = document.querySelector('.target-panel')
+      expect(panel).toHaveClass('overflow-hidden')
+      expect(panel).not.toHaveClass('overflow-visible')
+    })
+
+    it('should render close button when closable is true', async () => {
+      await act(async () => {
+        render(
+          <FullScreenModal open={true} closable={true}>
+            Content
+          </FullScreenModal>,
+        )
+      })
+      const closeButton = document.querySelector('.bg-components-button-tertiary-bg')
+      expect(closeButton).toBeInTheDocument()
+    })
+
+    it('should not render close button when closable is false', async () => {
+      await act(async () => {
+        render(
+          <FullScreenModal open={true} closable={false}>
+            Content
+          </FullScreenModal>,
+        )
+      })
+      const closeButton = document.querySelector('.bg-components-button-tertiary-bg')
+      expect(closeButton).not.toBeInTheDocument()
+    })
+  })
+
+  describe('Interactions', () => {
+    it('should call onClose when close button is clicked', async () => {
+      const user = userEvent.setup()
+      const onClose = vi.fn()
+
+      render(
+        <FullScreenModal open={true} closable={true} onClose={onClose}>
+          Content
+        </FullScreenModal>,
+      )
+
+      const closeBtn = document.querySelector('.bg-components-button-tertiary-bg')
+      expect(closeBtn).toBeInTheDocument()
+
+      await user.click(closeBtn!)
+      expect(onClose).toHaveBeenCalledTimes(1)
+    })
+
+    it('should call onClose when clicking the backdrop', async () => {
+      const user = userEvent.setup()
+      const onClose = vi.fn()
+
+      render(
+        <FullScreenModal open={true} onClose={onClose}>
+          <div data-testid="inner">Content</div>
+        </FullScreenModal>,
+      )
+
+      const dialog = document.querySelector('.modal-dialog')
+      if (dialog) {
+        await user.click(dialog)
+        expect(onClose).toHaveBeenCalled()
+      }
+      else {
+        throw new Error('Dialog root not found')
+      }
+    })
+
+    it('should call onClose when Escape key is pressed', async () => {
+      const user = userEvent.setup()
+      const onClose = vi.fn()
+
+      render(
+        <FullScreenModal open={true} onClose={onClose}>
+          Content
+        </FullScreenModal>,
+      )
+
+      await user.keyboard('{Escape}')
+      expect(onClose).toHaveBeenCalled()
+    })
+
+    it('should not call onClose when clicking inside the content', async () => {
+      const user = userEvent.setup()
+      const onClose = vi.fn()
+
+      render(
+        <FullScreenModal open={true} onClose={onClose}>
+          <div className="bg-background-default-subtle">
+            <button>Action</button>
+          </div>
+        </FullScreenModal>,
+      )
+
+      const innerButton = screen.getByRole('button', { name: 'Action' })
+      await user.click(innerButton)
+      expect(onClose).not.toHaveBeenCalled()
+
+      const contentPanel = document.querySelector('.bg-background-default-subtle')
+      await act(async () => {
+        fireEvent.click(contentPanel!)
+      })
+      expect(onClose).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('Default Props', () => {
+    it('should not throw if onClose is not provided', async () => {
+      const user = userEvent.setup()
+      render(<FullScreenModal open={true} closable={true}>Content</FullScreenModal>)
+
+      const closeButton = document.querySelector('.bg-components-button-tertiary-bg')
+      await user.click(closeButton!)
+    })
+  })
+})

web/app/components/base/linked-apps-panel/index.spec.tsx

@@ -0,0 +1,93 @@
+import { render, screen } from '@testing-library/react'
+import * as React from 'react'
+import { vi } from 'vitest'
+import { AppModeEnum } from '@/types/app'
+import LinkedAppsPanel from './index'
+
+vi.mock('next/link', () => ({
+  default: ({ children, href, className }: { children: React.ReactNode, href: string, className: string }) => (
+    <a href={href} className={className} data-testid="link-item">
+      {children}
+    </a>
+  ),
+}))
+
+describe('LinkedAppsPanel Component', () => {
+  const mockRelatedApps = [
+    {
+      id: 'app-1',
+      name: 'Chatbot App',
+      mode: AppModeEnum.CHAT,
+      icon_type: 'emoji' as const,
+      icon: '🤖',
+      icon_background: '#FFEAD5',
+      icon_url: '',
+    },
+    {
+      id: 'app-2',
+      name: 'Workflow App',
+      mode: AppModeEnum.WORKFLOW,
+      icon_type: 'image' as const,
+      icon: 'file-id',
+      icon_background: '#E4FBCC',
+      icon_url: 'https://example.com/icon.png',
+    },
+    {
+      id: 'app-3',
+      name: '',
+      mode: AppModeEnum.AGENT_CHAT,
+      icon_type: 'emoji' as const,
+      icon: '🕵️',
+      icon_background: '#D3F8DF',
+      icon_url: '',
+    },
+  ]
+
+  describe('Render', () => {
+    it('renders correctly with multiple apps', () => {
+      render(<LinkedAppsPanel relatedApps={mockRelatedApps} isMobile={false} />)
+
+      const items = screen.getAllByTestId('link-item')
+      expect(items).toHaveLength(3)
+
+      expect(screen.getByText('Chatbot App')).toBeInTheDocument()
+      expect(screen.getByText('Workflow App')).toBeInTheDocument()
+      expect(screen.getByText('--')).toBeInTheDocument()
+    })
+
+    it('displays correct app mode labels', () => {
+      render(<LinkedAppsPanel relatedApps={mockRelatedApps} isMobile={false} />)
+
+      expect(screen.getByText('Chatbot')).toBeInTheDocument()
+      expect(screen.getByText('Workflow')).toBeInTheDocument()
+      expect(screen.getByText('Agent')).toBeInTheDocument()
+    })
+
+    it('hides app name and centers content in mobile mode', () => {
+      render(<LinkedAppsPanel relatedApps={mockRelatedApps} isMobile={true} />)
+
+      expect(screen.queryByText('Chatbot App')).not.toBeInTheDocument()
+      expect(screen.queryByText('Workflow App')).not.toBeInTheDocument()
+
+      const items = screen.getAllByTestId('link-item')
+      expect(items[0]).toHaveClass('justify-center')
+    })
+
+    it('handles empty relatedApps list gracefully', () => {
+      const { container } = render(<LinkedAppsPanel relatedApps={[]} isMobile={false} />)
+      const items = screen.queryAllByTestId('link-item')
+      expect(items).toHaveLength(0)
+      expect(container.firstChild).toBeInTheDocument()
+    })
+  })
+
+  describe('Interaction', () => {
+    it('renders correct links for each app', () => {
+      render(<LinkedAppsPanel relatedApps={mockRelatedApps} isMobile={false} />)
+
+      const items = screen.getAllByTestId('link-item')
+      expect(items[0]).toHaveAttribute('href', '/app/app-1/overview')
+      expect(items[1]).toHaveAttribute('href', '/app/app-2/overview')
+    })
+  })
+})

web/app/components/base/list-empty/horizontal-line.spec.tsx

@@ -0,0 +1,33 @@
+import { render } from '@testing-library/react'
+import * as React from 'react'
+import HorizontalLine from './horizontal-line'
+
+describe('HorizontalLine', () => {
+  describe('Render', () => {
+    it('renders correctly', () => {
+      const { container } = render(<HorizontalLine />)
+      const svg = container.querySelector('svg')
+      expect(svg).toBeInTheDocument()
+      expect(svg).toHaveAttribute('width', '240')
+      expect(svg).toHaveAttribute('height', '2')
+    })
+
+    it('renders linear gradient definition', () => {
+      const { container } = render(<HorizontalLine />)
+      const defs = container.querySelector('defs')
+      const linearGradient = container.querySelector('linearGradient')
+      expect(defs).toBeInTheDocument()
+      expect(linearGradient).toBeInTheDocument()
+      expect(linearGradient).toHaveAttribute('id', 'paint0_linear_8619_59125')
+    })
+  })
+
+  describe('Style', () => {
+    it('applies custom className', () => {
+      const testClass = 'custom-test-class'
+      const { container } = render(<HorizontalLine className={testClass} />)
+      const svg = container.querySelector('svg')
+      expect(svg).toHaveClass(testClass)
+    })
+  })
+})

web/app/components/base/list-empty/index.spec.tsx

@@ -0,0 +1,37 @@
+import { render, screen } from '@testing-library/react'
+import * as React from 'react'
+import ListEmpty from './index'
+
+describe('ListEmpty Component', () => {
+  describe('Render', () => {
+    it('renders default icon when no icon is provided', () => {
+      const { container } = render(<ListEmpty />)
+      expect(container.querySelector('[data-icon="Variable02"]')).toBeInTheDocument()
+    })
+
+    it('renders custom icon when provided', () => {
+      const { container } = render(<ListEmpty icon={<div data-testid="custom-icon" />} />)
+      expect(container.querySelector('[data-icon="Variable02"]')).not.toBeInTheDocument()
+      expect(screen.getByTestId('custom-icon')).toBeInTheDocument()
+    })
+
+    it('renders design lines', () => {
+      const { container } = render(<ListEmpty />)
+      const svgs = container.querySelectorAll('svg')
+      expect(svgs).toHaveLength(5)
+    })
+  })
+
+  describe('Props', () => {
+    it('renders title and description correctly', () => {
+      const testTitle = 'Empty List'
+      const testDescription = <span data-testid="desc">No items found</span>
+
+      render(<ListEmpty title={testTitle} description={testDescription} />)
+
+      expect(screen.getByText(testTitle)).toBeInTheDocument()
+      expect(screen.getByTestId('desc')).toBeInTheDocument()
+      expect(screen.getByText('No items found')).toBeInTheDocument()
+    })
+  })
+})

web/app/components/base/list-empty/vertical-line.spec.tsx

@@ -0,0 +1,33 @@
+import { render } from '@testing-library/react'
+import * as React from 'react'
+import VerticalLine from './vertical-line'
+
+describe('VerticalLine', () => {
+  describe('Render', () => {
+    it('renders correctly', () => {
+      const { container } = render(<VerticalLine />)
+      const svg = container.querySelector('svg')
+      expect(svg).toBeInTheDocument()
+      expect(svg).toHaveAttribute('width', '2')
+      expect(svg).toHaveAttribute('height', '132')
+    })
+
+    it('renders linear gradient definition', () => {
+      const { container } = render(<VerticalLine />)
+      const defs = container.querySelector('defs')
+      const linearGradient = container.querySelector('linearGradient')
+      expect(defs).toBeInTheDocument()
+      expect(linearGradient).toBeInTheDocument()
+      expect(linearGradient).toHaveAttribute('id', 'paint0_linear_8619_59128')
+    })
+  })
+
+  describe('Style', () => {
+    it('applies custom className', () => {
+      const testClass = 'custom-test-class'
+      const { container } = render(<VerticalLine className={testClass} />)
+      const svg = container.querySelector('svg')
+      expect(svg).toHaveClass(testClass)
+    })
+  })
+})

web/app/components/base/logo/dify-logo.spec.tsx

@@ -0,0 +1,94 @@
+import { render, screen } from '@testing-library/react'
+import useTheme from '@/hooks/use-theme'
+import { Theme } from '@/types/app'
+import DifyLogo from './dify-logo'
+
+vi.mock('@/hooks/use-theme', () => ({
+  default: vi.fn(),
+}))
+
+vi.mock('@/utils/var', () => ({
+  basePath: '/test-base-path',
+}))
+
+describe('DifyLogo', () => {
+  const mockUseTheme = {
+    theme: Theme.light,
+    themes: ['light', 'dark'],
+    setTheme: vi.fn(),
+    resolvedTheme: Theme.light,
+    systemTheme: Theme.light,
+    forcedTheme: undefined,
+  }
+
+  beforeEach(() => {
+    vi.mocked(useTheme).mockReturnValue(mockUseTheme as ReturnType<typeof useTheme>)
+  })
+
+  describe('Render', () => {
+    it('renders correctly with default props', () => {
+      render(<DifyLogo />)
+      const img = screen.getByRole('img', { name: /dify logo/i })
+      expect(img).toBeInTheDocument()
+      expect(img).toHaveAttribute('src', '/test-base-path/logo/logo.svg')
+    })
+  })
+
+  describe('Props', () => {
+    it('applies custom size correctly', () => {
+      const { rerender } = render(<DifyLogo size="large" />)
+      let img = screen.getByRole('img', { name: /dify logo/i })
+      expect(img).toHaveClass('w-16')
+      expect(img).toHaveClass('h-7')
+
+      rerender(<DifyLogo size="small" />)
+      img = screen.getByRole('img', { name: /dify logo/i })
+      expect(img).toHaveClass('w-9')
+      expect(img).toHaveClass('h-4')
+    })
+
+    it('applies custom style correctly', () => {
+      render(<DifyLogo style="monochromeWhite" />)
+      const img = screen.getByRole('img', { name: /dify logo/i })
+      expect(img).toHaveAttribute('src', '/test-base-path/logo/logo-monochrome-white.svg')
+    })
+
+    it('applies custom className', () => {
+      render(<DifyLogo className="custom-test-class" />)
+      const img = screen.getByRole('img', { name: /dify logo/i })
+      expect(img).toHaveClass('custom-test-class')
+    })
+  })
+
+  describe('Theme behavior', () => {
+    it('uses monochromeWhite logo in dark theme when style is default', () => {
+      vi.mocked(useTheme).mockReturnValue({
+        ...mockUseTheme,
+        theme: Theme.dark,
+      } as ReturnType<typeof useTheme>)
+      render(<DifyLogo style="default" />)
+      const img = screen.getByRole('img', { name: /dify logo/i })
+      expect(img).toHaveAttribute('src', '/test-base-path/logo/logo-monochrome-white.svg')
+    })
+
+    it('uses monochromeWhite logo in dark theme when style is monochromeWhite', () => {
+      vi.mocked(useTheme).mockReturnValue({
+        ...mockUseTheme,
+        theme: Theme.dark,
+      } as ReturnType<typeof useTheme>)
+      render(<DifyLogo style="monochromeWhite" />)
+      const img = screen.getByRole('img', { name: /dify logo/i })
+      expect(img).toHaveAttribute('src', '/test-base-path/logo/logo-monochrome-white.svg')
+    })
+
+    it('uses default logo in light theme when style is default', () => {
+      vi.mocked(useTheme).mockReturnValue({
+        ...mockUseTheme,
+        theme: Theme.light,
+      } as ReturnType<typeof useTheme>)
+      render(<DifyLogo style="default" />)
+      const img = screen.getByRole('img', { name: /dify logo/i })
+      expect(img).toHaveAttribute('src', '/test-base-path/logo/logo.svg')
+    })
+  })
+})

web/app/components/base/logo/logo-embedded-chat-avatar.spec.tsx

@@ -0,0 +1,32 @@
+import { render, screen } from '@testing-library/react'
+import LogoEmbeddedChatAvatar from './logo-embedded-chat-avatar'
+
+vi.mock('@/utils/var', () => ({
+  basePath: '/test-base-path',
+}))
+
+describe('LogoEmbeddedChatAvatar', () => {
+  describe('Render', () => {
+    it('renders correctly with default props', () => {
+      render(<LogoEmbeddedChatAvatar />)
+      const img = screen.getByRole('img', { name: /logo/i })
+      expect(img).toBeInTheDocument()
+      expect(img).toHaveAttribute('src', '/test-base-path/logo/logo-embedded-chat-avatar.png')
+    })
+  })
+
+  describe('Props', () => {
+    it('applies custom className correctly', () => {
+      const customClass = 'custom-avatar-class'
+      render(<LogoEmbeddedChatAvatar className={customClass} />)
+      const img = screen.getByRole('img', { name: /logo/i })
+      expect(img).toHaveClass(customClass)
+    })
+
+    it('has valid alt text', () => {
+      render(<LogoEmbeddedChatAvatar />)
+      const img = screen.getByRole('img', { name: /logo/i })
+      expect(img).toHaveAttribute('alt', 'logo')
+    })
+  })
+})

web/app/components/base/logo/logo-embedded-chat-header.spec.tsx

@@ -0,0 +1,29 @@
+import { render, screen } from '@testing-library/react'
+import LogoEmbeddedChatHeader from './logo-embedded-chat-header'
+
+vi.mock('@/utils/var', () => ({
+  basePath: '/test-base-path',
+}))
+
+describe('LogoEmbeddedChatHeader', () => {
+  it('renders correctly with default props', () => {
+    const { container } = render(<LogoEmbeddedChatHeader />)
+    const img = screen.getByRole('img', { name: /logo/i })
+    expect(img).toBeInTheDocument()
+    expect(img).toHaveAttribute('src', '/test-base-path/logo/logo-embedded-chat-header.png')
+
+    const sources = container.querySelectorAll('source')
+    expect(sources).toHaveLength(3)
+    expect(sources[0]).toHaveAttribute('srcSet', '/logo/logo-embedded-chat-header.png')
+    expect(sources[1]).toHaveAttribute('srcSet', '/logo/logo-embedded-chat-header@2x.png')
+    expect(sources[2]).toHaveAttribute('srcSet', '/logo/logo-embedded-chat-header@3x.png')
+  })
+
+  it('applies custom className correctly', () => {
+    const customClass = 'custom-header-class'
+    render(<LogoEmbeddedChatHeader className={customClass} />)
+    const img = screen.getByRole('img', { name: /logo/i })
+    expect(img).toHaveClass(customClass)
+    expect(img).toHaveClass('h-6')
+  })
+})

web/app/components/base/logo/logo-site.spec.tsx

@@ -0,0 +1,22 @@
+import { render, screen } from '@testing-library/react'
+import LogoSite from './logo-site'
+
+vi.mock('@/utils/var', () => ({
+  basePath: '/test-base-path',
+}))
+
+describe('LogoSite', () => {
+  it('renders correctly with default props', () => {
+    render(<LogoSite />)
+    const img = screen.getByRole('img', { name: /logo/i })
+    expect(img).toBeInTheDocument()
+    expect(img).toHaveAttribute('src', '/test-base-path/logo/logo.png')
+  })
+
+  it('applies custom className correctly', () => {
+    const customClass = 'custom-site-class'
+    render(<LogoSite className={customClass} />)
+    const img = screen.getByRole('img', { name: /logo/i })
+    expect(img).toHaveClass(customClass)
+  })
+})

web/app/components/base/new-audio-button/index.spec.tsx

@@ -0,0 +1,205 @@
+import { act, render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import i18next from 'i18next'
+import { useParams, usePathname } from 'next/navigation'
+import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+import AudioBtn from './index'
+
+const mockPlayAudio = vi.fn()
+const mockPauseAudio = vi.fn()
+const mockGetAudioPlayer = vi.fn()
+
+vi.mock('next/navigation', () => ({
+  useParams: vi.fn(),
+  usePathname: vi.fn(),
+}))
+
+vi.mock('@/app/components/base/audio-btn/audio.player.manager', () => ({
+  AudioPlayerManager: {
+    getInstance: vi.fn(() => ({
+      getAudioPlayer: mockGetAudioPlayer,
+    })),
+  },
+}))
+
+describe('AudioBtn', () => {
+  const getButton = () => screen.getByRole('button')
+
+  const hoverAndCheckTooltip = async (expectedText: string) => {
+    const button = getButton()
+    await userEvent.hover(button)
+    expect(await screen.findByText(expectedText)).toBeInTheDocument()
+  }
+
+  const getAudioCallback = () => {
+    const lastCall = mockGetAudioPlayer.mock.calls[mockGetAudioPlayer.mock.calls.length - 1]
+    const callback = lastCall?.find((arg: unknown) => typeof arg === 'function') as ((event: string) => void) | undefined
+    if (!callback)
+      throw new Error('Audio callback not found - ensure mockGetAudioPlayer was called with a callback argument')
+    return callback
+  }
+
+  beforeAll(() => {
+    i18next.init({})
+  })
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockGetAudioPlayer.mockReturnValue({
+      playAudio: mockPlayAudio,
+      pauseAudio: mockPauseAudio,
+    })
+    ; (useParams as ReturnType<typeof vi.fn>).mockReturnValue({})
+    ; (usePathname as ReturnType<typeof vi.fn>).mockReturnValue('/')
+  })
+
+  describe('URL Routing', () => {
+    it('should generate public URL when token is present', async () => {
+      ; (useParams as ReturnType<typeof vi.fn>).mockReturnValue({ token: 'test-token' })
+
+      render(<AudioBtn value="test" />)
+      await userEvent.click(getButton())
+
+      await waitFor(() => expect(mockGetAudioPlayer).toHaveBeenCalled())
+      expect(mockGetAudioPlayer.mock.calls[0][0]).toBe('/text-to-audio')
+      expect(mockGetAudioPlayer.mock.calls[0][1]).toBe(true)
+    })
+
+    it('should generate app URL when appId is present', async () => {
+      ; (useParams as ReturnType<typeof vi.fn>).mockReturnValue({ appId: '123' })
+      ; (usePathname as ReturnType<typeof vi.fn>).mockReturnValue('/apps/123/chat')
+
+      render(<AudioBtn value="test" />)
+      await userEvent.click(getButton())
+
+      await waitFor(() => expect(mockGetAudioPlayer).toHaveBeenCalled())
+      expect(mockGetAudioPlayer.mock.calls[0][0]).toBe('/apps/123/text-to-audio')
+      expect(mockGetAudioPlayer.mock.calls[0][1]).toBe(false)
+    })
+
+    it('should generate installed app URL correctly', async () => {
+      ; (useParams as ReturnType<typeof vi.fn>).mockReturnValue({ appId: '456' })
+      ; (usePathname as ReturnType<typeof vi.fn>).mockReturnValue('/explore/installed/app')
+
+      render(<AudioBtn value="test" />)
+      await userEvent.click(getButton())
+
+      await waitFor(() => expect(mockGetAudioPlayer).toHaveBeenCalled())
+      expect(mockGetAudioPlayer.mock.calls[0][0]).toBe('/installed-apps/456/text-to-audio')
+    })
+  })
+
+  describe('State Management', () => {
+    it('should start in initial state', async () => {
+      render(<AudioBtn value="test" />)
+
+      await hoverAndCheckTooltip('play')
+      expect(getButton()).toHaveClass('action-btn')
+      expect(getButton()).not.toBeDisabled()
+    })
+
+    it('should transition to playing state', async () => {
+      render(<AudioBtn value="test" />)
+      await userEvent.click(getButton())
+
+      act(() => {
+        getAudioCallback()('play')
+      })
+
+      await hoverAndCheckTooltip('playing')
+      expect(getButton()).toHaveClass('action-btn-active')
+    })
+
+    it('should transition to ended state', async () => {
+      render(<AudioBtn value="test" />)
+      await userEvent.click(getButton())
+
+      act(() => {
+        getAudioCallback()('play')
+      })
+      act(() => {
+        getAudioCallback()('ended')
+      })
+
+      await hoverAndCheckTooltip('play')
+      expect(getButton()).not.toHaveClass('action-btn-active')
+    })
+
+    it('should handle paused event', async () => {
+      render(<AudioBtn value="test" />)
+      await userEvent.click(getButton())
+
+      act(() => {
+        getAudioCallback()('play')
+      })
+      act(() => {
+        getAudioCallback()('paused')
+      })
+
+      await hoverAndCheckTooltip('play')
+    })
+
+    it('should handle error event', async () => {
+      render(<AudioBtn value="test" />)
+      await userEvent.click(getButton())
+
+      act(() => {
+        getAudioCallback()('error')
+      })
+
+      await hoverAndCheckTooltip('play')
+    })
+
+    it('should handle loaded event', async () => {
+      render(<AudioBtn value="test" />)
+      await userEvent.click(getButton())
+
+      act(() => {
+        getAudioCallback()('loaded')
+      })
+
+      await hoverAndCheckTooltip('loading')
+    })
+  })
+
+  describe('Play/Pause', () => {
+    it('should call playAudio when clicked', async () => {
+      render(<AudioBtn value="test" />)
+      await userEvent.click(getButton())
+
+      await waitFor(() => expect(mockPlayAudio).toHaveBeenCalled())
+    })
+
+    it('should call pauseAudio when clicked while playing', async () => {
+      render(<AudioBtn value="test" />)
+      await userEvent.click(getButton())
+
+      act(() => {
+        getAudioCallback()('play')
+      })
+
+      await userEvent.click(getButton())
+      await waitFor(() => expect(mockPauseAudio).toHaveBeenCalled())
+    })
+
+    it('should disable button when loading', async () => {
+      render(<AudioBtn value="test" />)
+      await userEvent.click(getButton())
+
+      await waitFor(() => expect(getButton()).toBeDisabled())
+    })
+  })
+
+  describe('Props', () => {
+    it('should pass props to audio player', async () => {
+      render(<AudioBtn value="hello" id="msg-1" voice="en-US" />)
+      await userEvent.click(getButton())
+
+      await waitFor(() => expect(mockGetAudioPlayer).toHaveBeenCalled())
+      const call = mockGetAudioPlayer.mock.calls[0]
+      expect(call[2]).toBe('msg-1')
+      expect(call[3]).toBe('hello')
+      expect(call[4]).toBe('en-US')
+    })
+  })
+})

web/app/components/base/notion-connector/index.spec.tsx

@@ -0,0 +1,49 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import NotionConnector from './index'
+
+describe('NotionConnector', () => {
+  it('should render the layout and actual sub-components (Icons & Button)', () => {
+    const { container } = render(<NotionConnector onSetting={vi.fn()} />)
+
+    // Verify Title & Tip translations
+    expect(screen.getByText('datasetCreation.stepOne.notionSyncTitle')).toBeInTheDocument()
+    expect(screen.getByText('datasetCreation.stepOne.notionSyncTip')).toBeInTheDocument()
+
+    const notionWrapper = container.querySelector('.h-12.w-12')
+    const dotsWrapper = container.querySelector('.system-md-semibold')
+
+    expect(notionWrapper?.querySelector('svg')).toBeInTheDocument()
+    expect(dotsWrapper?.querySelector('svg')).toBeInTheDocument()
+
+    const button = screen.getByRole('button', {
+      name: /datasetcreation.stepone.connect/i,
+    })
+
+    expect(button).toBeInTheDocument()
+    expect(button).toHaveClass('btn', 'btn-primary')
+  })
+
+  it('should trigger the onSetting callback when the real button is clicked', async () => {
+    const onSetting = vi.fn()
+    const user = userEvent.setup()
+    render(<NotionConnector onSetting={onSetting} />)
+
+    const button = screen.getByRole('button', {
+      name: /datasetcreation.stepone.connect/i,
+    })
+
+    await user.click(button)
+
+    expect(onSetting).toHaveBeenCalledTimes(1)
+  })
+
+  it('should maintain the correct visual hierarchy classes', () => {
+    const { container } = render(<NotionConnector onSetting={vi.fn()} />)
+
+    // Verify the outer container has the specific workflow-process-bg
+    const mainContainer = container.firstChild
+    expect(mainContainer).toHaveClass('bg-workflow-process-bg', 'rounded-2xl', 'p-6')
+  })
+})

web/app/components/base/search-input/index.spec.tsx

@@ -0,0 +1,91 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import SearchInput from '.'
+
+describe('SearchInput', () => {
+  describe('Render', () => {
+    it('renders correctly with default props', () => {
+      render(<SearchInput value="" onChange={() => {}} />)
+      const input = screen.getByPlaceholderText('common.operation.search')
+      expect(input).toBeInTheDocument()
+      expect(input).toHaveValue('')
+    })
+
+    it('renders custom placeholder', () => {
+      render(<SearchInput value="" onChange={() => {}} placeholder="Custom Placeholder" />)
+      expect(screen.getByPlaceholderText('Custom Placeholder')).toBeInTheDocument()
+    })
+
+    it('shows clear button when value is present', () => {
+      const onChange = vi.fn()
+      render(<SearchInput value="has value" onChange={onChange} />)
+
+      const clearButton = screen.getByLabelText('common.operation.clear')
+      expect(clearButton).toBeInTheDocument()
+    })
+  })
+
+  describe('Interaction', () => {
+    it('calls onChange when typing', () => {
+      const onChange = vi.fn()
+      render(<SearchInput value="" onChange={onChange} />)
+      const input = screen.getByPlaceholderText('common.operation.search')
+
+      fireEvent.change(input, { target: { value: 'test' } })
+      expect(onChange).toHaveBeenCalledWith('test')
+    })
+
+    it('handles composition events', () => {
+      const onChange = vi.fn()
+      render(<SearchInput value="initial" onChange={onChange} />)
+      const input = screen.getByPlaceholderText('common.operation.search')
+
+      // Start composition
+      fireEvent.compositionStart(input)
+      fireEvent.change(input, { target: { value: 'final' } })
+
+      // While composing, onChange should NOT be called
+      expect(onChange).not.toHaveBeenCalled()
+      expect(input).toHaveValue('final')
+
+      // End composition
+      fireEvent.compositionEnd(input)
+      expect(onChange).toHaveBeenCalledTimes(1)
+      expect(onChange).toHaveBeenCalledWith('final')
+    })
+
+    it('calls onChange with empty string when clear button is clicked', () => {
+      const onChange = vi.fn()
+      render(<SearchInput value="has value" onChange={onChange} />)
+
+      const clearButton = screen.getByLabelText('common.operation.clear')
+      fireEvent.click(clearButton)
+      expect(onChange).toHaveBeenCalledWith('')
+    })
+
+    it('updates focus state on focus/blur', () => {
+      const { container } = render(<SearchInput value="" onChange={() => {}} />)
+      const wrapper = container.firstChild as HTMLElement
+      const input = screen.getByPlaceholderText('common.operation.search')
+
+      fireEvent.focus(input)
+      expect(wrapper).toHaveClass(/bg-components-input-bg-active/)
+
+      fireEvent.blur(input)
+      expect(wrapper).not.toHaveClass(/bg-components-input-bg-active/)
+    })
+  })
+
+  describe('Style', () => {
+    it('applies white style', () => {
+      const { container } = render(<SearchInput value="" onChange={() => {}} white />)
+      const wrapper = container.firstChild as HTMLElement
+      expect(wrapper).toHaveClass('!bg-white')
+    })
+
+    it('applies custom className', () => {
+      const { container } = render(<SearchInput value="" onChange={() => {}} className="custom-test" />)
+      const wrapper = container.firstChild as HTMLElement
+      expect(wrapper).toHaveClass('custom-test')
+    })
+  })
+})

web/app/components/base/skeleton/index.spec.tsx

@@ -0,0 +1,83 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  SkeletonContainer,
+  SkeletonPoint,
+  SkeletonRectangle,
+  SkeletonRow,
+} from './index'
+
+describe('Skeleton Components', () => {
+  describe('Individual Components', () => {
+    it('should forward attributes and render children in SkeletonContainer', () => {
+      render(
+        <SkeletonContainer data-testid="container" className="custom-container">
+          <span>Content</span>
+        </SkeletonContainer>,
+      )
+      const element = screen.getByTestId('container')
+      expect(element).toHaveClass('flex', 'flex-col', 'custom-container')
+      expect(screen.getByText('Content')).toBeInTheDocument()
+    })
+
+    it('should forward attributes and render children in SkeletonRow', () => {
+      render(
+        <SkeletonRow data-testid="row" className="custom-row">
+          <span>Row Content</span>
+        </SkeletonRow>,
+      )
+      const element = screen.getByTestId('row')
+      expect(element).toHaveClass('flex', 'items-center', 'custom-row')
+      expect(screen.getByText('Row Content')).toBeInTheDocument()
+    })
+
+    it('should apply base skeleton styles to SkeletonRectangle', () => {
+      render(<SkeletonRectangle data-testid="rect" className="w-10" />)
+      const element = screen.getByTestId('rect')
+      expect(element).toHaveClass('h-2', 'bg-text-quaternary', 'opacity-20', 'w-10')
+    })
+
+    it('should render the separator character correctly in SkeletonPoint', () => {
+      render(<SkeletonPoint data-testid="point" />)
+      const element = screen.getByTestId('point')
+      expect(element).toHaveTextContent('·')
+      expect(element).toHaveClass('text-text-quaternary')
+    })
+  })
+
+  describe('Composition & Layout', () => {
+    it('should render a full skeleton structure accurately', () => {
+      const { container } = render(
+        <SkeletonContainer className="main-wrapper">
+          <SkeletonRow>
+            <SkeletonRectangle className="rect-1" />
+            <SkeletonPoint />
+            <SkeletonRectangle className="rect-2" />
+          </SkeletonRow>
+        </SkeletonContainer>,
+      )
+
+      const wrapper = container.firstChild as HTMLElement
+      expect(wrapper).toHaveClass('main-wrapper')
+
+      expect(container.querySelector('.rect-1')).toBeInTheDocument()
+      expect(container.querySelector('.rect-2')).toBeInTheDocument()
+
+      const row = container.querySelector('.flex.items-center')
+      expect(row).toContainElement(container.querySelector('.rect-1') as HTMLElement)
+      expect(row).toHaveTextContent('·')
+    })
+  })
+
+  it('should handle rest props like event listeners', async () => {
+    const onClick = vi.fn()
+    const user = userEvent.setup()
+    render(<SkeletonRectangle onClick={onClick} data-testid="clickable" />)
+
+    const element = screen.getByTestId('clickable')
+
+    await user.click(element)
+    expect(onClick).toHaveBeenCalledTimes(1)
+  })
+})

web/app/components/base/slider/index.spec.tsx

@@ -0,0 +1,77 @@
+import { act, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import Slider from './index'
+
+describe('Slider Component', () => {
+  it('should render with correct default ARIA limits and current value', () => {
+    render(<Slider value={50} onChange={vi.fn()} />)
+
+    const slider = screen.getByRole('slider')
+    expect(slider).toHaveAttribute('aria-valuemin', '0')
+    expect(slider).toHaveAttribute('aria-valuemax', '100')
+    expect(slider).toHaveAttribute('aria-valuenow', '50')
+  })
+
+  it('should apply custom min, max, and step values', () => {
+    render(<Slider value={10} min={5} max={20} step={5} onChange={vi.fn()} />)
+
+    const slider = screen.getByRole('slider')
+    expect(slider).toHaveAttribute('aria-valuemin', '5')
+    expect(slider).toHaveAttribute('aria-valuemax', '20')
+    expect(slider).toHaveAttribute('aria-valuenow', '10')
+  })
+
+  it('should default to 0 if the value prop is NaN', () => {
+    render(<Slider value={Number.NaN} onChange={vi.fn()} />)
+
+    const slider = screen.getByRole('slider')
+    expect(slider).toHaveAttribute('aria-valuenow', '0')
+  })
+
+  it('should call onChange when arrow keys are pressed', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+
+    render(<Slider value={20} onChange={onChange} />)
+
+    const slider = screen.getByRole('slider')
+
+    await act(async () => {
+      slider.focus()
+      await user.keyboard('{ArrowRight}')
+    })
+
+    expect(onChange).toHaveBeenCalledTimes(1)
+    expect(onChange).toHaveBeenCalledWith(21, 0)
+  })
+
+  it('should not trigger onChange when disabled', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Slider value={20} onChange={onChange} disabled />)
+
+    const slider = screen.getByRole('slider')
+
+    expect(slider).toHaveAttribute('aria-disabled', 'true')
+
+    await act(async () => {
+      slider.focus()
+      await user.keyboard('{ArrowRight}')
+    })
+
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('should apply custom class names', () => {
+    render(
+      <Slider value={10} onChange={vi.fn()} className="outer-test" thumbClassName="thumb-test" />,
+    )
+
+    const sliderWrapper = screen.getByRole('slider').closest('.outer-test')
+    expect(sliderWrapper).toBeInTheDocument()
+
+    const thumb = screen.getByRole('slider')
+    expect(thumb).toHaveClass('thumb-test')
+  })
+})

web/app/components/base/sort/index.spec.tsx

@@ -0,0 +1,141 @@
+import { render, screen, waitFor, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import * as React from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import Sort from './index'
+
+const mockItems = [
+  { value: 'created_at', name: 'Date Created' },
+  { value: 'name', name: 'Name' },
+  { value: 'status', name: 'Status' },
+]
+
+describe('Sort component — real portal integration', () => {
+  const setup = (props = {}) => {
+    const onSelect = vi.fn()
+    const user = userEvent.setup()
+    const { container, rerender } = render(
+      <Sort value="created_at" items={mockItems} onSelect={onSelect} order="" {...props} />,
+    )
+
+    // helper: returns a non-null HTMLElement or throws with a clear message
+    const getTriggerWrapper = (): HTMLElement => {
+      const labelNode = screen.getByText('appLog.filter.sortBy')
+      // try to find a reasonable wrapper element; prefer '.block' but fallback to any ancestor div
+      const wrapper = labelNode.closest('.block') ?? labelNode.closest('div')
+      if (!wrapper)
+        throw new Error('Trigger wrapper element not found for "Sort by" label')
+      return wrapper as HTMLElement
+    }
+
+    // helper: returns right-side sort button element
+    const getSortButton = (): HTMLElement => {
+      const btn = container.querySelector('.rounded-r-lg')
+      if (!btn)
+        throw new Error('Sort button (rounded-r-lg) not found in rendered container')
+      return btn as HTMLElement
+    }
+
+    return { user, onSelect, rerender, getTriggerWrapper, getSortButton }
+  }
+
+  it('renders and shows selected item label and sort icon', () => {
+    const { getSortButton } = setup({ order: '' })
+
+    expect(screen.getByText('Date Created')).toBeInTheDocument()
+
+    const sortButton = getSortButton()
+    expect(sortButton).toBeInstanceOf(HTMLElement)
+    expect(sortButton.querySelector('svg')).toBeInTheDocument()
+  })
+
+  it('opens and closes the tooltip (portal mounts to document.body)', async () => {
+    const { user, getTriggerWrapper } = setup()
+
+    await user.click(getTriggerWrapper())
+    const tooltip = await screen.findByRole('tooltip')
+    expect(tooltip).toBeInTheDocument()
+    expect(document.body.contains(tooltip)).toBe(true)
+
+    // clicking the trigger again should close it
+    await user.click(getTriggerWrapper())
+    await waitFor(() => expect(screen.queryByRole('tooltip')).not.toBeInTheDocument())
+  })
+
+  it('renders options and calls onSelect with descending prefix when order is "-"', async () => {
+    const { user, onSelect, getTriggerWrapper } = setup({ order: '-' })
+
+    await user.click(getTriggerWrapper())
+    const tooltip = await screen.findByRole('tooltip')
+
+    mockItems.forEach((item) => {
+      expect(within(tooltip).getByText(item.name)).toBeInTheDocument()
+    })
+
+    await user.click(within(tooltip).getByText('Name'))
+    expect(onSelect).toHaveBeenCalledWith('-name')
+    await waitFor(() => expect(screen.queryByRole('tooltip')).not.toBeInTheDocument())
+  })
+
+  it('toggles sorting order: ascending -> descending via right-side button', async () => {
+    const { user, onSelect, getSortButton } = setup({ order: '', value: 'created_at' })
+    await user.click(getSortButton())
+    expect(onSelect).toHaveBeenCalledWith('-created_at')
+  })
+
+  it('toggles sorting order: descending -> ascending via right-side button', async () => {
+    const { user, onSelect, getSortButton } = setup({ order: '-', value: 'name' })
+    await user.click(getSortButton())
+    expect(onSelect).toHaveBeenCalledWith('name')
+  })
+
+  it('shows checkmark only for selected item in menu', async () => {
+    const { user, getTriggerWrapper } = setup({ value: 'status' })
+
+    await user.click(getTriggerWrapper())
+    const tooltip = await screen.findByRole('tooltip')
+
+    const statusRow = within(tooltip).getByText('Status').closest('.flex')
+    const nameRow = within(tooltip).getByText('Name').closest('.flex')
+
+    if (!statusRow)
+      throw new Error('Status option row not found in menu')
+    if (!nameRow)
+      throw new Error('Name option row not found in menu')
+
+    expect(statusRow.querySelector('svg')).toBeInTheDocument()
+    expect(nameRow.querySelector('svg')).not.toBeInTheDocument()
+  })
+
+  it('shows empty selection label when value is unknown', () => {
+    setup({ value: 'unknown_value' })
+    const label = screen.getByText('appLog.filter.sortBy')
+    const valueNode = label.nextSibling
+    if (!valueNode)
+      throw new Error('Expected a sibling node for the selection text')
+    expect(String(valueNode.textContent || '').trim()).toBe('')
+  })
+
+  it('handles undefined order prop without asserting a literal "undefined" prefix', async () => {
+    const { user, onSelect, getTriggerWrapper } = setup({ order: undefined })
+
+    await user.click(getTriggerWrapper())
+    const tooltip = await screen.findByRole('tooltip')
+
+    await user.click(within(tooltip).getByText('Name'))
+
+    expect(onSelect).toHaveBeenCalled()
+    expect(onSelect).toHaveBeenCalledWith(expect.stringMatching(/name$/))
+  })
+
+  it('clicking outside the open menu closes the portal', async () => {
+    const { user, getTriggerWrapper } = setup()
+    await user.click(getTriggerWrapper())
+    const tooltip = await screen.findByRole('tooltip')
+    expect(tooltip).toBeInTheDocument()
+
+    // click outside: body click should close the tooltip
+    await user.click(document.body)
+    await waitFor(() => expect(screen.queryByRole('tooltip')).not.toBeInTheDocument())
+  })
+})

web/app/components/base/switch/index.spec.tsx

@@ -0,0 +1,84 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import Switch from './index'
+
+describe('Switch', () => {
+  it('should render in unchecked state by default', () => {
+    render(<Switch />)
+    const switchElement = screen.getByRole('switch')
+    expect(switchElement).toBeInTheDocument()
+    expect(switchElement).toHaveAttribute('aria-checked', 'false')
+  })
+
+  it('should render in checked state when defaultValue is true', () => {
+    render(<Switch defaultValue={true} />)
+    const switchElement = screen.getByRole('switch')
+    expect(switchElement).toHaveAttribute('aria-checked', 'true')
+  })
+
+  it('should toggle state and call onChange when clicked', async () => {
+    const onChange = vi.fn()
+    const user = userEvent.setup()
+    render(<Switch onChange={onChange} />)
+
+    const switchElement = screen.getByRole('switch')
+
+    await user.click(switchElement)
+    expect(switchElement).toHaveAttribute('aria-checked', 'true')
+    expect(onChange).toHaveBeenCalledWith(true)
+    expect(onChange).toHaveBeenCalledTimes(1)
+
+    await user.click(switchElement)
+    expect(switchElement).toHaveAttribute('aria-checked', 'false')
+    expect(onChange).toHaveBeenCalledWith(false)
+    expect(onChange).toHaveBeenCalledTimes(2)
+  })
+
+  it('should not call onChange when disabled', async () => {
+    const onChange = vi.fn()
+    const user = userEvent.setup()
+    render(<Switch disabled onChange={onChange} />)
+
+    const switchElement = screen.getByRole('switch')
+    expect(switchElement).toHaveClass('!cursor-not-allowed', '!opacity-50')
+
+    await user.click(switchElement)
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('should apply correct size classes', () => {
+    const { rerender } = render(<Switch size="xs" />)
+    // We only need to find the element once
+    const switchElement = screen.getByRole('switch')
+    expect(switchElement).toHaveClass('h-2.5', 'w-3.5', 'rounded-sm')
+
+    rerender(<Switch size="sm" />)
+    expect(switchElement).toHaveClass('h-3', 'w-5')
+
+    rerender(<Switch size="md" />)
+    expect(switchElement).toHaveClass('h-4', 'w-7')
+
+    rerender(<Switch size="l" />)
+    expect(switchElement).toHaveClass('h-5', 'w-9')
+
+    rerender(<Switch size="lg" />)
+    expect(switchElement).toHaveClass('h-6', 'w-11')
+  })
+
+  it('should apply custom className', () => {
+    render(<Switch className="custom-test-class" />)
+    expect(screen.getByRole('switch')).toHaveClass('custom-test-class')
+  })
+
+  it('should apply correct background colors based on state', async () => {
+    const user = userEvent.setup()
+    render(<Switch />)
+    const switchElement = screen.getByRole('switch')
+
+    expect(switchElement).toHaveClass('bg-components-toggle-bg-unchecked')
+
+    await user.click(switchElement)
+    expect(switchElement).toHaveClass('bg-components-toggle-bg')
+  })
+})

web/app/components/base/tag/index.spec.tsx

@@ -0,0 +1,104 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import Tag from './index'
+import '@testing-library/jest-dom/vitest'
+
+describe('Tag Component', () => {
+  describe('Rendering', () => {
+    it('should render with text children', () => {
+      const { container } = render(<Tag>Hello World</Tag>)
+      expect(container.firstChild).toHaveTextContent('Hello World')
+    })
+
+    it('should render with ReactNode children', () => {
+      render(<Tag><span data-testid="child">Node</span></Tag>)
+      expect(screen.getByTestId('child')).toBeInTheDocument()
+    })
+
+    it('should always apply base layout classes', () => {
+      const { container } = render(<Tag>Test</Tag>)
+      expect(container.firstChild).toHaveClass(
+        'inline-flex',
+        'shrink-0',
+        'items-center',
+        'rounded-md',
+        'px-2.5',
+        'py-px',
+        'text-xs',
+        'leading-5',
+      )
+    })
+  })
+
+  describe('Color Variants', () => {
+    it.each([
+      { color: 'green', text: 'text-green-800', bg: 'bg-green-100' },
+      { color: 'yellow', text: 'text-yellow-800', bg: 'bg-yellow-100' },
+      { color: 'red', text: 'text-red-800', bg: 'bg-red-100' },
+      { color: 'gray', text: 'text-gray-800', bg: 'bg-gray-100' },
+    ])('should apply $color color classes', ({ color, text, bg }) => {
+      type colorType = 'green' | 'yellow' | 'red' | 'gray' | undefined
+      const { container } = render(<Tag color={color as colorType}>Test</Tag>)
+      expect(container.firstChild).toHaveClass(text, bg)
+    })
+
+    it('should default to green when no color specified', () => {
+      const { container } = render(<Tag>Test</Tag>)
+      expect(container.firstChild).toHaveClass('text-green-800', 'bg-green-100')
+    })
+
+    it('should not apply color classes for invalid color', () => {
+      type colorType = 'green' | 'yellow' | 'red' | 'gray' | undefined
+      const { container } = render(<Tag color={'invalid' as colorType}>Test</Tag>)
+      const className = (container.firstChild as HTMLElement)?.className || ''
+
+      expect(className).not.toMatch(/text-(green|yellow|red|gray)-800/)
+      expect(className).not.toMatch(/bg-(green|yellow|red|gray)-100/)
+    })
+  })
+
+  describe('Boolean Props', () => {
+    it('should apply border when bordered is true', () => {
+      const { container } = render(<Tag bordered>Test</Tag>)
+      expect(container.firstChild).toHaveClass('border-[1px]')
+    })
+
+    it('should not apply border by default', () => {
+      const { container } = render(<Tag>Test</Tag>)
+      expect(container.firstChild).not.toHaveClass('border-[1px]')
+    })
+
+    it('should hide background when hideBg is true', () => {
+      const { container } = render(<Tag hideBg>Test</Tag>)
+      expect(container.firstChild).toHaveClass('bg-transparent')
+    })
+
+    it('should apply both bordered and hideBg together', () => {
+      const { container } = render(<Tag bordered hideBg>Test</Tag>)
+      expect(container.firstChild).toHaveClass('border-[1px]', 'bg-transparent')
+    })
+
+    it('should override color background with hideBg', () => {
+      const { container } = render(<Tag color="red" hideBg>Test</Tag>)
+      const tag = container.firstChild
+      expect(tag).toHaveClass('bg-transparent', 'text-red-800')
+    })
+  })
+
+  describe('Custom Styling', () => {
+    it('should merge custom className', () => {
+      const { container } = render(<Tag className="my-custom-class">Test</Tag>)
+      expect(container.firstChild).toHaveClass('my-custom-class')
+    })
+
+    it('should preserve base classes with custom className', () => {
+      const { container } = render(<Tag className="my-custom-class">Test</Tag>)
+      expect(container.firstChild).toHaveClass('inline-flex', 'my-custom-class')
+    })
+
+    it('should handle empty className prop', () => {
+      const { container } = render(<Tag className="">Test</Tag>)
+      expect(container.firstChild).toBeInTheDocument()
+    })
+  })
+})

web/app/components/billing/apps-full-in-dialog/__tests__/index.spec.tsx

@@ -197,61 +197,30 @@ describe('AppsFull', () => {
   })
 
   describe('Edge Cases', () => {
-    it('should use the success color when usage is below 50%', () => {
-      ;(useProviderContext as Mock).mockReturnValue(buildProviderContext({
-        plan: {
-          ...baseProviderContextValue.plan,
-          type: Plan.sandbox,
-          usage: buildUsage({ buildApps: 2 }),
-          total: buildUsage({ buildApps: 5 }),
-          reset: {
-            apiRateLimit: null,
-            triggerEvents: null,
+    it('should apply distinct progress bar styling at different usage levels', () => {
+      const renderWithUsage = (used: number, total: number) => {
+        ;(useProviderContext as Mock).mockReturnValue(buildProviderContext({
+          plan: {
+            ...baseProviderContextValue.plan,
+            type: Plan.sandbox,
+            usage: buildUsage({ buildApps: used }),
+            total: buildUsage({ buildApps: total }),
+            reset: { apiRateLimit: null, triggerEvents: null },
           },
-        },
-      }))
+        }))
+        const { unmount } = render(<AppsFull loc="billing_dialog" />)
+        const className = screen.getByTestId('billing-progress-bar').className
+        unmount()
+        return className
+      }
 
-      render(<AppsFull loc="billing_dialog" />)
+      const normalClass = renderWithUsage(2, 10)
+      const warningClass = renderWithUsage(6, 10)
+      const errorClass = renderWithUsage(8, 10)
 
-      expect(screen.getByTestId('billing-progress-bar')).toHaveClass('bg-components-progress-bar-progress-solid')
-    })
-
-    it('should use the warning color when usage is between 50% and 80%', () => {
-      ;(useProviderContext as Mock).mockReturnValue(buildProviderContext({
-        plan: {
-          ...baseProviderContextValue.plan,
-          type: Plan.sandbox,
-          usage: buildUsage({ buildApps: 6 }),
-          total: buildUsage({ buildApps: 10 }),
-          reset: {
-            apiRateLimit: null,
-            triggerEvents: null,
-          },
-        },
-      }))
-
-      render(<AppsFull loc="billing_dialog" />)
-
-      expect(screen.getByTestId('billing-progress-bar')).toHaveClass('bg-components-progress-warning-progress')
-    })
-
-    it('should use the error color when usage is 80% or higher', () => {
-      ;(useProviderContext as Mock).mockReturnValue(buildProviderContext({
-        plan: {
-          ...baseProviderContextValue.plan,
-          type: Plan.sandbox,
-          usage: buildUsage({ buildApps: 8 }),
-          total: buildUsage({ buildApps: 10 }),
-          reset: {
-            apiRateLimit: null,
-            triggerEvents: null,
-          },
-        },
-      }))
-
-      render(<AppsFull loc="billing_dialog" />)
-
-      expect(screen.getByTestId('billing-progress-bar')).toHaveClass('bg-components-progress-error-progress')
+      expect(normalClass).not.toBe(warningClass)
+      expect(warningClass).not.toBe(errorClass)
+      expect(normalClass).not.toBe(errorClass)
     })
   })
 })

web/app/components/billing/header-billing-btn/__tests__/index.spec.tsx

@@ -70,7 +70,7 @@ describe('HeaderBillingBtn', () => {
     expect(screen.getByTestId('upgrade-btn')).toBeInTheDocument()
   })
 
-  it('renders team badge for team plan with correct styling', () => {
+  it('renders team badge for team plan', () => {
     ensureProviderContextMock().mockReturnValueOnce({
       plan: { type: Plan.team },
       enableBilling: true,
@@ -79,9 +79,7 @@ describe('HeaderBillingBtn', () => {
 
     render(<HeaderBillingBtn />)
 
-    const badge = screen.getByText('team').closest('div')
-    expect(badge).toBeInTheDocument()
-    expect(badge).toHaveClass('bg-[#E0EAFF]')
+    expect(screen.getByText('team')).toBeInTheDocument()
   })
 
   it('renders nothing when plan is not fetched', () => {
@@ -111,16 +109,11 @@ describe('HeaderBillingBtn', () => {
 
     const { rerender } = render(<HeaderBillingBtn onClick={onClick} />)
 
-    const badge = screen.getByText('pro').closest('div')
-
-    expect(badge).toHaveClass('cursor-pointer')
-
-    fireEvent.click(badge!)
+    const badge = screen.getByText('pro').closest('div')!
+    fireEvent.click(badge)
     expect(onClick).toHaveBeenCalledTimes(1)
 
     rerender(<HeaderBillingBtn onClick={onClick} isDisplayOnly />)
-    expect(screen.getByText('pro').closest('div')).toHaveClass('cursor-default')
-
     fireEvent.click(screen.getByText('pro').closest('div')!)
     expect(onClick).toHaveBeenCalledTimes(1)
   })

web/app/components/billing/pricing/plan-switcher/__tests__/tab.spec.tsx

@@ -47,8 +47,20 @@ describe('PlanSwitcherTab', () => {
       expect(handleClick).toHaveBeenCalledWith('self')
     })
 
-    it('should apply active text class when isActive is true', () => {
-      render(
+    it('should apply distinct styling when isActive is true', () => {
+      const { rerender } = render(
+        <Tab
+          Icon={Icon}
+          value="cloud"
+          label="Cloud"
+          isActive={false}
+          onClick={vi.fn()}
+        />,
+      )
+
+      const inactiveClassName = screen.getByText('Cloud').className
+
+      rerender(
         <Tab
           Icon={Icon}
           value="cloud"
@@ -58,7 +70,8 @@ describe('PlanSwitcherTab', () => {
         />,
       )
 
-      expect(screen.getByText('Cloud')).toHaveClass('text-saas-dify-blue-accessible')
+      const activeClassName = screen.getByText('Cloud').className
+      expect(activeClassName).not.toBe(inactiveClassName)
       expect(screen.getByTestId('tab-icon')).toHaveAttribute('data-active', 'true')
     })
   })

web/app/components/billing/progress-bar/__tests__/index.spec.tsx

@@ -7,7 +7,6 @@ describe('ProgressBar', () => {
       render(<ProgressBar percent={42} color="bg-test-color" />)
 
       const bar = screen.getByTestId('billing-progress-bar')
-      expect(bar).toHaveClass('bg-test-color')
       expect(bar.getAttribute('style')).toContain('width: 42%')
     })
 
@@ -18,11 +17,10 @@ describe('ProgressBar', () => {
       expect(bar.getAttribute('style')).toContain('width: 100%')
     })
 
-    it('uses the default color when no color prop is provided', () => {
+    it('renders with default color when no color prop is provided', () => {
       render(<ProgressBar percent={20} color={undefined as unknown as string} />)
 
       const bar = screen.getByTestId('billing-progress-bar')
-      expect(bar).toHaveClass('bg-components-progress-bar-progress-solid')
       expect(bar.getAttribute('style')).toContain('width: 20%')
     })
   })
@@ -31,9 +29,7 @@ describe('ProgressBar', () => {
     it('should render indeterminate progress bar when indeterminate is true', () => {
       render(<ProgressBar percent={0} color="bg-test-color" indeterminate />)
 
-      const bar = screen.getByTestId('billing-progress-bar-indeterminate')
-      expect(bar).toBeInTheDocument()
-      expect(bar).toHaveClass('bg-progress-bar-indeterminate-stripe')
+      expect(screen.getByTestId('billing-progress-bar-indeterminate')).toBeInTheDocument()
     })
 
     it('should not render normal progress bar when indeterminate is true', () => {
@@ -43,20 +39,20 @@ describe('ProgressBar', () => {
       expect(screen.getByTestId('billing-progress-bar-indeterminate')).toBeInTheDocument()
     })
 
-    it('should render with default width (w-[30px]) when indeterminateFull is false', () => {
-      render(<ProgressBar percent={0} color="bg-test-color" indeterminate indeterminateFull={false} />)
+    it('should render with different width based on indeterminateFull prop', () => {
+      const { rerender } = render(
+        <ProgressBar percent={0} color="bg-test-color" indeterminate indeterminateFull={false} />,
+      )
 
       const bar = screen.getByTestId('billing-progress-bar-indeterminate')
-      expect(bar).toHaveClass('w-[30px]')
-      expect(bar).not.toHaveClass('w-full')
-    })
+      const partialClassName = bar.className
 
-    it('should render with full width (w-full) when indeterminateFull is true', () => {
-      render(<ProgressBar percent={0} color="bg-test-color" indeterminate indeterminateFull />)
+      rerender(
+        <ProgressBar percent={0} color="bg-test-color" indeterminate indeterminateFull />,
+      )
 
-      const bar = screen.getByTestId('billing-progress-bar-indeterminate')
-      expect(bar).toHaveClass('w-full')
-      expect(bar).not.toHaveClass('w-[30px]')
+      const fullClassName = screen.getByTestId('billing-progress-bar-indeterminate').className
+      expect(partialClassName).not.toBe(fullClassName)
     })
   })
 })

web/app/components/billing/usage-info/__tests__/index.spec.tsx

@@ -71,8 +71,19 @@ describe('UsageInfo', () => {
       expect(screen.getByText('billing.plansCommon.unlimited')).toBeInTheDocument()
     })
 
-    it('applies warning color when usage is close to the limit', () => {
-      render(
+    it('applies distinct styling when usage is close to or exceeds the limit', () => {
+      const { rerender } = render(
+        <UsageInfo
+          Icon={TestIcon}
+          name="Storage"
+          usage={30}
+          total={100}
+        />,
+      )
+
+      const normalBarClass = screen.getByTestId('billing-progress-bar').className
+
+      rerender(
         <UsageInfo
           Icon={TestIcon}
           name="Storage"
@@ -81,12 +92,10 @@ describe('UsageInfo', () => {
         />,
       )
 
-      const progressBar = screen.getByTestId('billing-progress-bar')
-      expect(progressBar).toHaveClass('bg-components-progress-warning-progress')
-    })
+      const warningBarClass = screen.getByTestId('billing-progress-bar').className
+      expect(warningBarClass).not.toBe(normalBarClass)
 
-    it('applies error color when usage exceeds the limit', () => {
-      render(
+      rerender(
         <UsageInfo
           Icon={TestIcon}
           name="Storage"
@@ -95,8 +104,9 @@ describe('UsageInfo', () => {
         />,
       )
 
-      const progressBar = screen.getByTestId('billing-progress-bar')
-      expect(progressBar).toHaveClass('bg-components-progress-error-progress')
+      const errorBarClass = screen.getByTestId('billing-progress-bar').className
+      expect(errorBarClass).not.toBe(normalBarClass)
+      expect(errorBarClass).not.toBe(warningBarClass)
     })
 
     it('does not render the icon when hideIcon is true', () => {
@@ -173,8 +183,8 @@ describe('UsageInfo', () => {
         expect(screen.getAllByText('MB').length).toBeGreaterThanOrEqual(1)
       })
 
-      it('should render full-width indeterminate bar for sandbox users below threshold', () => {
-        render(
+      it('should render different indeterminate bar widths for sandbox vs non-sandbox', () => {
+        const { rerender } = render(
           <UsageInfo
             Icon={TestIcon}
             name="Storage"
@@ -187,12 +197,9 @@ describe('UsageInfo', () => {
           />,
         )
 
-        const bar = screen.getByTestId('billing-progress-bar-indeterminate')
-        expect(bar).toHaveClass('w-full')
-      })
+        const sandboxBarClass = screen.getByTestId('billing-progress-bar-indeterminate').className
 
-      it('should render narrow indeterminate bar for non-sandbox users below threshold', () => {
-        render(
+        rerender(
           <UsageInfo
             Icon={TestIcon}
             name="Storage"
@@ -205,13 +212,13 @@ describe('UsageInfo', () => {
           />,
         )
 
-        const bar = screen.getByTestId('billing-progress-bar-indeterminate')
-        expect(bar).toHaveClass('w-[30px]')
+        const nonSandboxBarClass = screen.getByTestId('billing-progress-bar-indeterminate').className
+        expect(sandboxBarClass).not.toBe(nonSandboxBarClass)
       })
     })
 
     describe('Sandbox Full Capacity', () => {
-      it('should render error color progress bar when sandbox usage >= threshold', () => {
+      it('should render determinate progress bar when sandbox usage >= threshold', () => {
         render(
           <UsageInfo
             Icon={TestIcon}
@@ -225,8 +232,8 @@ describe('UsageInfo', () => {
           />,
         )
 
-        const progressBar = screen.getByTestId('billing-progress-bar')
-        expect(progressBar).toHaveClass('bg-components-progress-error-progress')
+        expect(screen.getByTestId('billing-progress-bar')).toBeInTheDocument()
+        expect(screen.queryByTestId('billing-progress-bar-indeterminate')).not.toBeInTheDocument()
       })
 
       it('should display "threshold / threshold unit" format when sandbox is at full capacity', () => {
@@ -305,9 +312,7 @@ describe('UsageInfo', () => {
           />,
         )
 
-        // Tooltip wrapper should contain cursor-default class
-        const tooltipWrapper = container.querySelector('.cursor-default')
-        expect(tooltipWrapper).toBeInTheDocument()
+        expect(container.querySelector('[data-state]')).toBeInTheDocument()
       })
     })
   })

web/app/components/billing/usage-info/__tests__/vector-space-info.spec.tsx

@@ -61,11 +61,10 @@ describe('VectorSpaceInfo', () => {
       expect(screen.getByTestId('billing-progress-bar-indeterminate')).toBeInTheDocument()
     })
 
-    it('should render full-width indeterminate bar for sandbox users', () => {
+    it('should render indeterminate bar for sandbox users', () => {
       render(<VectorSpaceInfo />)
 
-      const bar = screen.getByTestId('billing-progress-bar-indeterminate')
-      expect(bar).toHaveClass('w-full')
+      expect(screen.getByTestId('billing-progress-bar-indeterminate')).toBeInTheDocument()
     })
 
     it('should display "< 50" format for sandbox below threshold', () => {
@@ -81,11 +80,11 @@ describe('VectorSpaceInfo', () => {
       mockVectorSpaceUsage = 50
     })
 
-    it('should render error color progress bar when at full capacity', () => {
+    it('should render determinate progress bar when at full capacity', () => {
       render(<VectorSpaceInfo />)
 
-      const progressBar = screen.getByTestId('billing-progress-bar')
-      expect(progressBar).toHaveClass('bg-components-progress-error-progress')
+      expect(screen.getByTestId('billing-progress-bar')).toBeInTheDocument()
+      expect(screen.queryByTestId('billing-progress-bar-indeterminate')).not.toBeInTheDocument()
     })
 
     it('should display "50 / 50 MB" format when at full capacity', () => {
@@ -108,19 +107,10 @@ describe('VectorSpaceInfo', () => {
       expect(screen.getByTestId('billing-progress-bar-indeterminate')).toBeInTheDocument()
     })
 
-    it('should render narrow indeterminate bar (not full width)', () => {
-      render(<VectorSpaceInfo />)
-
-      const bar = screen.getByTestId('billing-progress-bar-indeterminate')
-      expect(bar).toHaveClass('w-[30px]')
-      expect(bar).not.toHaveClass('w-full')
-    })
-
     it('should display "< 50 / total" format when below threshold', () => {
       render(<VectorSpaceInfo />)
 
       expect(screen.getByText(/< 50/)).toBeInTheDocument()
-      // 5 GB = 5120 MB
       expect(screen.getByText('5120MB')).toBeInTheDocument()
     })
   })
@@ -158,14 +148,6 @@ describe('VectorSpaceInfo', () => {
       expect(screen.getByTestId('billing-progress-bar-indeterminate')).toBeInTheDocument()
     })
 
-    it('should render narrow indeterminate bar (not full width)', () => {
-      render(<VectorSpaceInfo />)
-
-      const bar = screen.getByTestId('billing-progress-bar-indeterminate')
-      expect(bar).toHaveClass('w-[30px]')
-      expect(bar).not.toHaveClass('w-full')
-    })
-
     it('should display "< 50 / total" format when below threshold', () => {
       render(<VectorSpaceInfo />)
 
@@ -196,51 +178,24 @@ describe('VectorSpaceInfo', () => {
     })
   })
 
-  describe('Pro/Team Plan Warning State', () => {
-    it('should show warning color when Professional plan usage approaches limit (80%+)', () => {
+  describe('Pro/Team Plan Usage States', () => {
+    const renderAndGetBarClass = (usage: number) => {
       mockPlanType = Plan.professional
-      // 5120 MB * 80% = 4096 MB
-      mockVectorSpaceUsage = 4100
+      mockVectorSpaceUsage = usage
+      const { unmount } = render(<VectorSpaceInfo />)
+      const className = screen.getByTestId('billing-progress-bar').className
+      unmount()
+      return className
+    }
 
-      render(<VectorSpaceInfo />)
+    it('should show distinct progress bar styling at different usage levels', () => {
+      const normalClass = renderAndGetBarClass(100)
+      const warningClass = renderAndGetBarClass(4100)
+      const errorClass = renderAndGetBarClass(5200)
 
-      const progressBar = screen.getByTestId('billing-progress-bar')
-      expect(progressBar).toHaveClass('bg-components-progress-warning-progress')
-    })
-
-    it('should show warning color when Team plan usage approaches limit (80%+)', () => {
-      mockPlanType = Plan.team
-      // 20480 MB * 80% = 16384 MB
-      mockVectorSpaceUsage = 16500
-
-      render(<VectorSpaceInfo />)
-
-      const progressBar = screen.getByTestId('billing-progress-bar')
-      expect(progressBar).toHaveClass('bg-components-progress-warning-progress')
-    })
-  })
-
-  describe('Pro/Team Plan Error State', () => {
-    it('should show error color when Professional plan usage exceeds limit', () => {
-      mockPlanType = Plan.professional
-      // Exceeds 5120 MB
-      mockVectorSpaceUsage = 5200
-
-      render(<VectorSpaceInfo />)
-
-      const progressBar = screen.getByTestId('billing-progress-bar')
-      expect(progressBar).toHaveClass('bg-components-progress-error-progress')
-    })
-
-    it('should show error color when Team plan usage exceeds limit', () => {
-      mockPlanType = Plan.team
-      // Exceeds 20480 MB
-      mockVectorSpaceUsage = 21000
-
-      render(<VectorSpaceInfo />)
-
-      const progressBar = screen.getByTestId('billing-progress-bar')
-      expect(progressBar).toHaveClass('bg-components-progress-error-progress')
+      expect(normalClass).not.toBe(warningClass)
+      expect(warningClass).not.toBe(errorClass)
+      expect(normalClass).not.toBe(errorClass)
     })
   })
 
@@ -265,12 +220,10 @@ describe('VectorSpaceInfo', () => {
       expect(screen.getByTestId('billing-progress-bar-indeterminate')).toBeInTheDocument()
     })
 
-    it('should render narrow indeterminate bar (not full width) for enterprise', () => {
+    it('should render indeterminate bar for enterprise below threshold', () => {
       render(<VectorSpaceInfo />)
 
-      const bar = screen.getByTestId('billing-progress-bar-indeterminate')
-      expect(bar).toHaveClass('w-[30px]')
-      expect(bar).not.toHaveClass('w-full')
+      expect(screen.getByTestId('billing-progress-bar-indeterminate')).toBeInTheDocument()
     })
 
     it('should display "< 50 / total" format when below threshold', () => {

web/app/components/custom/custom-page/__tests__/index.spec.tsx

@@ -6,11 +6,8 @@ import { createMockProviderContextValue } from '@/__mocks__/provider-context'
 import { contactSalesUrl } from '@/app/components/billing/config'
 import { Plan } from '@/app/components/billing/type'
 import { useModalContext } from '@/context/modal-context'
-// Get the mocked functions
-// const { useProviderContext } = vi.requireMock('@/context/provider-context')
-// const { useModalContext } = vi.requireMock('@/context/modal-context')
 import { useProviderContext } from '@/context/provider-context'
-import CustomPage from './index'
+import CustomPage from '../index'
 
 // Mock external dependencies only
 vi.mock('@/context/provider-context', () => ({
@@ -23,7 +20,7 @@ vi.mock('@/context/modal-context', () => ({
 
 // Mock the complex CustomWebAppBrand component to avoid dependency issues
 // This is acceptable because it has complex dependencies (fetch, APIs)
-vi.mock('../custom-web-app-brand', () => ({
+vi.mock('@/app/components/custom/custom-web-app-brand', () => ({
   default: () => <div data-testid="custom-web-app-brand">CustomWebAppBrand</div>,
 }))
 

web/app/components/custom/custom-web-app-brand/__tests__/index.spec.tsx

@@ -7,7 +7,7 @@ import { useAppContext } from '@/context/app-context'
 import { useGlobalPublicStore } from '@/context/global-public-context'
 import { useProviderContext } from '@/context/provider-context'
 import { updateCurrentWorkspace } from '@/service/common'
-import CustomWebAppBrand from './index'
+import CustomWebAppBrand from '../index'
 
 vi.mock('@/app/components/base/toast', () => ({
   useToastContext: vi.fn(),
@@ -53,8 +53,8 @@ const renderComponent = () => render(<CustomWebAppBrand />)
 describe('CustomWebAppBrand', () => {
   beforeEach(() => {
     vi.clearAllMocks()
-    mockUseToastContext.mockReturnValue({ notify: mockNotify } as any)
-    mockUpdateCurrentWorkspace.mockResolvedValue({} as any)
+    mockUseToastContext.mockReturnValue({ notify: mockNotify } as unknown as ReturnType<typeof useToastContext>)
+    mockUpdateCurrentWorkspace.mockResolvedValue({} as unknown as Awaited<ReturnType<typeof updateCurrentWorkspace>>)
     mockUseAppContext.mockReturnValue({
       currentWorkspace: {
         custom_config: {
@@ -64,7 +64,7 @@ describe('CustomWebAppBrand', () => {
       },
       mutateCurrentWorkspace: vi.fn(),
       isCurrentWorkspaceManager: true,
-    } as any)
+    } as unknown as ReturnType<typeof useAppContext>)
     mockUseProviderContext.mockReturnValue({
       plan: {
         type: Plan.professional,
@@ -73,14 +73,14 @@ describe('CustomWebAppBrand', () => {
         reset: {},
       },
       enableBilling: false,
-    } as any)
+    } as unknown as ReturnType<typeof useProviderContext>)
     const systemFeaturesState = {
       branding: {
         enabled: true,
         workspace_logo: 'https://example.com/workspace-logo.png',
       },
     }
-    mockUseGlobalPublicStore.mockImplementation(selector => selector ? selector({ systemFeatures: systemFeaturesState } as any) : { systemFeatures: systemFeaturesState })
+    mockUseGlobalPublicStore.mockImplementation(selector => selector ? selector({ systemFeatures: systemFeaturesState, setSystemFeatures: vi.fn() } as unknown as ReturnType<typeof useGlobalPublicStore.getState>) : { systemFeatures: systemFeaturesState })
     mockGetImageUploadErrorMessage.mockReturnValue('upload error')
   })
 
@@ -94,7 +94,7 @@ describe('CustomWebAppBrand', () => {
       },
       mutateCurrentWorkspace: vi.fn(),
       isCurrentWorkspaceManager: false,
-    } as any)
+    } as unknown as ReturnType<typeof useAppContext>)
 
     const { container } = renderComponent()
     const fileInput = container.querySelector('input[type="file"]') as HTMLInputElement
@@ -112,7 +112,7 @@ describe('CustomWebAppBrand', () => {
       },
       mutateCurrentWorkspace: mutateMock,
       isCurrentWorkspaceManager: true,
-    } as any)
+    } as unknown as ReturnType<typeof useAppContext>)
 
     renderComponent()
     const switchInput = screen.getByRole('switch')

web/app/components/datasets/common/image-uploader/__tests__/constants.spec.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import {
+  ACCEPT_TYPES,
+  DEFAULT_IMAGE_FILE_BATCH_LIMIT,
+  DEFAULT_IMAGE_FILE_SIZE_LIMIT,
+  DEFAULT_SINGLE_CHUNK_ATTACHMENT_LIMIT,
+} from '../constants'
+
+describe('image-uploader constants', () => {
+  // Verify accepted image types
+  describe('ACCEPT_TYPES', () => {
+    it('should include standard image formats', () => {
+      expect(ACCEPT_TYPES).toContain('jpg')
+      expect(ACCEPT_TYPES).toContain('jpeg')
+      expect(ACCEPT_TYPES).toContain('png')
+      expect(ACCEPT_TYPES).toContain('gif')
+    })
+
+    it('should have exactly 4 types', () => {
+      expect(ACCEPT_TYPES).toHaveLength(4)
+    })
+  })
+
+  // Verify numeric limits are positive
+  describe('Limits', () => {
+    it('should have a positive file size limit', () => {
+      expect(DEFAULT_IMAGE_FILE_SIZE_LIMIT).toBeGreaterThan(0)
+      expect(DEFAULT_IMAGE_FILE_SIZE_LIMIT).toBe(2)
+    })
+
+    it('should have a positive batch limit', () => {
+      expect(DEFAULT_IMAGE_FILE_BATCH_LIMIT).toBeGreaterThan(0)
+      expect(DEFAULT_IMAGE_FILE_BATCH_LIMIT).toBe(5)
+    })
+
+    it('should have a positive single chunk attachment limit', () => {
+      expect(DEFAULT_SINGLE_CHUNK_ATTACHMENT_LIMIT).toBeGreaterThan(0)
+      expect(DEFAULT_SINGLE_CHUNK_ATTACHMENT_LIMIT).toBe(10)
+    })
+  })
+})

web/app/components/datasets/create/__tests__/icons.spec.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { indexMethodIcon, retrievalIcon } from '../icons'
+
+describe('create/icons', () => {
+  // Verify icon map exports have expected keys
+  describe('indexMethodIcon', () => {
+    it('should have high_quality and economical keys', () => {
+      expect(indexMethodIcon).toHaveProperty('high_quality')
+      expect(indexMethodIcon).toHaveProperty('economical')
+    })
+
+    it('should have truthy values for each key', () => {
+      expect(indexMethodIcon.high_quality).toBeTruthy()
+      expect(indexMethodIcon.economical).toBeTruthy()
+    })
+  })
+
+  describe('retrievalIcon', () => {
+    it('should have vector, fullText, and hybrid keys', () => {
+      expect(retrievalIcon).toHaveProperty('vector')
+      expect(retrievalIcon).toHaveProperty('fullText')
+      expect(retrievalIcon).toHaveProperty('hybrid')
+    })
+
+    it('should have truthy values for each key', () => {
+      expect(retrievalIcon.vector).toBeTruthy()
+      expect(retrievalIcon.fullText).toBeTruthy()
+      expect(retrievalIcon.hybrid).toBeTruthy()
+    })
+  })
+})

web/app/components/datasets/create/file-uploader/__tests__/constants.spec.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import {
+  PROGRESS_COMPLETE,
+  PROGRESS_ERROR,
+  PROGRESS_NOT_STARTED,
+} from '../constants'
+
+describe('file-uploader constants', () => {
+  // Verify progress sentinel values
+  describe('Progress Sentinels', () => {
+    it('should define PROGRESS_NOT_STARTED as -1', () => {
+      expect(PROGRESS_NOT_STARTED).toBe(-1)
+    })
+
+    it('should define PROGRESS_ERROR as -2', () => {
+      expect(PROGRESS_ERROR).toBe(-2)
+    })
+
+    it('should define PROGRESS_COMPLETE as 100', () => {
+      expect(PROGRESS_COMPLETE).toBe(100)
+    })
+
+    it('should have distinct values for all sentinels', () => {
+      const values = [PROGRESS_NOT_STARTED, PROGRESS_ERROR, PROGRESS_COMPLETE]
+      expect(new Set(values).size).toBe(values.length)
+    })
+
+    it('should have negative values for non-progress states', () => {
+      expect(PROGRESS_NOT_STARTED).toBeLessThan(0)
+      expect(PROGRESS_ERROR).toBeLessThan(0)
+    })
+  })
+})

web/app/components/datasets/documents/components/__tests__/list.spec.tsx

@@ -0,0 +1,240 @@
+import type { SimpleDocumentDetail } from '@/models/datasets'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { useDocumentSort } from '../document-list/hooks'
+import DocumentList from '../list'
+
+// Mock hooks used by DocumentList
+const mockHandleSort = vi.fn()
+const mockOnSelectAll = vi.fn()
+const mockOnSelectOne = vi.fn()
+const mockClearSelection = vi.fn()
+const mockHandleAction = vi.fn(() => vi.fn())
+const mockHandleBatchReIndex = vi.fn()
+const mockHandleBatchDownload = vi.fn()
+const mockShowEditModal = vi.fn()
+const mockHideEditModal = vi.fn()
+const mockHandleSave = vi.fn()
+
+vi.mock('../document-list/hooks', () => ({
+  useDocumentSort: vi.fn(() => ({
+    sortField: null,
+    sortOrder: null,
+    handleSort: mockHandleSort,
+    sortedDocuments: [],
+  })),
+  useDocumentSelection: vi.fn(() => ({
+    isAllSelected: false,
+    isSomeSelected: false,
+    onSelectAll: mockOnSelectAll,
+    onSelectOne: mockOnSelectOne,
+    hasErrorDocumentsSelected: false,
+    downloadableSelectedIds: [],
+    clearSelection: mockClearSelection,
+  })),
+  useDocumentActions: vi.fn(() => ({
+    handleAction: mockHandleAction,
+    handleBatchReIndex: mockHandleBatchReIndex,
+    handleBatchDownload: mockHandleBatchDownload,
+  })),
+}))
+
+vi.mock('@/app/components/datasets/metadata/hooks/use-batch-edit-document-metadata', () => ({
+  default: vi.fn(() => ({
+    isShowEditModal: false,
+    showEditModal: mockShowEditModal,
+    hideEditModal: mockHideEditModal,
+    originalList: [],
+    handleSave: mockHandleSave,
+  })),
+}))
+
+vi.mock('@/context/dataset-detail', () => ({
+  useDatasetDetailContextWithSelector: () => ({
+    doc_form: 'text_model',
+  }),
+}))
+
+// Mock child components that are complex
+vi.mock('../document-list/components', () => ({
+  DocumentTableRow: ({ doc, index }: { doc: SimpleDocumentDetail, index: number }) => (
+    <tr data-testid={`doc-row-${doc.id}`}>
+      <td>{index + 1}</td>
+      <td>{doc.name}</td>
+    </tr>
+  ),
+  renderTdValue: (val: string) => val || '-',
+  SortHeader: ({ field, label, onSort }: { field: string, label: string, onSort: (f: string) => void }) => (
+    <button data-testid={`sort-${field}`} onClick={() => onSort(field)}>{label}</button>
+  ),
+}))
+
+vi.mock('../../detail/completed/common/batch-action', () => ({
+  default: ({ selectedIds, onCancel }: { selectedIds: string[], onCancel: () => void }) => (
+    <div data-testid="batch-action">
+      <span data-testid="selected-count">{selectedIds.length}</span>
+      <button data-testid="cancel-selection" onClick={onCancel}>Cancel</button>
+    </div>
+  ),
+}))
+
+vi.mock('../../rename-modal', () => ({
+  default: ({ name, onClose }: { name: string, onClose: () => void }) => (
+    <div data-testid="rename-modal">
+      <span>{name}</span>
+      <button onClick={onClose}>Close</button>
+    </div>
+  ),
+}))
+
+vi.mock('@/app/components/datasets/metadata/edit-metadata-batch/modal', () => ({
+  default: ({ onHide }: { onHide: () => void }) => (
+    <div data-testid="edit-metadata-modal">
+      <button onClick={onHide}>Hide</button>
+    </div>
+  ),
+}))
+
+function createDoc(overrides: Partial<SimpleDocumentDetail> = {}): SimpleDocumentDetail {
+  return {
+    id: `doc-${Math.random().toString(36).slice(2, 8)}`,
+    name: 'Test Doc',
+    position: 1,
+    data_source_type: 'upload_file',
+    word_count: 100,
+    hit_count: 5,
+    indexing_status: 'completed',
+    enabled: true,
+    disabled_at: null,
+    disabled_by: null,
+    archived: false,
+    display_status: 'available',
+    created_from: 'web',
+    created_at: 1234567890,
+    ...overrides,
+  } as SimpleDocumentDetail
+}
+
+const defaultProps = {
+  embeddingAvailable: true,
+  documents: [] as SimpleDocumentDetail[],
+  selectedIds: [] as string[],
+  onSelectedIdChange: vi.fn(),
+  datasetId: 'ds-1',
+  pagination: { total: 0, current: 1, limit: 10, onChange: vi.fn() },
+  onUpdate: vi.fn(),
+  onManageMetadata: vi.fn(),
+  statusFilterValue: 'all',
+  remoteSortValue: '',
+}
+
+describe('DocumentList', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // Verify the table renders with column headers
+  describe('Rendering', () => {
+    it('should render the document table with headers', () => {
+      render(<DocumentList {...defaultProps} />)
+
+      expect(screen.getByText('#')).toBeInTheDocument()
+      expect(screen.getByTestId('sort-name')).toBeInTheDocument()
+      expect(screen.getByTestId('sort-word_count')).toBeInTheDocument()
+      expect(screen.getByTestId('sort-hit_count')).toBeInTheDocument()
+      expect(screen.getByTestId('sort-created_at')).toBeInTheDocument()
+    })
+
+    it('should render select-all area when embeddingAvailable is true', () => {
+      const { container } = render(<DocumentList {...defaultProps} embeddingAvailable={true} />)
+
+      // Checkbox component renders inside the first td
+      const firstTd = container.querySelector('thead td')
+      expect(firstTd?.textContent).toContain('#')
+    })
+
+    it('should still render # column when embeddingAvailable is false', () => {
+      const { container } = render(<DocumentList {...defaultProps} embeddingAvailable={false} />)
+
+      const firstTd = container.querySelector('thead td')
+      expect(firstTd?.textContent).toContain('#')
+    })
+
+    it('should render document rows from sortedDocuments', () => {
+      const docs = [createDoc({ id: 'a', name: 'Doc A' }), createDoc({ id: 'b', name: 'Doc B' })]
+      vi.mocked(useDocumentSort).mockReturnValue({
+        sortField: null,
+        sortOrder: 'desc',
+        handleSort: mockHandleSort,
+        sortedDocuments: docs,
+      } as unknown as ReturnType<typeof useDocumentSort>)
+
+      render(<DocumentList {...defaultProps} documents={docs} />)
+
+      expect(screen.getByTestId('doc-row-a')).toBeInTheDocument()
+      expect(screen.getByTestId('doc-row-b')).toBeInTheDocument()
+    })
+  })
+
+  // Verify sort headers trigger sort handler
+  describe('Sorting', () => {
+    it('should call handleSort when sort header is clicked', () => {
+      render(<DocumentList {...defaultProps} />)
+
+      fireEvent.click(screen.getByTestId('sort-name'))
+
+      expect(mockHandleSort).toHaveBeenCalledWith('name')
+    })
+  })
+
+  // Verify batch action bar appears when items selected
+  describe('Batch Actions', () => {
+    it('should show batch action bar when selectedIds is non-empty', () => {
+      render(<DocumentList {...defaultProps} selectedIds={['doc-1']} />)
+
+      expect(screen.getByTestId('batch-action')).toBeInTheDocument()
+      expect(screen.getByTestId('selected-count')).toHaveTextContent('1')
+    })
+
+    it('should not show batch action bar when no items selected', () => {
+      render(<DocumentList {...defaultProps} selectedIds={[]} />)
+
+      expect(screen.queryByTestId('batch-action')).not.toBeInTheDocument()
+    })
+
+    it('should call clearSelection when cancel is clicked in batch bar', () => {
+      render(<DocumentList {...defaultProps} selectedIds={['doc-1']} />)
+
+      fireEvent.click(screen.getByTestId('cancel-selection'))
+
+      expect(mockClearSelection).toHaveBeenCalled()
+    })
+  })
+
+  // Verify pagination renders when total > 0
+  describe('Pagination', () => {
+    it('should not render pagination when total is 0', () => {
+      const { container } = render(<DocumentList {...defaultProps} />)
+
+      expect(container.querySelector('[class*="pagination"]')).not.toBeInTheDocument()
+    })
+  })
+
+  // Verify empty state
+  describe('Edge Cases', () => {
+    it('should render table with no document rows when sortedDocuments is empty', () => {
+      // Reset sort mock to return empty sorted list
+      vi.mocked(useDocumentSort).mockReturnValue({
+        sortField: null,
+        sortOrder: 'desc',
+        handleSort: mockHandleSort,
+        sortedDocuments: [],
+      } as unknown as ReturnType<typeof useDocumentSort>)
+
+      render(<DocumentList {...defaultProps} documents={[]} />)
+
+      expect(screen.queryByTestId(/^doc-row-/)).not.toBeInTheDocument()
+    })
+  })
+})

web/app/components/datasets/documents/create-from-pipeline/process-documents/__tests__/form.spec.tsx

@@ -0,0 +1,167 @@
+import type { BaseConfiguration } from '@/app/components/base/form/form-scenarios/base/types'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import Toast from '@/app/components/base/toast'
+
+import Form from '../form'
+
+// Mock the Header component (sibling component, not a base component)
+vi.mock('../header', () => ({
+  default: ({ onReset, resetDisabled, onPreview, previewDisabled }: {
+    onReset: () => void
+    resetDisabled: boolean
+    onPreview: () => void
+    previewDisabled: boolean
+  }) => (
+    <div data-testid="form-header">
+      <button data-testid="reset-btn" onClick={onReset} disabled={resetDisabled}>Reset</button>
+      <button data-testid="preview-btn" onClick={onPreview} disabled={previewDisabled}>Preview</button>
+    </div>
+  ),
+}))
+
+const schema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  value: z.string().optional(),
+})
+
+const defaultConfigs: BaseConfiguration[] = [
+  { variable: 'name', type: 'text-input', label: 'Name', required: true, showConditions: [] } as BaseConfiguration,
+  { variable: 'value', type: 'text-input', label: 'Value', required: false, showConditions: [] } as BaseConfiguration,
+]
+
+const defaultProps = {
+  initialData: { name: 'test', value: '' },
+  configurations: defaultConfigs,
+  schema,
+  onSubmit: vi.fn(),
+  onPreview: vi.fn(),
+  ref: { current: null },
+  isRunning: false,
+}
+
+describe('Form (process-documents)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.spyOn(Toast, 'notify').mockImplementation(() => ({ clear: vi.fn() }))
+  })
+
+  // Verify basic rendering of form structure
+  describe('Rendering', () => {
+    it('should render form with header and fields', () => {
+      render(<Form {...defaultProps} />)
+
+      expect(screen.getByTestId('form-header')).toBeInTheDocument()
+      expect(screen.getByText('Name')).toBeInTheDocument()
+      expect(screen.getByText('Value')).toBeInTheDocument()
+    })
+
+    it('should render all configuration fields', () => {
+      const configs: BaseConfiguration[] = [
+        { variable: 'a', type: 'text-input', label: 'A', required: false, showConditions: [] } as BaseConfiguration,
+        { variable: 'b', type: 'text-input', label: 'B', required: false, showConditions: [] } as BaseConfiguration,
+        { variable: 'c', type: 'text-input', label: 'C', required: false, showConditions: [] } as BaseConfiguration,
+      ]
+
+      render(<Form {...defaultProps} configurations={configs} initialData={{ a: '', b: '', c: '' }} />)
+
+      expect(screen.getByText('A')).toBeInTheDocument()
+      expect(screen.getByText('B')).toBeInTheDocument()
+      expect(screen.getByText('C')).toBeInTheDocument()
+    })
+  })
+
+  // Verify form submission behavior
+  describe('Form Submission', () => {
+    it('should call onSubmit with valid data on form submit', async () => {
+      render(<Form {...defaultProps} />)
+      const form = screen.getByTestId('form-header').closest('form')!
+
+      fireEvent.submit(form)
+
+      await waitFor(() => {
+        expect(defaultProps.onSubmit).toHaveBeenCalled()
+      })
+    })
+
+    it('should call onSubmit with valid data via imperative handle', async () => {
+      const ref = { current: null as { submit: () => void } | null }
+      render(<Form {...defaultProps} ref={ref} />)
+
+      ref.current?.submit()
+
+      await waitFor(() => {
+        expect(defaultProps.onSubmit).toHaveBeenCalled()
+      })
+    })
+  })
+
+  // Verify validation shows Toast on error
+  describe('Validation', () => {
+    it('should show toast error when validation fails', async () => {
+      render(<Form {...defaultProps} initialData={{ name: '', value: '' }} />)
+      const form = screen.getByTestId('form-header').closest('form')!
+
+      fireEvent.submit(form)
+
+      await waitFor(() => {
+        expect(Toast.notify).toHaveBeenCalledWith(
+          expect.objectContaining({ type: 'error' }),
+        )
+      })
+    })
+
+    it('should not show toast error when validation passes', async () => {
+      render(<Form {...defaultProps} />)
+      const form = screen.getByTestId('form-header').closest('form')!
+
+      fireEvent.submit(form)
+
+      await waitFor(() => {
+        expect(defaultProps.onSubmit).toHaveBeenCalled()
+      })
+      expect(Toast.notify).not.toHaveBeenCalled()
+    })
+  })
+
+  // Verify header button states
+  describe('Header Controls', () => {
+    it('should pass isRunning to previewDisabled', () => {
+      render(<Form {...defaultProps} isRunning={true} />)
+
+      expect(screen.getByTestId('preview-btn')).toBeDisabled()
+    })
+
+    it('should call onPreview when preview button is clicked', () => {
+      render(<Form {...defaultProps} />)
+
+      fireEvent.click(screen.getByTestId('preview-btn'))
+
+      expect(defaultProps.onPreview).toHaveBeenCalled()
+    })
+
+    it('should render reset button (disabled when form is not dirty)', () => {
+      render(<Form {...defaultProps} />)
+
+      // Reset button is rendered but disabled since form is not dirty initially
+      expect(screen.getByTestId('reset-btn')).toBeInTheDocument()
+      expect(screen.getByTestId('reset-btn')).toBeDisabled()
+    })
+  })
+
+  // Verify edge cases
+  describe('Edge Cases', () => {
+    it('should render with empty configurations array', () => {
+      render(<Form {...defaultProps} configurations={[]} />)
+
+      expect(screen.getByTestId('form-header')).toBeInTheDocument()
+    })
+
+    it('should render with empty initialData', () => {
+      render(<Form {...defaultProps} initialData={{}} configurations={[]} />)
+
+      expect(screen.getByTestId('form-header')).toBeInTheDocument()
+    })
+  })
+})

web/app/components/datasets/documents/detail/metadata/components/__tests__/doc-type-selector.spec.tsx

@@ -0,0 +1,147 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import DocTypeSelector, { DocumentTypeDisplay } from '../doc-type-selector'
+
+vi.mock('@/hooks/use-metadata', () => ({
+  useMetadataMap: () => ({
+    book: { text: 'Book', iconName: 'book' },
+    web_page: { text: 'Web Page', iconName: 'web' },
+    paper: { text: 'Paper', iconName: 'paper' },
+    social_media_post: { text: 'Social Media Post', iconName: 'social' },
+    personal_document: { text: 'Personal Document', iconName: 'personal' },
+    business_document: { text: 'Business Document', iconName: 'business' },
+    wikipedia_entry: { text: 'Wikipedia', iconName: 'wiki' },
+  }),
+}))
+
+vi.mock('@/models/datasets', async (importOriginal) => {
+  const actual = await importOriginal() as Record<string, unknown>
+  return {
+    ...actual,
+    CUSTOMIZABLE_DOC_TYPES: ['book', 'web_page', 'paper'],
+  }
+})
+
+describe('DocTypeSelector', () => {
+  const defaultProps = {
+    docType: '' as '' | 'book',
+    documentType: undefined as '' | 'book' | undefined,
+    tempDocType: '' as '' | 'book' | 'web_page',
+    onTempDocTypeChange: vi.fn(),
+    onConfirm: vi.fn(),
+    onCancel: vi.fn(),
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // Verify first-time setup UI (no existing doc type)
+  describe('First Time Selection', () => {
+    it('should render description and selection title when no doc type exists', () => {
+      render(<DocTypeSelector {...defaultProps} docType="" documentType={undefined} />)
+
+      expect(screen.getByText(/metadata\.desc/)).toBeInTheDocument()
+      expect(screen.getByText(/metadata\.docTypeSelectTitle/)).toBeInTheDocument()
+    })
+
+    it('should render icon buttons for each doc type', () => {
+      const { container } = render(<DocTypeSelector {...defaultProps} />)
+
+      // Each doc type renders an IconButton wrapped in Radio
+      const iconButtons = container.querySelectorAll('button[type="button"]')
+      // 3 doc types + 1 confirm button = 4 buttons
+      expect(iconButtons.length).toBeGreaterThanOrEqual(3)
+    })
+
+    it('should render confirm button disabled when tempDocType is empty', () => {
+      render(<DocTypeSelector {...defaultProps} tempDocType="" />)
+
+      const confirmBtn = screen.getByText(/metadata\.firstMetaAction/)
+      expect(confirmBtn.closest('button')).toBeDisabled()
+    })
+
+    it('should render confirm button enabled when tempDocType is set', () => {
+      render(<DocTypeSelector {...defaultProps} tempDocType="book" />)
+
+      const confirmBtn = screen.getByText(/metadata\.firstMetaAction/)
+      expect(confirmBtn.closest('button')).not.toBeDisabled()
+    })
+
+    it('should call onConfirm when confirm button is clicked', () => {
+      render(<DocTypeSelector {...defaultProps} tempDocType="book" />)
+
+      fireEvent.click(screen.getByText(/metadata\.firstMetaAction/))
+
+      expect(defaultProps.onConfirm).toHaveBeenCalled()
+    })
+  })
+
+  // Verify change-type UI (has existing doc type)
+  describe('Change Doc Type', () => {
+    it('should render change title and warning when documentType exists', () => {
+      render(<DocTypeSelector {...defaultProps} docType="book" documentType="book" />)
+
+      expect(screen.getByText(/metadata\.docTypeChangeTitle/)).toBeInTheDocument()
+      expect(screen.getByText(/metadata\.docTypeSelectWarning/)).toBeInTheDocument()
+    })
+
+    it('should render save and cancel buttons when documentType exists', () => {
+      render(<DocTypeSelector {...defaultProps} docType="book" documentType="book" />)
+
+      expect(screen.getByText(/operation\.save/)).toBeInTheDocument()
+      expect(screen.getByText(/operation\.cancel/)).toBeInTheDocument()
+    })
+
+    it('should call onCancel when cancel button is clicked', () => {
+      render(<DocTypeSelector {...defaultProps} docType="book" documentType="book" />)
+
+      fireEvent.click(screen.getByText(/operation\.cancel/))
+
+      expect(defaultProps.onCancel).toHaveBeenCalled()
+    })
+  })
+})
+
+describe('DocumentTypeDisplay', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // Verify read-only display of current doc type
+  describe('Rendering', () => {
+    it('should render the doc type text', () => {
+      render(<DocumentTypeDisplay displayType="book" />)
+
+      expect(screen.getByText('Book')).toBeInTheDocument()
+    })
+
+    it('should show change link when showChangeLink is true', () => {
+      render(<DocumentTypeDisplay displayType="book" showChangeLink={true} />)
+
+      expect(screen.getByText(/operation\.change/)).toBeInTheDocument()
+    })
+
+    it('should not show change link when showChangeLink is false', () => {
+      render(<DocumentTypeDisplay displayType="book" showChangeLink={false} />)
+
+      expect(screen.queryByText(/operation\.change/)).not.toBeInTheDocument()
+    })
+
+    it('should call onChangeClick when change link is clicked', () => {
+      const onClick = vi.fn()
+      render(<DocumentTypeDisplay displayType="book" showChangeLink={true} onChangeClick={onClick} />)
+
+      fireEvent.click(screen.getByText(/operation\.change/))
+
+      expect(onClick).toHaveBeenCalled()
+    })
+
+    it('should fallback to "book" display when displayType is empty and no change link', () => {
+      render(<DocumentTypeDisplay displayType="" showChangeLink={false} />)
+
+      expect(screen.getByText('Book')).toBeInTheDocument()
+    })
+  })
+})

web/app/components/datasets/documents/detail/metadata/components/__tests__/field-info.spec.tsx

@@ -0,0 +1,116 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import FieldInfo from '../field-info'
+
+vi.mock('@/utils', () => ({
+  getTextWidthWithCanvas: (text: string) => text.length * 8,
+}))
+
+describe('FieldInfo', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // Verify read-only rendering
+  describe('Read-Only Mode', () => {
+    it('should render label and displayed value', () => {
+      render(<FieldInfo label="Title" displayedValue="My Document" />)
+
+      expect(screen.getByText('Title')).toBeInTheDocument()
+      expect(screen.getByText('My Document')).toBeInTheDocument()
+    })
+
+    it('should render value icon when provided', () => {
+      render(
+        <FieldInfo
+          label="Status"
+          displayedValue="Active"
+          valueIcon={<span data-testid="icon">*</span>}
+        />,
+      )
+
+      expect(screen.getByTestId('icon')).toBeInTheDocument()
+    })
+
+    it('should render displayedValue as plain text when not editing', () => {
+      render(<FieldInfo label="Author" displayedValue="John" showEdit={false} />)
+
+      expect(screen.getByText('John')).toBeInTheDocument()
+      expect(screen.queryByRole('textbox')).not.toBeInTheDocument()
+    })
+  })
+
+  // Verify edit mode rendering for each inputType
+  describe('Edit Mode', () => {
+    it('should render input field by default in edit mode', () => {
+      render(<FieldInfo label="Title" value="Test" showEdit={true} inputType="input" />)
+
+      const input = screen.getByRole('textbox')
+      expect(input).toBeInTheDocument()
+      expect(input).toHaveValue('Test')
+    })
+
+    it('should render textarea when inputType is textarea', () => {
+      render(<FieldInfo label="Desc" value="Long text" showEdit={true} inputType="textarea" />)
+
+      const textarea = screen.getByRole('textbox')
+      expect(textarea).toBeInTheDocument()
+      expect(textarea).toHaveValue('Long text')
+    })
+
+    it('should render select when inputType is select', () => {
+      const options = [
+        { value: 'en', name: 'English' },
+        { value: 'zh', name: 'Chinese' },
+      ]
+      render(
+        <FieldInfo
+          label="Language"
+          value="en"
+          showEdit={true}
+          inputType="select"
+          selectOptions={options}
+        />,
+      )
+
+      // SimpleSelect renders a button-like trigger
+      expect(screen.getByText('English')).toBeInTheDocument()
+    })
+
+    it('should call onUpdate when input value changes', () => {
+      const onUpdate = vi.fn()
+      render(<FieldInfo label="Title" value="" showEdit={true} inputType="input" onUpdate={onUpdate} />)
+
+      fireEvent.change(screen.getByRole('textbox'), { target: { value: 'New' } })
+
+      expect(onUpdate).toHaveBeenCalledWith('New')
+    })
+
+    it('should call onUpdate when textarea value changes', () => {
+      const onUpdate = vi.fn()
+      render(<FieldInfo label="Desc" value="" showEdit={true} inputType="textarea" onUpdate={onUpdate} />)
+
+      fireEvent.change(screen.getByRole('textbox'), { target: { value: 'Updated' } })
+
+      expect(onUpdate).toHaveBeenCalledWith('Updated')
+    })
+  })
+
+  // Verify edge cases
+  describe('Edge Cases', () => {
+    it('should render with empty value and label', () => {
+      render(<FieldInfo label="" value="" displayedValue="" />)
+
+      // Should not crash
+      const container = document.querySelector('.flex.min-h-5')
+      expect(container).toBeInTheDocument()
+    })
+
+    it('should render with default value prop', () => {
+      render(<FieldInfo label="Field" showEdit={true} inputType="input" defaultValue="default" />)
+
+      expect(screen.getByRole('textbox')).toBeInTheDocument()
+    })
+  })
+})

web/app/components/datasets/documents/detail/metadata/components/__tests__/metadata-field-list.spec.tsx

@@ -0,0 +1,149 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import MetadataFieldList from '../metadata-field-list'
+
+vi.mock('@/hooks/use-metadata', () => ({
+  useMetadataMap: () => ({
+    book: {
+      text: 'Book',
+      subFieldsMap: {
+        title: { label: 'Title', inputType: 'input' },
+        language: { label: 'Language', inputType: 'select' },
+        author: { label: 'Author', inputType: 'input' },
+      },
+    },
+    originInfo: {
+      text: 'Origin Info',
+      subFieldsMap: {
+        source: { label: 'Source', inputType: 'input' },
+        hit_count: { label: 'Hit Count', inputType: 'input', render: (val: number, segCount?: number) => `${val} / ${segCount}` },
+      },
+    },
+  }),
+  useLanguages: () => ({ en: 'English', zh: 'Chinese' }),
+  useBookCategories: () => ({ fiction: 'Fiction', nonfiction: 'Non-fiction' }),
+  usePersonalDocCategories: () => ({}),
+  useBusinessDocCategories: () => ({}),
+}))
+
+describe('MetadataFieldList', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // Verify rendering of metadata fields based on mainField
+  describe('Rendering', () => {
+    it('should render all fields for the given mainField', () => {
+      render(
+        <MetadataFieldList
+          mainField="book"
+          metadata={{ title: 'Test Book', language: 'en', author: 'John' }}
+        />,
+      )
+
+      expect(screen.getByText('Title')).toBeInTheDocument()
+      expect(screen.getByText('Language')).toBeInTheDocument()
+      expect(screen.getByText('Author')).toBeInTheDocument()
+    })
+
+    it('should return null when mainField is empty', () => {
+      const { container } = render(
+        <MetadataFieldList mainField="" metadata={{}} />,
+      )
+
+      expect(container.firstChild).toBeNull()
+    })
+
+    it('should display "-" for missing field values', () => {
+      render(
+        <MetadataFieldList
+          mainField="book"
+          metadata={{}}
+        />,
+      )
+
+      // All three fields should show "-"
+      const dashes = screen.getAllByText('-')
+      expect(dashes.length).toBeGreaterThanOrEqual(3)
+    })
+
+    it('should resolve select values to their display name', () => {
+      render(
+        <MetadataFieldList
+          mainField="book"
+          metadata={{ language: 'en' }}
+        />,
+      )
+
+      expect(screen.getByText('English')).toBeInTheDocument()
+    })
+  })
+
+  // Verify edit mode passes correct props
+  describe('Edit Mode', () => {
+    it('should render fields in edit mode when canEdit is true', () => {
+      render(
+        <MetadataFieldList
+          mainField="book"
+          canEdit={true}
+          metadata={{ title: 'Book Title' }}
+        />,
+      )
+
+      // In edit mode, FieldInfo renders input elements
+      const inputs = screen.getAllByRole('textbox')
+      expect(inputs.length).toBeGreaterThan(0)
+    })
+
+    it('should call onFieldUpdate when a field value changes', () => {
+      const onUpdate = vi.fn()
+      render(
+        <MetadataFieldList
+          mainField="book"
+          canEdit={true}
+          metadata={{ title: '' }}
+          onFieldUpdate={onUpdate}
+        />,
+      )
+
+      // Find the first textbox and type in it
+      const inputs = screen.getAllByRole('textbox')
+      fireEvent.change(inputs[0], { target: { value: 'New Title' } })
+
+      expect(onUpdate).toHaveBeenCalled()
+    })
+  })
+
+  // Verify fixed field types use docDetail as source
+  describe('Fixed Field Types', () => {
+    it('should use docDetail as source data for originInfo type', () => {
+      const docDetail = { source: 'Web', hit_count: 42, segment_count: 10 }
+
+      render(
+        <MetadataFieldList
+          mainField="originInfo"
+          docDetail={docDetail as never}
+          metadata={{}}
+        />,
+      )
+
+      expect(screen.getByText('Source')).toBeInTheDocument()
+      expect(screen.getByText('Web')).toBeInTheDocument()
+    })
+
+    it('should render custom render function output for fields with render', () => {
+      const docDetail = { source: 'API', hit_count: 15, segment_count: 5 }
+
+      render(
+        <MetadataFieldList
+          mainField="originInfo"
+          docDetail={docDetail as never}
+          metadata={{}}
+        />,
+      )
+
+      expect(screen.getByText('15 / 5')).toBeInTheDocument()
+    })
+  })
+})

web/app/components/datasets/documents/detail/metadata/hooks/__tests__/use-metadata-state.spec.ts

@@ -0,0 +1,164 @@
+import type { ReactNode } from 'react'
+import type { FullDocumentDetail } from '@/models/datasets'
+import { act, renderHook } from '@testing-library/react'
+import * as React from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { ToastContext } from '@/app/components/base/toast'
+
+import { useMetadataState } from '../use-metadata-state'
+
+const { mockNotify, mockModifyDocMetadata } = vi.hoisted(() => ({
+  mockNotify: vi.fn(),
+  mockModifyDocMetadata: vi.fn(),
+}))
+
+vi.mock('../../../context', () => ({
+  useDocumentContext: (selector: (state: { datasetId: string, documentId: string }) => unknown) =>
+    selector({ datasetId: 'ds-1', documentId: 'doc-1' }),
+}))
+
+vi.mock('@/service/datasets', () => ({
+  modifyDocMetadata: (...args: unknown[]) => mockModifyDocMetadata(...args),
+}))
+
+vi.mock('@/hooks/use-metadata', () => ({ useMetadataMap: () => ({}) }))
+
+vi.mock('@/utils', () => ({
+  asyncRunSafe: async (promise: Promise<unknown>) => {
+    try {
+      return [null, await promise]
+    }
+    catch (e) { return [e] }
+  },
+}))
+
+// Wrapper that provides ToastContext with the mock notify function
+const wrapper = ({ children }: { children: ReactNode }) =>
+  React.createElement(ToastContext.Provider, { value: { notify: mockNotify, close: vi.fn() }, children })
+
+type DocDetail = Parameters<typeof useMetadataState>[0]['docDetail']
+
+const makeDoc = (overrides: Partial<FullDocumentDetail> = {}): DocDetail =>
+  ({ doc_type: 'book', doc_metadata: { title: 'Test Book', author: 'Author' }, ...overrides } as DocDetail)
+
+describe('useMetadataState', () => {
+  // Verify all metadata editing workflows using a stable docDetail reference
+  it('should manage the full metadata editing lifecycle', async () => {
+    mockModifyDocMetadata.mockResolvedValue({ result: 'ok' })
+    const onUpdate = vi.fn()
+
+    // IMPORTANT: Create a stable reference outside the render callback
+    // to prevent useEffect infinite loops on docDetail?.doc_metadata
+    const stableDocDetail = makeDoc()
+
+    const { result } = renderHook(() =>
+      useMetadataState({ docDetail: stableDocDetail, onUpdate }), { wrapper })
+
+    // --- Initialization ---
+    expect(result.current.docType).toBe('book')
+    expect(result.current.editStatus).toBe(false)
+    expect(result.current.showDocTypes).toBe(false)
+    expect(result.current.metadataParams.documentType).toBe('book')
+    expect(result.current.metadataParams.metadata).toEqual({ title: 'Test Book', author: 'Author' })
+
+    // --- Enable editing ---
+    act(() => {
+      result.current.enableEdit()
+    })
+    expect(result.current.editStatus).toBe(true)
+
+    // --- Update individual field ---
+    act(() => {
+      result.current.updateMetadataField('title', 'Modified Title')
+    })
+    expect(result.current.metadataParams.metadata.title).toBe('Modified Title')
+    expect(result.current.metadataParams.metadata.author).toBe('Author')
+
+    // --- Cancel edit restores original data ---
+    act(() => {
+      result.current.cancelEdit()
+    })
+    expect(result.current.metadataParams.metadata.title).toBe('Test Book')
+    expect(result.current.editStatus).toBe(false)
+
+    // --- Doc type selection: cancel restores previous ---
+    act(() => {
+      result.current.enableEdit()
+    })
+    act(() => {
+      result.current.setShowDocTypes(true)
+    })
+    act(() => {
+      result.current.setTempDocType('web_page')
+    })
+    act(() => {
+      result.current.cancelDocType()
+    })
+    expect(result.current.tempDocType).toBe('book')
+    expect(result.current.showDocTypes).toBe(false)
+
+    // --- Confirm different doc type clears metadata ---
+    act(() => {
+      result.current.setShowDocTypes(true)
+    })
+    act(() => {
+      result.current.setTempDocType('web_page')
+    })
+    act(() => {
+      result.current.confirmDocType()
+    })
+    expect(result.current.metadataParams.documentType).toBe('web_page')
+    expect(result.current.metadataParams.metadata).toEqual({})
+
+    // --- Save succeeds ---
+    await act(async () => {
+      await result.current.saveMetadata()
+    })
+    expect(mockModifyDocMetadata).toHaveBeenCalledWith({
+      datasetId: 'ds-1',
+      documentId: 'doc-1',
+      body: { doc_type: 'web_page', doc_metadata: {} },
+    })
+    expect(mockNotify).toHaveBeenCalledWith(expect.objectContaining({ type: 'success' }))
+    expect(onUpdate).toHaveBeenCalled()
+    expect(result.current.editStatus).toBe(false)
+    expect(result.current.saveLoading).toBe(false)
+
+    // --- Save failure notifies error ---
+    mockNotify.mockClear()
+    mockModifyDocMetadata.mockRejectedValue(new Error('fail'))
+    act(() => {
+      result.current.enableEdit()
+    })
+    await act(async () => {
+      await result.current.saveMetadata()
+    })
+    expect(mockNotify).toHaveBeenCalledWith(expect.objectContaining({ type: 'error' }))
+  })
+
+  // Verify empty doc type starts in editing mode
+  it('should initialize in editing mode when no doc type exists', () => {
+    const stableDocDetail = makeDoc({ doc_type: '' as FullDocumentDetail['doc_type'], doc_metadata: {} as FullDocumentDetail['doc_metadata'] })
+    const { result } = renderHook(() => useMetadataState({ docDetail: stableDocDetail }), { wrapper })
+
+    expect(result.current.docType).toBe('')
+    expect(result.current.editStatus).toBe(true)
+    expect(result.current.showDocTypes).toBe(true)
+  })
+
+  // Verify "others" normalization
+  it('should normalize "others" doc_type to empty string', () => {
+    const stableDocDetail = makeDoc({ doc_type: 'others' as FullDocumentDetail['doc_type'] })
+    const { result } = renderHook(() => useMetadataState({ docDetail: stableDocDetail }), { wrapper })
+
+    expect(result.current.docType).toBe('')
+  })
+
+  // Verify undefined docDetail handling
+  it('should handle undefined docDetail gracefully', () => {
+    const { result } = renderHook(() => useMetadataState({ docDetail: undefined }), { wrapper })
+
+    expect(result.current.docType).toBe('')
+    expect(result.current.editStatus).toBe(true)
+  })
+})

web/app/components/datasets/hit-testing/components/query-input/__tests__/index.spec.tsx

@@ -1,40 +1,49 @@
+import type { FileEntity } from '@/app/components/datasets/common/image-uploader/types'
 import type { Query } from '@/models/datasets'
 import type { RetrievalConfig } from '@/types/app'
-import { render, screen } from '@testing-library/react'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import QueryInput from '../index'
 
-vi.mock('uuid', () => ({
-  v4: () => 'mock-uuid',
-}))
-
-vi.mock('@/app/components/base/button', () => ({
-  default: ({ children, onClick, disabled, loading }: { children: React.ReactNode, onClick: () => void, disabled?: boolean, loading?: boolean }) => (
-    <button data-testid="submit-button" onClick={onClick} disabled={disabled || loading}>
-      {children}
-    </button>
-  ),
-}))
-
+// Capture onChange callback so tests can trigger handleImageChange
+let capturedOnChange: ((files: FileEntity[]) => void) | null = null
 vi.mock('@/app/components/datasets/common/image-uploader/image-uploader-in-retrieval-testing', () => ({
-  default: ({ textArea, actionButton }: { textArea: React.ReactNode, actionButton: React.ReactNode }) => (
-    <div data-testid="image-uploader">
-      {textArea}
-      {actionButton}
-    </div>
-  ),
+  default: ({ textArea, actionButton, onChange }: { textArea: React.ReactNode, actionButton: React.ReactNode, onChange?: (files: FileEntity[]) => void }) => {
+    capturedOnChange = onChange ?? null
+    return (
+      <div data-testid="image-uploader">
+        {textArea}
+        {actionButton}
+      </div>
+    )
+  },
 }))
 
 vi.mock('@/app/components/datasets/common/retrieval-method-info', () => ({
   getIcon: () => '/test-icon.png',
 }))
 
+// Capture onSave callback for external retrieval modal
+let _capturedModalOnSave: ((data: { top_k: number, score_threshold: number, score_threshold_enabled: boolean }) => void) | null = null
 vi.mock('@/app/components/datasets/hit-testing/modify-external-retrieval-modal', () => ({
-  default: () => <div data-testid="external-retrieval-modal" />,
+  default: ({ onSave, onClose }: { onSave: (data: { top_k: number, score_threshold: number, score_threshold_enabled: boolean }) => void, onClose: () => void }) => {
+    _capturedModalOnSave = onSave
+    return (
+      <div data-testid="external-retrieval-modal">
+        <button data-testid="modal-save" onClick={() => onSave({ top_k: 10, score_threshold: 0.8, score_threshold_enabled: true })}>Save</button>
+        <button data-testid="modal-close" onClick={onClose}>Close</button>
+      </div>
+    )
+  },
 }))
 
+// Capture handleTextChange callback
+let _capturedHandleTextChange: ((e: React.ChangeEvent<HTMLTextAreaElement>) => void) | null = null
 vi.mock('../textarea', () => ({
-  default: ({ text }: { text: string }) => <textarea data-testid="textarea" defaultValue={text} />,
+  default: ({ text, handleTextChange }: { text: string, handleTextChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void }) => {
+    _capturedHandleTextChange = handleTextChange
+    return <textarea data-testid="textarea" defaultValue={text} onChange={handleTextChange} />
+  },
 }))
 
 vi.mock('@/context/dataset-detail', () => ({
@@ -42,7 +51,8 @@ vi.mock('@/context/dataset-detail', () => ({
 }))
 
 describe('QueryInput', () => {
-  const defaultProps = {
+  // Re-create per test to avoid cross-test mutation (handleTextChange mutates query objects)
+  const makeDefaultProps = () => ({
     onUpdateList: vi.fn(),
     setHitResult: vi.fn(),
     setExternalHitResult: vi.fn(),
@@ -55,10 +65,16 @@ describe('QueryInput', () => {
     isEconomy: false,
     hitTestingMutation: vi.fn(),
     externalKnowledgeBaseHitTestingMutation: vi.fn(),
-  }
+  })
+
+  let defaultProps: ReturnType<typeof makeDefaultProps>
 
   beforeEach(() => {
     vi.clearAllMocks()
+    defaultProps = makeDefaultProps()
+    capturedOnChange = null
+    _capturedModalOnSave = null
+    _capturedHandleTextChange = null
   })
 
   it('should render title', () => {
@@ -73,7 +89,7 @@ describe('QueryInput', () => {
 
   it('should render submit button', () => {
     render(<QueryInput {...defaultProps} />)
-    expect(screen.getByTestId('submit-button')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: /input\.testing/ })).toBeInTheDocument()
   })
 
   it('should disable submit button when text is empty', () => {
@@ -82,7 +98,7 @@ describe('QueryInput', () => {
       queries: [{ content: '', content_type: 'text_query', file_info: null }] satisfies Query[],
     }
     render(<QueryInput {...props} />)
-    expect(screen.getByTestId('submit-button')).toBeDisabled()
+    expect(screen.getByRole('button', { name: /input\.testing/ })).toBeDisabled()
   })
 
   it('should render retrieval method for non-external mode', () => {
@@ -101,11 +117,302 @@ describe('QueryInput', () => {
       queries: [{ content: 'a'.repeat(201), content_type: 'text_query', file_info: null }] satisfies Query[],
     }
     render(<QueryInput {...props} />)
-    expect(screen.getByTestId('submit-button')).toBeDisabled()
+    expect(screen.getByRole('button', { name: /input\.testing/ })).toBeDisabled()
   })
 
-  it('should disable submit button when loading', () => {
+  it('should show loading state on submit button when loading', () => {
     render(<QueryInput {...defaultProps} loading={true} />)
-    expect(screen.getByTestId('submit-button')).toBeDisabled()
+    const submitButton = screen.getByRole('button', { name: /input\.testing/ })
+    // The real Button component does not disable on loading; it shows a spinner
+    expect(submitButton).toBeInTheDocument()
+    expect(submitButton.querySelector('[role="status"]')).toBeInTheDocument()
+  })
+
+  // Cover line 83: images useMemo with image_query data
+  describe('Image Queries', () => {
+    it('should parse image_query entries from queries', () => {
+      const queries: Query[] = [
+        { content: 'test', content_type: 'text_query', file_info: null },
+        {
+          content: 'https://img.example.com/1.png',
+          content_type: 'image_query',
+          file_info: { id: 'img-1', name: 'photo.png', size: 1024, mime_type: 'image/png', extension: 'png', source_url: 'https://img.example.com/1.png' },
+        },
+      ]
+      render(<QueryInput {...defaultProps} queries={queries} />)
+
+      // Submit should be enabled since we have text + uploaded image
+      expect(screen.getByRole('button', { name: /input\.testing/ })).not.toBeDisabled()
+    })
+  })
+
+  // Cover lines 106-107: handleSaveExternalRetrievalSettings
+  describe('External Retrieval Settings', () => {
+    it('should open and close external retrieval modal', () => {
+      render(<QueryInput {...defaultProps} isExternal={true} />)
+
+      // Click settings button to open modal
+      fireEvent.click(screen.getByRole('button', { name: /settingTitle/ }))
+      expect(screen.getByTestId('external-retrieval-modal')).toBeInTheDocument()
+
+      // Close modal
+      fireEvent.click(screen.getByTestId('modal-close'))
+      expect(screen.queryByTestId('external-retrieval-modal')).not.toBeInTheDocument()
+    })
+
+    it('should save external retrieval settings and close modal', () => {
+      render(<QueryInput {...defaultProps} isExternal={true} />)
+
+      // Open modal
+      fireEvent.click(screen.getByRole('button', { name: /settingTitle/ }))
+      expect(screen.getByTestId('external-retrieval-modal')).toBeInTheDocument()
+
+      // Save settings
+      fireEvent.click(screen.getByTestId('modal-save'))
+      expect(screen.queryByTestId('external-retrieval-modal')).not.toBeInTheDocument()
+    })
+  })
+
+  // Cover line 121: handleTextChange when textQuery already exists
+  describe('Text Change Handling', () => {
+    it('should update existing text query on text change', () => {
+      render(<QueryInput {...defaultProps} />)
+
+      const textarea = screen.getByTestId('textarea')
+      fireEvent.change(textarea, { target: { value: 'updated text' } })
+
+      expect(defaultProps.setQueries).toHaveBeenCalledWith(
+        expect.arrayContaining([
+          expect.objectContaining({ content: 'updated text', content_type: 'text_query' }),
+        ]),
+      )
+    })
+
+    it('should create new text query when none exists', () => {
+      render(<QueryInput {...defaultProps} queries={[]} />)
+
+      const textarea = screen.getByTestId('textarea')
+      fireEvent.change(textarea, { target: { value: 'new text' } })
+
+      expect(defaultProps.setQueries).toHaveBeenCalledWith(
+        expect.arrayContaining([
+          expect.objectContaining({ content: 'new text', content_type: 'text_query' }),
+        ]),
+      )
+    })
+  })
+
+  // Cover lines 127-143: handleImageChange
+  describe('Image Change Handling', () => {
+    it('should update queries when images change', () => {
+      render(<QueryInput {...defaultProps} />)
+
+      const files: FileEntity[] = [{
+        id: 'f-1',
+        name: 'pic.jpg',
+        size: 2048,
+        mimeType: 'image/jpeg',
+        extension: 'jpg',
+        sourceUrl: 'https://img.example.com/pic.jpg',
+        uploadedId: 'uploaded-1',
+        progress: 100,
+      }]
+
+      capturedOnChange?.(files)
+
+      expect(defaultProps.setQueries).toHaveBeenCalledWith(
+        expect.arrayContaining([
+          expect.objectContaining({ content_type: 'text_query' }),
+          expect.objectContaining({
+            content: 'https://img.example.com/pic.jpg',
+            content_type: 'image_query',
+            file_info: expect.objectContaining({ id: 'uploaded-1', name: 'pic.jpg' }),
+          }),
+        ]),
+      )
+    })
+
+    it('should handle files with missing sourceUrl and uploadedId', () => {
+      render(<QueryInput {...defaultProps} />)
+
+      const files: FileEntity[] = [{
+        id: 'f-2',
+        name: 'no-url.jpg',
+        size: 512,
+        mimeType: 'image/jpeg',
+        extension: 'jpg',
+        progress: 100,
+        // sourceUrl and uploadedId are undefined
+      }]
+
+      capturedOnChange?.(files)
+
+      expect(defaultProps.setQueries).toHaveBeenCalledWith(
+        expect.arrayContaining([
+          expect.objectContaining({
+            content: '',
+            content_type: 'image_query',
+            file_info: expect.objectContaining({ id: '', source_url: '' }),
+          }),
+        ]),
+      )
+    })
+
+    it('should replace all existing image queries with new ones', () => {
+      const queries: Query[] = [
+        { content: 'text', content_type: 'text_query', file_info: null },
+        { content: 'old-img', content_type: 'image_query', file_info: { id: 'old', name: 'old.png', size: 100, mime_type: 'image/png', extension: 'png', source_url: '' } },
+      ]
+      render(<QueryInput {...defaultProps} queries={queries} />)
+
+      capturedOnChange?.([])
+
+      // Should keep text query but remove all image queries
+      expect(defaultProps.setQueries).toHaveBeenCalledWith(
+        expect.arrayContaining([
+          expect.objectContaining({ content_type: 'text_query' }),
+        ]),
+      )
+      // Should not contain image_query
+      const calledWith = defaultProps.setQueries.mock.calls[0][0] as Query[]
+      expect(calledWith.filter(q => q.content_type === 'image_query')).toHaveLength(0)
+    })
+  })
+
+  // Cover lines 146-162: onSubmit (hit testing mutation)
+  describe('Submit Handlers', () => {
+    it('should call hitTestingMutation on submit for non-external mode', async () => {
+      const mockMutation = vi.fn(async (_req, opts) => {
+        const response = { query: { content: '', tsne_position: { x: 0, y: 0 } }, records: [] }
+        opts?.onSuccess?.(response)
+        return response
+      })
+
+      render(<QueryInput {...defaultProps} hitTestingMutation={mockMutation} />)
+
+      fireEvent.click(screen.getByRole('button', { name: /input\.testing/ }))
+
+      await waitFor(() => {
+        expect(mockMutation).toHaveBeenCalledWith(
+          expect.objectContaining({
+            query: 'test query',
+            retrieval_model: expect.objectContaining({ search_method: 'semantic_search' }),
+          }),
+          expect.objectContaining({ onSuccess: expect.any(Function) }),
+        )
+      })
+      expect(defaultProps.setHitResult).toHaveBeenCalled()
+      expect(defaultProps.onUpdateList).toHaveBeenCalled()
+    })
+
+    it('should call onSubmit callback after successful hit testing', async () => {
+      const mockOnSubmit = vi.fn()
+      const mockMutation = vi.fn(async (_req, opts) => {
+        const response = { query: { content: '', tsne_position: { x: 0, y: 0 } }, records: [] }
+        opts?.onSuccess?.(response)
+        return response
+      })
+
+      render(<QueryInput {...defaultProps} hitTestingMutation={mockMutation} onSubmit={mockOnSubmit} />)
+
+      fireEvent.click(screen.getByRole('button', { name: /input\.testing/ }))
+
+      await waitFor(() => {
+        expect(mockOnSubmit).toHaveBeenCalled()
+      })
+    })
+
+    it('should use keywordSearch when isEconomy is true', async () => {
+      const mockResponse = { query: { content: '', tsne_position: { x: 0, y: 0 } }, records: [] }
+      const mockMutation = vi.fn(async (_req, opts) => {
+        opts?.onSuccess?.(mockResponse)
+        return mockResponse
+      })
+
+      render(<QueryInput {...defaultProps} hitTestingMutation={mockMutation} isEconomy={true} />)
+
+      fireEvent.click(screen.getByRole('button', { name: /input\.testing/ }))
+
+      await waitFor(() => {
+        expect(mockMutation).toHaveBeenCalledWith(
+          expect.objectContaining({
+            retrieval_model: expect.objectContaining({ search_method: 'keyword_search' }),
+          }),
+          expect.anything(),
+        )
+      })
+    })
+
+    // Cover lines 164-178: externalRetrievalTestingOnSubmit
+    it('should call externalKnowledgeBaseHitTestingMutation for external mode', async () => {
+      const mockExternalMutation = vi.fn(async (_req, opts) => {
+        const response = { query: { content: '' }, records: [] }
+        opts?.onSuccess?.(response)
+        return response
+      })
+
+      render(<QueryInput {...defaultProps} isExternal={true} externalKnowledgeBaseHitTestingMutation={mockExternalMutation} />)
+
+      fireEvent.click(screen.getByRole('button', { name: /input\.testing/ }))
+
+      await waitFor(() => {
+        expect(mockExternalMutation).toHaveBeenCalledWith(
+          expect.objectContaining({
+            query: 'test query',
+            external_retrieval_model: expect.objectContaining({
+              top_k: 4,
+              score_threshold: 0.5,
+              score_threshold_enabled: false,
+            }),
+          }),
+          expect.objectContaining({ onSuccess: expect.any(Function) }),
+        )
+      })
+      expect(defaultProps.setExternalHitResult).toHaveBeenCalled()
+      expect(defaultProps.onUpdateList).toHaveBeenCalled()
+    })
+
+    it('should include image attachment_ids in submit request', async () => {
+      const queries: Query[] = [
+        { content: 'test', content_type: 'text_query', file_info: null },
+        { content: 'img-url', content_type: 'image_query', file_info: { id: 'img-id', name: 'pic.png', size: 100, mime_type: 'image/png', extension: 'png', source_url: 'img-url' } },
+      ]
+      const mockResponse = { query: { content: '', tsne_position: { x: 0, y: 0 } }, records: [] }
+      const mockMutation = vi.fn(async (_req, opts) => {
+        opts?.onSuccess?.(mockResponse)
+        return mockResponse
+      })
+
+      render(<QueryInput {...defaultProps} queries={queries} hitTestingMutation={mockMutation} />)
+
+      fireEvent.click(screen.getByRole('button', { name: /input\.testing/ }))
+
+      await waitFor(() => {
+        expect(mockMutation).toHaveBeenCalledWith(
+          expect.objectContaining({
+            // uploadedId is mapped from file_info.id
+            attachment_ids: expect.arrayContaining(['img-id']),
+          }),
+          expect.anything(),
+        )
+      })
+    })
+  })
+
+  // Cover lines 217-238: retrieval method click handler
+  describe('Retrieval Method', () => {
+    it('should call onClickRetrievalMethod when retrieval method is clicked', () => {
+      render(<QueryInput {...defaultProps} />)
+
+      fireEvent.click(screen.getByText('dataset.retrieval.semantic_search.title'))
+
+      expect(defaultProps.onClickRetrievalMethod).toHaveBeenCalled()
+    })
+
+    it('should show keyword_search when isEconomy is true', () => {
+      render(<QueryInput {...defaultProps} isEconomy={true} />)
+
+      expect(screen.getByText('dataset.retrieval.keyword_search.title')).toBeInTheDocument()
+    })
   })
 })

web/app/components/datasets/metadata/hooks/__tests__/use-batch-edit-document-metadata.spec.ts

@@ -22,6 +22,7 @@ type MetadataItemWithEdit = {
   type: DataType
   value: string | number | null
   isMultipleValue?: boolean
+  isUpdated?: boolean
   updateType?: UpdateType
 }
 
@@ -615,6 +616,91 @@ describe('useBatchEditDocumentMetadata', () => {
     })
   })
 
+  describe('toCleanMetadataItem sanitization', () => {
+    it('should strip extra fields (isMultipleValue, updateType, isUpdated) from metadata items sent to backend', async () => {
+      const docListSingleDoc: DocListItem[] = [
+        {
+          id: 'doc-1',
+          doc_metadata: [
+            { id: '1', name: 'field_one', type: DataType.string, value: 'Old Value' },
+          ],
+        },
+      ]
+
+      const { result } = renderHook(() =>
+        useBatchEditDocumentMetadata({
+          ...defaultProps,
+          docList: docListSingleDoc as Parameters<typeof useBatchEditDocumentMetadata>[0]['docList'],
+        }),
+      )
+
+      const editedList: MetadataItemWithEdit[] = [
+        {
+          id: '1',
+          name: 'field_one',
+          type: DataType.string,
+          value: 'New Value',
+          isMultipleValue: true,
+          isUpdated: true,
+          updateType: UpdateType.changeValue,
+        },
+      ]
+
+      await act(async () => {
+        await result.current.handleSave(editedList, [], false)
+      })
+
+      const callArgs = mockMutateAsync.mock.calls[0][0]
+      const sentItem = callArgs.metadata_list[0].metadata_list[0]
+
+      // Only id, name, type, value should be present
+      expect(Object.keys(sentItem).sort()).toEqual(['id', 'name', 'type', 'value'].sort())
+      expect(sentItem).not.toHaveProperty('isMultipleValue')
+      expect(sentItem).not.toHaveProperty('updateType')
+      expect(sentItem).not.toHaveProperty('isUpdated')
+    })
+
+    it('should coerce undefined value to null in metadata items sent to backend', async () => {
+      const docListSingleDoc: DocListItem[] = [
+        {
+          id: 'doc-1',
+          doc_metadata: [
+            { id: '1', name: 'field_one', type: DataType.string, value: 'Value' },
+          ],
+        },
+      ]
+
+      const { result } = renderHook(() =>
+        useBatchEditDocumentMetadata({
+          ...defaultProps,
+          docList: docListSingleDoc as Parameters<typeof useBatchEditDocumentMetadata>[0]['docList'],
+        }),
+      )
+
+      // Pass an item with value explicitly set to undefined (via cast)
+      const editedList: MetadataItemWithEdit[] = [
+        {
+          id: '1',
+          name: 'field_one',
+          type: DataType.string,
+          value: undefined as unknown as null,
+          updateType: UpdateType.changeValue,
+        },
+      ]
+
+      await act(async () => {
+        await result.current.handleSave(editedList, [], false)
+      })
+
+      const callArgs = mockMutateAsync.mock.calls[0][0]
+      const sentItem = callArgs.metadata_list[0].metadata_list[0]
+
+      // value should be null, not undefined
+      expect(sentItem.value).toBeNull()
+      expect(sentItem.value).not.toBeUndefined()
+    })
+  })
+
   describe('Edge Cases', () => {
     it('should handle empty docList', () => {
       const { result } = renderHook(() =>

web/app/components/datasets/metadata/hooks/use-batch-edit-document-metadata.ts

@@ -71,6 +71,13 @@ const useBatchEditDocumentMetadata = ({
     return res
   }, [metaDataList])
 
+  const toCleanMetadataItem = (item: MetadataItemWithValue | MetadataItemWithEdit | MetadataItemInBatchEdit): MetadataItemWithValue => ({
+    id: item.id,
+    name: item.name,
+    type: item.type,
+    value: item.value ?? null,
+  })
+
   const formateToBackendList = (editedList: MetadataItemWithEdit[], addedList: MetadataItemInBatchEdit[], isApplyToAllSelectDocument: boolean) => {
     const updatedList = editedList.filter((editedItem) => {
       return editedItem.updateType === UpdateType.changeValue
@@ -92,24 +99,19 @@ const useBatchEditDocumentMetadata = ({
         .filter((item) => {
           return !removedList.find(removedItem => removedItem.id === item.id)
         })
-        .map(item => ({
-          id: item.id,
-          name: item.name,
-          type: item.type,
-          value: item.value,
-        }))
+        .map(toCleanMetadataItem)
       if (isApplyToAllSelectDocument) {
         // add missing metadata item
         updatedList.forEach((editedItem) => {
           if (!newMetadataList.find(i => i.id === editedItem.id) && !editedItem.isMultipleValue)
-            newMetadataList.push(editedItem)
+            newMetadataList.push(toCleanMetadataItem(editedItem))
         })
       }
 
       newMetadataList = newMetadataList.map((item) => {
         const editedItem = updatedList.find(i => i.id === item.id)
         if (editedItem)
-          return editedItem
+          return toCleanMetadataItem(editedItem)
         return item
       })
 

web/app/components/develop/__tests__/code.spec.tsx

@@ -9,23 +9,22 @@ vi.mock('@/utils/clipboard', () => ({
 describe('code.tsx components', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    vi.spyOn(console, 'error').mockImplementation(() => {})
     vi.useFakeTimers({ shouldAdvanceTime: true })
+    // jsdom does not implement scrollBy; mock it to prevent stderr noise
+    window.scrollBy = vi.fn()
   })
 
   afterEach(() => {
     vi.runOnlyPendingTimers()
     vi.useRealTimers()
+    vi.restoreAllMocks()
   })
 
   describe('Code', () => {
-    it('should render children', () => {
+    it('should render children as a code element', () => {
       render(<Code>const x = 1</Code>)
-      expect(screen.getByText('const x = 1')).toBeInTheDocument()
-    })
-
-    it('should render as code element', () => {
-      render(<Code>code snippet</Code>)
-      const codeElement = screen.getByText('code snippet')
+      const codeElement = screen.getByText('const x = 1')
       expect(codeElement.tagName).toBe('CODE')
     })
 
@@ -48,14 +47,9 @@ describe('code.tsx components', () => {
   })
 
   describe('Embed', () => {
-    it('should render value prop', () => {
+    it('should render value prop as a span element', () => {
       render(<Embed value="embedded content">ignored children</Embed>)
-      expect(screen.getByText('embedded content')).toBeInTheDocument()
-    })
-
-    it('should render as span element', () => {
-      render(<Embed value="test value">children</Embed>)
-      const span = screen.getByText('test value')
+      const span = screen.getByText('embedded content')
       expect(span.tagName).toBe('SPAN')
     })
 
@@ -65,7 +59,7 @@ describe('code.tsx components', () => {
       expect(embed).toHaveClass('embed-class')
     })
 
-    it('should not render children, only value', () => {
+    it('should render only value, not children', () => {
       render(<Embed value="shown">hidden children</Embed>)
       expect(screen.getByText('shown')).toBeInTheDocument()
       expect(screen.queryByText('hidden children')).not.toBeInTheDocument()
@@ -82,27 +76,6 @@ describe('code.tsx components', () => {
         )
         expect(screen.getByText('const hello = \'world\'')).toBeInTheDocument()
       })
-
-      it('should have shadow and rounded styles', () => {
-        const { container } = render(
-          <CodeGroup targetCode="code here">
-            <pre><code>fallback</code></pre>
-          </CodeGroup>,
-        )
-        const codeGroup = container.querySelector('.shadow-md')
-        expect(codeGroup).toBeInTheDocument()
-        expect(codeGroup).toHaveClass('rounded-2xl')
-      })
-
-      it('should have bg-zinc-900 background', () => {
-        const { container } = render(
-          <CodeGroup targetCode="code">
-            <pre><code>fallback</code></pre>
-          </CodeGroup>,
-        )
-        const codeGroup = container.querySelector('.bg-zinc-900')
-        expect(codeGroup).toBeInTheDocument()
-      })
     })
 
     describe('with array targetCode', () => {
@@ -184,23 +157,14 @@ describe('code.tsx components', () => {
     })
 
     describe('with title prop', () => {
-      it('should render title in header', () => {
+      it('should render title in an h3 heading', () => {
         render(
           <CodeGroup title="API Example" targetCode="code">
             <pre><code>fallback</code></pre>
           </CodeGroup>,
         )
-        expect(screen.getByText('API Example')).toBeInTheDocument()
-      })
-
-      it('should render title in h3 element', () => {
-        render(
-          <CodeGroup title="Example Title" targetCode="code">
-            <pre><code>fallback</code></pre>
-          </CodeGroup>,
-        )
         const h3 = screen.getByRole('heading', { level: 3 })
-        expect(h3).toHaveTextContent('Example Title')
+        expect(h3).toHaveTextContent('API Example')
       })
     })
 
@@ -223,30 +187,18 @@ describe('code.tsx components', () => {
         expect(screen.getByText('/api/users')).toBeInTheDocument()
       })
 
-      it('should render both tag and label with separator', () => {
-        const { container } = render(
+      it('should render both tag and label together', () => {
+        render(
           <CodeGroup tag="POST" label="/api/create" targetCode="code">
             <pre><code>fallback</code></pre>
           </CodeGroup>,
         )
         expect(screen.getByText('POST')).toBeInTheDocument()
         expect(screen.getByText('/api/create')).toBeInTheDocument()
-        const separator = container.querySelector('.rounded-full.bg-zinc-500')
-        expect(separator).toBeInTheDocument()
       })
     })
 
     describe('CopyButton functionality', () => {
-      it('should render copy button', () => {
-        render(
-          <CodeGroup targetCode="copyable code">
-            <pre><code>fallback</code></pre>
-          </CodeGroup>,
-        )
-        const copyButton = screen.getByRole('button')
-        expect(copyButton).toBeInTheDocument()
-      })
-
       it('should show "Copy" text initially', () => {
         render(
           <CodeGroup targetCode="code">
@@ -322,88 +274,32 @@ describe('code.tsx components', () => {
         expect(screen.getByText('child code content')).toBeInTheDocument()
       })
     })
-
-    describe('styling', () => {
-      it('should have not-prose class to prevent prose styling', () => {
-        const { container } = render(
-          <CodeGroup targetCode="code">
-            <pre><code>fallback</code></pre>
-          </CodeGroup>,
-        )
-        const codeGroup = container.querySelector('.not-prose')
-        expect(codeGroup).toBeInTheDocument()
-      })
-
-      it('should have my-6 margin', () => {
-        const { container } = render(
-          <CodeGroup targetCode="code">
-            <pre><code>fallback</code></pre>
-          </CodeGroup>,
-        )
-        const codeGroup = container.querySelector('.my-6')
-        expect(codeGroup).toBeInTheDocument()
-      })
-
-      it('should have overflow-hidden', () => {
-        const { container } = render(
-          <CodeGroup targetCode="code">
-            <pre><code>fallback</code></pre>
-          </CodeGroup>,
-        )
-        const codeGroup = container.querySelector('.overflow-hidden')
-        expect(codeGroup).toBeInTheDocument()
-      })
-    })
   })
 
   describe('Pre', () => {
-    describe('when outside CodeGroup context', () => {
-      it('should wrap children in CodeGroup', () => {
-        const { container } = render(
-          <Pre>
-            <pre><code>code content</code></pre>
-          </Pre>,
-        )
-        const codeGroup = container.querySelector('.bg-zinc-900')
-        expect(codeGroup).toBeInTheDocument()
-      })
-
-      it('should pass props to CodeGroup', () => {
-        render(
-          <Pre title="Pre Title">
-            <pre><code>code</code></pre>
-          </Pre>,
-        )
-        expect(screen.getByText('Pre Title')).toBeInTheDocument()
-      })
+    it('should wrap children in CodeGroup when outside CodeGroup context', () => {
+      render(
+        <Pre title="Pre Title">
+          <pre><code>code</code></pre>
+        </Pre>,
+      )
+      expect(screen.getByText('Pre Title')).toBeInTheDocument()
     })
 
-    describe('when inside CodeGroup context (isGrouped)', () => {
-      it('should return children directly without wrapping', () => {
-        render(
-          <CodeGroup targetCode="outer code">
-            <Pre>
-              <code>inner code</code>
-            </Pre>
-          </CodeGroup>,
-        )
-        expect(screen.getByText('outer code')).toBeInTheDocument()
-      })
+    it('should return children directly when inside CodeGroup context', () => {
+      render(
+        <CodeGroup targetCode="outer code">
+          <Pre>
+            <code>inner code</code>
+          </Pre>
+        </CodeGroup>,
+      )
+      expect(screen.getByText('outer code')).toBeInTheDocument()
     })
   })
 
   describe('CodePanelHeader (via CodeGroup)', () => {
-    it('should not render when neither tag nor label provided', () => {
-      const { container } = render(
-        <CodeGroup targetCode="code">
-          <pre><code>fallback</code></pre>
-        </CodeGroup>,
-      )
-      const headerDivider = container.querySelector('.border-b-white\\/7\\.5')
-      expect(headerDivider).not.toBeInTheDocument()
-    })
-
-    it('should render when only tag is provided', () => {
+    it('should render when tag is provided', () => {
       render(
         <CodeGroup tag="GET" targetCode="code">
           <pre><code>fallback</code></pre>
@@ -412,7 +308,7 @@ describe('code.tsx components', () => {
       expect(screen.getByText('GET')).toBeInTheDocument()
     })
 
-    it('should render when only label is provided', () => {
+    it('should render when label is provided', () => {
       render(
         <CodeGroup label="/api/endpoint" targetCode="code">
           <pre><code>fallback</code></pre>
@@ -420,17 +316,6 @@ describe('code.tsx components', () => {
       )
       expect(screen.getByText('/api/endpoint')).toBeInTheDocument()
     })
-
-    it('should render label with font-mono styling', () => {
-      render(
-        <CodeGroup label="/api/test" targetCode="code">
-          <pre><code>fallback</code></pre>
-        </CodeGroup>,
-      )
-      const label = screen.getByText('/api/test')
-      expect(label.className).toContain('font-mono')
-      expect(label.className).toContain('text-xs')
-    })
   })
 
   describe('CodeGroupHeader (via CodeGroup with multiple tabs)', () => {
@@ -446,39 +331,10 @@ describe('code.tsx components', () => {
       )
       expect(screen.getByRole('tablist')).toBeInTheDocument()
     })
-
-    it('should style active tab differently', () => {
-      const examples = [
-        { title: 'Active', code: 'active code' },
-        { title: 'Inactive', code: 'inactive code' },
-      ]
-      render(
-        <CodeGroup targetCode={examples}>
-          <pre><code>fallback</code></pre>
-        </CodeGroup>,
-      )
-      const activeTab = screen.getByRole('tab', { name: 'Active' })
-      expect(activeTab.className).toContain('border-emerald-500')
-      expect(activeTab.className).toContain('text-emerald-400')
-    })
-
-    it('should have header background styling', () => {
-      const examples = [
-        { title: 'Tab1', code: 'code1' },
-        { title: 'Tab2', code: 'code2' },
-      ]
-      const { container } = render(
-        <CodeGroup targetCode={examples}>
-          <pre><code>fallback</code></pre>
-        </CodeGroup>,
-      )
-      const header = container.querySelector('.bg-zinc-800')
-      expect(header).toBeInTheDocument()
-    })
   })
 
   describe('CodePanel (via CodeGroup)', () => {
-    it('should render code in pre element', () => {
+    it('should render code in a pre element', () => {
       render(
         <CodeGroup targetCode="pre content">
           <pre><code>fallback</code></pre>
@@ -487,50 +343,10 @@ describe('code.tsx components', () => {
       const preElement = screen.getByText('pre content').closest('pre')
       expect(preElement).toBeInTheDocument()
     })
-
-    it('should have text-white class on pre', () => {
-      render(
-        <CodeGroup targetCode="white text">
-          <pre><code>fallback</code></pre>
-        </CodeGroup>,
-      )
-      const preElement = screen.getByText('white text').closest('pre')
-      expect(preElement?.className).toContain('text-white')
-    })
-
-    it('should have text-xs class on pre', () => {
-      render(
-        <CodeGroup targetCode="small text">
-          <pre><code>fallback</code></pre>
-        </CodeGroup>,
-      )
-      const preElement = screen.getByText('small text').closest('pre')
-      expect(preElement?.className).toContain('text-xs')
-    })
-
-    it('should have overflow-x-auto on pre', () => {
-      render(
-        <CodeGroup targetCode="scrollable">
-          <pre><code>fallback</code></pre>
-        </CodeGroup>,
-      )
-      const preElement = screen.getByText('scrollable').closest('pre')
-      expect(preElement?.className).toContain('overflow-x-auto')
-    })
-
-    it('should have p-4 padding on pre', () => {
-      render(
-        <CodeGroup targetCode="padded">
-          <pre><code>fallback</code></pre>
-        </CodeGroup>,
-      )
-      const preElement = screen.getByText('padded').closest('pre')
-      expect(preElement?.className).toContain('p-4')
-    })
   })
 
-  describe('ClipboardIcon (via CopyButton in CodeGroup)', () => {
-    it('should render clipboard icon in copy button', () => {
+  describe('ClipboardIcon (via CopyButton)', () => {
+    it('should render clipboard SVG icon in copy button', () => {
       render(
         <CodeGroup targetCode="code">
           <pre><code>fallback</code></pre>
@@ -543,7 +359,7 @@ describe('code.tsx components', () => {
     })
   })
 
-  describe('edge cases', () => {
+  describe('Edge Cases', () => {
     it('should handle empty string targetCode', () => {
       render(
         <CodeGroup targetCode="">

web/app/components/develop/__tests__/doc.spec.tsx

@@ -53,6 +53,10 @@ vi.mock('@/hooks/use-theme', () => ({
 
 vi.mock('@/i18n-config/language', () => ({
   LanguagesSupported: ['en-US', 'zh-Hans', 'zh-Hant', 'pt-BR', 'es-ES', 'fr-FR', 'de-DE', 'ja-JP'],
+  getDocLanguage: (locale: string) => {
+    const map: Record<string, string> = { 'zh-Hans': 'zh', 'ja-JP': 'ja' }
+    return map[locale] || 'en'
+  },
 }))
 
 describe('Doc', () => {
@@ -63,7 +67,7 @@ describe('Doc', () => {
         prompt_variables: variables,
       },
     },
-  })
+  }) as unknown as Parameters<typeof Doc>[0]['appDetail']
 
   beforeEach(() => {
     vi.clearAllMocks()
@@ -123,13 +127,13 @@ describe('Doc', () => {
 
   describe('null/undefined appDetail', () => {
     it('should render nothing when appDetail has no mode', () => {
-      render(<Doc appDetail={{}} />)
+      render(<Doc appDetail={{} as unknown as Parameters<typeof Doc>[0]['appDetail']} />)
       expect(screen.queryByTestId('template-completion-en')).not.toBeInTheDocument()
       expect(screen.queryByTestId('template-chat-en')).not.toBeInTheDocument()
     })
 
     it('should render nothing when appDetail is null', () => {
-      render(<Doc appDetail={null} />)
+      render(<Doc appDetail={null as unknown as Parameters<typeof Doc>[0]['appDetail']} />)
       expect(screen.queryByTestId('template-completion-en')).not.toBeInTheDocument()
     })
   })

web/app/components/develop/__tests__/toc-panel.spec.tsx

@@ -0,0 +1,199 @@
+import type { TocItem } from '../hooks/use-doc-toc'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import TocPanel from '../toc-panel'
+
+/**
+ * Unit tests for the TocPanel presentational component.
+ * Covers collapsed/expanded states, item rendering, active section, and callbacks.
+ */
+describe('TocPanel', () => {
+  const defaultProps = {
+    toc: [] as TocItem[],
+    activeSection: '',
+    isTocExpanded: false,
+    onToggle: vi.fn(),
+    onItemClick: vi.fn(),
+  }
+
+  const sampleToc: TocItem[] = [
+    { href: '#introduction', text: 'Introduction' },
+    { href: '#authentication', text: 'Authentication' },
+    { href: '#endpoints', text: 'Endpoints' },
+  ]
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // Covers collapsed state rendering
+  describe('collapsed state', () => {
+    it('should render expand button when collapsed', () => {
+      render(<TocPanel {...defaultProps} />)
+
+      expect(screen.getByLabelText('Open table of contents')).toBeInTheDocument()
+    })
+
+    it('should not render nav or toc items when collapsed', () => {
+      render(<TocPanel {...defaultProps} toc={sampleToc} />)
+
+      expect(screen.queryByRole('navigation')).not.toBeInTheDocument()
+      expect(screen.queryByText('Introduction')).not.toBeInTheDocument()
+    })
+
+    it('should call onToggle(true) when expand button is clicked', () => {
+      const onToggle = vi.fn()
+      render(<TocPanel {...defaultProps} onToggle={onToggle} />)
+
+      fireEvent.click(screen.getByLabelText('Open table of contents'))
+
+      expect(onToggle).toHaveBeenCalledWith(true)
+    })
+  })
+
+  // Covers expanded state with empty toc
+  describe('expanded state - empty', () => {
+    it('should render nav with empty message when toc is empty', () => {
+      render(<TocPanel {...defaultProps} isTocExpanded />)
+
+      expect(screen.getByRole('navigation')).toBeInTheDocument()
+      expect(screen.getByText('appApi.develop.noContent')).toBeInTheDocument()
+    })
+
+    it('should render TOC header with title', () => {
+      render(<TocPanel {...defaultProps} isTocExpanded />)
+
+      expect(screen.getByText('appApi.develop.toc')).toBeInTheDocument()
+    })
+
+    it('should call onToggle(false) when close button is clicked', () => {
+      const onToggle = vi.fn()
+      render(<TocPanel {...defaultProps} isTocExpanded onToggle={onToggle} />)
+
+      fireEvent.click(screen.getByLabelText('Close'))
+
+      expect(onToggle).toHaveBeenCalledWith(false)
+    })
+  })
+
+  // Covers expanded state with toc items
+  describe('expanded state - with items', () => {
+    it('should render all toc items as links', () => {
+      render(<TocPanel {...defaultProps} isTocExpanded toc={sampleToc} />)
+
+      expect(screen.getByText('Introduction')).toBeInTheDocument()
+      expect(screen.getByText('Authentication')).toBeInTheDocument()
+      expect(screen.getByText('Endpoints')).toBeInTheDocument()
+    })
+
+    it('should render links with correct href attributes', () => {
+      render(<TocPanel {...defaultProps} isTocExpanded toc={sampleToc} />)
+
+      const links = screen.getAllByRole('link')
+      expect(links).toHaveLength(3)
+      expect(links[0]).toHaveAttribute('href', '#introduction')
+      expect(links[1]).toHaveAttribute('href', '#authentication')
+      expect(links[2]).toHaveAttribute('href', '#endpoints')
+    })
+
+    it('should not render empty message when toc has items', () => {
+      render(<TocPanel {...defaultProps} isTocExpanded toc={sampleToc} />)
+
+      expect(screen.queryByText('appApi.develop.noContent')).not.toBeInTheDocument()
+    })
+  })
+
+  // Covers active section highlighting
+  describe('active section', () => {
+    it('should apply active style to the matching toc item', () => {
+      render(
+        <TocPanel {...defaultProps} isTocExpanded toc={sampleToc} activeSection="authentication" />,
+      )
+
+      const activeLink = screen.getByText('Authentication').closest('a')
+      expect(activeLink?.className).toContain('font-medium')
+      expect(activeLink?.className).toContain('text-text-primary')
+    })
+
+    it('should apply inactive style to non-matching items', () => {
+      render(
+        <TocPanel {...defaultProps} isTocExpanded toc={sampleToc} activeSection="authentication" />,
+      )
+
+      const inactiveLink = screen.getByText('Introduction').closest('a')
+      expect(inactiveLink?.className).toContain('text-text-tertiary')
+      expect(inactiveLink?.className).not.toContain('font-medium')
+    })
+
+    it('should apply active indicator dot to active item', () => {
+      render(
+        <TocPanel {...defaultProps} isTocExpanded toc={sampleToc} activeSection="endpoints" />,
+      )
+
+      const activeLink = screen.getByText('Endpoints').closest('a')
+      const activeDot = activeLink?.querySelector('span:first-child')
+      expect(activeDot?.className).toContain('bg-text-accent')
+    })
+  })
+
+  // Covers click event delegation
+  describe('item click handling', () => {
+    it('should call onItemClick with the event and item when a link is clicked', () => {
+      const onItemClick = vi.fn()
+      render(
+        <TocPanel {...defaultProps} isTocExpanded toc={sampleToc} onItemClick={onItemClick} />,
+      )
+
+      fireEvent.click(screen.getByText('Authentication'))
+
+      expect(onItemClick).toHaveBeenCalledTimes(1)
+      expect(onItemClick).toHaveBeenCalledWith(
+        expect.any(Object),
+        { href: '#authentication', text: 'Authentication' },
+      )
+    })
+
+    it('should call onItemClick for each clicked item independently', () => {
+      const onItemClick = vi.fn()
+      render(
+        <TocPanel {...defaultProps} isTocExpanded toc={sampleToc} onItemClick={onItemClick} />,
+      )
+
+      fireEvent.click(screen.getByText('Introduction'))
+      fireEvent.click(screen.getByText('Endpoints'))
+
+      expect(onItemClick).toHaveBeenCalledTimes(2)
+    })
+  })
+
+  // Covers edge cases
+  describe('edge cases', () => {
+    it('should handle single item toc', () => {
+      const singleItem = [{ href: '#only', text: 'Only Section' }]
+      render(<TocPanel {...defaultProps} isTocExpanded toc={singleItem} activeSection="only" />)
+
+      expect(screen.getByText('Only Section')).toBeInTheDocument()
+      expect(screen.getAllByRole('link')).toHaveLength(1)
+    })
+
+    it('should handle toc items with empty text', () => {
+      const emptyTextItem = [{ href: '#empty', text: '' }]
+      render(<TocPanel {...defaultProps} isTocExpanded toc={emptyTextItem} />)
+
+      expect(screen.getAllByRole('link')).toHaveLength(1)
+    })
+
+    it('should handle active section that does not match any item', () => {
+      render(
+        <TocPanel {...defaultProps} isTocExpanded toc={sampleToc} activeSection="nonexistent" />,
+      )
+
+      // All items should be in inactive style
+      const links = screen.getAllByRole('link')
+      links.forEach((link) => {
+        expect(link.className).toContain('text-text-tertiary')
+        expect(link.className).not.toContain('font-medium')
+      })
+    })
+  })
+})

web/app/components/develop/__tests__/use-doc-toc.spec.ts

@@ -0,0 +1,425 @@
+import { act, renderHook } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { useDocToc } from '../hooks/use-doc-toc'
+
+/**
+ * Unit tests for the useDocToc custom hook.
+ * Covers TOC extraction, viewport-based expansion, scroll tracking, and click handling.
+ */
+describe('useDocToc', () => {
+  const defaultOptions = { appDetail: { mode: 'chat' }, locale: 'en-US' }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.useRealTimers()
+
+    Object.defineProperty(window, 'matchMedia', {
+      writable: true,
+      value: vi.fn().mockReturnValue({ matches: false }),
+    })
+  })
+
+  // Covers initial state values based on viewport width
+  describe('initial state', () => {
+    it('should set isTocExpanded to false on narrow viewport', () => {
+      const { result } = renderHook(() => useDocToc(defaultOptions))
+
+      expect(result.current.isTocExpanded).toBe(false)
+      expect(result.current.toc).toEqual([])
+      expect(result.current.activeSection).toBe('')
+    })
+
+    it('should set isTocExpanded to true on wide viewport', () => {
+      Object.defineProperty(window, 'matchMedia', {
+        writable: true,
+        value: vi.fn().mockReturnValue({ matches: true }),
+      })
+
+      const { result } = renderHook(() => useDocToc(defaultOptions))
+
+      expect(result.current.isTocExpanded).toBe(true)
+    })
+  })
+
+  // Covers TOC extraction from DOM article headings
+  describe('TOC extraction', () => {
+    it('should extract toc items from article h2 anchors', async () => {
+      vi.useFakeTimers()
+      const article = document.createElement('article')
+      const h2 = document.createElement('h2')
+      const anchor = document.createElement('a')
+      anchor.href = '#section-1'
+      anchor.textContent = 'Section 1'
+      h2.appendChild(anchor)
+      article.appendChild(h2)
+      document.body.appendChild(article)
+
+      const { result } = renderHook(() => useDocToc(defaultOptions))
+
+      await act(async () => {
+        vi.runAllTimers()
+      })
+
+      expect(result.current.toc).toEqual([
+        { href: '#section-1', text: 'Section 1' },
+      ])
+      expect(result.current.activeSection).toBe('section-1')
+
+      document.body.removeChild(article)
+      vi.useRealTimers()
+    })
+
+    it('should return empty toc when no article exists', async () => {
+      vi.useFakeTimers()
+      const { result } = renderHook(() => useDocToc(defaultOptions))
+
+      await act(async () => {
+        vi.runAllTimers()
+      })
+
+      expect(result.current.toc).toEqual([])
+      expect(result.current.activeSection).toBe('')
+      vi.useRealTimers()
+    })
+
+    it('should skip h2 headings without anchors', async () => {
+      vi.useFakeTimers()
+      const article = document.createElement('article')
+      const h2NoAnchor = document.createElement('h2')
+      h2NoAnchor.textContent = 'No Anchor'
+      article.appendChild(h2NoAnchor)
+
+      const h2WithAnchor = document.createElement('h2')
+      const anchor = document.createElement('a')
+      anchor.href = '#valid'
+      anchor.textContent = 'Valid'
+      h2WithAnchor.appendChild(anchor)
+      article.appendChild(h2WithAnchor)
+
+      document.body.appendChild(article)
+
+      const { result } = renderHook(() => useDocToc(defaultOptions))
+
+      await act(async () => {
+        vi.runAllTimers()
+      })
+
+      expect(result.current.toc).toHaveLength(1)
+      expect(result.current.toc[0]).toEqual({ href: '#valid', text: 'Valid' })
+
+      document.body.removeChild(article)
+      vi.useRealTimers()
+    })
+
+    it('should re-extract toc when appDetail changes', async () => {
+      vi.useFakeTimers()
+      const article = document.createElement('article')
+      document.body.appendChild(article)
+
+      const { result, rerender } = renderHook(
+        props => useDocToc(props),
+        { initialProps: defaultOptions },
+      )
+
+      await act(async () => {
+        vi.runAllTimers()
+      })
+
+      expect(result.current.toc).toEqual([])
+
+      // Add a heading, then change appDetail to trigger re-extraction
+      const h2 = document.createElement('h2')
+      const anchor = document.createElement('a')
+      anchor.href = '#new-section'
+      anchor.textContent = 'New Section'
+      h2.appendChild(anchor)
+      article.appendChild(h2)
+
+      rerender({ appDetail: { mode: 'workflow' }, locale: 'en-US' })
+
+      await act(async () => {
+        vi.runAllTimers()
+      })
+
+      expect(result.current.toc).toHaveLength(1)
+
+      document.body.removeChild(article)
+      vi.useRealTimers()
+    })
+
+    it('should re-extract toc when locale changes', async () => {
+      vi.useFakeTimers()
+      const article = document.createElement('article')
+      const h2 = document.createElement('h2')
+      const anchor = document.createElement('a')
+      anchor.href = '#sec'
+      anchor.textContent = 'Sec'
+      h2.appendChild(anchor)
+      article.appendChild(h2)
+      document.body.appendChild(article)
+
+      const { result, rerender } = renderHook(
+        props => useDocToc(props),
+        { initialProps: defaultOptions },
+      )
+
+      await act(async () => {
+        vi.runAllTimers()
+      })
+
+      expect(result.current.toc).toHaveLength(1)
+
+      rerender({ appDetail: defaultOptions.appDetail, locale: 'zh-Hans' })
+
+      await act(async () => {
+        vi.runAllTimers()
+      })
+
+      // Should still have the toc item after re-extraction
+      expect(result.current.toc).toHaveLength(1)
+
+      document.body.removeChild(article)
+      vi.useRealTimers()
+    })
+  })
+
+  // Covers manual toggle via setIsTocExpanded
+  describe('setIsTocExpanded', () => {
+    it('should toggle isTocExpanded state', () => {
+      const { result } = renderHook(() => useDocToc(defaultOptions))
+
+      expect(result.current.isTocExpanded).toBe(false)
+
+      act(() => {
+        result.current.setIsTocExpanded(true)
+      })
+
+      expect(result.current.isTocExpanded).toBe(true)
+
+      act(() => {
+        result.current.setIsTocExpanded(false)
+      })
+
+      expect(result.current.isTocExpanded).toBe(false)
+    })
+  })
+
+  // Covers smooth-scroll click handler
+  describe('handleTocClick', () => {
+    it('should prevent default and scroll to target element', () => {
+      const scrollContainer = document.createElement('div')
+      scrollContainer.className = 'overflow-auto'
+      scrollContainer.scrollTo = vi.fn()
+      document.body.appendChild(scrollContainer)
+
+      const target = document.createElement('div')
+      target.id = 'target-section'
+      Object.defineProperty(target, 'offsetTop', { value: 500 })
+      scrollContainer.appendChild(target)
+
+      const { result } = renderHook(() => useDocToc(defaultOptions))
+
+      const mockEvent = { preventDefault: vi.fn() } as unknown as React.MouseEvent<HTMLAnchorElement>
+      act(() => {
+        result.current.handleTocClick(mockEvent, { href: '#target-section', text: 'Target' })
+      })
+
+      expect(mockEvent.preventDefault).toHaveBeenCalled()
+      expect(scrollContainer.scrollTo).toHaveBeenCalledWith({
+        top: 420, // 500 - 80 (HEADER_OFFSET)
+        behavior: 'smooth',
+      })
+
+      document.body.removeChild(scrollContainer)
+    })
+
+    it('should do nothing when target element does not exist', () => {
+      const { result } = renderHook(() => useDocToc(defaultOptions))
+
+      const mockEvent = { preventDefault: vi.fn() } as unknown as React.MouseEvent<HTMLAnchorElement>
+      act(() => {
+        result.current.handleTocClick(mockEvent, { href: '#nonexistent', text: 'Missing' })
+      })
+
+      expect(mockEvent.preventDefault).toHaveBeenCalled()
+    })
+  })
+
+  // Covers scroll-based active section tracking
+  describe('scroll tracking', () => {
+    // Helper: set up DOM with scroll container, article headings, and matching target elements
+    const setupScrollDOM = (sections: Array<{ id: string, text: string, top: number }>) => {
+      const scrollContainer = document.createElement('div')
+      scrollContainer.className = 'overflow-auto'
+      document.body.appendChild(scrollContainer)
+
+      const article = document.createElement('article')
+      sections.forEach(({ id, text, top }) => {
+        // Heading with anchor for TOC extraction
+        const h2 = document.createElement('h2')
+        const anchor = document.createElement('a')
+        anchor.href = `#${id}`
+        anchor.textContent = text
+        h2.appendChild(anchor)
+        article.appendChild(h2)
+
+        // Target element for scroll tracking
+        const target = document.createElement('div')
+        target.id = id
+        target.getBoundingClientRect = vi.fn().mockReturnValue({ top })
+        scrollContainer.appendChild(target)
+      })
+      document.body.appendChild(article)
+
+      return {
+        scrollContainer,
+        article,
+        cleanup: () => {
+          document.body.removeChild(scrollContainer)
+          document.body.removeChild(article)
+        },
+      }
+    }
+
+    it('should register scroll listener when toc has items', async () => {
+      vi.useFakeTimers()
+      const { scrollContainer, cleanup } = setupScrollDOM([
+        { id: 'sec-a', text: 'Section A', top: 0 },
+      ])
+      const addSpy = vi.spyOn(scrollContainer, 'addEventListener')
+      const removeSpy = vi.spyOn(scrollContainer, 'removeEventListener')
+
+      const { unmount } = renderHook(() => useDocToc(defaultOptions))
+
+      await act(async () => {
+        vi.runAllTimers()
+      })
+
+      expect(addSpy).toHaveBeenCalledWith('scroll', expect.any(Function))
+
+      unmount()
+
+      expect(removeSpy).toHaveBeenCalledWith('scroll', expect.any(Function))
+
+      cleanup()
+      vi.useRealTimers()
+    })
+
+    it('should update activeSection when scrolling past a section', async () => {
+      vi.useFakeTimers()
+      // innerHeight/2 = 384 in jsdom (default 768), so top <= 384 means "scrolled past"
+      const { scrollContainer, cleanup } = setupScrollDOM([
+        { id: 'intro', text: 'Intro', top: 100 },
+        { id: 'details', text: 'Details', top: 600 },
+      ])
+
+      const { result } = renderHook(() => useDocToc(defaultOptions))
+
+      // Extract TOC items
+      await act(async () => {
+        vi.runAllTimers()
+      })
+
+      expect(result.current.toc).toHaveLength(2)
+      expect(result.current.activeSection).toBe('intro')
+
+      // Fire scroll — 'intro' (top=100) is above midpoint, 'details' (top=600) is below
+      await act(async () => {
+        scrollContainer.dispatchEvent(new Event('scroll'))
+      })
+
+      expect(result.current.activeSection).toBe('intro')
+
+      cleanup()
+      vi.useRealTimers()
+    })
+
+    it('should track the last section above the viewport midpoint', async () => {
+      vi.useFakeTimers()
+      const { scrollContainer, cleanup } = setupScrollDOM([
+        { id: 'sec-1', text: 'Section 1', top: 50 },
+        { id: 'sec-2', text: 'Section 2', top: 200 },
+        { id: 'sec-3', text: 'Section 3', top: 800 },
+      ])
+
+      const { result } = renderHook(() => useDocToc(defaultOptions))
+
+      await act(async () => {
+        vi.runAllTimers()
+      })
+
+      // Fire scroll — sec-1 (top=50) and sec-2 (top=200) are above midpoint (384),
+      // sec-3 (top=800) is below. The last one above midpoint wins.
+      await act(async () => {
+        scrollContainer.dispatchEvent(new Event('scroll'))
+      })
+
+      expect(result.current.activeSection).toBe('sec-2')
+
+      cleanup()
+      vi.useRealTimers()
+    })
+
+    it('should not update activeSection when no section is above midpoint', async () => {
+      vi.useFakeTimers()
+      const { scrollContainer, cleanup } = setupScrollDOM([
+        { id: 'far-away', text: 'Far Away', top: 1000 },
+      ])
+
+      const { result } = renderHook(() => useDocToc(defaultOptions))
+
+      await act(async () => {
+        vi.runAllTimers()
+      })
+
+      // Initial activeSection is set by extraction
+      const initialSection = result.current.activeSection
+
+      await act(async () => {
+        scrollContainer.dispatchEvent(new Event('scroll'))
+      })
+
+      // Should not change since the element is below midpoint
+      expect(result.current.activeSection).toBe(initialSection)
+
+      cleanup()
+      vi.useRealTimers()
+    })
+
+    it('should handle elements not found in DOM during scroll', async () => {
+      vi.useFakeTimers()
+      const scrollContainer = document.createElement('div')
+      scrollContainer.className = 'overflow-auto'
+      document.body.appendChild(scrollContainer)
+
+      // Article with heading but NO matching target element by id
+      const article = document.createElement('article')
+      const h2 = document.createElement('h2')
+      const anchor = document.createElement('a')
+      anchor.href = '#missing-target'
+      anchor.textContent = 'Missing'
+      h2.appendChild(anchor)
+      article.appendChild(h2)
+      document.body.appendChild(article)
+
+      const { result } = renderHook(() => useDocToc(defaultOptions))
+
+      await act(async () => {
+        vi.runAllTimers()
+      })
+
+      const initialSection = result.current.activeSection
+
+      // Scroll fires but getElementById returns null — no crash, no change
+      await act(async () => {
+        scrollContainer.dispatchEvent(new Event('scroll'))
+      })
+
+      expect(result.current.activeSection).toBe(initialSection)
+
+      document.body.removeChild(scrollContainer)
+      document.body.removeChild(article)
+      vi.useRealTimers()
+    })
+  })
+})

web/app/components/develop/doc.tsx

@@ -1,12 +1,13 @@
 'use client'
-import { RiCloseLine, RiListUnordered } from '@remixicon/react'
-import { useEffect, useMemo, useState } from 'react'
-import { useTranslation } from 'react-i18next'
+import type { ComponentType } from 'react'
+import type { App, AppSSO } from '@/types/app'
+import { useMemo } from 'react'
 import { useLocale } from '@/context/i18n'
 import useTheme from '@/hooks/use-theme'
-import { LanguagesSupported } from '@/i18n-config/language'
+import { getDocLanguage } from '@/i18n-config/language'
 import { AppModeEnum, Theme } from '@/types/app'
 import { cn } from '@/utils/classnames'
+import { useDocToc } from './hooks/use-doc-toc'
 import TemplateEn from './template/template.en.mdx'
 import TemplateJa from './template/template.ja.mdx'
 import TemplateZh from './template/template.zh.mdx'
@@ -19,225 +20,75 @@ import TemplateChatZh from './template/template_chat.zh.mdx'
 import TemplateWorkflowEn from './template/template_workflow.en.mdx'
 import TemplateWorkflowJa from './template/template_workflow.ja.mdx'
 import TemplateWorkflowZh from './template/template_workflow.zh.mdx'
+import TocPanel from './toc-panel'
+
+type AppDetail = App & Partial<AppSSO>
+type PromptVariable = { key: string, name: string }
 
 type IDocProps = {
-  appDetail: any
+  appDetail: AppDetail
+}
+
+// Shared props shape for all MDX template components
+type TemplateProps = {
+  appDetail: AppDetail
+  variables: PromptVariable[]
+  inputs: Record<string, string>
+}
+
+// Lookup table: [appMode][docLanguage] → template component
+// MDX components accept arbitrary props at runtime but expose a narrow static type,
+// so we assert the map type to allow passing TemplateProps when rendering.
+const TEMPLATE_MAP = {
+  [AppModeEnum.CHAT]: { zh: TemplateChatZh, ja: TemplateChatJa, en: TemplateChatEn },
+  [AppModeEnum.AGENT_CHAT]: { zh: TemplateChatZh, ja: TemplateChatJa, en: TemplateChatEn },
+  [AppModeEnum.ADVANCED_CHAT]: { zh: TemplateAdvancedChatZh, ja: TemplateAdvancedChatJa, en: TemplateAdvancedChatEn },
+  [AppModeEnum.WORKFLOW]: { zh: TemplateWorkflowZh, ja: TemplateWorkflowJa, en: TemplateWorkflowEn },
+  [AppModeEnum.COMPLETION]: { zh: TemplateZh, ja: TemplateJa, en: TemplateEn },
+} as Record<string, Record<string, ComponentType<TemplateProps>>>
+
+const resolveTemplate = (mode: string | undefined, locale: string): ComponentType<TemplateProps> | null => {
+  if (!mode)
+    return null
+  const langTemplates = TEMPLATE_MAP[mode]
+  if (!langTemplates)
+    return null
+  const docLang = getDocLanguage(locale)
+  return langTemplates[docLang] ?? langTemplates.en ?? null
 }
 
 const Doc = ({ appDetail }: IDocProps) => {
   const locale = useLocale()
-  const { t } = useTranslation()
-  const [toc, setToc] = useState<Array<{ href: string, text: string }>>([])
-  const [isTocExpanded, setIsTocExpanded] = useState(false)
-  const [activeSection, setActiveSection] = useState<string>('')
   const { theme } = useTheme()
+  const { toc, isTocExpanded, setIsTocExpanded, activeSection, handleTocClick } = useDocToc({ appDetail, locale })
 
-  const variables = appDetail?.model_config?.configs?.prompt_variables || []
-  const inputs = variables.reduce((res: any, variable: any) => {
+  // model_config.configs.prompt_variables exists in the raw API response but is not modeled in ModelConfig type
+  const variables: PromptVariable[] = (
+    appDetail?.model_config as unknown as Record<string, Record<string, PromptVariable[]>> | undefined
+  )?.configs?.prompt_variables ?? []
+  const inputs = variables.reduce<Record<string, string>>((res, variable) => {
     res[variable.key] = variable.name || ''
     return res
   }, {})
 
-  useEffect(() => {
-    const mediaQuery = window.matchMedia('(min-width: 1280px)')
-    setIsTocExpanded(mediaQuery.matches)
-  }, [])
-
-  useEffect(() => {
-    const extractTOC = () => {
-      const article = document.querySelector('article')
-      if (article) {
-        const headings = article.querySelectorAll('h2')
-        const tocItems = Array.from(headings).map((heading) => {
-          const anchor = heading.querySelector('a')
-          if (anchor) {
-            return {
-              href: anchor.getAttribute('href') || '',
-              text: anchor.textContent || '',
-            }
-          }
-          return null
-        }).filter((item): item is { href: string, text: string } => item !== null)
-        setToc(tocItems)
-        if (tocItems.length > 0)
-          setActiveSection(tocItems[0].href.replace('#', ''))
-      }
-    }
-
-    setTimeout(extractTOC, 0)
-  }, [appDetail, locale])
-
-  useEffect(() => {
-    const handleScroll = () => {
-      const scrollContainer = document.querySelector('.overflow-auto')
-      if (!scrollContainer || toc.length === 0)
-        return
-
-      let currentSection = ''
-      toc.forEach((item) => {
-        const targetId = item.href.replace('#', '')
-        const element = document.getElementById(targetId)
-        if (element) {
-          const rect = element.getBoundingClientRect()
-          if (rect.top <= window.innerHeight / 2)
-            currentSection = targetId
-        }
-      })
-
-      if (currentSection && currentSection !== activeSection)
-        setActiveSection(currentSection)
-    }
-
-    const scrollContainer = document.querySelector('.overflow-auto')
-    if (scrollContainer) {
-      scrollContainer.addEventListener('scroll', handleScroll)
-      handleScroll()
-      return () => scrollContainer.removeEventListener('scroll', handleScroll)
-    }
-  }, [toc, activeSection])
-
-  const handleTocClick = (e: React.MouseEvent<HTMLAnchorElement>, item: { href: string, text: string }) => {
-    e.preventDefault()
-    const targetId = item.href.replace('#', '')
-    const element = document.getElementById(targetId)
-    if (element) {
-      const scrollContainer = document.querySelector('.overflow-auto')
-      if (scrollContainer) {
-        const headerOffset = 80
-        const elementTop = element.offsetTop - headerOffset
-        scrollContainer.scrollTo({
-          top: elementTop,
-          behavior: 'smooth',
-        })
-      }
-    }
-  }
-
-  const Template = useMemo(() => {
-    if (appDetail?.mode === AppModeEnum.CHAT || appDetail?.mode === AppModeEnum.AGENT_CHAT) {
-      switch (locale) {
-        case LanguagesSupported[1]:
-          return <TemplateChatZh appDetail={appDetail} variables={variables} inputs={inputs} />
-        case LanguagesSupported[7]:
-          return <TemplateChatJa appDetail={appDetail} variables={variables} inputs={inputs} />
-        default:
-          return <TemplateChatEn appDetail={appDetail} variables={variables} inputs={inputs} />
-      }
-    }
-    if (appDetail?.mode === AppModeEnum.ADVANCED_CHAT) {
-      switch (locale) {
-        case LanguagesSupported[1]:
-          return <TemplateAdvancedChatZh appDetail={appDetail} variables={variables} inputs={inputs} />
-        case LanguagesSupported[7]:
-          return <TemplateAdvancedChatJa appDetail={appDetail} variables={variables} inputs={inputs} />
-        default:
-          return <TemplateAdvancedChatEn appDetail={appDetail} variables={variables} inputs={inputs} />
-      }
-    }
-    if (appDetail?.mode === AppModeEnum.WORKFLOW) {
-      switch (locale) {
-        case LanguagesSupported[1]:
-          return <TemplateWorkflowZh appDetail={appDetail} variables={variables} inputs={inputs} />
-        case LanguagesSupported[7]:
-          return <TemplateWorkflowJa appDetail={appDetail} variables={variables} inputs={inputs} />
-        default:
-          return <TemplateWorkflowEn appDetail={appDetail} variables={variables} inputs={inputs} />
-      }
-    }
-    if (appDetail?.mode === AppModeEnum.COMPLETION) {
-      switch (locale) {
-        case LanguagesSupported[1]:
-          return <TemplateZh appDetail={appDetail} variables={variables} inputs={inputs} />
-        case LanguagesSupported[7]:
-          return <TemplateJa appDetail={appDetail} variables={variables} inputs={inputs} />
-        default:
-          return <TemplateEn appDetail={appDetail} variables={variables} inputs={inputs} />
-      }
-    }
-    return null
-  }, [appDetail, locale, variables, inputs])
+  const TemplateComponent = useMemo(
+    () => resolveTemplate(appDetail?.mode, locale),
+    [appDetail?.mode, locale],
+  )
 
   return (
     <div className="flex">
       <div className={`fixed right-20 top-32 z-10 transition-all duration-150 ease-out ${isTocExpanded ? 'w-[280px]' : 'w-11'}`}>
-        {isTocExpanded
-          ? (
-              <nav className="toc flex max-h-[calc(100vh-150px)] w-full flex-col overflow-hidden rounded-xl border-[0.5px] border-components-panel-border bg-background-default-hover shadow-xl">
-                <div className="relative z-10 flex items-center justify-between border-b border-components-panel-border-subtle bg-background-default-hover px-4 py-2.5">
-                  <span className="text-xs font-medium uppercase tracking-wide text-text-tertiary">
-                    {t('develop.toc', { ns: 'appApi' })}
-                  </span>
-                  <button
-                    type="button"
-                    onClick={() => setIsTocExpanded(false)}
-                    className="group flex h-6 w-6 items-center justify-center rounded-md transition-colors hover:bg-state-base-hover"
-                    aria-label="Close"
-                  >
-                    <RiCloseLine className="h-3 w-3 text-text-quaternary transition-colors group-hover:text-text-secondary" />
-                  </button>
-                </div>
-
-                <div className="from-components-panel-border-subtle/20 pointer-events-none absolute left-0 right-0 top-[41px] z-10 h-2 bg-gradient-to-b to-transparent"></div>
-                <div className="pointer-events-none absolute left-0 right-0 top-[43px] z-10 h-3 bg-gradient-to-b from-background-default-hover to-transparent"></div>
-
-                <div className="relative flex-1 overflow-y-auto px-3 py-3 pt-1">
-                  {toc.length === 0
-                    ? (
-                        <div className="px-2 py-8 text-center text-xs text-text-quaternary">
-                          {t('develop.noContent', { ns: 'appApi' })}
-                        </div>
-                      )
-                    : (
-                        <ul className="space-y-0.5">
-                          {toc.map((item, index) => {
-                            const isActive = activeSection === item.href.replace('#', '')
-                            return (
-                              <li key={index}>
-                                <a
-                                  href={item.href}
-                                  onClick={e => handleTocClick(e, item)}
-                                  className={cn(
-                                    'group relative flex items-center rounded-md px-3 py-2 text-[13px] transition-all duration-200',
-                                    isActive
-                                      ? 'bg-state-base-hover font-medium text-text-primary'
-                                      : 'text-text-tertiary hover:bg-state-base-hover hover:text-text-secondary',
-                                  )}
-                                >
-                                  <span
-                                    className={cn(
-                                      'mr-2 h-1.5 w-1.5 rounded-full transition-all duration-200',
-                                      isActive
-                                        ? 'scale-100 bg-text-accent'
-                                        : 'scale-75 bg-components-panel-border',
-                                    )}
-                                  />
-                                  <span className="flex-1 truncate">
-                                    {item.text}
-                                  </span>
-                                </a>
-                              </li>
-                            )
-                          })}
-                        </ul>
-                      )}
-                </div>
-
-                <div className="pointer-events-none absolute bottom-0 left-0 right-0 z-10 h-4 rounded-b-xl bg-gradient-to-t from-background-default-hover to-transparent"></div>
-              </nav>
-            )
-          : (
-              <button
-                type="button"
-                onClick={() => setIsTocExpanded(true)}
-                className="group flex h-11 w-11 items-center justify-center rounded-full border-[0.5px] border-components-panel-border bg-components-panel-bg shadow-lg transition-all duration-150 hover:bg-background-default-hover hover:shadow-xl"
-                aria-label="Open table of contents"
-              >
-                <RiListUnordered className="h-5 w-5 text-text-tertiary transition-colors group-hover:text-text-secondary" />
-              </button>
-            )}
+        <TocPanel
+          toc={toc}
+          activeSection={activeSection}
+          isTocExpanded={isTocExpanded}
+          onToggle={setIsTocExpanded}
+          onItemClick={handleTocClick}
+        />
       </div>
       <article className={cn('prose-xl prose', theme === Theme.dark && 'prose-invert')}>
-        {Template}
+        {TemplateComponent && <TemplateComponent appDetail={appDetail} variables={variables} inputs={inputs} />}
       </article>
     </div>
   )