hvbrowser 0.1.0__py3-none-any.whl

hvbrowser/__init__.py

@@ -0,0 +1,32 @@
+__all__ = [
+    "HVDriver",
+    "SellItems",
+    "MarketCategory",
+    "MarketClient",
+    "MarketItem",
+    "MarketPageError",
+    "MarketSale",
+    "MarketSalePlan",
+    "MarketSaleQuote",
+    "MarketSaleReport",
+    "MarketSnapshot",
+    "MarketSubmissionError",
+    "HENTAIVERSE_ISEKAI_ROOT_URL",
+    "HENTAIVERSE_ROOT_URL",
+]
+
+
+from .hv import HVDriver, SellItems
+from .market import (
+    MarketCategory,
+    MarketClient,
+    MarketItem,
+    MarketPageError,
+    MarketSale,
+    MarketSalePlan,
+    MarketSaleQuote,
+    MarketSaleReport,
+    MarketSnapshot,
+    MarketSubmissionError,
+)
+from .urls import HENTAIVERSE_ISEKAI_ROOT_URL, HENTAIVERSE_ROOT_URL

hvbrowser/hv.py

@@ -0,0 +1,410 @@
+import re
+from abc import ABC
+from typing import Any
+
+from hbrowser.gallery import EHDriver
+from hbrowser.gallery.utils import setup_logger
+
+from .market import (
+    MarketCategory,
+    MarketClient,
+    MarketSalePlan,
+    MarketSaleReport,
+    MarketSnapshot,
+)
+from .urls import HENTAIVERSE_ISEKAI_ROOT_URL, HENTAIVERSE_ROOT_URL
+
+logger = setup_logger(__name__)
+
+
+def genxpath(imagepath: str) -> str:
+    return f'//img[@src="{imagepath}"]'
+
+
+class BSItems(ABC):
+    def __init__(
+        self,
+        consumables: list[str] | None = None,
+        materials: list[str] | None = None,
+        trophies: list[str] | None = None,
+        artifacts: list[str] | None = None,
+        figures: list[str] | None = None,
+        monster_items: list[str] | None = None,
+    ) -> None:
+        self.consumables = consumables or []
+        self.materials = materials or []
+        self.trophies = trophies or []
+        self.artifacts = artifacts or []
+        self.figures = figures or []
+        self.monster_items = monster_items or []
+
+    def market_names(self) -> dict[MarketCategory, tuple[str, ...]]:
+        return {
+            MarketCategory.CONSUMABLES: tuple(self.consumables),
+            MarketCategory.MATERIALS: tuple(self.materials),
+            MarketCategory.TROPHIES: tuple(self.trophies),
+            MarketCategory.ARTIFACTS: tuple(self.artifacts),
+            MarketCategory.FIGURES: tuple(self.figures),
+            MarketCategory.MONSTER_ITEMS: tuple(self.monster_items),
+        }
+
+
+class SellItems(BSItems):
+    pass
+
+
+class BuyItems(BSItems):
+    pass
+
+
+class HVDriver(EHDriver):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.url[self.name] = HENTAIVERSE_ROOT_URL
+        self.url["HentaiVerse isekai"] = HENTAIVERSE_ISEKAI_ROOT_URL
+
+    def _setname(self) -> str:
+        return "HentaiVerse"
+
+    @property
+    async def is_isekai(self) -> bool:
+        url = await self.page.evaluate("window.location.href")
+        return "isekai" in url
+
+    async def _get_path_prefix(self) -> str:
+        return "/isekai" if await self.is_isekai else ""
+
+    def searchxpath(self, srclist: list[Any] | tuple[Any, ...] | set[Any]) -> str:
+        return " | ".join([genxpath(imagepath) for imagepath in srclist])
+
+    async def goisekai(self) -> None:
+        logger.info("Navigating to HentaiVerse isekai page")
+        await self.get(HENTAIVERSE_ISEKAI_ROOT_URL)
+
+    async def inspect_market(self) -> MarketSnapshot:
+        """Return a read-only snapshot of the visible Market inventory."""
+        return await MarketClient(self).inspect(is_isekai=await self.is_isekai)
+
+    async def plan_market_sales(self, sellitems: SellItems) -> MarketSalePlan:
+        """Build a sale plan without clicking or submitting Market controls."""
+        return await MarketClient(self).plan_sales(
+            sellitems.market_names(), is_isekai=await self.is_isekai
+        )
+
+    async def validate_market_sales(self, plan: MarketSalePlan) -> None:
+        """Validate sale-form selectors without changing Market state."""
+        await MarketClient(self).validate_sale_forms(plan)
+
+    async def submit_market_sales(self, plan: MarketSalePlan) -> MarketSaleReport:
+        """Submit a previously reviewed sale plan."""
+        return await MarketClient(self).submit_sales(plan)
+
+    async def loetterycheck(self, num: int) -> None:
+        logger.info(f"Checking lottery tickets (target: {num})")
+        await self.gohomepage()
+
+        for lettory in ["Weapon Lottery", "Armor Lottery"]:
+            logger.debug(f"Processing {lettory}")
+            bazaar = await self.page.select("#parent_Bazaar")
+            lettory_xpath = f"//div[contains(text(), '{lettory}')]"
+            lettory_elements = await self.page.xpath(lettory_xpath, timeout=5)
+            if not lettory_elements:
+                continue
+            lettory_elem = lettory_elements[0]
+
+            # Hover bazaar then click lottery
+            await bazaar.mouse_move()
+            await lettory_elem.mouse_move()
+            await lettory_elem.mouse_click()
+            await self.page.wait(1)
+
+            currently_elements = await self.page.xpath(
+                "//*[contains(text(), 'You currently have')]", timeout=5
+            )
+            if not currently_elements:
+                continue
+            numbers: list[str] = re.findall(r"[\d,]+", currently_elements[0].text)
+            currently_number = numbers[0].replace(",", "")
+
+            hold_elements = await self.page.xpath(
+                "//*[contains(text(), 'You hold')]", timeout=5
+            )
+            if not hold_elements:
+                continue
+            numbers = re.findall(r"[\d,]+", hold_elements[0].text)
+            buy_number = numbers[0].replace(",", "")
+
+            logger.info(
+                f"{lettory}: Currently have {currently_number} credits, "
+                f"hold {buy_number} tickets"
+            )
+
+            if int(buy_number) < num and int(currently_number) > (num * 1000):
+                purchase_amount = num - int(buy_number)
+                logger.info(f"Purchasing {purchase_amount} tickets for {lettory}")
+                html_element = await self.page.select("#ticket_temp")
+                await html_element.clear_input()
+                await html_element.send_keys(str(purchase_amount))
+                await self.page.evaluate("submit_buy()")
+            else:
+                logger.debug(
+                    f"No purchase needed for {lettory} "
+                    f"(tickets: {buy_number}, credits: {currently_number})"
+                )
+
+    async def get_stamina(self) -> int:
+        stamina_elements = await self.page.xpath(
+            "//div[contains(text(), 'Stamina:')]", timeout=5
+        )
+        if not stamina_elements:
+            raise ValueError("Unable to find stamina readout")
+        match = re.search(r"Stamina:\s*(\d+)", stamina_elements[0].text)
+        if not match:
+            raise ValueError(
+                f"Unable to parse stamina from: {stamina_elements[0].text!r}"
+            )
+        return int(match.group(1))
+
+    async def recoverstamina(self) -> bool:
+        logger.info("Checking USR RESTORATIVE availability for stamina recovery")
+
+        stamina_readout = await self.page.select("#stamina_readout")
+        await stamina_readout.mouse_move()
+
+        restorative_elements = await self.page.xpath(
+            "//img[@onclick=\"document.getElementById('recoverform').submit()\"]",
+            timeout=5,
+        )
+        if not restorative_elements:
+            logger.debug("USR RESTORATIVE is not available")
+            return False
+
+        restorative_img = restorative_elements[0]
+        await restorative_img.mouse_move()
+        await restorative_img.mouse_click()
+        await self.page.wait(1)
+
+        error_elements = await self.page.xpath(
+            "//p[contains(@class, 'messagebox_error')]", timeout=2
+        )
+        if error_elements:
+            logger.warning(f"USR RESTORATIVE failed: {error_elements[0].text}")
+            await error_elements[0].click()
+            return False
+
+        logger.info("Used USR RESTORATIVE to recover stamina")
+        return True
+
+    async def _select_all_and_check_repair_submit(
+        self, equipcount_elements: list[Any]
+    ) -> tuple[bool | None, list[Any]]:
+        """全選裝備並回報 repair submit 按鈕狀態。
+
+        回傳 (is_disabled, submit_elements):
+        is_disabled 為 None 代表找不到 submit 按鈕，呼叫端應視為無需處理。
+        """
+        logger.debug(f"Before select_all click: {equipcount_elements[0].text!r}")
+        await self.wait(equipcount_elements[0].mouse_click, ischangeurl=False)
+
+        equipcount_after = await self.page.xpath("//label[@id='equipcount']", timeout=5)
+        if equipcount_after:
+            logger.debug(f"After select_all click: {equipcount_after[0].text!r}")
+
+        submit_elements = await self.page.xpath("//input[@id='equipsubmit']", timeout=5)
+        if not submit_elements:
+            logger.warning("Unable to find equipment repair submit button")
+            return None, []
+
+        is_disabled = await self.page.evaluate(
+            "document.getElementById('equipsubmit').disabled"
+        )
+        if is_disabled:
+            debug_state = await self.page.evaluate("""
+                JSON.stringify({
+                    selected_count: selected_count,
+                    selectable_count: selectable_count,
+                    block_submit: block_submit,
+                    materials: (() => {
+                        const totals = {};
+                        for (const el of document.querySelectorAll('input[name="eqids[]"]')) {
+                            if (el.checked && eqitems[el.value]) {
+                                for (const m in eqitems[el.value].m) {
+                                    totals[m] = (totals[m] || 0) + eqitems[el.value].m[m];
+                                }
+                            }
+                        }
+                        return Object.entries(totals).map(([id, need]) => ({
+                            id,
+                            name: itemdata[id] ? itemdata[id].n : undefined,
+                            need,
+                            have: itemdata[id] ? itemdata[id].c : undefined,
+                        }));
+                    })(),
+                })
+                """)
+            logger.warning(f"Not enough materials to repair equipment: {debug_state}")
+
+        return bool(is_disabled), submit_elements
+
+    async def _goto_repair_tab(self) -> bool:
+        """導航到 Bazaar -> The Armory -> Repair 頁籤。成功回傳 True。"""
+        try:
+            bazaar = await self.page.select("#parent_Bazaar")
+        except TimeoutError:
+            logger.warning(
+                "Timed out waiting for #parent_Bazaar; homepage may not have "
+                "finished loading yet, reloading and retrying once"
+            )
+            await self.gohomepage(force=True)
+            bazaar = await self.page.select("#parent_Bazaar")
+        armory_elements = await self.page.xpath(
+            "//div[contains(text(), 'The Armory')]", timeout=5
+        )
+        if not armory_elements:
+            logger.warning("Unable to find The Armory entry")
+            return False
+
+        await bazaar.mouse_move()
+        await armory_elements[0].mouse_move()
+        await self.wait(armory_elements[0].mouse_click, ischangeurl=True)
+
+        repair_elements = await self.page.xpath(
+            "//div[contains(@class, 'armory_tab') and contains(text(), 'Repair')]",
+            timeout=5,
+        )
+        if not repair_elements:
+            logger.warning("Unable to find Repair tab")
+            return False
+        await self.wait(repair_elements[0].click, ischangeurl=True)
+        return True
+
+    async def repairequipment(self) -> bool:
+        logger.info("Checking equipped gear for repairs")
+        if not await self._goto_repair_tab():
+            return True
+
+        equipcount_elements = await self.page.xpath(
+            "//label[@id='equipcount']", timeout=5
+        )
+        if not equipcount_elements:
+            logger.debug("No equipment needs repair")
+            return True
+
+        match = re.search(
+            r"Selected \d+ of (\d+) matching", equipcount_elements[0].text
+        )
+        if not match or int(match.group(1)) == 0:
+            logger.debug("No equipment needs repair")
+            return True
+
+        is_disabled, submit_elements = await self._select_all_and_check_repair_submit(
+            equipcount_elements
+        )
+        if is_disabled is None:
+            return True
+
+        if is_disabled:
+            logger.debug("Re-entering Repair tab to verify against fresh server state")
+            if not await self._goto_repair_tab():
+                return True
+
+            equipcount_reentered = await self.page.xpath(
+                "//label[@id='equipcount']", timeout=5
+            )
+            if not equipcount_reentered:
+                logger.debug("No equipment needs repair after re-entering Repair tab")
+                return True
+
+            is_disabled, submit_elements = (
+                await self._select_all_and_check_repair_submit(equipcount_reentered)
+            )
+            if is_disabled is None:
+                return True
+            if is_disabled:
+                logger.error(
+                    "Still not enough materials to repair equipment "
+                    "after re-entering Repair tab"
+                )
+                return False
+            logger.info(
+                "Repair submit was enabled after re-entering Repair tab; "
+                "the earlier disabled check was stale"
+            )
+
+        await submit_elements[0].mouse_click()
+        await self.page.wait(2)
+
+        equipcount_after_submit = await self.page.xpath(
+            "//label[@id='equipcount']", timeout=5
+        )
+        remaining = 0
+        if equipcount_after_submit:
+            match_after_submit = re.search(
+                r"Selected \d+ of (\d+) matching", equipcount_after_submit[0].text
+            )
+            if match_after_submit:
+                remaining = int(match_after_submit.group(1))
+
+        if remaining:
+            logger.error(
+                f"Repair submitted but {remaining} pieces of equipment still need repair"
+            )
+            return False
+
+        logger.info("Repaired equipment")
+        return True
+
+    async def monstercheck(self) -> None:
+        logger.info("Starting monster check")
+        await self.gohomepage()
+
+        # 進入 Monster Lab
+        logger.debug("Navigating to Monster Lab")
+        bazaar = await self.page.select("#parent_Bazaar")
+        monster_lab_elements = await self.page.xpath(
+            "//div[contains(text(), 'Monster Lab')]", timeout=5
+        )
+        if not monster_lab_elements:
+            return
+        monster_lab = monster_lab_elements[0]
+
+        await bazaar.mouse_move()
+        await monster_lab.mouse_move()
+        await monster_lab.mouse_click()
+        await self.page.wait(1)
+
+        path_prefix = await self._get_path_prefix()
+        feed_actions = {"feed": "food", "drug": "drugs"}
+        for action, resource in feed_actions.items():
+            xpath = self.searchxpath(
+                [f"{path_prefix}/y/monster/{action}allmonsters.png"]
+            )
+            images = await self.page.xpath(xpath, timeout=2)
+            if images:
+                logger.info("Feeding all monsters with %s", resource)
+                await self.page.evaluate(f"do_feed_all('{resource}')")
+                await self.page.wait(10)
+            else:
+                logger.debug("No feed all option available for %s", resource)
+
+    async def marketcheck(
+        self, sellitems: SellItems, *, commit: bool = False
+    ) -> MarketSalePlan | MarketSaleReport:
+        """Plan requested Market sales and submit only with explicit consent.
+
+        The default is read-only. This workflow never deposits credits and
+        never re-lists unrelated existing orders.
+        """
+        plan = await self.plan_market_sales(sellitems)
+        logger.info(
+            "Market sale plan contains %d item types and %d units",
+            len(plan.items),
+            plan.total_units,
+        )
+        if not commit:
+            return plan
+
+        await self.validate_market_sales(plan)
+        report = await self.submit_market_sales(plan)
+        logger.info("Market submitted %d verified item sales", len(report.sales))
+        return report

