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/atl.ts

@@ -2,17 +2,22 @@
 
 export type AtlProps = Record<string, any>;
 
+/** A literal, or an expression evaluated when the timeline runs (`{ e: expr }`). */
+export type AtlValue<T = any> = T | { e: any };
+
 export interface AtlBlock {
   steps: AtlStep[];
-  repeat: null | true | number;
+  repeat: null | true | AtlValue<number>;
+  /** Parameters of `transform name(a, b=1):`. */
+  params?: { n: string; d: any; kind: string }[];
 }
 
 export type AtlStep =
   | { op: "set"; props: AtlProps }
-  | { op: "move"; warp: "linear" | "ease" | "easein" | "easeout"; t: number; props: AtlProps }
-  | { op: "pause"; t: number }
+  | { op: "move"; warp: "linear" | "ease" | "easein" | "easeout"; t: AtlValue<number>; props: AtlProps }
+  | { op: "pause"; t: AtlValue<number> }
   | { op: "parallel"; blocks: AtlBlock[] }
-  | { op: "choice"; blocks: { w: number; block: AtlBlock }[] }
+  | { op: "choice"; blocks: { w: AtlValue<number>; block: AtlBlock }[] }
   | { op: "block"; block: AtlBlock }
   | { op: "on"; events: string[]; block: AtlBlock }
   | { op: "use"; name: string };
@@ -24,6 +29,20 @@ export interface AtlHost {
   props(name: string): AtlProps | null;
   /** Called after every change of the working properties. */
   apply(props: AtlProps): void;
+  /** Evaluate a run-time value with the transform's parameters in scope. */
+  eval?(expr: any, vars: Map<string, any>): any;
+}
+
+/** Bind `name(args)` of an `at` clause to the transform's parameters. `ev` evaluates in the caller's scope. */
+export function bindArguments(block: AtlBlock, spec: { args?: any[]; kw?: Record<string, any> },
+                              ev: (expr: any) => any): Map<string, any> {
+  const vars = new Map<string, any>();
+  (block.params ?? []).forEach((p, i) => {
+    if (spec.kw && Object.hasOwn(spec.kw, p.n)) vars.set(p.n, ev(spec.kw[p.n]));
+    else if (spec.args && i < spec.args.length) vars.set(p.n, ev(spec.args[i]));
+    else vars.set(p.n, p.d ? ev(p.d) : null);
+  });
+  return vars;
 }
 
 const SHOW_EVENTS = new Set(["show", "appear", "default", "start", "update", "replace"]);
