Memoize hot HTML helpers and lazy-load image module sprites for faster transitions

app.py

@@ -746,28 +746,36 @@ def _inscribe_decoration_html(state: Optional[GameState] = None) -> str:
     )
 
 
-def _banner_html(state: Optional[GameState] = None) -> str:
-    """Top-of-page parallax banner with the game title overlaid.
+# ---------------------------------------------------------------------------
+# Memoization caches for HTML helpers that are recomputed on every click.
+# Each helper is a pure function of a small slice of state (theme + lang +
+# mode at most). Caching by the relevant tuple turns repeated identical
+# calls into a dict lookup. On a 6-theme × 2-lang × 5-mode app, the caches
+# saturate at ~60 entries — bounded, no eviction needed.
+# ---------------------------------------------------------------------------
+_BANNER_HTML_CACHE: dict = {}
+_THEME_STYLE_CACHE: dict = {}
+_INSCRIBE_DECORATION_CACHE: dict = {}
+_LOCALIZED_CHROME_CACHE: dict = {}
 
-    Reads the cozy-forest near.png and embeds it as a data URI so the HTML
-    is fully self-contained (no static-file routing dependency).
 
-    The title and subtitle come from the active theme so each world reskins
-    the banner. Falls back to fantasy defaults when no state is provided
-    (initial render before any theme has been picked).
+def _banner_html(state: Optional[GameState] = None) -> str:
+    """Top-of-page parallax banner with the game title overlaid.
 
-    Once the player leaves the inscribe phase (mode == 'trial' or
-    'epilogue'), the banner collapses to a compact strip via the
-    `oracle-banner-compact` class so the trial visual gets that vertical
-    real estate. The banner re-renders on every UI bundle so the swap is
-    automatic."""
-    # Pull theme-driven title + subtitle.
-    from oracles.themes import get_theme as _get_theme
+    Cached by (theme, lang, mode) — these are the only fields the rendered
+    HTML depends on. The bundle re-runs this helper on every click; without
+    caching, each call rebuilds the same string. Cache hit is a dict
+    lookup; cache miss recomputes.
+    """
     theme_key = getattr(state, "theme", "fantasy") if state else "fantasy"
-    theme = _get_theme(theme_key)
     lang = _tlang(state)
+    mode = getattr(state, "mode", "inscribe") if state else "inscribe"
+    cache_key = (theme_key, lang, mode)
+    if cache_key in _BANNER_HTML_CACHE:
+        return _BANNER_HTML_CACHE[cache_key]
+    from oracles.themes import get_theme as _get_theme
+    theme = _get_theme(theme_key)
     # Game-wide title — every theme is a chapter under the same banner.
-    # The theme's display_name becomes a subtitle (smaller, italic).
     game_title = "弟子" if lang == "zh" else "THE APPRENTICE"
     theme_label = theme.localized_field("display_name", lang) or "The Apprentice"
     if lang != "zh":
@@ -777,18 +785,15 @@ def _banner_html(state: Optional[GameState] = None) -> str:
         theme.localized_field("banner_subtitle", lang)
         or _t("banner_default_subtitle", lang)
     )
-    # Prepend the theme name to the subtitle so the player still sees which
-    # chapter / world they're in even though the title is now universal.
     subtitle = _md_safe(f"{theme_label} — {subtitle_raw}")
 
     # Decide tall vs compact based on phase. Inscribe = tall (intro vibe).
     # Trial/epilogue = compact (give screen real estate to the visuals).
-    mode = getattr(state, "mode", "inscribe") if state else "inscribe"
     is_compact = mode in ("trial", "epilogue", "send_off")
     extra_cls = " oracle-banner-compact" if is_compact else ""
 
     if not _PARALLAX_PNG.exists():