hvbrowser/live_probe.py

@@ -0,0 +1,111 @@
+"""Credential-safe, read-only smoke checks for a configured account."""
+
+import os
+from collections import Counter
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+
+from .hv import HVDriver
+from .market import MarketCategory, MarketClient, MarketPageError
+
+
+class LiveProbeRefused(RuntimeError):
+    """A live probe was stopped before browser construction."""
+
+
+@dataclass(frozen=True)
+class MarketCategorySummary:
+    category: MarketCategory
+    item_types: int
+    stocked_item_types: int
+
+
+@dataclass(frozen=True)
+class MarketQuoteSummary:
+    category: MarketCategory
+    item_id: int
+    stock: int
+    sell_order_id: int
+    order_text: str
+
+
+@dataclass(frozen=True)
+class LiveProbeResult:
+    stamina: int
+    is_isekai: bool
+    market: tuple[MarketCategorySummary, ...]
+    quote: MarketQuoteSummary | None
+
+
+def validate_live_environment(
+    environment: Mapping[str, str] | None = None,
+) -> None:
+    """Require credential indirection without selecting an account profile."""
+    current = os.environ if environment is None else environment
+    missing = [name for name in ("EH_USERNAME", "EH_PASSWORD") if not current.get(name)]
+    if missing:
+        raise LiveProbeRefused(
+            "Missing credential environment variables: " + ", ".join(missing)
+        )
+
+
+async def run_live_probe(
+    *,
+    inspect_market_form: bool = False,
+    driver_factory: Callable[[], HVDriver] | None = None,
+    environment: Mapping[str, str] | None = None,
+) -> LiveProbeResult:
+    """Log in and inspect non-battle state without performing any mutation."""
+    validate_live_environment(environment)
+    create_driver = driver_factory or (lambda: HVDriver(headless=True))
+
+    async with create_driver() as driver:
+        battle_markers = await driver.page.xpath("//*[@id='battle_main']", timeout=2)
+        if battle_markers:
+            raise LiveProbeRefused(
+                "An active battle was detected; the read-only probe stopped"
+            )
+
+        stamina = await driver.get_stamina()
+        is_isekai = await driver.is_isekai
+        market_client = MarketClient(driver)
+        snapshot = await market_client.inspect(is_isekai=is_isekai)
+
+        item_counts = Counter(item.category for item in snapshot.items)
+        stocked_counts = Counter(
+            item.category for item in snapshot.items if item.stock > 0
+        )
+        categories = tuple(
+            MarketCategorySummary(
+                category=category,
+                item_types=item_counts[category],
+                stocked_item_types=stocked_counts[category],
+            )
+            for category in MarketCategory
+            if item_counts[category]
+        )
+
+        quote_summary: MarketQuoteSummary | None = None
+        if inspect_market_form:
+            for item in (item for item in snapshot.items if item.stock > 0):
+                try:
+                    quote = await market_client.inspect_sale_quote(
+                        item, is_isekai=is_isekai
+                    )
+                except MarketPageError:
+                    continue
+                quote_summary = MarketQuoteSummary(
+                    category=item.category,
+                    item_id=item.item_id,
+                    stock=quote.current_stock,
+                    sell_order_id=quote.sell_order_id,
+                    order_text=quote.order_text,
+                )
+                break
+
+        return LiveProbeResult(
+            stamina=stamina,
+            is_isekai=is_isekai,
+            market=categories,
+            quote=quote_summary,
+        )

