Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

65.0 KB
Raw Blame
"""Tests for web/utils/vite_helper.py."""

import hashlib
import io
import json
import os
import threading
from pathlib import Path
from unittest.mock import Mock, patch

import pytest


class TestViteHelperInit:
    """Tests for ViteHelper initialization."""

    def test_init_without_app(self):
        """Test initialization without Flask app."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        assert helper.app is None
        assert helper.manifest is None
        assert helper.is_dev is False

    def test_init_with_app_calls_init_app(self):
        """Test that initialization with app calls init_app."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        mock_app = Mock()
        mock_app.debug = False
        mock_app.config = {}
        mock_app.jinja_env = Mock()
        mock_app.jinja_env.globals = {}

        with patch.object(ViteHelper, "_load_manifest"):
            helper = ViteHelper(app=mock_app)
            assert helper.app is mock_app


class TestViteHelperInitApp:
    """Tests for ViteHelper.init_app method."""

    def test_init_app_sets_app_attribute(self):
        """Test that init_app sets the app attribute."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        mock_app = Mock()
        mock_app.debug = False
        mock_app.config = {}
        mock_app.jinja_env = Mock()
        mock_app.jinja_env.globals = {}

        with patch.object(helper, "_load_manifest"):
            helper.init_app(mock_app)
            assert helper.app is mock_app

    def test_init_app_sets_dev_mode_from_debug(self):
        """Test that is_dev is set from app.debug."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        mock_app = Mock()
        mock_app.debug = True
        mock_app.config = {}
        mock_app.jinja_env = Mock()
        mock_app.jinja_env.globals = {}

        helper.init_app(mock_app)
        assert helper.is_dev is True

    def test_init_app_sets_dev_mode_from_config(self):
        """Test that is_dev can be set from VITE_DEV_MODE config."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        mock_app = Mock()
        mock_app.debug = False
        mock_app.config = {"VITE_DEV_MODE": True}
        mock_app.jinja_env = Mock()
        mock_app.jinja_env.globals = {}

        helper.init_app(mock_app)
        assert helper.is_dev is True

    def test_init_app_registers_vite_asset_global(self):
        """Test that vite_asset is registered as Jinja global."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        mock_app = Mock()
        mock_app.debug = True
        mock_app.config = {}
        mock_app.jinja_env = Mock()
        mock_app.jinja_env.globals = {}

        helper.init_app(mock_app)
        assert "vite_asset" in mock_app.jinja_env.globals
        assert mock_app.jinja_env.globals["vite_asset"] == helper.vite_asset

    def test_init_app_registers_vite_hmr_global(self):
        """Test that vite_hmr is registered as Jinja global."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        mock_app = Mock()
        mock_app.debug = True
        mock_app.config = {}
        mock_app.jinja_env = Mock()
        mock_app.jinja_env.globals = {}

        helper.init_app(mock_app)
        assert "vite_hmr" in mock_app.jinja_env.globals
        assert mock_app.jinja_env.globals["vite_hmr"] == helper.vite_hmr

    def test_init_app_loads_manifest_in_production(self):
        """Test that manifest is loaded in production mode."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        mock_app = Mock()
        mock_app.debug = False
        mock_app.config = {}
        mock_app.jinja_env = Mock()
        mock_app.jinja_env.globals = {}

        with patch.object(helper, "_load_manifest") as mock_load:
            helper.init_app(mock_app)
            mock_load.assert_called_once()

    def test_init_app_skips_manifest_in_dev(self):
        """Test that manifest loading is skipped in dev mode."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        mock_app = Mock()
        mock_app.debug = True
        mock_app.config = {}
        mock_app.jinja_env = Mock()
        mock_app.jinja_env.globals = {}

        with patch.object(helper, "_load_manifest") as mock_load:
            helper.init_app(mock_app)
            mock_load.assert_not_called()


class TestViteHelperLoadManifest:
    """Tests for ViteHelper._load_manifest method."""

    def test_load_manifest_reads_json_file(self, tmp_path):
        """Test that manifest JSON is loaded from file."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.app = Mock()
        helper.app.config = {"STATIC_DIR": str(tmp_path)}

        manifest_data = {"js/app.js": {"file": "assets/app-abc123.js"}}

        manifest_path = tmp_path / "dist" / ".vite" / "manifest.json"
        manifest_path.parent.mkdir(parents=True)
        manifest_path.write_text(json.dumps(manifest_data), encoding="utf-8")
        asset_path = tmp_path / "dist" / "assets" / "app-abc123.js"
        asset_path.parent.mkdir()
        asset_path.write_text("// built", encoding="utf-8")

        helper._load_manifest()
        assert helper.manifest == manifest_data

    def test_load_manifest_uses_default_static_dir(self, monkeypatch, tmp_path):
        """Test that default static directory is used when not configured."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.app = Mock()
        helper.app.config = {}

        monkeypatch.chdir(tmp_path)
        helper._load_manifest()
        assert helper.manifest == {}

    def test_load_manifest_handles_missing_file(self, tmp_path):
        """Test that missing manifest file results in empty dict."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.app = Mock()
        helper.app.config = {"STATIC_DIR": str(tmp_path)}

        helper._load_manifest()
        assert helper.manifest == {}


class TestViteHelperViteHmr:
    """Tests for ViteHelper.vite_hmr method."""

    def test_vite_hmr_returns_script_in_dev_mode(self):
        """Test that HMR script is returned in development mode."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = True

        result = helper.vite_hmr()
        assert "localhost:5173" in str(result)
        assert "@vite/client" in str(result)
        assert '<script type="module"' in str(result)

    def test_vite_hmr_returns_empty_in_production(self):
        """Test that empty string is returned in production mode."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = False

        result = helper.vite_hmr()
        assert result == ""


class TestViteHelperViteAsset:
    """Tests for ViteHelper.vite_asset method.

    Every helper here is a bare ``ViteHelper()`` with ``_manifest_path``
    left at None and ``manifest`` assigned in memory, which is the
    *no-`dist_root`* path: `_refresh_manifest_if_stale()` returns without
    touching the filesystem and `_entry_problem()` checks the manifest's
    shape only. These are markup/branching tests; they are not coverage of
    the on-disk validation, which needs a real `dist/` tree and lives in
    `TestRequestedEntryConsistency`.
    """

    def test_vite_asset_returns_dev_server_url_in_dev_mode(self):
        """Test that dev server URL is returned in development mode."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = True

        result = helper.vite_asset("js/app.js")
        assert "localhost:5173" in str(result)
        assert "js/app.js" in str(result)
        assert '<script type="module"' in str(result)

    def test_vite_asset_uses_default_entry_point(self):
        """Test that default entry point is used when not specified."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = True

        result = helper.vite_asset()
        assert "js/app.js" in str(result)

    def test_vite_asset_returns_manifest_path_in_production(self):
        """Test that manifest file path is returned in production."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = False
        helper.manifest = {
            "js/app.js": {
                "file": "assets/app-abc123.js",
            }
        }

        result = helper.vite_asset("js/app.js")
        assert "/static/dist/assets/app-abc123.js" in str(result)
        assert '<script type="module"' in str(result)

    def test_vite_asset_includes_css_from_manifest(self):
        """Test that CSS files from manifest are included."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = False
        helper.manifest = {
            "js/app.js": {
                "file": "assets/app-abc123.js",
                "css": ["assets/app-abc123.css", "assets/vendor-def456.css"],
            }
        }

        result = helper.vite_asset("js/app.js")
        assert "/static/dist/assets/app-abc123.css" in str(result)
        assert "/static/dist/assets/vendor-def456.css" in str(result)
        assert '<link rel="stylesheet"' in str(result)

    def test_vite_asset_returns_fallback_when_no_manifest(self):
        """Test that fallback is returned when manifest is empty."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = False
        helper.manifest = {}

        result = helper.vite_asset("js/app.js")
        assert "Vite build not found" in str(result)

    def test_vite_asset_returns_fallback_for_missing_entry(self):
        """Test that fallback is returned for missing entry point."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = False
        helper.manifest = {"other/file.js": {"file": "assets/other.js"}}

        result = helper.vite_asset("js/missing.js")
        assert "Vite build not found" in str(result)


