Style: enforce 2-space indent and double quotes

eslint.config.js

@@ -28,7 +28,7 @@ export default tseslint.config(
     files: ["**/*.ts", "**/*.tsx"],
     rules: {
       // --- Project Conventions ---
-      quotes: ["error", "single", { avoidEscape: true }],
+      quotes: ["error", "double", { avoidEscape: true }],
       "comma-dangle": ["error", "always-multiline"],
       indent: ["error", 2, { SwitchCase: 1 }],
 
@@ -68,7 +68,6 @@ export default tseslint.config(
       "import/no-duplicates": "error",
 
       // --- General ---
-      "no-console": "warn",
       "prefer-const": "error",
       "no-var": "error",
       eqeqeq: ["error", "always"],

packages/framework/src/index.ts

@@ -1,19 +1,38 @@
 // Resource management
-export { DisposableBag } from './utils';
+export { DisposableBag } from "./utils";
-export type { IDisposable, DisposableItem } from './utils';
+export type { IDisposable, DisposableItem } from "./utils";
 
 // Drag & drop utilities
-export { dragDropEventEffect, DragDropEventType } from './utils';
+export { dragDropEventEffect, DragDropEventType } from "./utils";
-export type { DragDropEvent } from './utils';
+export type { DragDropEvent } from "./utils";
 
 // Data-driven object spawning
-export { spawnEffect } from './spawner';
+export { spawnEffect } from "./spawner";
-export type { Spawner } from './spawner';
+export type { Spawner } from "./spawner";
 
 // Scene base classes
-export { ReactiveScene, GameHostScene, FadeScene, FADE_SCENE_KEY } from './scenes';
+export {
-export type { ReactiveSceneOptions, ReactiveScenePhaserData, SceneController, GameHostSceneOptions, FadeSceneData } from './scenes';
+  ReactiveScene,
+  GameHostScene,
+  FadeScene,
+  FADE_SCENE_KEY,
+} from "./scenes";
+export type {
+  ReactiveSceneOptions,
+  ReactiveScenePhaserData,
+  SceneController,
+  GameHostSceneOptions,
+  FadeSceneData,
+} from "./scenes";
 
 // React ↔ Phaser bridge
-export { PhaserGame, PhaserScene, phaserContext, defaultPhaserConfig, GameUI, type PhaserGameContext, type SceneController as PhaserSceneController } from './ui';
+export {
-export type { PhaserGameProps, PhaserSceneProps, GameUIOptions } from './ui';
+  PhaserGame,
+  PhaserScene,
+  phaserContext,
+  defaultPhaserConfig,
+  GameUI,
+  type PhaserGameContext,
+  type SceneController as PhaserSceneController,
+} from "./ui";
+export type { PhaserGameProps, PhaserSceneProps, GameUIOptions } from "./ui";

packages/framework/src/scenes/FadeScene.ts

@@ -1,89 +1,83 @@
-import Phaser from 'phaser';
+import { ReactiveScene } from "./ReactiveScene";
-import { ReactiveScene, type ReactiveScenePhaserData } from './ReactiveScene';
 
 export interface FadeSceneData {
-    [key: string]: unknown;
+  [key: string]: unknown;
 }
 
 /**
  * 处理淡入淡出到黑色的过渡场景
  */
 export class FadeScene extends ReactiveScene<FadeSceneData> {
-    private overlay!: Phaser.GameObjects.Rectangle;
+  private overlay!: Phaser.GameObjects.Rectangle;
-    private isFading = false;
+  private isFading = false;
 
-    constructor() {
+  constructor() {
-        super(FADE_SCENE_KEY);
+    super(FADE_SCENE_KEY);
+  }
+
+  create(): void {
+    super.create();
+
+    // 创建黑色遮罩层，覆盖整个游戏区域
+    const game = this.game;
+    this.overlay = this.add
+      .rectangle(0, 0, game.scale.width, game.scale.height, 0x000000, 1)
+      .setOrigin(0)
+      .setAlpha(1)
+      .setDepth(999999)
+      .setInteractive({ useHandCursor: false });
+
+    // 防止遮罩阻挡输入
+    this.overlay.disableInteractive();
+  }
+
+  /**
+   * 淡入（从黑色到透明）
+   * @param duration 动画时长（毫秒）
+   */
+  fadeIn(duration = 300): Promise<void> {
+    return this.fadeTo(0, duration);
+  }
+
+  /**
+   * 淡出（从透明到黑色）
+   * @param duration 动画时长（毫秒）
+   */
+  fadeOut(duration = 300): Promise<void> {
+    return this.fadeTo(1, duration);
+  }
+
+  /**
+   * 淡入淡出到指定透明度
+   */
+  private fadeTo(targetAlpha: number, duration: number): Promise<void> {
+    // 如果 overlay 还未初始化，直接返回 resolved promise
+    if (!this.overlay) {
+      console.warn("FadeScene: overlay 未初始化，跳过过渡动画");
+      return Promise.resolve();
     }
 
-    create(): void {
+    if (this.isFading) {
-        super.create();
+      console.warn("FadeScene: 正在进行过渡动画");
-
-        // 创建黑色遮罩层，覆盖整个游戏区域
-        const game = this.game;
-        this.overlay = this.add.rectangle(
-            0,
-            0,
-            game.scale.width,
-            game.scale.height,
-            0x000000,
-            1
-        ).setOrigin(0)
-            .setAlpha(1)
-            .setDepth(999999)
-            .setInteractive({ useHandCursor: false });
-
-        // 防止遮罩阻挡输入
-        this.overlay.disableInteractive();
     }
 
-    /**
+    this.isFading = true;
-     * 淡入（从黑色到透明）
+    this.overlay.setAlpha(targetAlpha === 1 ? 0 : 1);
-     * @param duration 动画时长（毫秒）
-     */
-    fadeIn(duration = 300): Promise<void> {
-        return this.fadeTo(0, duration);
-    }
 
-    /**
+    return new Promise<void>((resolve) => {
-     * 淡出（从透明到黑色）
+      this.tweens.add({
-     * @param duration 动画时长（毫秒）
+        targets: this.overlay,
-     */
+        alpha: targetAlpha,
-    fadeOut(duration = 300): Promise<void> {
+        duration,
-        return this.fadeTo(1, duration);
+        ease: "Linear",
-    }
+        onComplete: () => {
-
+          this.isFading = false;
-    /**
+          resolve();
-     * 淡入淡出到指定透明度
+        },
-     */
+      });
-    private fadeTo(targetAlpha: number, duration: number): Promise<void> {
+    });
-        // 如果 overlay 还未初始化，直接返回 resolved promise
+  }
-        if (!this.overlay) {
-            console.warn('FadeScene: overlay 未初始化，跳过过渡动画');
-            return Promise.resolve();
-        }
-
-        if (this.isFading) {
-            console.warn('FadeScene: 正在进行过渡动画');
-        }
-
-        this.isFading = true;
-        this.overlay.setAlpha(targetAlpha === 1 ? 0 : 1);
-
-        return new Promise<void>((resolve) => {
-            this.tweens.add({
-                targets: this.overlay,
-                alpha: targetAlpha,
-                duration,
-                ease: 'Linear',
-                onComplete: () => {
-                    this.isFading = false;
-                    resolve();
-                },
-            });
-        });
-    }
 }
 
 // 导出常量供 PhaserGame 使用
-export const FADE_SCENE_KEY = '__fade__';
+export const FADE_SCENE_KEY = "__fade__";

packages/framework/src/scenes/GameHostScene.ts

@@ -1,36 +1,37 @@
-import type { GameHost } from 'boardgame-core';
+import { ReactiveScene } from "./ReactiveScene";
-import { ReactiveScene } from './ReactiveScene';
+
+import type { GameHost } from "boardgame-core";
 
 export interface GameHostSceneOptions<TState extends Record<string, unknown>> {
-    gameHost: GameHost<TState>;
+  gameHost: GameHost<TState>;
-    [key: string]: unknown;
+  [key: string]: unknown;
 }
 
-export abstract class GameHostScene<TState extends Record<string, unknown>>
+export abstract class GameHostScene<
-    extends ReactiveScene<GameHostSceneOptions<TState>>
+  TState extends Record<string, unknown>,
-{
+> extends ReactiveScene<GameHostSceneOptions<TState>> {
-    public get gameHost(): GameHost<TState> {
+  public get gameHost(): GameHost<TState> {
-        const gameHost = this.initData.gameHost as GameHost<TState>;
+    const gameHost = this.initData.gameHost as GameHost<TState>;
-        if (!gameHost) {
+    if (!gameHost) {
-            throw new Error(
+      throw new Error(
-                `GameHostScene (${this.scene.key}): gameHost 未提供。` +
+        `GameHostScene (${this.scene.key}): gameHost 未提供。` +
-                `确保在 PhaserScene 组件的 data 属性中传入 gameHost。`
+          "确保在 PhaserScene 组件的 data 属性中传入 gameHost。",
-            );
+      );
-        }
-        return gameHost;
     }
+    return gameHost;
+  }
 
-    public get state(): TState {
+  public get state(): TState {
-        return this.gameHost?.state.value;
+    return this.gameHost?.state.value;
-    }
+  }
 
-    addInterruption(promise: Promise<void>){
+  addInterruption(promise: Promise<void>) {
-        this.gameHost?.addInterruption(promise);
+    this.gameHost?.addInterruption(promise);
-    }
+  }
 
-    addTweenInterruption(tween: Phaser.Tweens.Tween){
+  addTweenInterruption(tween: Phaser.Tweens.Tween) {
-        this.addInterruption(new Promise(
+    this.addInterruption(
-            resolve => tween.once('complete', resolve)
+      new Promise((resolve) => tween.once("complete", resolve)),
-        ));
+    );
-    }
+  }
 }

packages/framework/src/scenes/ReactiveScene.ts

@@ -1,87 +1,90 @@
-import Phaser from 'phaser';
+import { effect, type ReadonlySignal } from "@preact/signals-core";
-import { effect, type ReadonlySignal } from '@preact/signals-core';
+import { Scene } from "phaser";
-import { DisposableBag, type IDisposable } from '../utils';
+
+import { DisposableBag, type IDisposable } from "../utils";
+
+import type Phaser from "phaser";
 
 type CleanupFn = void | (() => void);
 
 // 前向声明，避免循环导入
 export interface SceneController {
-    launch(sceneKey: string): Promise<void>;
+  launch(sceneKey: string): Promise<void>;
-    restart(): Promise<void>;
+  restart(): Promise<void>;
-    currentScene: ReadonlySignal<string | null>;
+  currentScene: ReadonlySignal<string | null>;
-    isTransitioning: ReadonlySignal<boolean>;
+  isTransitioning: ReadonlySignal<boolean>;
 }
 
 export interface ReactiveScenePhaserData {
-    phaserGame: ReadonlySignal<{ game: Phaser.Game }>;
+  phaserGame: ReadonlySignal<{ game: Phaser.Game }>;
-    sceneController: SceneController;
+  sceneController: SceneController;
 }
 
-export interface ReactiveSceneOptions<TData extends Record<string, unknown> = {}> {
+export interface ReactiveSceneOptions {
-    key?: string;
+  key?: string;
 }
 
 /**
  * 通用的响应式 Scene 基类
  * @typeparam TData - 通过 init(data) 接收的数据类型（必须包含 phaserGame 和 sceneController）
  */
-export abstract class ReactiveScene<TData extends Record<string, unknown> = {}>
+export abstract class ReactiveScene<TData = object>
-    extends Phaser.Scene
+  extends Scene
-    implements IDisposable
+  implements IDisposable
 {
-    protected disposables = new DisposableBag();
+  protected disposables = new DisposableBag();
-    private _initData?: TData & ReactiveScenePhaserData;
+  private _initData?: TData & ReactiveScenePhaserData;
 
-    /**
+  /**
-     * 获取通过 init() 注入的数据
+   * 获取通过 init() 注入的数据
-     * 在 create() 阶段保证可用
+   * 在 create() 阶段保证可用
-     */
+   */
-    public get initData(): TData & ReactiveScenePhaserData {
+  public get initData(): TData & ReactiveScenePhaserData {
-        if (!this._initData) {
+    if (!this._initData) {
-            throw new Error(
+      throw new Error(
-                `ReactiveScene (${this.scene.key}): initData 尚未初始化。` +
+        `ReactiveScene (${this.scene.key}): initData 尚未初始化。` +
-                `确保场景通过 PhaserScene 组件注册，并在 create() 阶段访问。`
+          "确保场景通过 PhaserScene 组件注册，并在 create() 阶段访问。",
-            );
+      );
-        }
-        return this._initData;
     }
+    return this._initData;
+  }
 
-    /**
+  /**
-     * 获取 Phaser game 实例的响应式信号
+   * 获取 Phaser game 实例的响应式信号
-     */
+   */
-    public get phaserGame(): ReadonlySignal<{ game: Phaser.Game }> {
+  public get phaserGame(): ReadonlySignal<{ game: Phaser.Game }> {
-        return this.initData.phaserGame;
+    return this.initData.phaserGame;
-    }
+  }
 
-    /**
+  /**
-     * 获取场景控制器
+   * 获取场景控制器
-     */
+   */
-    public get sceneController(): SceneController {
+  public get sceneController(): SceneController {
-        return this.initData.sceneController;
+    return this.initData.sceneController;
-    }
+  }
 
-    constructor(key?: string) {
+  constructor(key?: string) {
-        super(key);
+    super(key);
-    }
+  }
 
-    init(data: TData & ReactiveScenePhaserData): void {
+  init(data: TData & ReactiveScenePhaserData): void {
-        this._initData = data;
+    this._initData = data;
-    }
+  }
 
-    create(): void {
+  create(): void {
-        this.events.on('shutdown', this.dispose, this);
+    this.events.on("shutdown", this.dispose, this);
-    }
+  }
 
-    dispose(): void {
+  dispose(): void {
-        this.disposables.dispose();
+    this.disposables.dispose();
-    }
+  }
 
-    public addDisposable(disposable: IDisposable): void {
+  public addDisposable(disposable: IDisposable): void {
-        this.disposables.add(disposable);
+    this.disposables.add(disposable);
-    }
+  }
 
-    /** 注册响应式监听（场景关闭时自动清理） */
+  /** 注册响应式监听（场景关闭时自动清理） */
-    public addEffect(fn: () => CleanupFn): void {
+  public addEffect(fn: () => CleanupFn): void {
-        this.disposables.add(effect(fn));
+    this.disposables.add(effect(fn));
-    }
+  }
 }

packages/framework/src/scenes/index.ts

@@ -1,8 +1,12 @@
-export { ReactiveScene } from './ReactiveScene';
+export { ReactiveScene } from "./ReactiveScene";
-export type { ReactiveSceneOptions, ReactiveScenePhaserData, SceneController } from './ReactiveScene';
+export type {
+  ReactiveSceneOptions,
+  ReactiveScenePhaserData,
+  SceneController,
+} from "./ReactiveScene";
 
-export { FadeScene, FADE_SCENE_KEY } from './FadeScene';
+export { FadeScene, FADE_SCENE_KEY } from "./FadeScene";
-export type { FadeSceneData } from './FadeScene';
+export type { FadeSceneData } from "./FadeScene";
 
-export { GameHostScene } from './GameHostScene';
+export { GameHostScene } from "./GameHostScene";
-export type { GameHostSceneOptions } from './GameHostScene';
+export type { GameHostSceneOptions } from "./GameHostScene";

packages/framework/src/ui/GameUI.tsx

@@ -1,11 +1,11 @@
 export interface GameUIOptions {
   container: HTMLElement;
-  root: any;
+  root: HTMLElement;
 }
 
 export class GameUI {
   private container: HTMLElement;
-  private root: any;
+  private root: HTMLElement;
 
   constructor(options: GameUIOptions) {
     this.container = options.container;
@@ -13,13 +13,13 @@ export class GameUI {
   }
 
   mount(): void {
-    import('preact').then(({ render }) => {
+    import("preact").then(({ render }) => {
       render(this.root, this.container);
     });
   }
 
   unmount(): void {
-    import('preact').then(({ render }) => {
+    import("preact").then(({ render }) => {
       render(null, this.container);
     });
   }

packages/framework/src/ui/PhaserBridge.tsx

@@ -1,219 +1,243 @@
-import Phaser from 'phaser';
 import { signal, useSignal, useSignalEffect } from '@preact/signals';
-import { createContext, h } from 'preact';
+import Phaser, { AUTO } from 'phaser';
+import { createContext } from 'preact';
 import { useContext, useEffect, useRef } from 'preact/hooks';
-import { ReadonlySignal } from "@preact/signals-core";
+
+import {
+  FadeScene as FadeSceneClass,
+  FADE_SCENE_KEY,
+} from '../scenes/FadeScene';
+
 import type { ReactiveScene } from '../scenes';
-import { FadeScene as FadeSceneClass, FADE_SCENE_KEY } from '../scenes/FadeScene';
+import type { ReadonlySignal } from '@preact/signals-core';
 
 export interface SceneController {
-    /** 启动场景（带淡入淡出过渡） */
+  /** 启动场景（带淡入淡出过渡） */
-    launch(sceneKey: string): Promise<void>;
+  launch(sceneKey: string): Promise<void>;
-    /** 重新启动当前场景（带淡入淡出过渡） */
+  /** 重新启动当前场景（带淡入淡出过渡） */
-    restart(): Promise<void>;
+  restart(): Promise<void>;
-    /** 当前活跃场景 key */
+  /** 当前活跃场景 key */
-    currentScene: ReadonlySignal<string | null>;
+  currentScene: ReadonlySignal<string | null>;
-    /** 是否正在过渡 */
+  /** 是否正在过渡 */
-    isTransitioning: ReadonlySignal<boolean>;
+  isTransitioning: ReadonlySignal<boolean>;
 }
 
 export interface PhaserGameContext {
-    game: Phaser.Game;
+  game: Phaser.Game;
-    sceneController: SceneController;
+  sceneController: SceneController;
 }
 
-export const phaserContext = createContext<ReadonlySignal<PhaserGameContext> | null>(null);
+export const phaserContext =
+  createContext<ReadonlySignal<PhaserGameContext> | null>(null);
 
 export const defaultPhaserConfig: Phaser.Types.Core.GameConfig = {
-    type: Phaser.AUTO,
+  type: AUTO,
-    width: 560,
+  width: 560,
-    height: 560,
+  height: 560,
-    parent: 'phaser-container',
+  parent: 'phaser-container',
-    backgroundColor: '#f9fafb',
+  backgroundColor: '#f9fafb',
-    scene: [],
+  scene: [],
 };
 
 export interface PhaserGameProps {
-    config?: Partial<Phaser.Types.Core.GameConfig>;
+  config?: Partial<Phaser.Types.Core.GameConfig>;
-    /** 初始启动的场景 key */
+  /** 初始启动的场景 key */
-    initialScene?: string;
+  initialScene?: string;
-    children?: any;
+  children?: preact.ComponentChildren;
 }
 
 export function PhaserGame(props: PhaserGameProps) {
-    const gameSignal = useSignal<PhaserGameContext>({ game: undefined!, sceneController: undefined! });
+  const gameSignal = useSignal<PhaserGameContext>({
-    const initialSceneLaunched = useRef(false);
+    game: undefined!,
+    sceneController: undefined!,
+  });
+  const initialSceneLaunched = useRef(false);
 
-    useSignalEffect(() => {
+  useSignalEffect(() => {
-        const config: Phaser.Types.Core.GameConfig = {
+    const config: Phaser.Types.Core.GameConfig = {
-            ...defaultPhaserConfig,
+      ...defaultPhaserConfig,
-            ...props.config,
+      ...props.config,
-        };
+    };
-        const phaserGame = new Phaser.Game(config);
+    const phaserGame = new Phaser.Game(config);
 
-        // 添加 FadeScene 并启动它来初始化 overlay
+    // 添加 FadeScene 并启动它来初始化 overlay
-        const fadeScene = new FadeSceneClass();
+    const fadeScene = new FadeSceneClass();
-        phaserGame.scene.add(FADE_SCENE_KEY, fadeScene, true); // 改为 true 以触发 create
+    phaserGame.scene.add(FADE_SCENE_KEY, fadeScene, true); // 改为 true 以触发 create
 
-        // 创建 SceneController
+    // 创建 SceneController
-        const currentScene = signal<string | null>(null);
+    const currentScene = signal<string | null>(null);
-        const isTransitioning = signal(false);
+    const isTransitioning = signal(false);
 
-        const sceneController: SceneController = {
+    const sceneController: SceneController = {
-            async launch(sceneKey: string) {
+      async launch(sceneKey: string) {
-                if (isTransitioning.value) {
+        if (isTransitioning.value) {
-                    console.warn('SceneController: 正在进行场景切换');
+          console.warn('SceneController: 正在进行场景切换');
-                    return;
+          return;
-                }
-
-                // 等待场景注册完成（最多等待 100ms）
-                let retries = 0;
-                while (!phaserGame.scene.getScene(sceneKey) && retries < 10) {
-                    await new Promise(resolve => setTimeout(resolve, 10));
-                    retries++;
-                }
-
-                // 验证场景是否已注册
-                if (!phaserGame.scene.getScene(sceneKey)) {
-                    console.error(`SceneController: 场景 "${sceneKey}" 未注册`);
-                    return;
-                }
-
-                isTransitioning.value = true;
-                const fade = phaserGame.scene.getScene(FADE_SCENE_KEY) as FadeSceneClass;
-
-                // 淡出到黑色
-                phaserGame.scene.bringToTop(FADE_SCENE_KEY);
-                await fade.fadeOut(300);
-
-                // 停止当前场景
-                if (currentScene.value) {
-                    phaserGame.scene.stop(currentScene.value);
-                }
-
-                // 确保场景已注册后再启动
-                // （场景应该已经在 PhaserScene 组件中注册）
-                if (!phaserGame.scene.getScene(sceneKey)) {
-                    console.error(`SceneController: 场景 "${sceneKey}" 在切换时仍未注册`);
-                    isTransitioning.value = false;
-                    return;
-                }
-
-                // 启动新场景
-                phaserGame.scene.start(sceneKey);
-                currentScene.value = sceneKey;
-
-                // 淡入
-                await fade.fadeIn(300);
-                isTransitioning.value = false;
-            },
-            async restart() {
-                if (isTransitioning.value) {
-                    console.warn('SceneController: 正在进行场景切换');
-                    return;
-                }
-
-                if (!currentScene.value) {
-                    console.warn('SceneController: 没有当前场景，无法 restart');
-                    return;
-                }
-
-                const sceneKey = currentScene.value;
-                const scene = phaserGame.scene.getScene(sceneKey);
-
-                if (!scene) {
-                    console.error(`SceneController: 场景 "${sceneKey}" 不存在`);
-                    return;
-                }
-
-                isTransitioning.value = true;
-                const fade = phaserGame.scene.getScene(FADE_SCENE_KEY) as FadeSceneClass;
-
-                // 淡出到黑色
-                phaserGame.scene.bringToTop(FADE_SCENE_KEY);
-                await fade.fadeOut(300);
-
-                // 重启当前场景
-                scene.scene.restart();
-
-                // 淡入
-                await fade.fadeIn(300);
-                isTransitioning.value = false;
-            },
-            currentScene,
-            isTransitioning,
-        };
-
-        gameSignal.value = { game: phaserGame, sceneController };
-
-        return () => {
-            gameSignal.value = { game: undefined!, sceneController: undefined! };
-            initialSceneLaunched.current = false;
-            phaserGame.destroy(true);
-        };
-    });
-
-    // 启动初始场景（仅一次）
-    useEffect(() => {
-        const ctx = gameSignal.value;
-        if (!initialSceneLaunched.current && props.initialScene && ctx?.sceneController) {
-            initialSceneLaunched.current = true;
-            // 使用 microtask 确保所有子组件的场景注册已完成
-            Promise.resolve().then(() => {
-                ctx.sceneController.launch(props.initialScene!);
-            });
-        }
-    }, [gameSignal.value, props.initialScene]);
-
-    return (
-        <div id="phaser-container" className="w-full h-full">
-            <phaserContext.Provider value={gameSignal}>
-                {props.children}
-            </phaserContext.Provider>
-        </div>
-    );
-}
-
-export interface PhaserSceneProps<TData extends Record<string, unknown> = {}> {
-    sceneKey: string;
-    scene: ReactiveScene<TData>;
-    data?: TData;
-    children?: any;
-}
-
-export const phaserSceneContext = createContext<ReadonlySignal<ReactiveScene> | null>(null);
-
-export function PhaserScene<TData extends Record<string, unknown> = {}>(props: PhaserSceneProps<TData>) {
-    const phaserGameSignal = useContext(phaserContext);
-    const sceneSignal = useSignal<ReactiveScene<TData>>();
-    const registered = useRef(false);
-
-    useSignalEffect(() => {
-        if (!phaserGameSignal) return;
-        const ctx = phaserGameSignal.value;
-        if (!ctx?.game) return;
-
-        const game = ctx.game;
-
-        // 注册场景到 Phaser（但不启动）
-        if (!game.scene.getScene(props.sceneKey)) {
-            const initData = {
-                ...props.data,
-                phaserGame: phaserGameSignal,
-                sceneController: ctx.sceneController,
-            };
-            game.scene.add(props.sceneKey, props.scene, false, initData);
         }
 
-        sceneSignal.value = props.scene;
+        // 等待场景注册完成（最多等待 100ms）
-        registered.current = true;
+        let retries = 0;
+        while (!phaserGame.scene.getScene(sceneKey) && retries < 10) {
+          await new Promise((resolve) => setTimeout(resolve, 10));
+          retries++;
+        }
 
-        return () => {
+        // 验证场景是否已注册
-            sceneSignal.value = undefined;
+        if (!phaserGame.scene.getScene(sceneKey)) {
-            registered.current = false;
+          console.error(`SceneController: 场景 "${sceneKey}" 未注册`);
-            // 不在这里移除场景，让 SceneController 管理生命周期
+          return;
-        };
+        }
-    });
 
-    return <phaserSceneContext.Provider value={sceneSignal as ReadonlySignal<ReactiveScene>}>{props.children}</phaserSceneContext.Provider>;
+        isTransitioning.value = true;
+        const fade = phaserGame.scene.getScene(
+          FADE_SCENE_KEY,
+        ) as FadeSceneClass;
+
+        // 淡出到黑色
+        phaserGame.scene.bringToTop(FADE_SCENE_KEY);
+        await fade.fadeOut(300);
+
+        // 停止当前场景
+        if (currentScene.value) {
+          phaserGame.scene.stop(currentScene.value);
+        }
+
+        // 确保场景已注册后再启动
+        // （场景应该已经在 PhaserScene 组件中注册）
+        if (!phaserGame.scene.getScene(sceneKey)) {
+          console.error(`SceneController: 场景 "${sceneKey}" 在切换时仍未注册`);
+          isTransitioning.value = false;
+          return;
+        }
+
+        // 启动新场景
+        phaserGame.scene.start(sceneKey);
+        currentScene.value = sceneKey;
+
+        // 淡入
+        await fade.fadeIn(300);
+        isTransitioning.value = false;
+      },
+      async restart() {
+        if (isTransitioning.value) {
+          console.warn('SceneController: 正在进行场景切换');
+          return;
+        }
+
+        if (!currentScene.value) {
+          console.warn('SceneController: 没有当前场景，无法 restart');
+          return;
+        }
+
+        const sceneKey = currentScene.value;
+        const scene = phaserGame.scene.getScene(sceneKey);
+
+        if (!scene) {
+          console.error(`SceneController: 场景 "${sceneKey}" 不存在`);
+          return;
+        }
+
+        isTransitioning.value = true;
+        const fade = phaserGame.scene.getScene(
+          FADE_SCENE_KEY,
+        ) as FadeSceneClass;
+
+        // 淡出到黑色
+        phaserGame.scene.bringToTop(FADE_SCENE_KEY);
+        await fade.fadeOut(300);
+
+        // 重启当前场景
+        scene.scene.restart();
+
+        // 淡入
+        await fade.fadeIn(300);
+        isTransitioning.value = false;
+      },
+      currentScene,
+      isTransitioning,
+    };
+
+    gameSignal.value = { game: phaserGame, sceneController };
+
+    return () => {
+      gameSignal.value = { game: undefined!, sceneController: undefined! };
+      initialSceneLaunched.current = false;
+      phaserGame.destroy(true);
+    };
+  });
+
+  // 启动初始场景（仅一次）
+  useEffect(() => {
+    const ctx = gameSignal.value;
+    if (
+      !initialSceneLaunched.current &&
+      props.initialScene &&
+      ctx?.sceneController
+    ) {
+      initialSceneLaunched.current = true;
+      // 使用 microtask 确保所有子组件的场景注册已完成
+      Promise.resolve().then(() => {
+        ctx.sceneController.launch(props.initialScene!);
+      });
+    }
+  }, [gameSignal.value, props.initialScene]);
+
+  return (
+    <div id="phaser-container" className="w-full h-full">
+      <phaserContext.Provider value={gameSignal}>
+        {props.children}
+      </phaserContext.Provider>
+    </div>
+  );
+}
+
+export interface PhaserSceneProps<TData = {}> {
+  sceneKey: string;
+  scene: ReactiveScene<TData>;
+  data?: TData;
+  children?: any;
+}
+
+export const phaserSceneContext =
+  createContext<ReadonlySignal<ReactiveScene> | null>(null);
+
+export function PhaserScene<TData = {}>(props: PhaserSceneProps<TData>) {
+  const phaserGameSignal = useContext(phaserContext);
+  const sceneSignal = useSignal<ReactiveScene<TData>>();
+  const registered = useRef(false);
+
+  useSignalEffect(() => {
+    if (!phaserGameSignal) return;
+    const ctx = phaserGameSignal.value;
+    if (!ctx?.game) return;
+
+    const game = ctx.game;
+
+    // 注册场景到 Phaser（但不启动）
+    if (!game.scene.getScene(props.sceneKey)) {
+      const initData = {
+        ...props.data,
+        phaserGame: phaserGameSignal,
+        sceneController: ctx.sceneController,
+      };
+      game.scene.add(props.sceneKey, props.scene, false, initData);
+    }
+
+    sceneSignal.value = props.scene;
+    registered.current = true;
+
+    return () => {
+      sceneSignal.value = undefined;
+      registered.current = false;
+      // 不在这里移除场景，让 SceneController 管理生命周期
+    };
+  });
+
+  return (
+    <phaserSceneContext.Provider
+      value={sceneSignal as ReadonlySignal<ReactiveScene>}
+    >
+      {props.children}
+    </phaserSceneContext.Provider>
+  );
 }

packages/framework/src/ui/index.ts

@@ -1,5 +1,12 @@
-export { GameUI } from './GameUI';
+export { GameUI } from "./GameUI";
-export type { GameUIOptions } from './GameUI';
+export type { GameUIOptions } from "./GameUI";
 
-export { PhaserGame, PhaserScene, phaserContext, defaultPhaserConfig, type PhaserGameContext, type SceneController } from './PhaserBridge';
+export {
-export type { PhaserGameProps, PhaserSceneProps } from './PhaserBridge';
+  PhaserGame,
+  PhaserScene,
+  phaserContext,
+  defaultPhaserConfig,
+  type PhaserGameContext,
+  type SceneController,
+} from "./PhaserBridge";
+export type { PhaserGameProps, PhaserSceneProps } from "./PhaserBridge";

packages/framework/src/utils/disposable.ts

@@ -1,46 +1,42 @@
 export interface IDisposable {
-    dispose(): void;
+  dispose(): void;
 }
 
 export type DisposableItem = IDisposable | (() => void);
 
 export class DisposableBag implements IDisposable {
-    private _disposables = new Set<DisposableItem>();
+  private _disposables = new Set<DisposableItem>();
-    private _isDisposed = false;
+  private _isDisposed = false;
 
-    get isDisposed(): boolean {
+  get isDisposed(): boolean {
-        return this._isDisposed;
+    return this._isDisposed;
+  }
+
+  add(item: DisposableItem): void {
+    if (this._isDisposed) {
+      this._execute(item);
+      return;
+    }
+    this._disposables.add(item);
+  }
+
+  dispose(): void {
+    if (this._isDisposed) return;
+
+    this._isDisposed = true;
+
+    for (const item of this._disposables) {
+      this._execute(item);
     }
 
-    add(item: DisposableItem): void {
+    this._disposables.clear();
-        if (this._isDisposed) {
+  }
-            this._execute(item);
+
-            return;
+  private _execute(item: DisposableItem): void {
-        }
+    if (typeof item === "function") {
-        this._disposables.add(item);
+      item();
-    }
+    } else {
-
+      item.dispose();
-    dispose(): void {
-        if (this._isDisposed) return;
-
-        this._isDisposed = true;
-
-        for (const item of this._disposables) {
-            try {
-                this._execute(item);
-            } catch (error) {
-                console.error('Error during resource disposal:', error);
-            }
-        }
-
-        this._disposables.clear();
-    }
-
-    private _execute(item: DisposableItem): void {
-        if (typeof item === 'function') {
-            item();
-        } else {
-            item.dispose();
-        }
     }
+  }
 }

packages/framework/src/utils/dnd.ts

@@ -1,4 +1,4 @@
-import { DisposableBag } from "./disposable";
+import type { DisposableBag } from "./disposable";
 
 type PointerRecord = {
   id: number;

packages/framework/src/utils/index.ts

@@ -1,3 +1,7 @@
-export { DisposableBag } from './disposable';
+export { DisposableBag } from "./disposable";
-export type { IDisposable, DisposableItem } from './disposable';
+export type { IDisposable, DisposableItem } from "./disposable";
-export { dragDropEventEffect, DragDropEventType, type DragDropEvent } from './dnd';
+export {
+  dragDropEventEffect,
+  DragDropEventType,
+  type DragDropEvent,
+} from "./dnd";