hvbrowser/market.py

@@ -0,0 +1,353 @@
+import re
+from collections.abc import Collection, Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any, Protocol
+
+from .urls import HENTAIVERSE_ISEKAI_ROOT_URL, HENTAIVERSE_ROOT_URL
+
+MARKET_ROOT_URL = f"{HENTAIVERSE_ROOT_URL}/"
+ISEKAI_MARKET_ROOT_URL = HENTAIVERSE_ISEKAI_ROOT_URL
+
+
+class MarketCategory(StrEnum):
+    CONSUMABLES = "co"
+    MATERIALS = "ma"
+    TROPHIES = "tr"
+    ARTIFACTS = "ar"
+    FIGURES = "fi"
+    MONSTER_ITEMS = "mo"
+
+
+_CATEGORY_LABELS: dict[MarketCategory, str] = {
+    MarketCategory.CONSUMABLES: "Consumables",
+    MarketCategory.MATERIALS: "Materials",
+    MarketCategory.TROPHIES: "Trophies",
+    MarketCategory.ARTIFACTS: "Artifacts",
+    MarketCategory.FIGURES: "Figures",
+    MarketCategory.MONSTER_ITEMS: "Monster Items",
+}
+
+PERSISTENT_MARKET_CATEGORIES = tuple(MarketCategory)
+ISEKAI_MARKET_CATEGORIES = (
+    MarketCategory.CONSUMABLES,
+    MarketCategory.MATERIALS,
+    MarketCategory.TROPHIES,
+)
+
+# The selectors and stock-confirmation path are covered offline, but the live
+# meaning of the selected sell-side quote has not yet been confirmed against
+# the current authenticated Market DOM.  Keep every public submission entry
+# point fail-closed until that read-only verification has happened.
+_MARKET_SUBMISSION_VERIFIED = False
+
+
+@dataclass(frozen=True)
+class MarketItem:
+    category: MarketCategory
+    item_id: int
+    name: str
+    stock: int
+
+
+@dataclass(frozen=True)
+class MarketSnapshot:
+    is_isekai: bool
+    items: tuple[MarketItem, ...]
+
+    def items_in(self, category: MarketCategory) -> tuple[MarketItem, ...]:
+        return tuple(item for item in self.items if item.category is category)
+
+
+@dataclass(frozen=True)
+class MarketSalePlan:
+    """A read-only snapshot of inventory selected for sale."""
+
+    is_isekai: bool
+    items: tuple[MarketItem, ...]
+
+    @property
+    def total_units(self) -> int:
+        return sum(item.stock for item in self.items)
+
+
+@dataclass(frozen=True)
+class MarketSaleQuote:
+    """Read-only pricing evidence from the first visible sell-side order."""
+
+    item: MarketItem
+    sell_order_id: int
+    order_text: str
+    current_stock: int
+
+
+@dataclass(frozen=True)
+class MarketSale:
+    item: MarketItem
+    remaining_stock: int
+
+
+@dataclass(frozen=True)
+class MarketSaleReport:
+    is_isekai: bool
+    sales: tuple[MarketSale, ...]
+
+
+class MarketPageError(RuntimeError):
+    """The Market page did not expose the expected read-only structure."""
+
+
+class MarketSubmissionError(RuntimeError):
+    """The Market rejected a sale or did not confirm the inventory change."""
+
+
+class _MarketDriver(Protocol):
+    page: Any
+
+    async def get(self, url: str) -> None: ...
+
+
+@dataclass(frozen=True)
+class _SaleForm:
+    sell_order_id: int
+    order_text: str
+    current_stock: int
+    stock_control: Any
+    update_button: Any
+
+
+def market_browse_url(category: MarketCategory, *, is_isekai: bool) -> str:
+    if is_isekai and category not in ISEKAI_MARKET_CATEGORIES:
+        raise ValueError(f"{market_category_label(category)} is unavailable in Isekai")
+    root = ISEKAI_MARKET_ROOT_URL if is_isekai else MARKET_ROOT_URL
+    return f"{root}?s=Bazaar&ss=mk&screen=browseitems&filter={category.value}"
+
+
+def market_item_url(category: MarketCategory, item_id: int, *, is_isekai: bool) -> str:
+    return f"{market_browse_url(category, is_isekai=is_isekai)}&itemid={item_id}"
+
+
+def market_category_label(category: MarketCategory) -> str:
+    return _CATEGORY_LABELS[category]
+
+
+def parse_market_item_id(onclick: str) -> int:
+    patterns = (
+        r"[?&]itemid=(\d+)",
+        r"\bitemid\D+(\d+)",
+        r"\bselect_market_item\(\s*(\d+)\s*\)",
+    )
+    for pattern in patterns:
+        match = re.search(pattern, onclick)
+        if match:
+            return int(match.group(1))
+    raise MarketPageError(
+        f"Unable to parse Market item id from row action: {onclick!r}"
+    )
+
+
+def parse_market_stock(text: str) -> int:
+    normalized = text.strip().replace(",", "")
+    if not normalized:
+        return 0
+    match = re.search(r"\d+", normalized)
+    if not match:
+        raise MarketPageError(f"Unable to parse Market stock value: {text!r}")
+    return int(match.group(0))
+
+
+def parse_market_sell_order_id(onclick: str) -> int:
+    match = re.search(
+        r"\bautofill_from_sell_order\(\s*(\d+)\s*,\s*0\s*,\s*0\s*\)",
+        onclick,
+    )
+    if not match:
+        raise MarketPageError(
+            f"Unable to parse Market sell-order id from action: {onclick!r}"
+        )
+    return int(match.group(1))
+
+
+class MarketClient:
+    """Market inspection, explicit sale planning, and verified submission."""
+
+    def __init__(self, driver: _MarketDriver) -> None:
+        self._driver = driver
+
+    async def inspect(self, *, is_isekai: bool) -> MarketSnapshot:
+        categories = (
+            ISEKAI_MARKET_CATEGORIES if is_isekai else PERSISTENT_MARKET_CATEGORIES
+        )
+        items: list[MarketItem] = []
+        for category in categories:
+            items.extend(await self._inspect_category(category, is_isekai=is_isekai))
+        return MarketSnapshot(is_isekai=is_isekai, items=tuple(items))
+
+    async def plan_sales(
+        self,
+        requested_names: Mapping[MarketCategory, Collection[str]],
+        *,
+        is_isekai: bool,
+    ) -> MarketSalePlan:
+        """Select stocked inventory without changing Market state."""
+        snapshot = await self.inspect(is_isekai=is_isekai)
+        normalized_requests = {
+            category: {name.casefold() for name in names}
+            for category, names in requested_names.items()
+        }
+        selected = tuple(
+            item
+            for item in snapshot.items
+            if item.stock > 0
+            and item.name.casefold() in normalized_requests.get(item.category, set())
+        )
+        return MarketSalePlan(is_isekai=is_isekai, items=selected)
+
+    async def validate_sale_forms(self, plan: MarketSalePlan) -> None:
+        """Verify every planned item form without clicking or submitting it."""
+        for item in plan.items:
+            await self.inspect_sale_quote(item, is_isekai=plan.is_isekai)
+
+    async def inspect_sale_quote(
+        self, item: MarketItem, *, is_isekai: bool
+    ) -> MarketSaleQuote:
+        """Inspect the current sell-side pricing source without clicking it."""
+        sale_form = await self._open_sale_form(item, is_isekai=is_isekai)
+        return MarketSaleQuote(
+            item=item,
+            sell_order_id=sale_form.sell_order_id,
+            order_text=sale_form.order_text,
+            current_stock=sale_form.current_stock,
+        )
+
+    async def submit_sales(self, plan: MarketSalePlan) -> MarketSaleReport:
+        """Submit an explicitly prepared plan and verify each stock change.
+
+        This operation never deposits credits and never touches existing sell
+        orders that are not present in ``plan``.
+        """
+        if not _MARKET_SUBMISSION_VERIFIED:
+            raise MarketSubmissionError(
+                "Market submission is disabled until the current live quote "
+                "and pricing semantics have been verified read-only"
+            )
+
+        return await self._submit_verified_sales(plan)
+
+    async def _submit_verified_sales(self, plan: MarketSalePlan) -> MarketSaleReport:
+        """Execute the guarded submission algorithm after live verification."""
+        sales: list[MarketSale] = []
+        for item in plan.items:
+            sale_form = await self._open_sale_form(item, is_isekai=plan.is_isekai)
+            if sale_form.current_stock != item.stock:
+                raise MarketSubmissionError(
+                    f"Market sale plan is stale for {item.name!r}: "
+                    f"planned={item.stock}, current={sale_form.current_stock}"
+                )
+            await self._driver.page.evaluate(
+                f"autofill_from_sell_order({sale_form.sell_order_id},0,0);"
+            )
+            await sale_form.stock_control.click()
+            await sale_form.update_button.click()
+            await self._driver.page.wait(1)
+            await self._raise_for_submission_error(item)
+
+            remaining_stock = await self._read_item_stock(
+                item, is_isekai=plan.is_isekai
+            )
+            if remaining_stock != 0:
+                raise MarketSubmissionError(
+                    f"Market did not sell all planned stock for {item.name!r}: "
+                    f"before={item.stock}, after={remaining_stock}"
+                )
+            sales.append(MarketSale(item=item, remaining_stock=remaining_stock))
+        return MarketSaleReport(is_isekai=plan.is_isekai, sales=tuple(sales))
+
+    async def _open_sale_form(self, item: MarketItem, *, is_isekai: bool) -> _SaleForm:
+        await self._driver.get(
+            market_item_url(item.category, item.item_id, is_isekai=is_isekai)
+        )
+        try:
+            sell_order_cells = await self._driver.page.xpath(
+                "//*[@id='market_itemsell']"
+                "//td[contains(@onclick, 'autofill_from_sell_order')]",
+                timeout=5,
+            )
+            stock_control = await self._driver.page.select(
+                "#sell_order_stock_field > span", timeout=5
+            )
+            update_button = await self._driver.page.select(
+                "#sellorder_update", timeout=5
+            )
+        except TimeoutError as error:
+            raise MarketPageError(
+                f"Market sale form is missing for {item.name!r}"
+            ) from error
+        if not sell_order_cells:
+            raise MarketPageError(
+                f"Market has no existing sell order to price {item.name!r}"
+            )
+        onclick = str(sell_order_cells[0].attrs.get("onclick", ""))
+        return _SaleForm(
+            sell_order_id=parse_market_sell_order_id(onclick),
+            order_text=sell_order_cells[0].text.strip(),
+            current_stock=parse_market_stock(stock_control.text),
+            stock_control=stock_control,
+            update_button=update_button,
+        )
+
+    async def _read_item_stock(self, item: MarketItem, *, is_isekai: bool) -> int:
+        await self._driver.get(
+            market_item_url(item.category, item.item_id, is_isekai=is_isekai)
+        )
+        try:
+            stock_control = await self._driver.page.select(
+                "#sell_order_stock_field > span", timeout=5
+            )
+        except TimeoutError as error:
+            raise MarketSubmissionError(
+                f"Market stock confirmation is missing for {item.name!r}"
+            ) from error
+        return parse_market_stock(stock_control.text)
+
+    async def _raise_for_submission_error(self, item: MarketItem) -> None:
+        try:
+            error_message = await self._driver.page.select(
+                "#messagebox_inner p.messagebox_error", timeout=1
+            )
+        except TimeoutError:
+            return
+        message = error_message.text.strip() or "unknown Market error"
+        raise MarketSubmissionError(f"Market rejected {item.name!r}: {message}")
+
+    async def _inspect_category(
+        self, category: MarketCategory, *, is_isekai: bool
+    ) -> list[MarketItem]:
+        await self._driver.get(market_browse_url(category, is_isekai=is_isekai))
+        try:
+            item_list = await self._driver.page.select("#market_itemlist", timeout=5)
+        except TimeoutError as error:
+            raise MarketPageError(
+                f"Market item list is missing for {market_category_label(category)}"
+            ) from error
+
+        rows = await item_list.query_selector_all("table > tbody > tr[onclick]")
+        items: list[MarketItem] = []
+        for row in rows:
+            cells = await row.query_selector_all("td")
+            if len(cells) < 2:
+                raise MarketPageError(
+                    f"Market row has fewer than two cells in "
+                    f"{market_category_label(category)}"
+                )
+            name = cells[0].text.strip()
+            onclick = str(row.attrs.get("onclick", ""))
+            items.append(
+                MarketItem(
+                    category=category,
+                    item_id=parse_market_item_id(onclick),
+                    name=name,
+                    stock=parse_market_stock(cells[1].text),
+                )
+            )
+        return items