@pytest.fixture(autouse=True)
def _reset_warned_causes():
    """Reset the module-level "already warned" guard around every test.

    `_warned_causes` is intentionally module-level state (so each distinct
    cause is reported once per process, not once per request). That means it
    leaks across tests unless we reset it, both before and after, so tests
    that check "warns" and tests that check "doesn't warn" don't depend on
    execution order.
    """
    import local_deep_research.web.utils.vite_helper as vite_helper_module

    vite_helper_module._warned_causes.clear()
    yield
    vite_helper_module._warned_causes.clear()


class TestViteHelperFallbackAssets:
    """Tests for ViteHelper._fallback_assets method."""

    def test_fallback_assets_returns_comment(self):
        """Test that fallback returns informative HTML comment."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        result = helper._fallback_assets()

        assert "Vite build not found" in str(result)
        assert "npm run build" in str(result)

    def test_missing_assets_banner_is_visible_and_self_contained(self):
        """The body-level banner names the problem and the fix."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = False
        helper.manifest = {}
        result_str = str(helper.missing_assets_banner())

        assert 'id="ldr-vite-missing-assets-banner"' in result_str
        assert "not been built" in result_str
        assert "npm run build" in result_str
        # Inline styles are required: the real stylesheet is what's missing.
        assert "style=" in result_str

    def test_missing_assets_banner_mentions_restart_as_a_fallback(self):
        """A restart is the last resort, not the instruction.

        The helper re-reads the manifest on every production render, so a
        rebuild is picked up without restarting anything - and the banner
        must say so, because telling operators to bounce the server for a
        problem a reload already fixes is how a 30-second fix becomes an
        outage. It still names a restart, as the fallback for the case where
        the banner survives a successful build and reload, which is the same
        thing `docs/FRONTEND_BUILD_SYSTEM.md` says.

        Merely asserting that the word "restart" appears is satisfied by the
        wording this replaced ("run `npm run build`, then restart the
        server"), which said the opposite. The sentences that carry the
        meaning are pinned instead.
        """
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = False
        helper.manifest = {}
        result_str = " ".join(str(helper.missing_assets_banner()).split())

        assert "picked up" in result_str
        assert "without a restart" in result_str
        assert "restarting the server is the last resort" in result_str

    def test_missing_assets_banner_empty_when_assets_built(self):
        """A healthy production build renders no banner at all."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = False
        helper.manifest = {"js/app.js": {"file": "assets/app-abc123.js"}}

        assert str(helper.missing_assets_banner()) == ""

    def test_missing_assets_banner_empty_in_dev_mode(self):
        """Dev-server mode has no manifest by design - never banner it."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = True
        helper.manifest = None

        assert str(helper.missing_assets_banner()) == ""

    def test_fallback_assets_logs_warning_once(self):
        """Test that a server-side warning is logged the first time."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            helper._fallback_assets()

        mock_logger.warning.assert_called_once()
        (message,), _ = mock_logger.warning.call_args
        assert "npm run build" in message

    def test_fallback_assets_with_entry_logs_entry_not_found(self):
        """When entry_point is passed, the warning names the missing entry.

        This locks the differentiated log contract: a missing manifest file
        and a missing entry inside an existing manifest are different
        operator-facing problems and must not share one vague message.
        """
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            helper._fallback_assets(entry_point="js/app.js")

        mock_logger.warning.assert_called_once()
        (message,), _ = mock_logger.warning.call_args
        assert "manifest entry" in message
        assert "js/app.js" in message
        assert "manifest not found" not in message

    def test_fallback_assets_does_not_repeat_warning(self):
        """Test that the warning is only logged once across repeated calls."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            helper._fallback_assets()
            helper._fallback_assets()
            helper._fallback_assets()

        mock_logger.warning.assert_called_once()

    def test_fallback_assets_warning_not_repeated_across_instances(self):
        """Test the guard is process/module-wide, not per-instance."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper_a = ViteHelper()
        helper_b = ViteHelper()

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            helper_a._fallback_assets()
            helper_b._fallback_assets()

        mock_logger.warning.assert_called_once()


def _write_manifest(static_dir, manifest):
    manifest_path = static_dir / "dist" / ".vite" / "manifest.json"
    manifest_path.parent.mkdir(parents=True, exist_ok=True)
    manifest_path.write_text(json.dumps(manifest), encoding="utf-8")
    return manifest_path


def _write_asset(static_dir, relative_path):
    asset_path = static_dir / "dist" / relative_path
    asset_path.parent.mkdir(parents=True, exist_ok=True)
    asset_path.write_text("// built", encoding="utf-8")
    return asset_path


def _production_helper(static_dir):
    from local_deep_research.web.utils.vite_helper import ViteHelper

    helper = ViteHelper()
    helper.is_dev = False
    helper.manifest = {}
    helper._manifest_path = static_dir / "dist" / ".vite" / "manifest.json"
    return helper


def _count_reads_and_parses(monkeypatch):
    """Record every manifest `Path.open` and every `json.loads`."""
    import local_deep_research.web.utils.vite_helper as vite_helper_module

    real_open = Path.open
    real_loads = vite_helper_module.json.loads
    opens = []
    parses = []

    def counting_open(path, *args, **kwargs):
        opens.append(path)
        return real_open(path, *args, **kwargs)

    def counting_loads(*args, **kwargs):
        parses.append(args)
        return real_loads(*args, **kwargs)

    monkeypatch.setattr(Path, "open", counting_open)
    monkeypatch.setattr(vite_helper_module.json, "loads", counting_loads)
    return opens, parses


def _swap_manifest_after_the_first_read(
    monkeypatch, manifest_path, replacement
):
    """Replace the manifest on disk the moment its first read returns.

    The reader gets the original bytes (served from memory, so the swap
    cannot retroactively change what it saw), and every later read sees the
    replacement - exactly the ordering a rebuild lands in during startup.
    """
    real_open = Path.open
    original = manifest_path.read_bytes()
    swapped = False

    def open_then_swap(path, *args, **kwargs):
        nonlocal swapped
        if path != manifest_path or swapped:
            return real_open(path, *args, **kwargs)
        swapped = True
        manifest_path.write_bytes(replacement)
        return io.BytesIO(original)

    monkeypatch.setattr(Path, "open", open_then_swap)


def _assert_fallback_and_banner(helper, stale_url):
    assert helper.assets_are_missing() is True
    assert stale_url not in str(helper.vite_asset())
    assert "Vite build not found" in str(helper.vite_asset())
    assert "ldr-vite-missing-assets-banner" in str(
        helper.missing_assets_banner()
    )


class TestViteHelperRefreshManifestIfStale:
    def test_unchanged_bytes_are_reread_but_not_reparsed(
        self, tmp_path, monkeypatch
    ):
        """Catches a revert that re-parses JSON on every healthy request.

        The steady-state cost is one bounded read plus a hash. Deleting the
        `fingerprint == self._manifest_fingerprint` short-circuit in
        `_adopt_manifest_from_disk` makes `json.loads` run per request and
        fails the `parses == []` assertion.
        """
        manifest = {"js/app.js": {"file": "js/app.OLDHASH.js"}}
        _write_manifest(tmp_path, manifest)
        _write_asset(tmp_path, "js/app.OLDHASH.js")
        helper = _production_helper(tmp_path)
        helper._refresh_manifest_if_stale()

        opens, parses = _count_reads_and_parses(monkeypatch)
        helper._refresh_manifest_if_stale()

        assert opens == [helper._manifest_path]
        assert parses == []

    def test_a_refused_manifest_is_parsed_once_not_once_per_request(
        self, tmp_path, monkeypatch
    ):
        """Catches removal of the rejected-fingerprint backoff.

        Adoption is a pure function of the manifest bytes, so re-parsing
        bytes already refused cannot change the verdict. Without the
        `fingerprint == self._rejected_fingerprint` short-circuit, a broken
        build re-parses on every `vite_asset()` *and* every banner call;
        with it, 50 renders cost one parse.
        """
        manifest_path = _write_manifest(
            tmp_path, {"js/app.js": {"file": "js/app.OLDHASH.js"}}
        )
        manifest_path.write_text("{broken", encoding="utf-8")
        helper = _production_helper(tmp_path)
        helper._refresh_manifest_if_stale()

        _opens, parses = _count_reads_and_parses(monkeypatch)
        for _ in range(50):
            helper.vite_asset()
            helper.missing_assets_banner()

        assert parses == []

    def test_the_backoff_still_adopts_a_later_valid_rebuild(self, tmp_path):
        """The backoff must not latch: new bytes are always parsed."""
        manifest_path = _write_manifest(
            tmp_path, {"js/app.js": {"file": "js/app.OLDHASH.js"}}
        )
        manifest_path.write_text("{broken", encoding="utf-8")
        helper = _production_helper(tmp_path)
        for _ in range(20):
            helper.vite_asset()

        _write_manifest(tmp_path, {"js/app.js": {"file": "js/app.NEW.js"}})
        _write_asset(tmp_path, "js/app.NEW.js")

        assert "js/app.NEW.js" in str(helper.vite_asset())

    def test_a_manifest_larger_than_the_read_cap_is_refused(self, tmp_path):
        """Catches a revert to an unbounded `read_bytes()`.

        A capped read means an oversized manifest is refused instead of
        materialised; the helper degrades rather than allocating whatever
        the file happens to contain.
        """
        from local_deep_research.web.utils.vite_helper import (
            _MAX_MANIFEST_BYTES,
        )

        manifest_path = _write_manifest(
            tmp_path, {"js/app.js": {"file": "js/app.OK.js"}}
        )
        _write_asset(tmp_path, "js/app.OK.js")
        padding = "A" * (_MAX_MANIFEST_BYTES + 1)
        manifest_path.write_text(
            json.dumps({"js/app.js": {"file": "js/app.OK.js", "pad": padding}}),
            encoding="utf-8",
        )
        helper = _production_helper(tmp_path)

        _assert_fallback_and_banner(helper, "js/app.OK.js")
        # The refusal has to remember *which* bytes it refused, like every
        # other refusal: without it the state is permanently "unknown", so
        # nothing downstream can tell a repeat of the same bad file from a
        # fresh one, and the backoff that the other refusal paths rely on
        # never engages.
        assert (
            helper._rejected_fingerprint
            == hashlib.sha256(
                manifest_path.read_bytes()[: _MAX_MANIFEST_BYTES + 1]
            ).hexdigest()
        )
        # Deleting the size check does not make this file *servable*: the
        # capped read hands `json.loads` a truncated document, which is
        # refused as malformed with the identical fingerprint. So the
        # markup, the banner and the fingerprint above are all satisfied by
        # a helper that has no size check at all. The recorded cause is the
        # only thing that distinguishes them.
        cause, _location = helper._manifest_failure
        assert "read cap" in cause, cause
        assert "not valid JSON" not in cause, cause

    def test_a_deeply_nested_manifest_degrades_instead_of_raising(
        self, tmp_path
    ):
        """Catches narrowing the parse guard back to `except ValueError`.

        `json.loads` raises RecursionError - not a ValueError - on deeply
        nested input, so an unguarded parse escapes into template rendering
        and turns every page into a 500 instead of a banner.
        """
        manifest_path = _write_manifest(
            tmp_path, {"js/app.js": {"file": "js/app.OK.js"}}
        )
        _write_asset(tmp_path, "js/app.OK.js")
        manifest_path.write_text(
            "[" * 200_000 + "]" * 200_000, encoding="utf-8"
        )
        helper = _production_helper(tmp_path)

        _assert_fallback_and_banner(helper, "js/app.OK.js")

    def test_no_filesystem_access_without_a_manifest_path(self):
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = False
        helper.manifest = {}

        with patch.object(Path, "open") as mock_open_path:
            helper._refresh_manifest_if_stale()

        mock_open_path.assert_not_called()

    def test_no_filesystem_access_in_dev_mode(self):
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = True
        helper._manifest_path = Path("/fake/static/dist/.vite/manifest.json")

        with patch.object(Path, "open") as mock_open_path:
            helper._refresh_manifest_if_stale()

        mock_open_path.assert_not_called()

    def test_initial_missing_manifest_recovers_after_a_valid_rebuild(
        self, tmp_path
    ):
        helper = _production_helper(tmp_path)
        helper._refresh_manifest_if_stale()
        _assert_fallback_and_banner(helper, "OLDHASH")

        manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
        _write_manifest(tmp_path, manifest)
        _write_asset(tmp_path, "js/app.NEWHASH.js")

        assert "js/app.NEWHASH.js" in str(helper.vite_asset())
        assert str(helper.missing_assets_banner()) == ""

    def test_vite_asset_reflects_a_valid_rebuild_on_the_next_request(
        self, tmp_path
    ):
        old_manifest = {"js/app.js": {"file": "js/app.OLDHASH.js"}}
        new_manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
        _write_manifest(tmp_path, old_manifest)
        _write_asset(tmp_path, "js/app.OLDHASH.js")
        helper = _production_helper(tmp_path)
        helper._refresh_manifest_if_stale()

        _write_manifest(tmp_path, new_manifest)
        _write_asset(tmp_path, "js/app.NEWHASH.js")

        assert helper.manifest == old_manifest
        assert "js/app.NEWHASH.js" in str(helper.vite_asset())
        assert helper.manifest == new_manifest

    def test_consistent_manifest_without_app_entry_is_refreshed(self, tmp_path):
        old_manifest = {"js/other.js": {"file": "js/other.OLDHASH.js"}}
        new_manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
        _write_manifest(tmp_path, old_manifest)
        _write_asset(tmp_path, "js/other.OLDHASH.js")
        helper = _production_helper(tmp_path)
        helper._refresh_manifest_if_stale()
        assert helper.assets_are_missing() is True

        _write_manifest(tmp_path, new_manifest)
        _write_asset(tmp_path, "js/app.NEWHASH.js")

        assert "js/app.NEWHASH.js" in str(helper.vite_asset())


class TestManifestAssetUrlEncoding:
    @pytest.mark.parametrize("field", ["file", "css"])
    @pytest.mark.parametrize(
        "filename",
        ["chunk?x.js", "chunk#x.js", "chunk%41.js", "chunk name.js", "文.js"],
    )
    def test_rendered_url_addresses_the_literal_filename(self, field, filename):
        """URL syntax must not change the filename validated on disk.

        This checks tag generation with an in-memory manifest: percent
        decoding the emitted path once must recover the exact filename,
        with no query or fragment and no duplicated encoding.
        """
        import re
        from urllib.parse import unquote, urlsplit

        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        entry = (
            {"file": filename}
            if field == "file"
            else {"file": "app.js", "css": [filename]}
        )
        helper.manifest = {"js/app.js": entry}
        html = str(helper.vite_asset())
        attribute = "src" if field == "file" else "href"
        match = re.search(rf'{attribute}="([^"]+)"', html)
        assert match is not None, html
        url = urlsplit(match.group(1))
        assert url.query == ""
        assert url.fragment == ""
        assert unquote(url.path) == f"/static/dist/{filename}"


class TestManifestSnapshotCoherence:
    def test_the_stored_fingerprint_describes_the_bytes_held_in_memory(
        self, tmp_path, monkeypatch
    ):
        """Catches any revert that fingerprints the file, not the bytes read.

        The startup read returns manifest A and the file becomes B before the
        fingerprint is taken. The invariant asserted here is the one that
        makes staleness detection work at all: `_manifest_fingerprint` is
        sha256(A) - the bytes actually in `self.manifest` - *not* sha256(B),
        the file's current content. Re-deriving the fingerprint from a second
        read or a stat (the shape this helper had before) stores B's key
        alongside A's data, and the next refresh sees "unchanged" and latches
        OLDHASH forever, which the follow-up assertions then catch.
        """
        from local_deep_research.web.utils.vite_helper import ViteHelper

        old_manifest = {"js/app.js": {"file": "js/app.OLDHASH.js"}}
        new_manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
        manifest_path = _write_manifest(tmp_path, old_manifest)
        _write_asset(tmp_path, "js/app.OLDHASH.js")
        _write_asset(tmp_path, "js/app.NEWHASH.js")
        original = json.dumps(old_manifest).encode("utf-8")
        replacement = json.dumps(new_manifest).encode("utf-8")
        assert manifest_path.read_bytes() == original
        _swap_manifest_after_the_first_read(
            monkeypatch, manifest_path, replacement
        )

        helper = ViteHelper()
        helper.app = Mock(config={"STATIC_DIR": str(tmp_path)})
        helper._load_manifest()

        # The replacement has already landed on disk, but startup adopted A.
        assert manifest_path.read_bytes() == replacement
        assert helper.manifest == old_manifest
        assert (
            helper._manifest_fingerprint == hashlib.sha256(original).hexdigest()
        )

        helper._refresh_manifest_if_stale()

        assert helper.manifest == new_manifest
        assert (
            helper._manifest_fingerprint
            == hashlib.sha256(replacement).hexdigest()
        )
        assert "js/app.NEWHASH.js" in str(helper.vite_asset())


class TestConcurrentManifestReplacement:
    """A rebuild landing mid-render must not poison the next render."""

    def test_a_manifest_swapped_mid_validation_cannot_poison_the_memo(
        self, tmp_path, monkeypatch
    ):
        """Catches splitting the snapshot back into separate attributes.

        `vite_asset()` renders from a manifest, asks whether that manifest's
        entry is servable, and records the answer. While those three lived
        in separate attributes, a refresh landing between the render's
        snapshot and the verdict's memo key stored a *positive* verification
        of manifest A under manifest B's fingerprint - after which B was
        served with validation skipped, durably, until its bytes changed
        again. The interleaving is forced through a monkeypatched hook, not
        timing, so this is deterministic rather than a stress test.

        B is deliberately a manifest that *renders*: its entry is an object
        with a perfectly good `file` string, pointing at a chunk that is not
        on disk. A B whose entry merely lacked `file` would be caught by the
        render path's own `.get("file")` guard even with the memo poisoned,
        so it could not tell a coherent snapshot apart from a bad one. With
        this B, the only thing standing between the poisoned memo and a
        `<script>` tag naming a file that does not exist is verifying B for
        itself.
        """
        from local_deep_research.web.utils.vite_helper import ViteHelper

        manifest_a = {"js/app.js": {"file": "js/app.AAA.js"}}
        manifest_b = {"js/app.js": {"file": "js/app.MISSING.js"}}
        _write_manifest(tmp_path, manifest_a)
        _write_asset(tmp_path, "js/app.AAA.js")
        # js/app.MISSING.js is deliberately never written.
        helper = _production_helper(tmp_path)

        real_entry_problem = ViteHelper._entry_problem
        swapped = threading.Event()

        def swap_then_validate(self, *args, **kwargs):
            # Runs in the render thread once `vite_asset()` has taken the
            # snapshot it will render from (A) and before that snapshot is
            # verified. A second thread publishes B here, and this returns
            # only once it has.
            if not swapped.is_set():
                swapped.set()

                def rewriter():
                    _write_manifest(tmp_path, manifest_b)
                    helper._refresh_manifest_if_stale()

                rewriter_thread = threading.Thread(
                    target=rewriter, name="manifest-rewriter"
                )
                rewriter_thread.start()
                rewriter_thread.join()
            return real_entry_problem(self, *args, **kwargs)

        monkeypatch.setattr(ViteHelper, "_entry_problem", swap_then_validate)

        rendered = []
        render_thread = threading.Thread(
            target=lambda: rendered.append(str(helper.vite_asset("js/app.js"))),
            name="render",
        )
        render_thread.start()
        render_thread.join()

        # The render that verified A serves A: its tag names a file that the
        # manifest it rendered from actually defines.
        assert rendered, "the render thread raised before producing markup"
        assert "js/app.AAA.js" in rendered[0]
        assert helper.manifest == manifest_b

        # The next render sees B, and must verify B for itself. A memo
        # attributed to the wrong manifest serves B's dangling URL here,
        # with no banner and no warning.
        html = str(helper.vite_asset("js/app.js"))
        assert "Vite build not found" in html
        assert "js/app.MISSING.js" not in html
        assert "js/app.AAA.js" not in html
        assert "<script" not in html
        assert helper.assets_are_missing() is True

    def test_a_rewritten_manifest_is_reverified_not_served_from_the_old_memo(
        self, tmp_path
    ):
        """Catches hoisting `verified_entries` off the state onto `self`.

        The sequential half of the pair above: no threads, no forced
        interleaving, just a manifest rewritten between two renders. The
        memo lives on the state, so the new state starts with an empty one
        and the new manifest is walked for itself. Hoisted onto the helper
        it survives the state swap, `js/app.js` is still "verified", and the
        second render serves a chunk that was never flushed - the exact
        stale URL this PR exists to stop.
        """
        _write_manifest(tmp_path, {"js/app.js": {"file": "js/app.AAA.js"}})
        _write_asset(tmp_path, "js/app.AAA.js")
        helper = _production_helper(tmp_path)

        assert "js/app.AAA.js" in str(helper.vite_asset("js/app.js"))
        assert helper.assets_are_missing() is False

        # New bytes; js/app.BBB.js is deliberately never written.
        _write_manifest(tmp_path, {"js/app.js": {"file": "js/app.BBB.js"}})

        html = str(helper.vite_asset("js/app.js"))
        assert "Vite build not found" in html
        assert "js/app.BBB.js" not in html
        assert "<script" not in html
        assert helper.assets_are_missing() is True

    def test_an_asset_deleted_after_verification_is_noticed_in_the_window(
        self, tmp_path, monkeypatch
    ):
        """Catches a memo that outlives the files it verified.

        Nothing rewrites `manifest.json` when a chunk is deleted from
        `dist/`, so the bytes-changed invalidation never fires and a
        verification recorded once would otherwise stand for the life of the
        process: `assets_are_missing()` keeps saying False and the page
        keeps carrying a `<script>` tag for a file that is gone. Each
        positive result is therefore stamped and re-checked once it is older
        than `_VERIFICATION_TTL_SECONDS`.

        The clock is faked rather than slept on, and the window is pinned at
        both ends: a midpoint, a point just under the TTL, and the TTL
        boundary itself. The comparison in `_entry_problem()` is a strict
        `<` (delta against `_VERIFICATION_TTL_SECONDS`), so a memo taken at
        t=0 must still answer at a delta just under the TTL and must be
        re-checked at a delta exactly equal to it; a `<` -> `<=` regression
        would keep answering from the memo at the exact boundary too, and
        only the boundary step below would catch that.
        """
        import local_deep_research.web.utils.vite_helper as vite_helper_module

        clock = {"now": 1000.0}
        monkeypatch.setattr(
            vite_helper_module, "_monotonic", lambda: clock["now"]
        )

        _write_manifest(tmp_path, {"js/app.js": {"file": "js/app.OK.js"}})
        asset = _write_asset(tmp_path, "js/app.OK.js")
        helper = _production_helper(tmp_path)

        verified_at = clock["now"]
        assert "js/app.OK.js" in str(helper.vite_asset("js/app.js"))
        assert helper.assets_are_missing() is False

        # manifest.json is untouched: same bytes, same hash, same state.
        asset.unlink()

        ttl = vite_helper_module._VERIFICATION_TTL_SECONDS

        clock["now"] = verified_at + ttl / 2
        assert helper.assets_are_missing() is False

        # Just under the TTL: still memoised, deletion not yet surfaced.
        clock["now"] = verified_at + ttl - 0.001
        assert helper.assets_are_missing() is False

        # Exactly at the TTL: the strict `<` must treat the memo as expired.
        clock["now"] = verified_at + ttl
        _assert_fallback_and_banner(helper, "js/app.OK.js")

    def test_a_verified_entry_without_a_file_string_still_falls_back(
        self, monkeypatch
    ):
        """Catches reverting `file_info.get("file")` to `file_info["file"]`.

        Validation and rendering are two separate reads of the same dict, so
        the render path may not treat the verdict as a guarantee about what
        it is about to subscript. With a bare subscript an entry that has no
        'file' key raises KeyError out of Jinja - a 500 on every page,
        instead of the degraded page the banner exists for.
        """
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = False
        helper.manifest = {"js/app.js": {"css": ["css/app.css"]}}
        monkeypatch.setattr(
            ViteHelper, "_entry_problem", lambda *args, **kwargs: None
        )

        html = str(helper.vite_asset("js/app.js"))

        assert "Vite build not found" in html
        assert "<script" not in html
        assert "<link" not in html


class TestContentChangeDetection:
    def test_equal_size_same_mtime_rewrite_is_adopted(self, tmp_path):
        old_manifest = {"js/app.js": {"file": "js/app.OLDHASH.js"}}
        new_manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
        old_bytes = json.dumps(old_manifest).encode("utf-8")
        new_bytes = json.dumps(new_manifest).encode("utf-8")
        assert len(old_bytes) == len(new_bytes)

        manifest_path = _write_manifest(tmp_path, old_manifest)
        _write_asset(tmp_path, "js/app.OLDHASH.js")
        helper = _production_helper(tmp_path)
        helper._refresh_manifest_if_stale()
        original_stat = manifest_path.stat()

        _write_asset(tmp_path, "js/app.NEWHASH.js")
        manifest_path.write_bytes(new_bytes)
        os.utime(
            manifest_path,
            ns=(original_stat.st_atime_ns, original_stat.st_mtime_ns),
        )
        rewritten_stat = manifest_path.stat()
        assert (
            rewritten_stat.st_mtime_ns,
            rewritten_stat.st_size,
        ) == (original_stat.st_mtime_ns, original_stat.st_size)

        helper._refresh_manifest_if_stale()

        assert helper.manifest == new_manifest
        assert "js/app.NEWHASH.js" in str(helper.vite_asset())


class TestFailClosedOnUnusableManifest:
    def test_deleted_manifest_drops_old_urls_and_recovers(self, tmp_path):
        old_manifest = {"js/app.js": {"file": "js/app.OLDHASH.js"}}
        new_manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
        manifest_path = _write_manifest(tmp_path, old_manifest)
        old_asset = _write_asset(tmp_path, "js/app.OLDHASH.js")
        helper = _production_helper(tmp_path)
        helper._refresh_manifest_if_stale()

        manifest_path.unlink()
        old_asset.unlink()
        _assert_fallback_and_banner(helper, "OLDHASH")

        _write_manifest(tmp_path, new_manifest)
        _write_asset(tmp_path, "js/app.NEWHASH.js")
        assert "js/app.NEWHASH.js" in str(helper.vite_asset())

    def test_malformed_manifest_drops_old_urls_and_recovers(self, tmp_path):
        old_manifest = {"js/app.js": {"file": "js/app.OLDHASH.js"}}
        new_manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
        manifest_path = _write_manifest(tmp_path, old_manifest)
        _write_asset(tmp_path, "js/app.OLDHASH.js")
        helper = _production_helper(tmp_path)
        helper._refresh_manifest_if_stale()
        old_fingerprint = helper._manifest_fingerprint

        manifest_path.write_text("{broken", encoding="utf-8")
        _assert_fallback_and_banner(helper, "OLDHASH")
        # The adopted fingerprint is dropped with the manifest it described;
        # the refused bytes are remembered separately, which is what stops
        # the degraded path re-parsing them on every request.
        assert helper._manifest_fingerprint is None
        assert helper._rejected_fingerprint not in (None, old_fingerprint)

        _write_manifest(tmp_path, new_manifest)
        _write_asset(tmp_path, "js/app.NEWHASH.js")
        assert "js/app.NEWHASH.js" in str(helper.vite_asset())

    def test_incomplete_manifest_drops_old_urls_and_recovers(self, tmp_path):
        old_manifest = {"js/app.js": {"file": "js/app.OLDHASH.js"}}
        incomplete_manifest = {
            "js/app.js": {
                "file": "js/app.NEWHASH.js",
                "css": ["css/app.NEWHASH.css"],
            }
        }
        _write_manifest(tmp_path, old_manifest)
        _write_asset(tmp_path, "js/app.OLDHASH.js")
        helper = _production_helper(tmp_path)
        helper._refresh_manifest_if_stale()

        _write_manifest(tmp_path, incomplete_manifest)
        _write_asset(tmp_path, "js/app.NEWHASH.js")
        _assert_fallback_and_banner(helper, "OLDHASH")

        _write_asset(tmp_path, "css/app.NEWHASH.css")
        assert "js/app.NEWHASH.js" in str(helper.vite_asset())


class TestRequestedEntryConsistency:
    """Validation is scoped to the closure of the entry actually asked for."""

    def test_an_unrelated_entry_missing_from_disk_still_serves_app_js(
        self, tmp_path
    ):
        """Catches re-widening validation to every manifest entry.

        The real manifest carries 67 top-level entries, 65 of them fonts
        that no template ever passes to `vite_asset()`. Validating all of
        them all-or-nothing turns one missing font - a single 404 on `main`
        - into an empty manifest, a blank page and a red banner. Only the
        requested entry's own closure may gate it.
        """
        manifest = {
            "js/app.js": {
                "file": "js/app.OKHASH.js",
                "css": ["css/app.OKHASH.css"],
                "imports": ["_vendor.js"],
            },
            "_vendor.js": {"file": "js/vendor.OKHASH.js"},
            "fonts/fa-solid-900.ttf": {
                "file": "fonts/fa-solid-900.MISSING.ttf"
            },
        }
        _write_manifest(tmp_path, manifest)
        _write_asset(tmp_path, "js/app.OKHASH.js")
        _write_asset(tmp_path, "css/app.OKHASH.css")
        _write_asset(tmp_path, "js/vendor.OKHASH.js")
        helper = _production_helper(tmp_path)

        html = str(helper.vite_asset("js/app.js"))
        assert "js/app.OKHASH.js" in html
        assert "css/app.OKHASH.css" in html
        assert str(helper.missing_assets_banner()) == ""
        assert helper.assets_are_missing() is False

    def test_the_unrelated_entry_is_still_refused_when_it_is_requested(
        self, tmp_path
    ):
        """Scoping must not become "never check": asking for it still fails."""
        manifest = {
            "js/app.js": {"file": "js/app.OKHASH.js"},
            "fonts/fa-solid-900.ttf": {
                "file": "fonts/fa-solid-900.MISSING.ttf"
            },
        }
        _write_manifest(tmp_path, manifest)
        _write_asset(tmp_path, "js/app.OKHASH.js")
        helper = _production_helper(tmp_path)

        html = str(helper.vite_asset("fonts/fa-solid-900.ttf"))
        assert "Vite build not found" in html
        assert "<script" not in html
        assert "<link" not in html

    def test_primary_file_missing_degrades_until_the_chunk_is_flushed(
        self, tmp_path
    ):
        """Catches removing the existence check on the entry's own `file`.

        Vite writes manifest.json before every hashed chunk is flushed, so an
        entry pointing at a file that is not there yet must degrade - and
        must recover on the very next call once it lands, which only works
        because negative results are not cached.
        """
        manifest = {"js/app.js": {"file": "js/app.NEWHASH.js"}}
        _write_manifest(tmp_path, manifest)
        helper = _production_helper(tmp_path)

        _assert_fallback_and_banner(helper, "NEWHASH")

        _write_asset(tmp_path, "js/app.NEWHASH.js")
        assert "js/app.NEWHASH.js" in str(helper.vite_asset())

    def test_missing_css_makes_the_requested_entry_unservable(self, tmp_path):
        """Catches dropping `css` from the per-entry closure walk.

        Without it the entry is served with a <link> to a stylesheet that
        404s - a styled-looking tag pointing at nothing.
        """
        manifest = {
            "js/app.js": {
                "file": "js/app.OKHASH.js",
                "css": ["css/app.MISSING.css"],
            }
        }
        _write_manifest(tmp_path, manifest)
        _write_asset(tmp_path, "js/app.OKHASH.js")
        helper = _production_helper(tmp_path)

        _assert_fallback_and_banner(helper, "app.OKHASH.js")

    def test_dangling_import_reference_is_rejected(self, tmp_path):
        manifest = {
            "js/app.js": {
                "file": "js/app.OKHASH.js",
                "imports": ["js/missing.js"],
            }
        }
        _write_manifest(tmp_path, manifest)
        _write_asset(tmp_path, "js/app.OKHASH.js")
        helper = _production_helper(tmp_path)

        _assert_fallback_and_banner(helper, "app.OKHASH.js")

    def test_an_unflushed_static_import_is_rejected(self, tmp_path):
        """A chunk the entry needs up front still gates the whole entry."""
        manifest = {
            "js/app.js": {
                "file": "js/app.OKHASH.js",
                "imports": ["js/vendor.js"],
            },
            "js/vendor.js": {"file": "js/vendor.MISSING.js"},
        }
        _write_manifest(tmp_path, manifest)
        _write_asset(tmp_path, "js/app.OKHASH.js")
        helper = _production_helper(tmp_path)

        _assert_fallback_and_banner(helper, "app.OKHASH.js")

    def test_an_unflushed_lazy_chunk_warns_but_still_serves_the_page(
        self, tmp_path
    ):
        """Catches putting `dynamicImports` back in the blocking closure.

        The shipped `js/app.js` entry lazily imports a canvg chunk that only
        the diagram-export path ever pulls in. Gating the entry on it means
        one unflushed lazy chunk renders the login form as a red banner -
        the app is unreachable over a feature nobody on that page uses. The
        chunk is still validated, and the operator is still told once; the
        blast radius is the one feature, not the whole UI.
        """
        manifest = {
            "js/app.js": {
                "file": "js/app.OKHASH.js",
                "dynamicImports": ["js/lazy.js"],
            },
            "js/lazy.js": {"file": "js/lazy.MISSING.js"},
        }
        _write_manifest(tmp_path, manifest)
        _write_asset(tmp_path, "js/app.OKHASH.js")
        helper = _production_helper(tmp_path)

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            html = str(helper.vite_asset("js/app.js"))

        assert "js/app.OKHASH.js" in html
        assert "Vite build not found" not in html
        assert str(helper.missing_assets_banner()) == ""
        assert helper.assets_are_missing() is False
        mock_logger.warning.assert_called_once()
        (message,), _ = mock_logger.warning.call_args
        assert "js/lazy.MISSING.js" in message
        assert "on demand" in message

    def test_a_dangling_lazy_reference_warns_but_still_serves_the_page(
        self, tmp_path
    ):
        """A `dynamicImports` name the manifest never defines is advisory too."""
        manifest = {
            "js/app.js": {
                "file": "js/app.OKHASH.js",
                "dynamicImports": ["js/nowhere.js"],
            }
        }
        _write_manifest(tmp_path, manifest)
        _write_asset(tmp_path, "js/app.OKHASH.js")
        helper = _production_helper(tmp_path)

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            html = str(helper.vite_asset("js/app.js"))

        assert "js/app.OKHASH.js" in html
        mock_logger.warning.assert_called_once()
        (message,), _ = mock_logger.warning.call_args
        assert "js/nowhere.js" in message

    def test_cyclic_imports_are_validated_once_and_served(self, tmp_path):
        """Catches dropping the `visited` set: a cycle would hang forever.

        "Hang forever" is why the walk runs on a worker thread with a
        bounded `join()`: without `visited` this test would not fail, it
        would never return, and a hung worker takes the whole suite with it
        instead of reporting one red test. The thread is a daemon so the
        interpreter can still exit if the assertion below trips.
        """
        manifest = {
            "js/app.js": {
                "file": "js/app.OKHASH.js",
                "imports": ["js/vendor.js"],
            },
            "js/vendor.js": {
                "file": "js/vendor.OKHASH.js",
                "dynamicImports": ["js/app.js"],
            },
        }
        _write_manifest(tmp_path, manifest)
        _write_asset(tmp_path, "js/app.OKHASH.js")
        _write_asset(tmp_path, "js/vendor.OKHASH.js")
        helper = _production_helper(tmp_path)

        helper._refresh_manifest_if_stale()
        assert helper.manifest == manifest

        verdicts = []
        walker = threading.Thread(
            target=lambda: verdicts.append(helper.assets_are_missing()),
            name="closure-walk",
            daemon=True,
        )
        walker.start()
        walker.join(timeout=30)

        assert not walker.is_alive(), (
            "the closure walk did not terminate on a cycle"
        )
        assert verdicts == [False]

    def test_path_outside_dist_is_rejected(self, tmp_path):
        """Catches dropping the `is_relative_to(dist_root)` containment check.

        `..`-escaping and symlinked targets must not become servable URLs
        just because the file happens to exist.
        """
        manifest = {"js/app.js": {"file": "../escaped.js"}}
        _write_manifest(tmp_path, manifest)
        escaped = tmp_path / "escaped.js"
        escaped.write_text("// outside dist", encoding="utf-8")
        helper = _production_helper(tmp_path)

        _assert_fallback_and_banner(helper, "escaped.js")

    def test_an_absolute_path_into_dist_is_rejected(self, tmp_path):
        """Catches accepting an absolute manifest path that lands in dist/.

        `dist_root / "/srv/app/static/dist/js/app.js"` is the absolute path
        itself (pathlib lets the absolute operand win), so containment and
        `is_file()` both pass - and the value is then pasted into
        `src="/static/dist/<path>"`, publishing the server's filesystem
        layout to every visitor on a URL that 404s anyway.
        """
        served = tmp_path / "dist" / "js" / "app.OKHASH.js"
        served.parent.mkdir(parents=True, exist_ok=True)
        served.write_text("// built", encoding="utf-8")
        _write_manifest(tmp_path, {"js/app.js": {"file": str(served)}})
        helper = _production_helper(tmp_path)

        html = str(helper.vite_asset("js/app.js"))
        assert "Vite build not found" in html
        assert str(tmp_path) not in html
        assert "<script" not in html

    @pytest.mark.parametrize(
        "manifest_file_value",
        [
            "js/app.OKHASH.js/",  # trailing separator
            "js//app.OKHASH.js",  # empty segment
            "js/app.OKHASH.js/.",  # '.' segment
            "./js/app.OKHASH.js",  # leading '.' segment
            "js/../js/app.OKHASH.js",  # '..' segment that stays inside
        ],
    )
    def test_an_unnormalised_path_is_rejected(
        self, tmp_path, manifest_file_value
    ):
        """Catches accepting paths pathlib normalises but a URL does not.

        Every value here resolves to the same real file inside `dist/`, so
        containment and `is_file()` both pass - and then the raw string is
        pasted into `src="/static/dist/<path>"`, where it is not the URL of
        the file that was just verified. `js/app.OKHASH.js/` renders a
        trailing slash, `js//app.OKHASH.js` renders a doubled separator, and
        the dot segments render paths a static handler is under no
        obligation to fold. All 404 while the check says "verified".
        """
        _write_manifest(tmp_path, {"js/app.js": {"file": manifest_file_value}})
        _write_asset(tmp_path, "js/app.OKHASH.js")
        helper = _production_helper(tmp_path)

        _assert_fallback_and_banner(helper, "app.OKHASH.js")

    def test_the_normalised_form_of_that_path_is_still_served(self, tmp_path):
        """The rejection above must be about the shape, not the file.

        Without this row, rejecting every path unconditionally passes the
        parametrised test.
        """
        _write_manifest(tmp_path, {"js/app.js": {"file": "js/app.OKHASH.js"}})
        _write_asset(tmp_path, "js/app.OKHASH.js")
        helper = _production_helper(tmp_path)

        assert "js/app.OKHASH.js" in str(helper.vite_asset("js/app.js"))
        assert helper.assets_are_missing() is False


class TestRefusedManifestIsReported:
    """A manifest that exists but is refused must not be silent or misdescribed."""

    def test_a_refused_manifest_warns_and_names_the_file(self, tmp_path):
        """Catches a silent `_fail_closed()`.

        Deleting the warning from `_fail_closed` (or gating the startup
        warning on `manifest_path.exists()` again) leaves a present-but-
        unusable manifest logging nothing at all, and the render-time
        fallback then blames a file that is sitting right there.
        """
        manifest_path = _write_manifest(
            tmp_path, {"js/app.js": {"file": "js/app.OK.js"}}
        )
        manifest_path.write_text("{broken", encoding="utf-8")
        helper = _production_helper(tmp_path)

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            markup = str(helper.vite_asset("js/app.js"))

        mock_logger.warning.assert_called_once()
        (message,), _ = mock_logger.warning.call_args
        assert str(manifest_path) in message
        assert "not valid JSON" in message
        assert "manifest not found" not in message
        # The rendered comment says the manifest was refused rather than
        # blaming a file that is sitting right there - and, unlike the log,
        # it carries neither the server's filesystem layout nor any
        # manifest-controlled text into every visitor's HTML.
        assert "read and refused" in markup
        assert str(manifest_path) not in markup
        assert str(tmp_path) not in markup

    def test_a_repeated_failure_warns_once_per_distinct_cause(self, tmp_path):
        """Catches a revert to the single-boolean "already warned" flag.

        With one process-wide boolean the first transient burns the only
        warning and every later, different failure is silent forever.
        Arrays and empty objects share one rejection cause, so changing
        between them must not warn again; removing the file is a distinct
        cause and must produce another warning.
        """
        manifest_path = _write_manifest(
            tmp_path, {"js/app.js": {"file": "js/app.OK.js"}}
        )
        manifest_path.write_text("{broken", encoding="utf-8")
        helper = _production_helper(tmp_path)

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            for _ in range(5):
                helper.vite_asset("js/app.js")
            assert mock_logger.warning.call_count == 1

            manifest_path.write_text("[1, 2, 3]", encoding="utf-8")
            helper.vite_asset("js/app.js")
            assert mock_logger.warning.call_count == 2

            manifest_path.write_text("{}", encoding="utf-8")
            helper.vite_asset("js/app.js")
            assert mock_logger.warning.call_count == 2

            manifest_path.unlink()
            helper.vite_asset("js/app.js")

        assert mock_logger.warning.call_count == 3
        messages = [call.args[0] for call in mock_logger.warning.call_args_list]
        assert "not valid JSON" in messages[0]
        assert "not a non-empty JSON object" in messages[1]
        assert "no readable manifest file" in messages[2]

    def test_an_unservable_entry_names_the_file_that_is_missing(self, tmp_path):
        """Catches dropping the reason from the entry-level warning."""
        _write_manifest(tmp_path, {"js/app.js": {"file": "js/app.GONE.js"}})
        helper = _production_helper(tmp_path)

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            helper.vite_asset("js/app.js")

        mock_logger.warning.assert_called_once()
        (message,), _ = mock_logger.warning.call_args
        assert "manifest entry" in message
        assert "js/app.js" in message
        assert "js/app.GONE.js" in message


class TestManifestDerivedTextInTheLog:
    """What a manifest says must not decide how much of the log it owns."""

    def test_churning_manifest_bytes_warn_once_not_once_per_render(
        self, tmp_path
    ):
        """Catches putting the fingerprint back in the warning's cause key.

        A manifest being rewritten with fresh garbage yields new bytes on
        every render and the *same* operator problem. Keying "warn once" on
        the bytes turns one warning into one per render, which buries every
        other line in the log; the fingerprint belongs in the message, where
        it identifies the snapshot without multiplying the records.
        """
        manifest_path = tmp_path / "dist" / ".vite" / "manifest.json"
        manifest_path.parent.mkdir(parents=True, exist_ok=True)
        helper = _production_helper(tmp_path)

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            for index in range(300):
                manifest_path.write_text(
                    "{broken " + "x" * index, encoding="utf-8"
                )
                helper.vite_asset("js/app.js")

        mock_logger.warning.assert_called_once()
        (message,), _ = mock_logger.warning.call_args
        assert "not valid JSON" in message
        assert "sha256" in message

    def test_a_manifest_key_cannot_forge_a_second_log_line(self, tmp_path):
        """Catches interpolating manifest-supplied text into a log record raw.

        manifest.json is not written by this process. A key containing a
        newline splices a second, fabricated record into the log that no
        aggregator can tell apart from a real one - so the text is escaped,
        not dropped: the operator still sees what the manifest actually
        said.
        """
        forged = "js/app.js\nERROR | totally-real-log-line"
        _write_manifest(
            tmp_path,
            {
                "js/app.js": {
                    "file": "js/app.OKHASH.js",
                    "imports": [forged],
                },
                forged: {},
            },
        )
        _write_asset(tmp_path, "js/app.OKHASH.js")
        helper = _production_helper(tmp_path)

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            helper.vite_asset("js/app.js")

        mock_logger.warning.assert_called_once()
        (message,), _ = mock_logger.warning.call_args
        assert "\n" not in message
        assert "\r" not in message
        assert "totally-real-log-line" in message


class TestViteAssetWarningIntegration:
    """End-to-end coverage of vite_asset()'s warning/banner behavior.

    "End-to-end" here means template-global to markup, not manifest file to
    markup: like `TestViteHelperViteAsset` these helpers have no
    ``_manifest_path``, so they exercise only the no-`dist_root` path and no
    file is ever read or checked. The disk-backed equivalents are in
    `TestRefusedManifestIsReported` and `TestRequestedEntryConsistency`.
    """

    def test_manifest_present_no_banner_no_warning(self):
        """Normal production path: no banner, no warning."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = False
        helper.manifest = {
            "js/app.js": {
                "file": "assets/app-abc123.js",
                "css": ["assets/app-abc123.css"],
            }
        }

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            result = helper.vite_asset("js/app.js")

        result_str = str(result)
        assert "assets/app-abc123.js" in result_str
        assert "ldr-vite-missing-assets-banner" not in result_str
        mock_logger.warning.assert_not_called()

    def test_manifest_missing_shows_banner_and_warns(self):
        """No manifest at all: fallback markup returned and warning logged."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = False
        helper.manifest = {}

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            result = helper.vite_asset("js/app.js")

        assert "Vite build not found" in str(result)
        mock_logger.warning.assert_called_once()
        # Manifest file itself is missing - operator must rebuild everything,
        # so the message names the manifest, not a specific entry.
        (message,), _ = mock_logger.warning.call_args
        assert "manifest not found" in message
        assert "manifest entry" not in message

    def test_manifest_missing_entry_shows_banner_and_warns(self):
        """Manifest exists but lacks the requested entry: fallback + warning."""
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = False
        helper.manifest = {"other/file.js": {"file": "assets/other.js"}}

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            result = helper.vite_asset("js/app.js")

        assert "Vite build not found" in str(result)
        mock_logger.warning.assert_called_once()
        # Manifest exists but the requested entry is absent - the message
        # must name the specific entry so the operator knows what's missing.
        (message,), _ = mock_logger.warning.call_args
        assert "manifest entry" in message
        assert "js/app.js" in message
        assert "manifest not found" not in message

    def test_dev_server_mode_never_warns_even_without_manifest(self):
        """Dev-server mode is a legitimate no-manifest state - must stay silent.

        In dev mode `vite_asset()` returns the Vite dev-server URL directly
        and never consults the manifest, so the "assets not built" warning
        (which only makes sense for the production/manifest path) must never
        fire here, even though `self.manifest` is None/unset just like the
        "never built" case.
        """
        from local_deep_research.web.utils.vite_helper import ViteHelper

        helper = ViteHelper()
        helper.is_dev = True
        helper.manifest = None

        with patch(
            "local_deep_research.web.utils.vite_helper.logger"
        ) as mock_logger:
            result = helper.vite_asset("js/app.js")

        result_str = str(result)
        assert "localhost:5173" in result_str
        assert "ldr-vite-missing-assets-banner" not in result_str
        mock_logger.warning.assert_not_called()


class TestViteSingleton:
    """Tests for the singleton vite instance."""

    def test_singleton_is_vite_helper_instance(self):
        """Test that singleton is a ViteHelper instance."""
        from local_deep_research.web.utils.vite_helper import vite, ViteHelper

        assert isinstance(vite, ViteHelper)