feat: Ren'Py screens (screen/call screen/show screen) with actions and styles

Converter
- screens.py parses the screen language: containers (fixed, frame, vbox, hbox,
  grid, vpgrid, viewport, button, has), widgets (text, textbutton, imagebutton,
  add, bar ...), if/for/use/transclude, default, python, key, timer, on, inline ATL,
  conditional properties, and decompiled forms (unparenthesised operators,
  glued property values, comma separated actions)
- style statements, call/show/hide screen operators and Python-level
  renpy.show_screen are translated; only screens the game shows are audited,
  unused stock screens no longer block an import; undefined screens do
- ATL values may be computed at run time and transforms take parameters
  (at blink(0.2, 0.3)); blur property

Player
- screens.ts builds the DOM from the IR and rebuilds it on state changes;
  buttons with idle/hover/selected/insensitive states, tooltips, sounds, modal
  screens, timers and keys that survive re-rendering, saved with the save file
- Actions: Jump, Call, Return, SetVariable, Toggle*, SetScreenVariable, Show, Hide,
  ToggleScreen, Function, Play, Notify, If, Language, ShowMenu, OpenURL ...
- Crop/LiveCrop/Solid/Frame/Transform/DynamicDisplayable values, crop property,
  globals(), renpy.variant/change_language/seen_image, transition stubs

Tests: screen parser and runtime (linkedom DOM), screens fixture compiled from
tests/fixtures/screens.rpy. Docs: docs/SCREENS.md.

Twisted-Thoughts now passes the strict compatibility check.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

frontend/src/player/engine.ts

@@ -6,6 +6,7 @@ import { Renderer, type ResolvedImage } from "./renderer";
 import { fastPoint, interpolate, parseText, plainText, renderText, waitPoints } from "./text";
 import { languageName, rememberLanguage, type Translator } from "./i18n";
 import { naniText } from "./naninovel";
