[Werewolf] - update legacy-adapter and player to work with Werewolf

I'm not crazy about the way we are injecting the unstable_playerControls
(previously __mainContext) - it would be nice to learn what exactly
werewolf needs and see if we could work around it with transformers or
more targeted exposed actions

Also updated the way that our dependencies use @kaggle-environments/core
to make the development experience a bit more streamlined

Author: develra

kaggle_environments/envs/open_spiel_env/games/chess/visualizer/default/src/chess_renderer.ts

@@ -1,8 +1,7 @@
 import { ChessStep } from '@kaggle-environments/core';
 import { DARK_SQUARE_COLOR, DEFAULT_NUM_COLS, DEFAULT_NUM_ROWS, LIGHT_SQUARE_COLOR, PIECE_IMAGES_SRC } from './consts';
-import { RendererOptions } from './main';
 
-export function renderer(options: RendererOptions) {
+export function renderer(options: any) {
   const { steps, step, parent, playerNames, width = 400, height = 400, viewer } = options;
 
   let currentBoardElement: HTMLElement | null = null;

package.json

@@ -19,6 +19,7 @@
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.46.1",
     "vite": "^5.0.0",
-    "vite-plugin-checker": "^0.11.0"
+    "vite-plugin-checker": "^0.11.0",
+    "vite-tsconfig-paths": "^5.1.4"
   }
 }

pnpm-lock.yaml

@@ -1,7 +1,7 @@
-import { ReplayData } from "./types";
+import { ReplayData } from './types';
 
 export interface GameAdapter {
   mount(container: HTMLElement, initialData: ReplayData): void;
-  render(step: number, replay: ReplayData, agents: any[]): void;
+  render(step: number, replay: ReplayData, agents: any[], replayerInstance?: any): void;
   unmount(): void;
 }

web/core/src/adapter.ts

