#src.wesktop.runtime_bridge

#src.wesktop.runtime_bridge

Host-side native bridge for reacting to fastware build changes.

The PRIMARY update path is page-side: native windows load the same page as the browser, so the framework's /__fastware/client.js reloads the page (over the SSE update channel) when the build id changes -- no host involvement, no polling.

This module is the host-side complement, used mainly for reset flows: it lets the desktop host reload the window, clear the web cache, and -- where pywebview exposes a window focus event -- poll /__fastware/version on focus to detect a changed build id and reload.

Every function takes a duck-typed pywebview window object, so the module is unit-testable with a fake window and imports no pywebview and no GUI.

Build ids have NO ordering: reload happens on a DIFFERENT id, never on a "newer" one.

#reload

def reload(window: Any) -> None

Reload the page in window by injecting location.reload().

#clear_web_cache

def clear_web_cache(window: Any) -> bool

Best-effort clear of window's web cache.

Uses pywebview's native clear_cache when the installed version exposes it (returns True). Otherwise clears the Cache Storage API from the page via injected JS (returns False -- native API unavailable).

#fetch_build_id

def fetch_build_id(version_url: str, *, timeout: float=2.0) -> str | None

GET the fastware version endpoint and return its build_id.

Returns None on any failure (network error, non-JSON body, or a missing/ non-string build_id) -- a probe failure must never crash the host.

#check_and_reload

def check_and_reload(window: Any, version_url: str, last_build_id: str | None, *, clear_cache: bool=True, timeout: float=2.0) -> str | None

Probe version_url; reload window if the build id DIFFERS.

Returns the observed build id: the new one on change, otherwise last_build_id; None is never returned on a successful probe. On a probe failure the function returns last_build_id unchanged and does not reload. The first observation (last_build_id is None) records the id without reloading.

#install_focus_poll

def install_focus_poll(window: Any, version_url: str, *, on_change: Callable[[str], None] | None=None, initial_build_id: str | None=None, timeout: float=2.0) -> bool

Wire a version poll to window's focus event, if one exists.

On each focus the version endpoint is probed; on a DIFFERENT build id the window is reloaded and on_change is invoked with the new id.

Returns True if a focus event was found and wired, False otherwise. A False result is the documented limitation on pywebview builds without a focus event -- the page-side client.js remains the update path there.