+import { ScreenManager, type ScreenHost } from "./screens";
 import { DEFAULT_SETTINGS, SLOTS, Restart, el, loadJSON, saveJSON, type SaveApi, type SaveMeta, type Settings } from "./engine-util";
 import type {
   CharacterDef, Expr, Frame, GameData, ImageDef, Label, Layer, Manifest, Node, SaveData, ScriptModule,
@@ -35,6 +36,9 @@ export class Engine {
   private stack: Frame[] = [];
   private gen = 0;
   private waiters: (() => void)[] = [];
+  private screens: ScreenManager;
+  private screenFonts = new Map<string, string>();
+  private seenImages = new Set<string>();
   private running = false;
 
   private skip = false;
@@ -101,7 +105,8 @@ export class Engine {
       del: (n) => void delete this.store[n],
     };
     this.py = new Python(scope);
-    this.builtins = this.makeBuiltins();
+    this.screens = new ScreenManager(this.screenHost(), game.screens ?? {}, game.styles ?? {});
+    this.builtins = { ...this.makeBuiltins(), ...this.screens.builtins() };
 
     const [w, h] = game.resolution;
     this.baseSize = Number(game.ui.text_size) || Math.round(h * 0.0306);
@@ -113,6 +118,15 @@ export class Engine {
       evalCond: (c) => truthy(this.safeEval(c)),
       transform: (name) => game.transforms[name] ?? null,
       atl: (name) => game.atl?.[name] ?? null,
+      evalExpr: (expr, frame) => {
+        const saved = this.py.locals;
+        this.py.locals = frame ? [...saved, frame] : saved;
+        try {
+          return this.safeEval(expr);
+        } finally {
+          this.py.locals = saved;
+        }
+      },
       text: (e) => this.interp(this.tr.str(pyStr(this.safeEval(e)))),
     });
     this.audio = new AudioSystem(this.settings, (f) => this.fileUrl(f), game.channels ?? {});
@@ -125,6 +139,7 @@ export class Engine {
   }
 
   destroy() {
+    this.screens.destroy();
     this.gen++;
     this.wakeAll();
     this.audio.stopAll();
@@ -303,8 +318,12 @@ export class Engine {
         throw new JumpSignal("jump", "__quit__");
       },
       version: () => "pgvn",
+      ...this.screens.renpyApi(),
       // presentation-only: nothing to roll back or replay, and the next transition is chosen by `with`
       end_replay: () => null,
+      variant: (name: string) => ["pc", "large", "web", "medium"].includes(String(name)),
+      change_language: (code: any) => void this.setLanguage(code === null || code === undefined ? this.game.sourceLang ?? "und" : String(code)),
+      seen_image: (name: any) => this.seenImages.has(String(name)),
       block_rollback: () => null,
       transition: () => null,
     };
@@ -330,6 +349,10 @@ export class Engine {
       random,
       math: { floor: Math.floor, ceil: Math.ceil, sqrt: Math.sqrt, pi: Math.PI, pow: Math.pow },
       len: (x: any) => (x instanceof PyDict ? x.map.size : x?.length ?? 0),
+      // a read-only view: `"name" in globals()` works, writes do not reach the game
+      globals: () => new PyDict(Object.entries(this.store)),
+      ...Object.fromEntries(["Dissolve", "Fade", "ImageDissolve", "MoveTransition", "CropMove", "PushMove",
+        "Pixellate", "ComposeTransition", "With"].map((n) => [n, () => null])),
       str: (x: any) => pyStr(x),
       int: (x: any) => Math.trunc(num(x)),
       float: (x: any) => num(x),
@@ -385,7 +408,72 @@ export class Engine {
     }
   }
 
+  private screenHost(): ScreenHost {
+    const engine = this;
+    return {
+      py: this.py,
+      fileUrl: (path) => this.fileUrl(path),
+      image: (value) => this.screenImage(value),
+      text: (el, value, size) => renderText(el, parseText(this.interp(this.tr.str(value))), Infinity, size),
+      fontFamily: (file) => this.screenFont(file),
+      get baseSize() { return engine.baseSize; },
+      play: (channel, file, loop) => this.audio.play(channel, [file], { loop }),
+      stop: (channel) => this.audio.stop(channel, 0),
+      notify: (message) => this.notify(message),
+      jump: (label) => this.restart(() => this.guardedJump(label)),
+      call: (label) => this.restart(() => this.call(label)),
+      quit: () => this.onExit(),
+      mainMenu: () => this.restart(() => { this.stack = []; this.cur = { label: "", path: [0] }; }),
+      openMenu: () => this.openGameMenu(),
+      openUrl: (url) => {
+        if (/^https?:\/\//i.test(url)) window.open(url, "_blank", "noopener,noreferrer");
+      },
+      setLanguage: (code) => void this.setLanguage(code ?? this.game.sourceLang ?? "und"),
+      transform: (name) => this.game.transforms[name] ?? null,
+      atl: (name) => this.game.atl?.[name] ?? null,
+    };
+  }
+
+  /** A jump requested from a widget; the special menu/quit targets end the session instead. */
+  private guardedJump(label: string) {
+    try {
+      this.jump(label);
+    } catch (err) {
+      if (!(err instanceof Restart)) throw err;
+      this.cur = { label: "", path: [0] };
+      if (err.message === "__quit__") this.onExit();
+    }
+  }
+
+  private screenImage(value: string): HTMLElement | null {
+    if (/^#[0-9a-f]{3,8}$/i.test(value)) {
+      const box = el("div");
+      box.style.background = value;
+      box.style.width = box.style.height = "100%";
+      return box;
+    }
+    const resolved = this.resolveImage(value.split(" "));
+    if (resolved) return this.renderer.displayable(resolved.def);
+    const url = this.fileUrl(value);
+    if (!url) return null;
+    const img = new Image();
+    img.src = url;
+    img.draggable = false;
+    return img;
+  }
+
+  private screenFont(file: string): string | null {
+    let family = this.screenFonts.get(file);
+    if (!family) {
+      family = `pg-scr-${this.screenFonts.size}`;
+      this.screenFonts.set(file, family);
+      this.loadFont(family, file);
+    }
+    return family;
+  }
+
   private resetStore() {
+    this.screens.clear();
     this.store = {};
     try {
       this.py.exec(this.game.init);
@@ -557,6 +645,7 @@ export class Engine {
         }
         try {
           await this.exec(node);
+          this.screens.refresh();
         } catch (err) {
           if (err instanceof JumpSignal) {
             if (err.kind === "jump") this.jump(err.target);
@@ -577,6 +666,13 @@ export class Engine {
     }
   }
 
+  private screenArgs(node: Node) {
+    return {
+      args: (node.args ?? []).map((e: Expr) => this.safeEval(e)),
+      kw: Object.fromEntries(Object.entries(node.kw ?? {}).map(([k, e]) => [k, this.safeEval(e as Expr)])),
+    };
+  }
+
   private async exec(node: Node) {
     switch (node.op) {
       case "nani_exit":
@@ -688,6 +784,26 @@ export class Engine {
         return this.jump(node.target ?? pyStr(this.safeEval(node.expr)));
       case "call":
         return this.call(node.target ?? pyStr(this.safeEval(node.expr)), node.args);
+      case "call_screen": {
+        const { args, kw } = this.screenArgs(node);
+        this.interactionStart();
+        this.setSkip(false);
+        const value = await this.wait<any>((done) => this.screens.show(node.name, args, kw, { call: true, onReturn: done }));
+        this.screens.hideCall(node.name);
+        this.store._return = value ?? null;
+        this.advance();
+        return;
+      }
+      case "show_screen": {
+        const { args, kw } = this.screenArgs(node);
+        this.screens.show(node.name, args, kw);
+        this.advance();
+        return;
+      }
+      case "hide_screen":
+        this.screens.hide(node.name);
+        this.advance();
+        return;
       case "camera":
         this.renderer.camera(node.at ?? []);
         this.advance();
@@ -727,6 +843,7 @@ export class Engine {
       return;
     }
     const tag = node.as ?? (node.img.name ? node.img.name[0] : img.name[0]);
+    for (let n = 1; n <= img.name.length; n++) this.seenImages.add(img.name.slice(0, n).join(" "));
     const zorder = node.zorder ? Number(this.safeEval(node.zorder)) : undefined;
     this.renderer.show(img, tag, node.at ?? [], { zorder, behind: node.behind });
   }
@@ -1003,6 +1120,7 @@ export class Engine {
     this.wakeAll();
     this.onAdvance = null;
     this.skipTick = null;
+    this.screens.hideCalls();
     this.closeScreen();
     this.menuEl.classList.add("pg-hidden");
     this.centeredEl.classList.add("pg-hidden");
@@ -1097,6 +1215,7 @@ export class Engine {
       cur: anchor(this.cur),
       stack: this.stack.map((f) => ({ ...anchor(f), saved: encodeValue(f.saved) })),
       store: encodeValue(this.store),
+      screens: encodeValue(this.screens.snapshot()),
       scene: this.renderer.snapshot(),
       music: this.audio.current("music"),
       window: this.windowShown,
@@ -1142,6 +1261,7 @@ export class Engine {
     this.restart(() => {
       this.resetStore();
       Object.assign(this.store, decodeValue(data.store));
+      this.screens.restore(decodeValue(data.screens ?? []));
       this.renderer.scene();
       for (const s of data.scene) {
         const img = this.resolveImage(s.name);
@@ -1239,7 +1359,7 @@ export class Engine {
     this.centeredEl = el("div", "pg-centered pg-hidden");
     this.screen = el("div", "pg-screen pg-hidden");
     this.notifyEl = el("div", "pg-notify pg-hidden");
-    stage.append(this.nvlEl, this.textbox, this.centeredEl, this.menuEl, this.screen, this.notifyEl);
+    stage.append(this.nvlEl, this.textbox, this.centeredEl, this.menuEl, this.screens.layer, this.screen, this.notifyEl);
 
     // touch-friendly menu button outside the scaled stage
     const hud = el("button", "pg-hud-btn", "☰");
@@ -1255,7 +1375,7 @@ export class Engine {
 
     stage.addEventListener("click", (ev) => {
       if (!this.screen.classList.contains("pg-hidden")) return;
-      if ((ev.target as HTMLElement).closest(".pg-menu, .pg-quick")) return;
+      if ((ev.target as HTMLElement).closest(".pg-menu, .pg-quick, .pg-sbtn, .pg-sframe, .pg-swindow, .pg-sviewport, .pg-sbar, .pg-smodal")) return;
       this.advanceInput();
     });
     stage.addEventListener("wheel", (ev) => {