hvbrowser/runtime.py

@@ -0,0 +1,17 @@
+"""Shared browser primitives used by HentaiVerse domain packages.
+
+This module is the intentional boundary through which higher-level HV packages
+access the underlying browser runtime. Keeping that boundary here avoids
+requiring those packages to depend on ``hbrowser`` directly.
+"""
+
+from hbrowser.gallery.element_action import ElementAction
+from hbrowser.gallery.utils import is_connection_error, setup_logger
+from hbrowser.notify import notify
+
+__all__ = [
+    "ElementAction",
+    "is_connection_error",
+    "notify",
+    "setup_logger",
+]

hvbrowser/urls.py

@@ -0,0 +1,4 @@
+"""Canonical HentaiVerse realm roots owned by the domain package."""
+
+HENTAIVERSE_ROOT_URL = "https://hentaiverse.org"
+HENTAIVERSE_ISEKAI_ROOT_URL = f"{HENTAIVERSE_ROOT_URL}/isekai/"

hvbrowser-0.1.0.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: hvbrowser
+Version: 0.1.0
+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
+Author: Kuan-Lun Wang
+License: GNU Affero General Public License v3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.14
+Requires-Dist: hbrowser<0.36,>=0.35.0
+Provides-Extra: dev
+Requires-Dist: black>=26.5.1; extra == 'dev'
+Requires-Dist: mypy>=2.1.0; extra == 'dev'
+Requires-Dist: pymarkdownlnt>=0.9.38; extra == 'dev'
+Requires-Dist: pytest>=9.1.1; extra == 'dev'
+Requires-Dist: ruff>=0.15.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# HVBrowser
+
+HVBrowser provides browser automation APIs for HentaiVerse. It builds on
+`hbrowser` for the shared authenticated browser session.
+
+The package was extracted from the historical combined `hbrowser`
+distribution. Battle-domain APIs live in the separate `hvbattle` package.
+
+## Development
+
+Build a clean environment backed by the PyPI release of `hbrowser`:
+
+```bash
+bash scripts/rebuild-env.sh
+```
+
+For coordinated local development, overlay the clean environment manually:
+
+```bash
+uv pip install --python .venv/bin/python --reinstall --no-deps --editable \
+  /Users/kuanlun_wang/Desktop/git-repo/hbrowser.clone
+```
+
+Commands that must preserve this editable overlay use `uv run --no-sync`.
+
+## Read-only Market inspection
+
+Market inspection and sale planning are non-mutating by default:
+
+```python
+import asyncio
+
+from hvbrowser import HVDriver, SellItems
+
+
+async def main() -> None:
+    async with HVDriver(headless=True) as driver:
+        snapshot = await driver.inspect_market()
+        plan = await driver.marketcheck(SellItems(materials=["Low-Grade Metals"]))
+        print(len(snapshot.items), plan.total_units)
+
+
+asyncio.run(main())
+```
+
+The compatibility `marketcheck()` call requires `commit=True` before it can
+request submission. Submission is currently blocked by a fail-closed runtime
+gate until the current quote selector and pricing semantics have been confirmed
+with the read-only live probe. The guarded implementation never deposits
+credits and never re-lists unrelated orders.
+
+## Guarded live smoke test
+
+The surrounding `hentaiverse` workspace owns account selection. This smoke
+probe only refuses to construct a browser unless credentials are supplied
+indirectly through the environment. It stops when an active battle is detected
+and contains no click, submit, repair, recovery, lottery, monster-lab, or battle
+call:
+
+```bash
+uv run --no-sync python scripts/live_readonly_smoke.py \
+  --inspect-market-form
+```

hvbrowser-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+hvbrowser/__init__.py,sha256=V2lb5K_qmdfxLuU2qijsII7BR1irhy5-qubcq_VSX1c,662
+hvbrowser/hv.py,sha256=3xrXIJWqrgxIi9cAfZbQ8OfmJT3te6m1lD69dq4YEhQ,15615
+hvbrowser/live_probe.py,sha256=OvIF935NWQbGfldoSJSPWdmhoWmzjOuiC0X0XdX5MiU,3589
+hvbrowser/market.py,sha256=0lQVoRaCBMy2yQlTJ0h9x3_e_TzCdRLZhCbLaSv82SA,12348
+hvbrowser/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hvbrowser/runtime.py,sha256=9Doe3KbiXAEu2QH3pQUUii8ERti0J5efiaevpcvSsy8,544
+hvbrowser/urls.py,sha256=fFwITwW-3iOgfcnUi1YKI67Orqgf3DqSpetrVXHxeSw,183
+hvbrowser-0.1.0.dist-info/METADATA,sha256=Vlk3rh145bZBEPj5HkISUH9tf1vFfUxZe5GtUGUmAYQ,2890
+hvbrowser-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+hvbrowser-0.1.0.dist-info/RECORD,,

hvbrowser-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any