hvbrowser 0.2.2__tar.gz → 0.2.4__tar.gz

{hvbrowser-0.2.2 → hvbrowser-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hvbrowser
-Version: 0.2.2
+Version: 0.2.4
 Summary: Browser automation APIs for HentaiVerse.
 Project-URL: Homepage, https://github.com/Kuan-Lun/hvbrowser
 Project-URL: Tracker, https://github.com/Kuan-Lun/hvbrowser/issues
@@ -13,7 +13,7 @@ Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or l
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: <3.15,>=3.14
-Requires-Dist: hbrowser<0.37,>=0.36.4
+Requires-Dist: hbrowser<0.37,>=0.36.6
 Provides-Extra: dev
 Requires-Dist: black>=26.5.1; extra == 'dev'
 Requires-Dist: mypy>=2.3.0; extra == 'dev'

{hvbrowser-0.2.2 → hvbrowser-0.2.4}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hvbrowser"
-version = "0.2.2"
+version = "0.2.4"
 description = "Browser automation APIs for HentaiVerse."
 readme = "README.md"
 authors = [{ name = "Kuan-Lun Wang" }]
 license = "AGPL-3.0-or-later"
 license-files = ["LICENSE"]
 requires-python = ">=3.14,<3.15"
-dependencies = ["hbrowser>=0.36.4,<0.37"]
+dependencies = ["hbrowser>=0.36.6,<0.37"]
 
 classifiers = [
     "Development Status :: 3 - Alpha",

{hvbrowser-0.2.2 → hvbrowser-0.2.4}/src/hvbrowser/__init__.py

@@ -1,5 +1,16 @@
 """Public HentaiVerse browser composition API."""
 
+from .account_context import (
+    AccountContextError,
+    AccountContextState,
+    AccountContextStateError,
+    HentaiVerseAccountContext,
+    RealmBindingViolationError,
+    RealmBoundHVDriver,
+    RealmRuntime,
+    RealmTabBindingError,
+    realm_root_url,
+)
 from .equipment_repair import (
     EquipmentRepairClient,
     EquipmentRepairOutcome,
@@ -61,6 +72,9 @@ from .session import HentaiVerseSession
 from .urls import HENTAIVERSE_ISEKAI_ROOT_URL, HENTAIVERSE_ROOT_URL
 
 __all__ = [
+    "AccountContextError",
+    "AccountContextState",
+    "AccountContextStateError",
     "EquipmentRepairClient",
     "EquipmentRepairOutcome",
     "EquipmentRepairPageError",
@@ -71,6 +85,7 @@ __all__ = [
     "HENTAIVERSE_ISEKAI_ROOT_URL",
     "HENTAIVERSE_ROOT_URL",
     "HVDriver",
+    "HentaiVerseAccountContext",
     "HentaiVerseSession",
     "LOTTERY_TICKET_PRICE_GP",
     "LotteryClient",
@@ -105,11 +120,16 @@ __all__ = [
     "PlayerSnapshot",
     "PlayerStateChangedError",
     "Realm",
+    "RealmBindingViolationError",
+    "RealmBoundHVDriver",
     "RealmDetectionError",
     "RealmNavigator",
+    "RealmRuntime",
+    "RealmTabBindingError",
     "StaminaRecoveryError",
     "StaminaRecoveryOutcome",
     "StaminaRecoveryReport",
     "classify_maintenance_navigation_blocker",
     "realm_from_url",
+    "realm_root_url",
 ]

hvbrowser-0.2.4/src/hvbrowser/account_context.py

@@ -0,0 +1,523 @@
+"""One authenticated browser context with realm-bound HentaiVerse runtimes.
+
+The account context owns the browser lifecycle.  Persistent and Isekai each
+receive one immutable browser target and one driver that can never be switched
+to the other target.  Higher layers retain campaign and scheduling policy; this
+module only establishes and enforces the browser/realm ownership boundary.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from enum import StrEnum
+from functools import partial
+from typing import Any, Self, cast
+
+from hbrowser.gallery.browser import (
+    BrowserCloser,
+    BrowserFactory,
+    BrowserOwner,
+    TabFactory,
+    TabHandle,
+    TabNavigator,
+    TabTransport,
+    TargetIdGetter,
+    create_browser,
+    stop_browser,
+)
+
+from .hv import HVDriver
+from .realm import Realm, RealmDetectionError, realm_from_url
+from .urls import HENTAIVERSE_ISEKAI_ROOT_URL, HENTAIVERSE_ROOT_URL
+
+type AccountAuthenticator = Callable[[RealmBoundHVDriver], Awaitable[None]]
+type BoundDriverFactory[TabT] = Callable[
+    [Realm, TabTransport[TabT]], RealmBoundHVDriver
+]
+type CurrentUrlReader[TabT] = Callable[[TabT], Awaitable[object]]
+
+
+class AccountContextError(RuntimeError):
+    """Base error for account-context lifecycle and binding failures."""
+
+
+class AccountContextStateError(AccountContextError):
+    """An account-context operation is invalid in the current state."""
+
+
+class RealmTabBindingError(AccountContextError):
+    """A realm driver or operation attempted to use a different browser tab."""
+
+
+class RealmBindingViolationError(AccountContextError):
+    """A completed realm operation left its tab in another realm."""
+
+
+class AccountContextState(StrEnum):
+    """Lifecycle state of :class:`HentaiVerseAccountContext`."""
+
+    NEW = "new"
+    OPEN = "open"
+    CLOSED = "closed"
+
+
+def realm_root_url(realm: Realm) -> str:
+    """Return the canonical home URL for ``realm``."""
+
+    if not isinstance(realm, Realm):
+        raise TypeError("realm must be a Realm")
+    if realm is Realm.ISEKAI:
+        return HENTAIVERSE_ISEKAI_ROOT_URL
+    return HENTAIVERSE_ROOT_URL
+
+
+async def _read_zendriver_url(tab: Any) -> object:
+    return await tab.evaluate("window.location.href")
+
+
+async def _default_authenticator(driver: RealmBoundHVDriver) -> None:
+    await driver.login()
+
+
+class RealmBoundHVDriver(HVDriver):
+    """An :class:`HVDriver` permanently attached to one owner-managed target.
+
+    The browser is externally owned by :class:`BrowserOwner`.  This driver must
+    therefore never launch or close the browser.  Its inherited HentaiVerse
+    methods remain available for existing hvbrowser and hvbattle clients, while
+    the ``page`` property rejects replacement after the initial binding.
+    """
+
+    def __init__(
+        self,
+        realm: Realm,
+        transport: TabTransport[Any],
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        if not isinstance(realm, Realm):
+            raise TypeError("realm must be a Realm")
+        if transport.role != realm.value:
+            raise RealmTabBindingError(
+                f"tab role {transport.role!r} does not match realm {realm.value!r}"
+            )
+
+        self._realm_page: Any = None
+        self._realm_page_frozen = False
+        self._realm = realm
+        self._transport = transport
+        self._bound = False
+        super().__init__(*args, **kwargs)
+
+    @property
+    def page(self) -> Any:
+        """The fixed raw tab used by inherited browser clients."""
+
+        return self._realm_page
+
+    @page.setter
+    def page(self, value: Any) -> None:
+        current = getattr(self, "_realm_page", None)
+        if getattr(self, "_realm_page_frozen", False) and value is not current:
+            raise RealmTabBindingError(
+                f"cannot replace the {self._realm.value} realm tab"
+            )
+        self._realm_page = value
+
+    @property
+    def realm(self) -> Realm:
+        return self._realm
+
+    @property
+    def transport(self) -> TabTransport[Any]:
+        return self._transport
+
+    @property
+    def tab_handle(self) -> TabHandle:
+        return self._transport.handle
+
+    @property
+    def is_bound(self) -> bool:
+        return self._bound
+
+    async def bind(self, browser: Any) -> Self:
+        """Bind once to this driver's transport without taking ownership."""
+
+        if self._bound:
+            raise RealmTabBindingError(f"{self._realm.value} driver is already bound")
+
+        async def bind_tab(tab: Any) -> None:
+            self.bind_existing_browser(browser, tab, owns_browser=False)
+            self._realm_page_frozen = True
+            self._bound = True
+
+        await self._transport.execute(bind_tab)
+        return self
+
+    async def _init_browser(self) -> None:
+        raise AccountContextStateError(
+            "a realm-bound driver cannot launch a browser; start its account "
+            "context instead"
+        )
+
+
+class RealmRuntime[TabT]:
+    """Execute work on one fixed realm tab and enforce realm identity.
+
+    Calls to :meth:`execute` hold both the runtime operation lock and the
+    underlying target lock.  Existing clients may use the supplied bound driver
+    inside the callback without consulting a mutable current-page pointer.
+    """
+
+    def __init__(
+        self,
+        *,
+        realm: Realm,
+        transport: TabTransport[TabT],
+        driver: RealmBoundHVDriver,
+        current_url_reader: CurrentUrlReader[TabT],
+    ) -> None:
+        if transport.role != realm.value:
+            raise RealmTabBindingError(
+                f"tab role {transport.role!r} does not match realm {realm.value!r}"
+            )
+        if driver.realm is not realm or driver.transport is not transport:
+            raise RealmTabBindingError(
+                "realm driver and runtime must share one realm transport"
+            )
+        if not driver.is_bound:
+            raise RealmTabBindingError("realm driver must be bound before use")
+
+        self._realm = realm
+        self._transport = transport
+        self._driver = driver
+        self._current_url_reader = current_url_reader
+        self._operation_lock = asyncio.Lock()
+
+    @property
+    def realm(self) -> Realm:
+        return self._realm
+
+    @property
+    def transport(self) -> TabTransport[TabT]:
+        return self._transport
+
+    @property
+    def tab_handle(self) -> TabHandle:
+        return self._transport.handle
+
+    @property
+    def driver(self) -> RealmBoundHVDriver:
+        """The immutable-page driver used by operations in this runtime."""
+
+        return self._driver
+
+    async def _read_current_url(self) -> object:
+        return await self._transport.execute(self._current_url_reader)
+
+    async def current_realm(self) -> Realm:
+        """Inspect the realm currently displayed by the fixed tab."""
+
+        return realm_from_url(await self._read_current_url())
+
+    async def _assert_current_realm(self) -> None:
+        current = await self.current_realm()
+        if current is not self._realm:
+            raise RealmTabBindingError(
+                f"{self._realm.value} runtime observed the {current.value} realm"
+            )
+
+    async def _navigate_home(self) -> None:
+        await self._transport.navigate(realm_root_url(self._realm))
+        await self._assert_current_realm()
+
+    async def ensure_realm(self) -> None:
+        """Restore this tab to its bound realm if it drifted elsewhere."""
+
+        async with self._operation_lock:
+            try:
+                await self._assert_current_realm()
+            except RealmDetectionError, RealmTabBindingError:
+                await self._navigate_home()
+
+    async def _ensure_before_operation(self) -> None:
+        try:
+            await self._assert_current_realm()
+        except RealmDetectionError, RealmTabBindingError:
+            await self._navigate_home()
+
+    async def _restore_after_operation(self) -> None:
+        try:
+            await self._assert_current_realm()
+        except (RealmDetectionError, RealmTabBindingError) as drift_error:
+            try:
+                await self._navigate_home()
+            except BaseException as restore_error:
+                drift_error.add_note(
+                    "restoring the bound realm also failed: "
+                    f"{type(restore_error).__name__}"
+                )
+            raise RealmBindingViolationError(
+                f"operation left the {self._realm.value} realm tab outside its "
+                "binding"
+            ) from drift_error
+
+    async def execute[ResultT](
+        self,
+        operation: Callable[[RealmBoundHVDriver], Awaitable[ResultT]],
+    ) -> ResultT:
+        """Run one operation against the fixed driver and verify its realm."""
+
+        async with self._operation_lock:
+            await self._ensure_before_operation()
+
+            async def run(_: TabT) -> ResultT:
+                return await operation(self._driver)
+
+            try:
+                result = await self._transport.execute(run)
+            except BaseException as operation_error:
+                try:
+                    await self._restore_after_operation()
+                except RealmBindingViolationError as binding_error:
+                    operation_error.add_note(
+                        "the realm operation failed after leaving its bound realm; "
+                        f"the tab was restored ({type(binding_error).__name__})"
+                    )
+                raise
+
+            await self._restore_after_operation()
+            return result
+
+    async def navigate(self, url: str) -> None:
+        """Navigate within this runtime's realm, rejecting cross-realm URLs."""
+
+        try:
+            destination = realm_from_url(url)
+        except RealmDetectionError as error:
+            raise RealmTabBindingError(
+                f"{self._realm.value} runtime rejected an untrusted destination"
+            ) from error
+        if destination is not self._realm:
+            raise RealmTabBindingError(
+                f"{self._realm.value} runtime rejected a cross-realm destination"
+            )
+
+        async with self._operation_lock:
+            await self._ensure_before_operation()
+            await self._transport.navigate(url)
+            await self._restore_after_operation()
+
+    async def go_home(self) -> None:
+        """Navigate the fixed tab to its canonical realm root."""
+
+        await self.navigate(realm_root_url(self._realm))
+
+    async def _authenticate(
+        self,
+        authenticator: AccountAuthenticator,
+    ) -> None:
+        """Run the one account login before normal realm checks are enabled."""
+
+        async with self._operation_lock:
+
+            async def authenticate(_: TabT) -> None:
+                await authenticator(self._driver)
+
+            await self._transport.execute(authenticate)
+            await self._assert_current_realm()
+
+    async def _establish(self) -> None:
+        async with self._operation_lock:
+            await self._navigate_home()
+
+
+class HentaiVerseAccountContext[BrowserT, TabT]:
+    """Own one authenticated browser and two fixed HentaiVerse realm tabs."""
+
+    def __init__(
+        self,
+        *,
+        headless: bool = True,
+        authenticator: AccountAuthenticator | None = None,
+        browser_factory: BrowserFactory[BrowserT, TabT] | None = None,
+        browser_closer: BrowserCloser[BrowserT] | None = None,
+        tab_factory: TabFactory[BrowserT, TabT] | None = None,
+        tab_navigator: TabNavigator[TabT] | None = None,
+        target_id_getter: TargetIdGetter[TabT] | None = None,
+        current_url_reader: CurrentUrlReader[TabT] | None = None,
+        driver_factory: BoundDriverFactory[TabT] | None = None,
+        owner_id: str | None = None,
+    ) -> None:
+        default_browser_factory = partial(create_browser, headless=headless)
+        resolved_browser_factory = browser_factory or cast(
+            BrowserFactory[BrowserT, TabT],
+            default_browser_factory,
+        )
+        self._browser: BrowserT | None = None
+
+        async def capture_browser() -> tuple[BrowserT, TabT]:
+            browser, tab = await resolved_browser_factory()
+            self._browser = browser
+            return browser, tab
+
+        self._owner = BrowserOwner(
+            headless=headless,
+            main_tab_role=Realm.PERSISTENT.value,
+            owner_id=owner_id,
+            browser_factory=capture_browser,
+            browser_closer=browser_closer
+            or cast(BrowserCloser[BrowserT], stop_browser),
+            tab_factory=tab_factory,
+            tab_navigator=tab_navigator,
+            target_id_getter=target_id_getter,
+        )
+        self._authenticator = authenticator or _default_authenticator
+        self._current_url_reader = current_url_reader or cast(
+            CurrentUrlReader[TabT],
+            _read_zendriver_url,
+        )
+        self._driver_factory = driver_factory or cast(
+            BoundDriverFactory[TabT],
+            lambda realm, transport: RealmBoundHVDriver(
+                realm,
+                transport,
+                headless=headless,
+            ),
+        )
+        self._persistent: RealmRuntime[TabT] | None = None
+        self._isekai: RealmRuntime[TabT] | None = None
+        self._state = AccountContextState.NEW
+        self._lifecycle_lock = asyncio.Lock()
+
+    @property
+    def state(self) -> AccountContextState:
+        return self._state
+
+    @property
+    def owner(self) -> BrowserOwner[BrowserT, TabT]:
+        return self._owner
+
+    def _require_open(self) -> None:
+        if self._state is not AccountContextState.OPEN:
+            raise AccountContextStateError(
+                f"account context is not open (state: {self._state.value})"
+            )
+
+    @property
+    def persistent(self) -> RealmRuntime[TabT]:
+        self._require_open()
+        assert self._persistent is not None
+        return self._persistent
+
+    @property
+    def isekai(self) -> RealmRuntime[TabT]:
+        self._require_open()
+        assert self._isekai is not None
+        return self._isekai
+
+    def runtime(self, realm: Realm) -> RealmRuntime[TabT]:
+        """Return the fixed runtime for ``realm``."""
+
+        if not isinstance(realm, Realm):
+            raise TypeError("realm must be a Realm")
+        if realm is Realm.ISEKAI:
+            return self.isekai
+        return self.persistent
+
+    async def _bind_runtime(
+        self,
+        realm: Realm,
+        transport: TabTransport[TabT],
+    ) -> RealmRuntime[TabT]:
+        browser = self._browser
+        if browser is None:
+            raise AccountContextStateError("started browser owner has no browser")
+        driver = self._driver_factory(realm, transport)
+        if not isinstance(driver, RealmBoundHVDriver):
+            raise TypeError("driver_factory must return RealmBoundHVDriver")
+        await driver.bind(browser)
+        return RealmRuntime(
+            realm=realm,
+            transport=transport,
+            driver=driver,
+            current_url_reader=self._current_url_reader,
+        )
+
+    async def start(self) -> Self:
+        """Start, authenticate once, and establish both realm tabs."""
+
+        async with self._lifecycle_lock:
+            if self._state is AccountContextState.OPEN:
+                return self
+            if self._state is not AccountContextState.NEW:
+                raise AccountContextStateError(
+                    f"cannot start account context in {self._state.value!r} state"
+                )
+
+            try:
+                await self._owner.start()
+                persistent = await self._bind_runtime(
+                    Realm.PERSISTENT,
+                    self._owner.main_tab,
+                )
+                await persistent._authenticate(self._authenticator)
+
+                isekai_transport = await self._owner.open_tab(Realm.ISEKAI.value)
+                isekai = await self._bind_runtime(Realm.ISEKAI, isekai_transport)
+                await isekai._establish()
+            except BaseException as startup_error:
+                try:
+                    await self._owner.close()
+                except BaseException as cleanup_error:
+                    startup_error.add_note(
+                        "account browser cleanup also failed: "
+                        f"{type(cleanup_error).__name__}"
+                    )
+                self._state = AccountContextState.CLOSED
+                raise
+
+            self._persistent = persistent
+            self._isekai = isekai
+            self._state = AccountContextState.OPEN
+            return self
+
+    async def close(self) -> None:
+        """Close the single browser owner; bound drivers never close it."""
+
+        async with self._lifecycle_lock:
+            if self._state is AccountContextState.CLOSED:
+                return
+            try:
+                await self._owner.close()
+            finally:
+                self._state = AccountContextState.CLOSED
+
+    async def __aenter__(self) -> Self:
+        return await self.start()
+
+    async def __aexit__(
+        self,
+        exc_type: Any,
+        exc_value: Any,
+        traceback: Any,
+    ) -> None:
+        del exc_type, exc_value, traceback
+        await self.close()
+
+
+__all__ = [
+    "AccountAuthenticator",
+    "AccountContextError",
+    "AccountContextState",
+    "AccountContextStateError",
+    "BoundDriverFactory",
+    "CurrentUrlReader",
+    "HentaiVerseAccountContext",
+    "RealmBindingViolationError",
+    "RealmBoundHVDriver",
+    "RealmRuntime",
+    "RealmTabBindingError",
+    "realm_root_url",
+]

hvbrowser-0.2.4/tests/test_account_context.py

@@ -0,0 +1,236 @@
+import unittest
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from unittest.mock import AsyncMock
+
+from hvbrowser.account_context import (
+    AccountContextState,
+    AccountContextStateError,
+    HentaiVerseAccountContext,
+    RealmBindingViolationError,
+    RealmBoundHVDriver,
+    RealmTabBindingError,
+)
+from hvbrowser.realm import Realm
+from hvbrowser.urls import HENTAIVERSE_ISEKAI_ROOT_URL, HENTAIVERSE_ROOT_URL
+
+
+@dataclass(slots=True)
+class _FakeTab:
+    target_id: str
+    url: str = "about:blank"
+    navigations: list[str] = field(default_factory=list)
+
+    async def evaluate(self, script: str) -> str:
+        if script != "window.location.href":
+            raise AssertionError(f"unexpected script: {script}")
+        return self.url
+
+    async def get(self, url: str) -> None:
+        self.url = url
+        self.navigations.append(url)
+
+
+@dataclass(slots=True)
+class _FakeBrowser:
+    current_tab: _FakeTab
+
+
+class AccountContextTests(unittest.IsolatedAsyncioTestCase):
+    def _context(
+        self,
+        *,
+        authenticator: Callable[[RealmBoundHVDriver], Awaitable[None]] | None = None,
+    ) -> tuple[
+        HentaiVerseAccountContext[_FakeBrowser, _FakeTab],
+        _FakeBrowser,
+        _FakeTab,
+        _FakeTab,
+        AsyncMock,
+        list[str],
+    ]:
+        persistent_tab = _FakeTab("persistent-target")
+        isekai_tab = _FakeTab("isekai-target")
+        browser = _FakeBrowser(persistent_tab)
+        browser_closer = AsyncMock()
+        authentication_targets: list[str] = []
+
+        async def create_browser() -> tuple[_FakeBrowser, _FakeTab]:
+            return browser, persistent_tab
+
+        async def open_tab(_: _FakeBrowser) -> _FakeTab:
+            return isekai_tab
+
+        async def navigate(tab: _FakeTab, url: str) -> None:
+            await tab.get(url)
+
+        async def authenticate(driver: RealmBoundHVDriver) -> None:
+            authentication_targets.append(driver.tab_handle.target_id)
+            await driver.page.get(HENTAIVERSE_ROOT_URL)
+
+        context = HentaiVerseAccountContext(
+            owner_id="account-test",
+            authenticator=authenticator or authenticate,
+            browser_factory=create_browser,
+            browser_closer=browser_closer,
+            tab_factory=open_tab,
+            tab_navigator=navigate,
+            target_id_getter=lambda tab: tab.target_id,
+        )
+        return (
+            context,
+            browser,
+            persistent_tab,
+            isekai_tab,
+            browser_closer,
+            authentication_targets,
+        )
+
+    async def test_one_login_establishes_two_immutable_realm_targets(self) -> None:
+        (
+            context,
+            _,
+            persistent_tab,
+            isekai_tab,
+            browser_closer,
+            authentication_targets,
+        ) = self._context()
+
+        async with context:
+            self.assertEqual(context.state, AccountContextState.OPEN)
+            self.assertEqual(authentication_targets, ["persistent-target"])
+            self.assertEqual(context.persistent.realm, Realm.PERSISTENT)
+            self.assertEqual(context.isekai.realm, Realm.ISEKAI)
+            self.assertEqual(
+                context.persistent.tab_handle.target_id,
+                "persistent-target",
+            )
+            self.assertEqual(context.isekai.tab_handle.target_id, "isekai-target")
+            self.assertEqual(
+                context.persistent.tab_handle.owner_id,
+                context.isekai.tab_handle.owner_id,
+            )
+            self.assertIs(context.persistent.driver.page, persistent_tab)
+            self.assertIs(context.isekai.driver.page, isekai_tab)
+            self.assertFalse(context.persistent.driver.owns_browser)
+            self.assertFalse(context.isekai.driver.owns_browser)
+            self.assertEqual(persistent_tab.url, HENTAIVERSE_ROOT_URL)
+            self.assertEqual(isekai_tab.url, HENTAIVERSE_ISEKAI_ROOT_URL)
+
+        self.assertEqual(context.state, AccountContextState.CLOSED)
+        browser_closer.assert_awaited_once()
+
+    async def test_runtime_does_not_follow_browser_current_tab(self) -> None:
+        context, browser, persistent_tab, isekai_tab, _, _ = self._context()
+        await context.start()
+        self.addAsyncCleanup(context.close)
+        browser.current_tab = isekai_tab
+
+        persistent_seen = await context.persistent.execute(
+            lambda driver: _return(driver.page.target_id)
+        )
+        browser.current_tab = persistent_tab
+        isekai_seen = await context.isekai.execute(
+            lambda driver: _return(driver.page.target_id)
+        )
+
+        self.assertEqual(persistent_seen, "persistent-target")
+        self.assertEqual(isekai_seen, "isekai-target")
+
+    async def test_runtime_repairs_drift_before_running_operation(self) -> None:
+        context, _, persistent_tab, _, _, _ = self._context()
+        await context.start()
+        self.addAsyncCleanup(context.close)
+        persistent_tab.url = HENTAIVERSE_ISEKAI_ROOT_URL
+
+        seen_url = await context.persistent.execute(
+            lambda driver: driver.page.evaluate("window.location.href")
+        )
+
+        self.assertEqual(seen_url, HENTAIVERSE_ROOT_URL)
+        self.assertEqual(persistent_tab.url, HENTAIVERSE_ROOT_URL)
+        self.assertEqual(persistent_tab.navigations[-1], HENTAIVERSE_ROOT_URL)
+
+    async def test_runtime_restores_and_reports_post_operation_drift(self) -> None:
+        context, _, persistent_tab, _, _, _ = self._context()
+        await context.start()
+        self.addAsyncCleanup(context.close)
+
+        async def cross_realm(driver: RealmBoundHVDriver) -> None:
+            await driver.page.get(HENTAIVERSE_ISEKAI_ROOT_URL)
+
+        with self.assertRaises(RealmBindingViolationError):
+            await context.persistent.execute(cross_realm)
+
+        self.assertEqual(persistent_tab.url, HENTAIVERSE_ROOT_URL)
+
+    async def test_failed_operation_still_restores_bound_realm(self) -> None:
+        context, _, _, isekai_tab, _, _ = self._context()
+        await context.start()
+        self.addAsyncCleanup(context.close)
+
+        async def fail_after_drift(driver: RealmBoundHVDriver) -> None:
+            await driver.page.get("https://example.test/outside")
+            raise LookupError("operation failed")
+
+        with self.assertRaisesRegex(LookupError, "operation failed"):
+            await context.isekai.execute(fail_after_drift)
+
+        self.assertEqual(isekai_tab.url, HENTAIVERSE_ISEKAI_ROOT_URL)
+
+    async def test_navigation_rejects_cross_realm_before_touching_tab(self) -> None:
+        context, _, _, isekai_tab, _, _ = self._context()
+        await context.start()
+        self.addAsyncCleanup(context.close)
+        previous_navigations = list(isekai_tab.navigations)
+
+        with self.assertRaisesRegex(RealmTabBindingError, "cross-realm"):
+            await context.isekai.navigate(HENTAIVERSE_ROOT_URL)
+
+        self.assertEqual(isekai_tab.navigations, previous_navigations)
+
+    async def test_bound_driver_rejects_page_replacement(self) -> None:
+        context, _, _, _, _, _ = self._context()
+        await context.start()
+        self.addAsyncCleanup(context.close)
+
+        with self.assertRaisesRegex(RealmTabBindingError, "cannot replace"):
+            context.persistent.driver.page = _FakeTab("replacement")
+
+    async def test_authentication_failure_closes_the_owned_browser(self) -> None:
+        async def fail_authentication(_: RealmBoundHVDriver) -> None:
+            raise PermissionError("login failed")
+
+        context, _, _, _, browser_closer, _ = self._context(
+            authenticator=fail_authentication
+        )
+
+        with self.assertRaisesRegex(PermissionError, "login failed"):
+            await context.start()
+
+        self.assertEqual(context.state, AccountContextState.CLOSED)
+        browser_closer.assert_awaited_once()
+        with self.assertRaises(AccountContextStateError):
+            await context.start()
+
+    async def test_close_is_idempotent_and_runtimes_require_open_context(self) -> None:
+        context, _, _, _, browser_closer, _ = self._context()
+
+        with self.assertRaises(AccountContextStateError):
+            _ = context.persistent
+
+        await context.start()
+        await context.close()
+        await context.close()
+
+        browser_closer.assert_awaited_once()
+        with self.assertRaises(AccountContextStateError):
+            _ = context.isekai
+
+
+async def _return[ResultT](value: ResultT) -> ResultT:
+    return value
+
+
+if __name__ == "__main__":
+    unittest.main()