@@ -8,6 +8,7 @@ type LegacyRenderer = (options: any, container?: HTMLElement) => void;
 export class LegacyAdapter implements GameAdapter {
   private container: HTMLElement | null = null;
   private renderer: LegacyRenderer;
+  private isInitialRender = true;
 
   constructor(renderer: LegacyRenderer) {
     this.renderer = renderer;
@@ -17,11 +18,32 @@ export class LegacyAdapter implements GameAdapter {
     this.container = container;
   }
 
-  render(step: number, replay: ReplayData, agents: any[]): void {
+  // replayerInstance passing is a bit of a hack for werewolf - would be nice to eliminate it
+  render(step: number, replay: ReplayData, agents: any[], replayerInstance?: any): void {
     if (!this.container) return;
 
-    // Clear container before rendering, as legacy renderers often append.
-    this.container.innerHTML = '';
+    // Clear container only on the first render pass.
+    if (this.isInitialRender) {
+      this.container.innerHTML = '';
+      this.isInitialRender = false;
+    }
+
+    // Generally it would be better to not do this - but werewolf needs some inner frame control
+    // that conforms to this interface - marking as unstable for now to see if we can figure out
+    // a better long-term solution here
+    const unstable_replayerControls = replayerInstance
+      ? {
+          setStep: (newStep: number) => replayerInstance.setStep(newStep),
+          play: (continuing?: boolean) => replayerInstance.play(continuing),
+          pause: () => replayerInstance.pause(),
+          setPlaying: (playing: boolean) => replayerInstance.setPlayingState(playing),
+          // Expose current step and playing state for renderer to read
+          step: replayerInstance.step,
+          playing: replayerInstance.playing,
+          // Expose the actual player object for advanced scenarios if needed
+          _replayerInstance: replayerInstance,
+        }
+      : undefined;
 
     const renderOptions = {
       // For chess/poker
@@ -37,6 +59,8 @@ export class LegacyAdapter implements GameAdapter {
       step: step,
       width: this.container.clientWidth,
       height: this.container.clientHeight,
+
+      unstable_replayerControls: unstable_replayerControls,
     };
 
     // Some legacy renderers take the container as a second argument.

web/core/src/legacy-adapter.ts

@@ -218,10 +218,13 @@ export class ReplayVisualizer {
       needsRender = true;
     }
 
-    // Update steps from 'setSteps'
+    // Update steps from 'setSteps' - this is a special case.
+    // The renderer is taking control of the steps, and we just need to update
+    // our controls to match, not trigger a destructive re-render.
     if (event.data.setSteps && this.replay) {
       this.replay.steps = event.data.setSteps;
-      needsRender = true;
+      this.stepSlider.max = (this.replay.steps.length > 0 ? this.replay.steps.length - 1 : 0).toString();
+      this.renderControls();
     }
 
     // Overwrite replay object if a full 'replay' is provided
@@ -285,7 +288,7 @@ export class ReplayVisualizer {
 
     // Only render/tick if not told to skip (e.g., during HMR restore)
     if (!options.skipRender) {
-      this.adapter.render(this.step, this.replay, this.agents);
+      this.adapter.render(this.step, this.replay, this.agents, this);
       this.tick();
     }
   }
@@ -300,7 +303,7 @@ export class ReplayVisualizer {
     }
     // --- End HMR Logic ---
 
-    this.adapter.render(this.step, this.replay, this.agents);
+    this.adapter.render(this.step, this.replay, this.agents, this);
     this.renderControls();
   }
 
@@ -334,6 +337,18 @@ export class ReplayVisualizer {
     this.renderControls();
   }
 
+  /**
+   * Sets the playing state directly and updates controls, but does not trigger
+   * the timer-based 'tick()' method. Useful for renderers that implement their
+   * own playback logic (e.g., audio-driven).
+   * @param playing The new playing state.
+   */
+  public setPlayingState(playing: boolean) {
+    if (this.playing === playing) return;
+    this.playing = playing;
+    this.renderControls();
+  }
+
   private tick = () => {
     if (!this.playing || !this.replay) return;
 

web/core/src/player.ts

@@ -3,32 +3,32 @@ import { GameAdapter } from './adapter';
 import { ReplayData } from './types';
 
 interface RendererProps {
-    replay: ReplayData;
-    step: number;
-    agents: any[];
+  replay: ReplayData;
+  step: number;
+  agents: any[];
 }
 
 export class PreactAdapter implements GameAdapter {
-    private container: HTMLElement | null = null;
-    private renderer: FunctionComponent<RendererProps>;
+  private container: HTMLElement | null = null;
+  private renderer: FunctionComponent<RendererProps>;
 
-    constructor(renderer: FunctionComponent<RendererProps>) {
-        this.renderer = renderer;
-    }
+  constructor(renderer: FunctionComponent<RendererProps>) {
+    this.renderer = renderer;
+  }
 
-    mount(container: HTMLElement, initialData: ReplayData): void {
-        this.container = container;
-        this.render(0, initialData, []);
-    }
+  mount(container: HTMLElement, initialData: ReplayData): void {
+    this.container = container;
+    this.render(0, initialData, []);
+  }
 
-    render(step: number, replay: ReplayData, agents: any[]): void {
-        if (!this.container) return;
-        render(h(this.renderer, { replay, step, agents }), this.container);
-    }
+  render(step: number, replay: ReplayData, agents: any[]): void {
+    if (!this.container) return;
+    render(h(this.renderer, { replay, step, agents }), this.container);
+  }
 
-    unmount(): void {
-        if (!this.container) return;
-        render(null, this.container);
-        this.container = null;
-    }
+  unmount(): void {
+    if (!this.container) return;
+    render(null, this.container);
+    this.container = null;
+  }
 }

web/core/src/preact-adapter.ts

@@ -1,19 +1,19 @@
-import { defineConfig } from "vite";
-import { resolve } from "path";
-import dts from "vite-plugin-dts";
+import { defineConfig } from 'vite';
+import { resolve } from 'path';
+import dts from 'vite-plugin-dts';
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [dts()],
   build: {
     lib: {
-      entry: resolve(__dirname, "src/index.ts"),
-      name: "@kaggle-environments/core",
-      fileName: "index"
+      entry: resolve(__dirname, 'src/index.ts'),
+      name: '@kaggle-environments/core',
+      fileName: 'index',
     },
-    outDir: "dist",
+    outDir: 'dist',
     rollupOptions: {
-      external: ["preact", "preact/hooks", "htm"]
-    }
-  }
+      external: ['preact', 'preact/hooks', 'htm'],
+    },
+  },
 });

web/core/vite.config.ts

@@ -17,6 +17,10 @@
     "skipLibCheck": true,
     "jsx": "preserve",
     "jsxImportSource": "preact",
-    "types": ["vite/client"]
+    "types": ["vite/client"],
+    "baseUrl": ".",
+    "paths": {
+      "@kaggle-environments/core": ["core/src/index.ts"]
+    }
   }
 }