-        return (
+        result = (
             f"<div class='oracle-banner{extra_cls}' style='background:"
             "linear-gradient(180deg,var(--w-panel) 0%, var(--w-night) 100%);'>"
             "<div class='oracle-banner-overlay'>"
@@ -796,14 +801,10 @@ def _banner_html(state: Optional[GameState] = None) -> str:
             f"<div class='oracle-banner-sub'>{subtitle}</div>"
             "</div></div>"
         )
-    # Serve the parallax PNG via Gradio's file route instead of inlining
-    # ~200KB of base64 into every banner render. _banner_html() runs on
-    # every click handler (banner_html is in every outputs bundle), so the
-    # base64 work was repeated per click and inflated each response by
-    # ~270KB. Now the URL is a tiny constant string and the browser
-    # caches the PNG after the first request.
+        _BANNER_HTML_CACHE[cache_key] = result
+        return result
     src = f"/gradio_api/file={_PARALLAX_PNG.as_posix()}"
-    return (
+    result = (
         f"<div class='oracle-banner{extra_cls}'>"
         f"<img src='{src}' alt='banner'/>"
         "<div class='oracle-banner-overlay'>"
@@ -811,6 +812,8 @@ def _banner_html(state: Optional[GameState] = None) -> str:
         f"<div class='oracle-banner-sub'>{subtitle}</div>"
         "</div></div>"
     )
+    _BANNER_HTML_CACHE[cache_key] = result
+    return result
 
 
 def _processing_overlay_html(state: Optional[GameState] = None) -> str:
@@ -926,18 +929,21 @@ def _theme_style_overrides_html(state: Optional[GameState] = None) -> str:
     (fantasy uses the baseline). The block is injected into a gr.HTML slot
     at the top of the layout that re-renders on every event.
     """
-    from oracles.themes import get_theme as _get_theme
     theme_key = getattr(state, "theme", "fantasy") if state else "fantasy"
+    if theme_key in _THEME_STYLE_CACHE:
+        return _THEME_STYLE_CACHE[theme_key]
+    from oracles.themes import get_theme as _get_theme
     theme = _get_theme(theme_key)
     if not theme.palette:
+        _THEME_STYLE_CACHE[theme_key] = ""
         return ""
-    # Build "--name: value;" lines for each variable.
     decls = "\n  ".join(
         f"--{name}: {value} !important;"
         for name, value in theme.palette.items()
     )
-    # Scope to :root so the same vars used elsewhere in the stylesheet cascade.
-    return f"<style data-theme='{theme.key}'>\n:root {{\n  {decls}\n}}\n</style>"
+    result = f"<style data-theme='{theme.key}'>\n:root {{\n  {decls}\n}}\n</style>"
+    _THEME_STYLE_CACHE[theme_key] = result
+    return result
 
 
 # ---------------------------------------------------------------------------
@@ -3684,21 +3690,26 @@ def _localized_chrome_updates(state: GameState):
     don't clobber values the user has just typed in.
     """
     lang = _tlang(state)
+    nl_current_key = getattr(state, "narration_length", "medium") or "medium"
+    theme_key = getattr(state, "theme", "fantasy") or "fantasy"
+    # Cache by (lang, narration-length key, theme key) — the only fields
+    # the returned tuple of gr.update() objects actually depends on. The
+    # theme is in the key because _theme_dropdown_update inspects state.theme.
+    cache_key = (lang, nl_current_key, theme_key)
+    if cache_key in _LOCALIZED_CHROME_CACHE:
+        return _LOCALIZED_CHROME_CACHE[cache_key]
     from oracles.state import NARRATION_LENGTHS as _NL
     nl_choices = [v[0][lang] if isinstance(v[0], dict) else v[0]
                   for v in _NL.values()]
     nl_default_label = _NL["medium"][0]
     nl_default = (nl_default_label[lang] if isinstance(nl_default_label, dict)
                   else nl_default_label)
-    # Map the current state.narration_length key back to its localized label
-    # so the dropdown's `value` stays in sync after a language flip.
-    nl_current_key = getattr(state, "narration_length", "medium") or "medium"
     nl_current_entry = _NL.get(nl_current_key, _NL["medium"])
     nl_current_label = nl_current_entry[0]
     nl_current = (nl_current_label[lang] if isinstance(nl_current_label, dict)
                   else nl_current_label)
 
-    return (
+    result = (
         gr.update(
             label=_t("label_narration_length", lang),
             info=_t("info_narration_length", lang),
@@ -3741,6 +3752,8 @@ def _localized_chrome_updates(state: GameState):
         _theme_dropdown_update(state, lang),
         gr.update(label=_t("label_chronicle_accordion", lang)),
     )
+    _LOCALIZED_CHROME_CACHE[cache_key] = result
+    return result
 
 
 def _theme_dropdown_update(state: GameState, lang: str):

oracles/images.py

@@ -107,13 +107,26 @@ def _load_scene_decor_data_uris() -> None:
             _SCENE_DECOR_DATA_URIS[name] = uri
 
 
-_load_sprite_data_uris()
-_load_scene_texture_data_uris()
-_load_scene_decor_data_uris()
+# Lazy initialization — these loaders read 15 PNGs and base64-encode them
+# into RAM. Doing that at module import time (the old behavior) added 1-3s
+# to every cold start on HF Spaces' shared CPU. The accessors below call
+# ``_ensure_loaded()`` on first use instead.
+_LOADED = False
+
+
+def _ensure_loaded() -> None:
+    global _LOADED
+    if _LOADED:
+        return
+    _load_sprite_data_uris()
+    _load_scene_texture_data_uris()
+    _load_scene_decor_data_uris()
+    _LOADED = True
 
 
 def sprite_data_uri(name: str) -> Optional[str]:
     """Return a data URI for a Klein sprite, or None if it doesn't exist."""
+    _ensure_loaded()
     return _SPRITE_DATA_URIS.get(name)
 
 
@@ -736,10 +749,15 @@ def generate_scene_image(
 ) -> ImageResult:
     """Generate a scene image for `resolution`.
 
+    Triggers the lazy sprite/texture/decor data-uri load on first call so
+    cold start doesn't pay for it. After this returns once, the dicts stay
+    populated for subsequent calls.
+
     MOCK path (default): always returns an SVG (or PNG via cairosvg) card.
     LIVE path: try Klein endpoint; on any failure, silently fall back to mock.
     Caption is always populated even if file writes fail.
     """
+    _ensure_loaded()
     os.makedirs(out_dir, exist_ok=True)
 
     caption = f"Trial {resolution.trial_index}: {resolution.tactic}"