@@ -50,15 +69,34 @@ function nextFrame() {
 export class AtlRunner {
   private token = 0;
 
-  constructor(private host: AtlHost, private props: AtlProps) {}
+  constructor(private host: AtlHost, private props: AtlProps, private vars: Map<string, any> = new Map()) {}
 
-  /** Start the timeline; resolves when it ends (never, for endless loops) or is stopped. */
-  async start(block: AtlBlock): Promise<void> {
+  /** Resolve `{ e: expr }` values (also inside tuples). */
+  private val<T = any>(v: AtlValue<T> | undefined): any {
+    if (Array.isArray(v)) return v.map((x) => this.val(x));
+    if (v && typeof v === "object" && "e" in v) return this.host.eval ? this.host.eval((v as any).e, this.vars) : null;
+    return v;
+  }
+
+  private props_(values: AtlProps): AtlProps {
+    return Object.fromEntries(Object.entries(values).map(([k, v]) => [k, this.val(v)]));
+  }
+
+  private seconds(v: AtlValue<number> | undefined): number {
+    const n = Number(this.val(v));
+    return Number.isFinite(n) ? Math.max(0, n) : 0;
+  }
+
+  /** Start the timeline; resolves when it ends (never, for endless loops) or is stopped.
+   *  The result is true only when the timeline ran to its end. */
+  async start(block: AtlBlock): Promise<boolean> {
     const token = ++this.token;
     try {
       await this.run(block, token, 0, "show");
+      return true;
     } catch (err) {
       if (!(err instanceof Stopped)) throw err;
+      return false;
     }
   }
 
@@ -126,7 +164,7 @@ export class AtlRunner {
       }
       loops++;
       if (block.repeat === null) return;
-      if (block.repeat !== true && loops >= block.repeat) return;
+      if (block.repeat !== true && loops >= this.seconds(block.repeat as AtlValue<number>)) return;
       // a loop without any waiting step would freeze the page: yield one frame per turn
       if (!waited && performance.now() - startedAt < 1) await nextFrame();
     }
@@ -136,22 +174,27 @@ export class AtlRunner {
   private async step(step: AtlStep, token: number, depth: number, event: string): Promise<boolean> {
     switch (step.op) {
       case "set":
-        Object.assign(this.props, step.props);
+        Object.assign(this.props, this.props_(step.props));
         this.apply();
         return false;
-      case "pause":
-        await this.sleep(step.t, token);
-        return step.t > 0;
-      case "move":
-        await this.move(step, token);
-        return step.t > 0;
+      case "pause": {
+        const t = this.seconds(step.t);
+        await this.sleep(t, token);
+        return t > 0;
+      }
+      case "move": {
+        const t = this.seconds(step.t);
+        await this.move(step, t, token);
+        return t > 0;
+      }
       case "parallel":
         await Promise.all(step.blocks.map((b) => this.run(b, token, depth + 1, event)));
         return true;
       case "choice": {
-        const total = step.blocks.reduce((s, b) => s + b.w, 0);
+        const weights = step.blocks.map((b) => this.seconds(b.w) || 1);
+        const total = weights.reduce((s, w) => s + w, 0);
         let pick = Math.random() * total;
-        const chosen = step.blocks.find((b) => (pick -= b.w) < 0) ?? step.blocks[step.blocks.length - 1];
+        const chosen = step.blocks.find((_, i) => (pick -= weights[i]) < 0) ?? step.blocks[step.blocks.length - 1];
         if (chosen) await this.run(chosen.block, token, depth + 1, event);
         return true;
       }
@@ -199,22 +242,23 @@ export class AtlRunner {
     }
   }
 
-  private async move(step: Extract<AtlStep, { op: "move" }>, token: number) {
+  private async move(step: Extract<AtlStep, { op: "move" }>, seconds: number, token: number) {
+    const target = this.props_(step.props);
     const from: AtlProps = {};
-    for (const key of Object.keys(step.props)) from[key] = this.current(key);
+    for (const key of Object.keys(target)) from[key] = this.current(key);
     const curve = curves[step.warp] ?? curves.linear;
     const start = performance.now();
-    const duration = step.t * 1000;
+    const duration = seconds * 1000;
     while (duration > 0) {
       await nextFrame();
       this.alive(token);
       const raw = Math.min(1, (performance.now() - start) / duration);
       const k = curve(raw);
-      for (const [key, to] of Object.entries(step.props)) this.props[key] = mix(from[key], to, k);
+      for (const [key, to] of Object.entries(target)) this.props[key] = mix(from[key], to, k);
       this.apply();
       if (raw >= 1) return;
     }
-    Object.assign(this.props, step.props);
+    Object.assign(this.props, target);
     this.apply();
   }
 }

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) => {

frontend/src/player/player.css

@@ -343,3 +343,20 @@
 .pg-dialog-row { display: flex; justify-content: flex-end; gap: 10px; }
 .pg-dialog button { font-size: 15px; padding: 9px 18px; }
 .pg-dialog .pg-primary { background: #ff9f43; border-color: #ff9f43; color: #1a1205; font-weight: 650; }
+
+/* --- game screens (Ren'Py screen language) ------------------------------------------ */
+.pg-usr { position: absolute; inset: 0; pointer-events: none; }
+.pg-sinst { position: absolute; inset: 0; pointer-events: none; }
+.pg-sinst.pg-smodal { pointer-events: auto; }
+.pg-sw { pointer-events: none; min-width: 0; min-height: 0; color: var(--pg-text, #fff); font-size: var(--pg-font, 24px); }
+.pg-sframe, .pg-swindow, .pg-sviewport, .pg-sbar, .pg-sbtn { pointer-events: auto; }
+.pg-sbtn { cursor: pointer; user-select: none; }
+.pg-sbtn.pg-sdisabled { cursor: default; }
+.pg-sbtn:focus-visible { outline: 2px solid var(--pg-accent, #4af); outline-offset: 2px; }
+.pg-simgbtn img, .pg-simgbtn .pg-simg { display: block; pointer-events: none; }
+.pg-stext { white-space: pre-wrap; }
+.pg-sbar { background: rgba(255, 255, 255, 0.18); min-width: 40px; min-height: 12px; }
+.pg-sbar-fill { background: var(--pg-accent, #4af); width: 100%; height: 100%; }
+.pg-sbar:not(.pg-svbar) .pg-sbar-fill { height: 100%; }
+.pg-sadd { pointer-events: none; }
+.pg-sviewport { scrollbar-width: thin; }

frontend/src/player/renderer.ts

@@ -1,7 +1,7 @@
 // DOM renderer for the image layer: one absolutely positioned element per shown tag.
 // The stage has the game's native resolution and is scaled with a CSS transform.
 
-import { AtlRunner, type AtlBlock } from "./atl";
+import { AtlRunner, bindArguments, type AtlBlock } from "./atl";
 import type { AtSpec, ImageDef, ShownImage, Transition } from "./types";
 
 const POSITIONS: Record<string, Record<string, number>> = {
@@ -29,6 +29,8 @@ export interface RendererHost {
   evalCond(e: any): boolean;
   transform(name: string): Record<string, any> | null;
   atl(name: string): AtlBlock | null;
+  /** Evaluate an expression, optionally with extra variables (ATL parameters) in scope. */
+  evalExpr(expr: any, frame?: Map<string, any>): any;
   text(e: any): string;
 }
 
@@ -105,7 +107,8 @@ export class Renderer {
         block: (name) => this.host.atl(name),
         props: (name) => this.host.transform(name),
         apply: (p) => this.style(entry.el, { ...p }),
-      }, live);
+        eval: (expr, frame) => this.host.evalExpr(expr, frame),
+      }, live, bindArguments(block, spec, (e) => this.host.evalExpr(e)));
       entry.runners.push({ runner, block });
       void runner.start(block).catch((err) => console.warn("[pgvn] ATL", err));
     }
@@ -207,6 +210,11 @@ export class Renderer {
     return document.createElement("div");
   }
 
+  /** An element for an image definition, for UI built outside the scene (screens). */
+  displayable(def: ImageDef): HTMLElement {
+    return this.build(def);
+  }
+
   /** Frame-by-frame ATL animation: swaps children on timers while attached. */
   private animated(def: ImageDef, depth: number): HTMLElement {
     const box = document.createElement("div");
@@ -311,7 +319,10 @@ export class Renderer {
     if (ax.endsWith("px") || ay.endsWith("px"))
       el.style.transform = `translate(calc(-1 * ${ax}), calc(-1 * ${ay})) scale(${zx}, ${zy})`;
     if (p.alpha !== undefined) el.style.opacity = String(p.alpha);
-    if (p.filter) el.style.filter = `${p.filter}(1)`;
+    const filters: string[] = [];
+    if (p.filter) filters.push(`${p.filter}(1)`);
+    if (typeof p.blur === "number" && p.blur > 0) filters.push(`blur(${p.blur}px)`);
+    if (filters.length) el.style.filter = filters.join(" ");
   }
 
   // --- transitions ---------------------------------------------------------------

frontend/src/player/types.ts

@@ -53,6 +53,9 @@ export interface AtSpec {
   props?: Record<string, any>;
   /** Animated transform: a name from GameData.atl or an inline timeline. */
   atl?: string | import("./atl").AtlBlock;
+  /** Arguments of `at name(args)` for a parameterised transform. */
+  args?: Expr[];
+  kw?: Record<string, Expr>;
   effect?: "shake";
   d?: number;
   dist?: number;
@@ -109,6 +112,8 @@ export interface GameData {
   images: Record<string, ImageDef>;
   transforms: Record<string, Record<string, any>>;
   atl?: Record<string, import("./atl").AtlBlock>;
+  screens?: Record<string, import("./screens").ScreenDef>;
+  styles?: Record<string, import("./screens").StyleDef>;
   transitions: Record<string, Transition | null>;
   audio: Record<string, string>;
   channels?: Record<string, { mixer: string; loop: boolean }>;
@@ -155,4 +160,5 @@ export interface SaveData {
   camera?: AtSpec[];
   menuSeen?: string[];
   text?: string;
+  screens?: { name: string; args: any[]; kw: Record<string, any> }[];
 }