界面迁移更新

2026-09-05 00:12:11 +08:00
parent e2762d631d
commit 0aa66e1ec7
3187 changed files with 667915 additions and 211 deletions
@@ -0,0 +1,116 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveBootstrap } from '../../YouleNexus/assets/framework/config/bootstrap.ts';
+import { BUILD_IDENTITY } from '../../YouleNexus/assets/framework/config/sources/defaults.ts';
+import type { ConfigFetcher, RemoteConfig } from '../../YouleNexus/assets/framework/config/remote-config.ts';
+import { PROFILES } from '../../YouleNexus/assets/framework/config/profiles.ts';
+
+function fetcherReturning(config: RemoteConfig): ConfigFetcher & { calls: string[] } {
+  const calls: string[] = [];
+  return { calls, fetch: async (url: string) => { calls.push(url); return config; } };
+}
+const throwingFetcher: ConfigFetcher = {
+  fetch: async () => { throw new Error('net down'); },
+};
+
+const REMOTE: RemoteConfig = { data: { player_server_tcp: '5.5.5.5:5000' } };
+
+test('debug + profile=local：用 profile.server 直连，不抓远程', async () => {
+  const fetcher = fetcherReturning(REMOTE);
+  const r = await resolveBootstrap({ mode: 'debug', win: {}, search: '?profile=local', fetcher, isNative: false });
+  assert.deepEqual(r.servers, ['ws://127.0.0.1:3088']);
+  assert.equal(r.rawConfig, null);
+  assert.equal(fetcher.calls.length, 0);
+});
+
+test('debug + prod + H5：抓远程配置产出 servers，identity 来自 defaults', async () => {
+  const fetcher = fetcherReturning(REMOTE);
+  const r = await resolveBootstrap({ mode: 'debug', win: {}, search: '', fetcher, isNative: false });
+  assert.deepEqual(r.servers, ['ws://5.5.5.5:5000']);
+  assert.equal(r.identity.agentid, BUILD_IDENTITY.agentid);
+  assert.equal(r.identity.gameid, BUILD_IDENTITY.gameid);
+  assert.equal(fetcher.calls.length, 1);
+});
+
+test('debug + H5 显式 URL query 覆盖身份（最高优先级）', async () => {
+  const fetcher = fetcherReturning(REMOTE);
+  const r = await resolveBootstrap({ mode: 'debug', win: {}, search: '?agentid=999&channelid=C9', fetcher, isNative: false });
+  assert.equal(r.identity.agentid, '999');
+  assert.equal(r.identity.channelid, 'C9');
+});
+
+test('debug + 原生模式：identity 来自 window.settings', async () => {
+  const fetcher = fetcherReturning(REMOTE);
+  const win = { settings: { getothername: () => 'NA', getchannelName: () => 'NC', getmarketname: () => 3 } };
+  const r = await resolveBootstrap({ mode: 'debug', win, search: '', fetcher, isNative: true });
+  assert.equal(r.identity.agentid, 'NA');
+  assert.equal(r.identity.channelid, 'NC');
+  assert.equal(r.identity.marketid, 3);
+});
+
+test('远程抓取失败 → 抛 ConfigFetchError（不兜底）', async () => {
+  await assert.rejects(
+    resolveBootstrap({ mode: 'debug', win: {}, search: '', fetcher: throwingFetcher, isNative: false }),
+    /远程配置抓取失败/,
+  );
+});
+
+test('远程配置未给出可用服务器地址 → 抛错（不兜底）', async () => {
+  const emptyFetcher: ConfigFetcher = { fetch: async () => ({ data: {} }) };
+  await assert.rejects(
+    resolveBootstrap({ mode: 'debug', win: {}, search: '', fetcher: emptyFetcher, isNative: false }),
+    /未给出可用服务器/,
+  );
+});
+
+test('debug 结果含 mode/isDebugger', async () => {
+  const fetcher = fetcherReturning(REMOTE);
+  const r = await resolveBootstrap({ mode: 'debug', win: {}, search: '', fetcher, isNative: false });
+  assert.equal(r.mode, 'debug');
+  assert.equal(r.isDebugger, true);
+});
+
+test('release：忽略所有 URL 覆盖，强制 prod，identity 不被 URL 改', async () => {
+  const fetcher = fetcherReturning(REMOTE);
+  const r = await resolveBootstrap({ mode: 'release', win: {}, search: '?profile=local&agentid=999', fetcher, isNative: false });
+  assert.equal(r.profile.name, 'prod');
+  assert.deepEqual(r.servers, ['ws://5.5.5.5:5000']); // 走远程，不是 local 直连
+  assert.equal(r.identity.agentid, BUILD_IDENTITY.agentid); // 999 无效
+  assert.equal(r.isDebugger, false);
+  assert.equal(r.mode, 'release');
+  assert.equal(fetcher.calls.length, 1);
+});
+
+test('release：原生身份仍生效（URL 的 999 无效）', async () => {
+  const fetcher = fetcherReturning(REMOTE);
+  const win = { settings: { getothername: () => 'NA', getchannelName: () => 'NC', getmarketname: () => 3 } };
+  const r = await resolveBootstrap({ mode: 'release', win, search: '?agentid=999', fetcher, isNative: true });
+  assert.equal(r.identity.agentid, 'NA');
+  assert.equal(r.identity.channelid, 'NC');
+});
+
+test('debug + serverOverride：走远程全链路但连接地址覆盖为本地', async () => {
+  const fetcher = fetcherReturning(REMOTE);   // REMOTE.player_server_tcp = 5.5.5.5:5000
+  const r = await resolveBootstrap({ mode: 'debug', win: {}, search: '?profile=staging', fetcher, isNative: false });
+  assert.deepEqual(r.servers, [PROFILES.staging.serverOverride]); // 覆盖为 profile.serverOverride
+  assert.ok(r.rawConfig);                      // 远程配置仍抓取（全链路）
+  assert.equal(fetcher.calls.length, 1);
+});
+
+test('release：serverOverride 不生效（强制 prod，用远程解析地址）', async () => {
+  const fetcher = fetcherReturning(REMOTE);
+  const r = await resolveBootstrap({ mode: 'release', win: {}, search: '?profile=staging', fetcher, isNative: true });
+  assert.deepEqual(r.servers, ['ws://5.5.5.5:5000']); // prod 无 override，用远程解析
+});
+
+test('debug：account 来自当前 profile', async () => {
+  const fetcher = fetcherReturning(REMOTE);
+  const r = await resolveBootstrap({ mode: 'debug', win: {}, search: '?profile=staging', fetcher, isNative: false });
+  assert.deepEqual(r.account, PROFILES.staging.account);
+});
+
+test('release：account 恒为 undefined（不从调试配置泄漏账号）', async () => {
+  const fetcher = fetcherReturning(REMOTE);
+  const r = await resolveBootstrap({ mode: 'release', win: {}, search: '?profile=staging', fetcher, isNative: true });
+  assert.equal(r.account, undefined);
+});
@@ -0,0 +1,38 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveIdentity } from '../../YouleNexus/assets/framework/config/identity.ts';
+import { BUILD_IDENTITY } from '../../YouleNexus/assets/framework/config/sources/defaults.ts';
+
+test('BUILD_IDENTITY 含全部字段且 gameid 为固定 token', () => {
+  assert.ok(BUILD_IDENTITY.gameid.length > 0);
+  assert.ok('agentid' in BUILD_IDENTITY);
+  assert.ok('channelid' in BUILD_IDENTITY);
+  assert.ok('marketid' in BUILD_IDENTITY);
+  assert.equal(typeof BUILD_IDENTITY.version, 'number'); // 协议 version = 数字 versionCode
+});
+
+test('resolveIdentity：后面的 source 覆盖前面的', () => {
+  const id = resolveIdentity([
+    () => BUILD_IDENTITY,
+    () => ({ agentid: 'A2' }),
+    () => ({ agentid: 'A3', channelid: 'C3' }),
+  ]);
+  assert.equal(id.agentid, 'A3');
+  assert.equal(id.channelid, 'C3');
+  assert.equal(id.gameid, BUILD_IDENTITY.gameid); // 未被覆盖
+});
+
+test('resolveIdentity：undefined / null / 空串 不覆盖', () => {
+  const id = resolveIdentity([
+    () => BUILD_IDENTITY,
+    () => ({ agentid: undefined as any, channelid: '' , marketid: null as any }),
+  ]);
+  assert.equal(id.agentid, BUILD_IDENTITY.agentid);
+  assert.equal(id.channelid, BUILD_IDENTITY.channelid);
+  assert.equal(id.marketid, BUILD_IDENTITY.marketid);
+});
+
+test('resolveIdentity：marketid=0 是有效值，应覆盖', () => {
+  const id = resolveIdentity([() => BUILD_IDENTITY, () => ({ marketid: 0 })]);
+  assert.equal(id.marketid, 0);
+});
@@ -0,0 +1,27 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveActiveProfile, PROFILES, ACTIVE_PROFILE } from '../../YouleNexus/assets/framework/config/profiles.ts';
+
+test('默认返回 ACTIVE_PROFILE', () => {
+  const p = resolveActiveProfile('');
+  assert.equal(p.name, ACTIVE_PROFILE);
+});
+
+test('prod profile 无调试覆盖、isDebugger=false', () => {
+  const prod = PROFILES['prod'];
+  assert.equal(prod.isDebugger, false);
+  assert.equal(prod.server, undefined);
+  assert.equal(prod.identity, undefined);
+  assert.ok(prod.gameserver && prod.gameserver.length > 0);
+});
+
+test('?profile=local 切到 local，含调试服地址', () => {
+  const p = resolveActiveProfile('?profile=local');
+  assert.equal(p.name, 'local');
+  assert.ok(p.server && p.server.startsWith('ws://'));
+});
+
+test('未知 profile 回退到 ACTIVE_PROFILE', () => {
+  const p = resolveActiveProfile('?profile=nope');
+  assert.equal(p.name, ACTIVE_PROFILE);
+});
@@ -0,0 +1,57 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { getParam, resolveServers, type RemoteConfig } from '../../YouleNexus/assets/framework/config/remote-config.ts';
+import type { ChannelIdentity } from '../../YouleNexus/assets/framework/config/identity.ts';
+
+const ID: ChannelIdentity = { agentid: 'A', channelid: 'C', gameid: 'G', marketid: 2, version: 1 };
+
+const CONFIG: RemoteConfig = {
+  data: {
+    player_server_tcp: '1.1.1.1:1000',       // 顶层默认
+    agentlist: [{
+      agentid: 'A',
+      player_server_tcp: '2.2.2.2:2000',     // agent 级覆盖
+      gamelist: [{
+        gameid: 'G',
+        channellist: [{
+          channelid: 'C',
+          player_server_tcp: '3.3.3.3:3000', // channel 级覆盖（最具体）
+          visitor_server_tcp: '4.4.4.4:4000',
+          marketlist: [{ marketid: 2 }],
+        }],
+      }],
+    }],
+  },
+};
+
+test('getParam：最具体层级胜出', () => {
+  assert.equal(getParam(CONFIG, 'player_server_tcp', ID), '3.3.3.3:3000');
+});
+
+test('getParam：channel 未匹配时回退到 agent 级值', () => {
+  const id2 = { ...ID, channelid: 'OTHER' };
+  assert.equal(getParam(CONFIG, 'player_server_tcp', id2), '2.2.2.2:2000');
+});
+
+test('getParam：agent 未匹配时回退到顶层默认', () => {
+  const id3 = { ...ID, agentid: 'NONE' };
+  assert.equal(getParam(CONFIG, 'player_server_tcp', id3), '1.1.1.1:1000');
+});
+
+test('getParam：键不存在 → null', () => {
+  assert.equal(getParam(CONFIG, 'not_a_key', ID), null);
+});
+
+test('getParam：无 data → null', () => {
+  assert.equal(getParam({}, 'player_server_tcp', ID), null);
+});
+
+test('resolveServers：player 优先、visitor 回退，前缀 ws://', () => {
+  assert.deepEqual(resolveServers(CONFIG, ID), ['ws://3.3.3.3:3000', 'ws://4.4.4.4:4000']);
+});
+
+test('resolveServers：已带 ws:// 不重复前缀；无地址 → 空数组', () => {
+  const cfg: RemoteConfig = { data: { player_server_tcp: 'ws://9.9.9.9:9' } };
+  assert.deepEqual(resolveServers(cfg, ID), ['ws://9.9.9.9:9']);
+  assert.deepEqual(resolveServers({ data: {} }, ID), []);
+});
@@ -0,0 +1,16 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveRuntimeMode } from '../../YouleNexus/assets/framework/config/runtime-mode.ts';
+
+test('override 优先于构建类型', () => {
+  assert.equal(resolveRuntimeMode(true, 'release'), 'release');
+  assert.equal(resolveRuntimeMode(false, 'debug'), 'debug');
+});
+
+test('无 override：debug 构建 → debug', () => {
+  assert.equal(resolveRuntimeMode(true, null), 'debug');
+});
+
+test('无 override：release 构建 → release', () => {
+  assert.equal(resolveRuntimeMode(false, null), 'release');
+});
@@ -0,0 +1,29 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { nativeSettingsSource } from '../../../YouleNexus/assets/framework/config/sources/native-settings.ts';
+
+test('优先从 window.settings 读取 agentid/channelid/marketid', () => {
+  const win = {
+    settings: {
+      getothername: (name: string) => (name === 'agent' ? 'NA' : ''),
+      getchannelName: () => 'NC',
+      getmarketname: () => 7,
+    },
+  };
+  assert.deepEqual(nativeSettingsSource(win)(), { agentid: 'NA', channelid: 'NC', marketid: 7 });
+});
+
+test('settings 抛错时回退到全局 app_agent / app_market', () => {
+  const win: any = {
+    settings: { getothername: () => { throw new Error('no bridge'); },
+                getchannelName: () => { throw new Error('no bridge'); },
+                getmarketname: () => { throw new Error('no bridge'); } },
+    app_agent: 'GA',
+    app_market: 5,
+  };
+  assert.deepEqual(nativeSettingsSource(win)(), { agentid: 'GA', marketid: 5 });
+});
+
+test('完全无原生注入 → 空对象', () => {
+  assert.deepEqual(nativeSettingsSource({})(), {});
+});
@@ -0,0 +1,21 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { queryStringSource } from '../../../YouleNexus/assets/framework/config/sources/query-string.ts';
+
+test('解析 agentid/channelid/marketid/version', () => {
+  const src = queryStringSource('?agentid=A1&channelid=C1&marketid=2&version=10001');
+  assert.deepEqual(src(), { agentid: 'A1', channelid: 'C1', marketid: '2', version: 10001 }); // version 解析为数字
+});
+
+test('缺省键不出现在结果里', () => {
+  const src = queryStringSource('?agentid=A1');
+  assert.deepEqual(src(), { agentid: 'A1' });
+});
+
+test('空 query → 空对象', () => {
+  assert.deepEqual(queryStringSource('')(), {});
+});
+
+test('不含前导 ? 也能解析', () => {
+  assert.deepEqual(queryStringSource('agentid=A1')(), { agentid: 'A1' });
+});
@@ -0,0 +1,14 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { APP, Route, RECV_TIMEOUT_MS, RECONNECT_INTERVAL_MS, LOGIN_GUARD_MS, SERVER_ROTATE_EVERY } from '../../YouleNexus/assets/framework/core/constants.ts';
+
+test('框架常量与 docs/protocol 对齐', () => {
+  assert.equal(APP, 'youle');
+  assert.equal(Route.agent, 'agent');
+  assert.equal(Route.room, 'room');
+  assert.equal(Route.platform, 'platform');
+  assert.equal(RECV_TIMEOUT_MS, 30000);
+  assert.equal(RECONNECT_INTERVAL_MS, 10000);
+  assert.equal(LOGIN_GUARD_MS, 4000);
+  assert.equal(SERVER_ROTATE_EVERY, 3);
+});
@@ -0,0 +1,40 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { EventBus } from '../../YouleNexus/assets/framework/core/events.ts';
+
+test('on/emit 传递参数', () => {
+  const bus = new EventBus<{ hi: [number, string] }>();
+  let got: [number, string] | null = null;
+  bus.on('hi', (n, s) => { got = [n, s]; });
+  bus.emit('hi', 7, 'x');
+  assert.deepEqual(got, [7, 'x']);
+});
+
+test('off 取消订阅', () => {
+  const bus = new EventBus<{ ping: [] }>();
+  let count = 0;
+  const fn = () => { count++; };
+  bus.on('ping', fn);
+  bus.emit('ping');
+  bus.off('ping', fn);
+  bus.emit('ping');
+  assert.equal(count, 1);
+});
+
+test('once 只触发一次', () => {
+  const bus = new EventBus<{ ping: [] }>();
+  let count = 0;
+  bus.once('ping', () => { count++; });
+  bus.emit('ping');
+  bus.emit('ping');
+  assert.equal(count, 1);
+});
+
+test('一个事件订阅者抛错不影响其它订阅者', () => {
+  const bus = new EventBus<{ ping: [] }>();
+  let reached = false;
+  bus.on('ping', () => { throw new Error('boom'); });
+  bus.on('ping', () => { reached = true; });
+  bus.emit('ping');
+  assert.equal(reached, true);
+});
@@ -0,0 +1,21 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { toView, fromView } from '../../YouleNexus/assets/framework/core/seat.ts';
+
+test('toView：自己永远是视图 0 号位', () => {
+  assert.equal(toView(2, 2, 4), 0); // mySeat=2, target=2 → 0
+});
+
+test('toView：他人按环形相对自己排布', () => {
+  // 4 人桌，我在 2 号位：座位 3→视图1，座位 0→视图2，座位 1→视图3
+  assert.equal(toView(2, 3, 4), 1);
+  assert.equal(toView(2, 0, 4), 2);
+  assert.equal(toView(2, 1, 4), 3);
+});
+
+test('fromView 是 toView 的逆运算', () => {
+  const seatCount = 4, mySeat = 2;
+  for (let s = 0; s < seatCount; s++) {
+    assert.equal(fromView(mySeat, toView(mySeat, s, seatCount), seatCount), s);
+  }
+});
@@ -0,0 +1,9 @@
+import type { OutboundEnvelope, InboundMessage } from '../../YouleNexus/assets/framework/core/types/envelope.ts';
+import type { LoginRequestData, LoginResponseData } from '../../YouleNexus/assets/framework/core/types/login.ts';
+
+const out: OutboundEnvelope<LoginRequestData> = {
+  app: 'youle', route: 'agent', rpc: 'player_login',
+  data: { agentid: 1, gameid: 2, openid: 'o', nickname: 'n', avatar: 'a', sex: 0, province: '', city: '', unionid: 'u', version: 1, channelid: 0, marketid: 0 },
+};
+const inb: InboundMessage<LoginResponseData> = { route: 'agent', rpc: 'player_login', data: { state: 0, playerid: 9 } };
+void out; void inb;
@@ -0,0 +1,27 @@
+import type { Transport } from '../../YouleNexus/assets/framework/net/transport.ts';
+
+/** 内存 Transport：模拟服务器。用 microtask 队列异步触发回调，贴近真实 WS 时序。 */
+export class FakeTransport implements Transport {
+  sent: string[] = [];
+  url = '';
+  private openCb?: () => void;
+  private msgCb?: (f: string) => void;
+  private closeCb?: () => void;
+  private pending: Array<() => void> = [];
+  private closed = false;
+
+  connect(url: string): void { this.url = url; this.pending.push(() => this.openCb?.()); }
+  send(frame: string): void { if (!this.closed) this.sent.push(frame); }
+  close(): void { if (this.closed) return; this.closed = true; this.pending.push(() => this.closeCb?.()); }
+  onOpen(cb: () => void): void { this.openCb = cb; }
+  onMessage(cb: (f: string) => void): void { this.msgCb = cb; }
+  onClose(cb: () => void): void { this.closeCb = cb; }
+
+  /** 测试侧：模拟服务器推一帧给客户端。 */
+  serverPush(frame: string): void { if (!this.closed) this.pending.push(() => this.msgCb?.(frame)); }
+
+  /** 冲刷所有挂起回调（解析微任务）。 */
+  async flush(): Promise<void> {
+    while (this.pending.length) { const fn = this.pending.shift()!; fn(); await Promise.resolve(); }
+  }
+}
@@ -0,0 +1,57 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { NetClient } from '../../YouleNexus/assets/framework/net/net-client.ts';
+import { FakeTransport } from '../helpers/fake-transport.ts';
+import { parseLoginResponse } from '../../YouleNexus/assets/framework/protocol/login.ts';
+import type { Clock } from '../../YouleNexus/assets/framework/net/heartbeat.ts';
+
+const realishClock: Clock = { setTimeout: (fn, ms) => setTimeout(fn, ms), clearTimeout: (h: any) => clearTimeout(h) };
+const IDENTITY = { agentid: 1, gameid: 2, openid: 'o', nickname: 'n', avatar: 'a', sex: 0, province: '', city: '', unionid: 'u', version: 1, channelid: 0, marketid: 0 };
+
+test('login 全流程：握手→登录→业务包，且 parseLoginResponse 识别房间恢复', async () => {
+  const t = new FakeTransport();
+  const client = new NetClient({ servers: 'ws://srv', transportFactory: () => t, clock: realishClock });
+  client.setIdentity(IDENTITY);
+
+  let loginData: any = null;
+  const business: any[] = [];
+  client.on('login', (d: any) => { loginData = d; });
+  client.on('message', (m: any) => business.push(m));
+
+  client.start();
+  await t.flush();
+
+  // 服务器先发握手包（原始串，应被忽略）
+  t.serverPush('@toconconHELLO');
+  await t.flush();
+
+  // 客户端应已发出 player_login
+  assert.equal(JSON.parse(t.sent[0]).rpc, 'player_login');
+
+  // 服务器回 login 响应（单层，带房间恢复 + 对局）
+  t.serverPush(JSON.stringify({
+    route: 'agent', rpc: 'player_login',
+    data: { state: 0, playerid: 42, bean: 500, roomcode: 'ROOM1', isbattle: 1, deskinfo: { round: 3 } },
+  }));
+  await t.flush();
+
+  assert.ok(loginData);
+  const parsed = parseLoginResponse(loginData);
+  assert.equal(parsed.ok, true);
+  assert.equal(parsed.playerid, 42);
+  assert.equal(parsed.inRoom, true);
+  assert.equal(parsed.hasBattle, true);
+  assert.deepEqual(parsed.deskinfo, { round: 3 });
+
+  // 心跳包（单层，忽略，不进 business）
+  t.serverPush(JSON.stringify({ com: '@serverheartbeat' }));
+  // 正常业务推送（单层，门控已清，放行）
+  t.serverPush(JSON.stringify({ route: 'room', rpc: 'other_join_room', data: { seat: 2 } }));
+  await t.flush();
+
+  assert.equal(business.length, 1);
+  assert.equal(business[0].rpc, 'other_join_room');
+  assert.equal(business[0].data.seat, 2);
+
+  client.stop();
+});
@@ -0,0 +1,95 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { computeLpos, computeContentSize, computeWidgetAlignment } from '../../scripts/legacy-layer-to-cocos-prefab.mjs';
+
+test('computeLpos 锚点转换（实测验证：渠道logo）', () => {
+  const spirit = { x: '734', y: '143', w: '59', h: '148' };
+  const lpos = computeLpos(spirit);
+  // x = 734 + 59/2 - 640 = 123.5
+  // y = 360 - (143 + 148/2) = 143
+  assert.equal(lpos.x, 123.5);
+  assert.equal(lpos.y, 143);
+  assert.equal(lpos.z, 0);
+});
+
+test('computeLpos 锚点转换（实测验证：游客登录）', () => {
+  const spirit = { x: '540', y: '388', w: '320', h: '95' };
+  const lpos = computeLpos(spirit);
+  // x = 540 + 160 - 640 = 60
+  // y = 360 - (388 + 47.5) = -75.5
+  assert.equal(lpos.x, 60);
+  assert.equal(lpos.y, -75.5);
+});
+
+test('computeLpos 字符串转数字（X/Y 为字符串 "0"/"-100"）', () => {
+  const spirit = { x: '0', y: '-100', w: '100', h: '100' };
+  const lpos = computeLpos(spirit);
+  // x = 0 + 50 - 640 = -590
+  // y = 360 - (-100 + 50) = 410
+  assert.equal(lpos.x, -590);
+  assert.equal(lpos.y, 410);
+});
+
+test('computeContentSize 直接读 Width/Height（SizeCalcMode=0 路径）', () => {
+  const spirit = { w: '320', h: '95', sizeCalcMode: '0' };
+  const size = computeContentSize(spirit);
+  assert.equal(size.width, 320);
+  assert.equal(size.height, 95);
+});
+
+test('computeContentSize 默认 SizeCalcMode=0（字段缺失视作 0）', () => {
+  const spirit = { w: '100', h: '50' }; // no sizeCalcMode
+  const size = computeContentSize(spirit);
+  assert.equal(size.width, 100);
+  assert.equal(size.height, 50);
+});
+
+test('computeContentSize SizeCalcMode=1 → throw（不静默）', () => {
+  const spirit = { w: '100', h: '50', sizeCalcMode: '1' };
+  assert.throws(() => computeContentSize(spirit), /SizeCalcMode=1.*reverse gameabc\.min\.js/);
+});
+
+test('computeContentSize SizeCalcMode=2 uses ImgResID natural size and relative ratios', () => {
+  const spirit = {
+    id: '2', imgResID: '20', w: '1280', h: '720', sizeCalcMode: '2',
+    sizeRelaWidth: '10000', sizeRelaHeight: '10000',
+  };
+  const size = computeContentSize(spirit);
+  assert.equal(size.width, 1280);
+  assert.equal(size.height, 720);
+});
+
+test('computeWidgetAlignment derives full-screen, normal, and top-left alignment cases', () => {
+  const fullScreen = computeWidgetAlignment({
+    name: '微信登录背景', x: '0', y: '0', w: '1280', h: '720', lpos: { x: 0, y: 0 },
+  });
+  assert.equal(fullScreen._alignFlags, 45);
+  assert.equal(fullScreen._left, 0);
+  assert.equal(fullScreen._right, 0);
+  assert.equal(fullScreen._top, 0);
+  assert.equal(fullScreen._bottom, 0);
+  assert.equal(fullScreen._horizontalCenter, undefined);
+  assert.equal(fullScreen._verticalCenter, undefined);
+  assert.equal(fullScreen._originalWidth, 100);
+  assert.equal(fullScreen._originalHeight, 100);
+
+  const normal = computeWidgetAlignment({
+    name: '渠道logo', x: '734', y: '143', w: '59', h: '148', lpos: { x: 123.5, y: 0 },
+  });
+  assert.equal(normal._alignFlags, 16);
+  assert.equal(normal._horizontalCenter, 123.5);
+  assert.equal(normal._verticalCenter, 0);
+  assert.equal(normal._left, undefined);
+  assert.equal(normal._right, undefined);
+  assert.equal(normal._top, undefined);
+  assert.equal(normal._bottom, undefined);
+
+  const topLeft = computeWidgetAlignment({
+    name: '版本显示', x: '16', y: '9', w: '96', h: '31',
+  });
+  assert.equal(topLeft._alignFlags, 9);
+  assert.equal(topLeft._left, -576);
+  assert.equal(topLeft._top, 335.5);
+  assert.equal(topLeft._horizontalCenter, undefined);
+  assert.equal(topLeft._verticalCenter, undefined);
+});
@@ -0,0 +1,908 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Layer Version="2.6" SaveTime="2019-01-04 17:51:20">
+  <PropertyList>
+    <Property Name="ID" Value="2"/>
+    <Property Name="Name" Value="Login_Layer"/>
+    <Property Name="Description" Value=""/>
+  </PropertyList>
+  <OptionList/>
+  <EventList/>
+  <SpiritList>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="0"/>
+        <Property Name="ID" Value="2"/>
+        <Property Name="Name" Value="微信登录背景"/>
+        <Property Name="ImgResID" Value="20"/>
+        <Property Name="X" Value="0"/>
+        <Property Name="Y" Value="0"/>
+        <Property Name="Width" Value="1280"/>
+        <Property Name="Height" Value="720"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="1"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="0"/>
+        <Property Name="CoordRelaY" Value="0"/>
+        <Property Name="SizeCalcMode" Value="2"/>
+        <Property Name="SizeParentID" Value="20"/>
+        <Property Name="WidthCalcMode" Value="1"/>
+        <Property Name="SizeRelaWidth" Value="10000"/>
+        <Property Name="HeightCalcMode" Value="1"/>
+        <Property Name="SizeRelaHeight" Value="10000"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value="2"/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="0"/>
+        <Property Name="ID" Value="405"/>
+        <Property Name="Name" Value="Spirit405"/>
+        <Property Name="ImgResID" Value="5"/>
+        <Property Name="X" Value="734"/>
+        <Property Name="Y" Value="143"/>
+        <Property Name="Width" Value="59"/>
+        <Property Name="Height" Value="148"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="2"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="734"/>
+        <Property Name="CoordRelaY" Value="143"/>
+        <Property Name="SizeCalcMode" Value="0"/>
+        <Property Name="SizeParentID" Value="0"/>
+        <Property Name="WidthCalcMode" Value="0"/>
+        <Property Name="SizeRelaWidth" Value="59"/>
+        <Property Name="HeightCalcMode" Value="0"/>
+        <Property Name="SizeRelaHeight" Value="148"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value="405"/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="1"/>
+        <Property Name="ID" Value="285"/>
+        <Property Name="Name" Value="版本显示"/>
+        <Property Name="FontSize" Value="18"/>
+        <Property Name="FontBold" Value="0"/>
+        <Property Name="FontColor" Value="16777215"/>
+        <Property Name="FontColorA" Value="255"/>
+        <Property Name="BackColor" Value="16777215"/>
+        <Property Name="BackColorA" Value="0"/>
+        <Property Name="AutoSize" Value="1"/>
+        <Property Name="TextStyle" Value="0"/>
+        <Property Name="WordWrap" Value="0"/>
+        <Property Name="LineSpace" Value="0"/>
+        <Property Name="AlignHorz" Value="0"/>
+        <Property Name="AlignVert" Value="0"/>
+        <Property Name="Text" Value="版本显示"/>
+        <Property Name="X" Value="16"/>
+        <Property Name="Y" Value="9"/>
+        <Property Name="Width" Value="96"/>
+        <Property Name="Height" Value="31"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="3"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="16"/>
+        <Property Name="CoordRelaY" Value="9"/>
+        <Property Name="SizeCalcMode" Value="0"/>
+        <Property Name="SizeParentID" Value="0"/>
+        <Property Name="WidthCalcMode" Value="0"/>
+        <Property Name="SizeRelaWidth" Value="96"/>
+        <Property Name="HeightCalcMode" Value="0"/>
+        <Property Name="SizeRelaHeight" Value="31"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value="285"/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="0"/>
+        <Property Name="ID" Value="248"/>
+        <Property Name="Name" Value="协议确认"/>
+        <Property Name="ImgResID" Value="93"/>
+        <Property Name="X" Value="479"/>
+        <Property Name="Y" Value="542"/>
+        <Property Name="Width" Value="52"/>
+        <Property Name="Height" Value="51"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="4"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="479"/>
+        <Property Name="CoordRelaY" Value="542"/>
+        <Property Name="SizeCalcMode" Value="2"/>
+        <Property Name="SizeParentID" Value="93"/>
+        <Property Name="WidthCalcMode" Value="1"/>
+        <Property Name="SizeRelaWidth" Value="10000"/>
+        <Property Name="HeightCalcMode" Value="1"/>
+        <Property Name="SizeRelaHeight" Value="10000"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value=""/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="0"/>
+        <Property Name="ID" Value="249"/>
+        <Property Name="Name" Value="协议内容"/>
+        <Property Name="ImgResID" Value="94"/>
+        <Property Name="X" Value="565"/>
+        <Property Name="Y" Value="556"/>
+        <Property Name="Width" Value="220"/>
+        <Property Name="Height" Value="29"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="5"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="565"/>
+        <Property Name="CoordRelaY" Value="556"/>
+        <Property Name="SizeCalcMode" Value="2"/>
+        <Property Name="SizeParentID" Value="94"/>
+        <Property Name="WidthCalcMode" Value="1"/>
+        <Property Name="SizeRelaWidth" Value="10000"/>
+        <Property Name="HeightCalcMode" Value="1"/>
+        <Property Name="SizeRelaHeight" Value="10000"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value=""/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="0"/>
+        <Property Name="ID" Value="481"/>
+        <Property Name="Name" Value="Spirit481"/>
+        <Property Name="ImgResID" Value="10"/>
+        <Property Name="X" Value="1160"/>
+        <Property Name="Y" Value="0"/>
+        <Property Name="Width" Value="120"/>
+        <Property Name="Height" Value="120"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="6"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="1160"/>
+        <Property Name="CoordRelaY" Value="0"/>
+        <Property Name="SizeCalcMode" Value="0"/>
+        <Property Name="SizeParentID" Value="0"/>
+        <Property Name="WidthCalcMode" Value="0"/>
+        <Property Name="SizeRelaWidth" Value="120"/>
+        <Property Name="HeightCalcMode" Value="0"/>
+        <Property Name="SizeRelaHeight" Value="120"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value=""/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="0"/>
+        <Property Name="ID" Value="482"/>
+        <Property Name="Name" Value="Spirit482"/>
+        <Property Name="ImgResID" Value="10"/>
+        <Property Name="X" Value="0"/>
+        <Property Name="Y" Value="600"/>
+        <Property Name="Width" Value="120"/>
+        <Property Name="Height" Value="120"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="7"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="0"/>
+        <Property Name="CoordRelaY" Value="600"/>
+        <Property Name="SizeCalcMode" Value="0"/>
+        <Property Name="SizeParentID" Value="0"/>
+        <Property Name="WidthCalcMode" Value="0"/>
+        <Property Name="SizeRelaWidth" Value="120"/>
+        <Property Name="HeightCalcMode" Value="0"/>
+        <Property Name="SizeRelaHeight" Value="120"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value=""/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="0"/>
+        <Property Name="ID" Value="177"/>
+        <Property Name="Name" Value="Spirit177"/>
+        <Property Name="ImgResID" Value="177"/>
+        <Property Name="X" Value="540"/>
+        <Property Name="Y" Value="388"/>
+        <Property Name="Width" Value="320"/>
+        <Property Name="Height" Value="95"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="8"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="540"/>
+        <Property Name="CoordRelaY" Value="388"/>
+        <Property Name="SizeCalcMode" Value="2"/>
+        <Property Name="SizeParentID" Value="177"/>
+        <Property Name="WidthCalcMode" Value="1"/>
+        <Property Name="SizeRelaWidth" Value="10000"/>
+        <Property Name="HeightCalcMode" Value="1"/>
+        <Property Name="SizeRelaHeight" Value="10000"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value=""/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="0"/>
+        <Property Name="ID" Value="3"/>
+        <Property Name="Name" Value="微信登录"/>
+        <Property Name="ImgResID" Value="22"/>
+        <Property Name="X" Value="258"/>
+        <Property Name="Y" Value="384"/>
+        <Property Name="Width" Value="400"/>
+        <Property Name="Height" Value="116"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="9"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="258"/>
+        <Property Name="CoordRelaY" Value="384"/>
+        <Property Name="SizeCalcMode" Value="2"/>
+        <Property Name="SizeParentID" Value="22"/>
+        <Property Name="WidthCalcMode" Value="1"/>
+        <Property Name="SizeRelaWidth" Value="10000"/>
+        <Property Name="HeightCalcMode" Value="1"/>
+        <Property Name="SizeRelaHeight" Value="10000"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value="3"/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="3"/>
+        <Property Name="ID" Value="3254"/>
+        <Property Name="Name" Value="Spirit3254"/>
+        <Property Name="Frame" Value="1"/>
+        <Property Name="ImgResID" Value="427"/>
+        <Property Name="X" Value="342"/>
+        <Property Name="Y" Value="393"/>
+        <Property Name="Width" Value="301"/>
+        <Property Name="Height" Value="97"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="10"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="342"/>
+        <Property Name="CoordRelaY" Value="393"/>
+        <Property Name="SizeCalcMode" Value="2"/>
+        <Property Name="SizeParentID" Value="427"/>
+        <Property Name="WidthCalcMode" Value="1"/>
+        <Property Name="SizeRelaWidth" Value="10000"/>
+        <Property Name="HeightCalcMode" Value="1"/>
+        <Property Name="SizeRelaHeight" Value="10000"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value=""/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="3"/>
+        <Property Name="ID" Value="3255"/>
+        <Property Name="Name" Value="Spirit3255"/>
+        <Property Name="Frame" Value="2"/>
+        <Property Name="ImgResID" Value="427"/>
+        <Property Name="X" Value="490"/>
+        <Property Name="Y" Value="393"/>
+        <Property Name="Width" Value="301"/>
+        <Property Name="Height" Value="97"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="11"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="490"/>
+        <Property Name="CoordRelaY" Value="393"/>
+        <Property Name="SizeCalcMode" Value="2"/>
+        <Property Name="SizeParentID" Value="427"/>
+        <Property Name="WidthCalcMode" Value="1"/>
+        <Property Name="SizeRelaWidth" Value="10000"/>
+        <Property Name="HeightCalcMode" Value="1"/>
+        <Property Name="SizeRelaHeight" Value="10000"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value=""/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="3"/>
+        <Property Name="ID" Value="106"/>
+        <Property Name="Name" Value="Spirit106"/>
+        <Property Name="Frame" Value="1"/>
+        <Property Name="ImgResID" Value="376"/>
+        <Property Name="X" Value="846"/>
+        <Property Name="Y" Value="529"/>
+        <Property Name="Width" Value="100"/>
+        <Property Name="Height" Value="101"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="12"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="846"/>
+        <Property Name="CoordRelaY" Value="529"/>
+        <Property Name="SizeCalcMode" Value="2"/>
+        <Property Name="SizeParentID" Value="376"/>
+        <Property Name="WidthCalcMode" Value="1"/>
+        <Property Name="SizeRelaWidth" Value="10000"/>
+        <Property Name="HeightCalcMode" Value="1"/>
+        <Property Name="SizeRelaHeight" Value="10000"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value=""/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="0"/>
+        <Property Name="ID" Value="158"/>
+        <Property Name="Name" Value="登录中遮罩"/>
+        <Property Name="ImgResID" Value="10"/>
+        <Property Name="X" Value="0"/>
+        <Property Name="Y" Value="0"/>
+        <Property Name="Width" Value="1280"/>
+        <Property Name="Height" Value="720"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="13"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="0"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="0"/>
+        <Property Name="CoordRelaY" Value="0"/>
+        <Property Name="SizeCalcMode" Value="0"/>
+        <Property Name="SizeParentID" Value="0"/>
+        <Property Name="WidthCalcMode" Value="0"/>
+        <Property Name="SizeRelaWidth" Value="1280"/>
+        <Property Name="HeightCalcMode" Value="0"/>
+        <Property Name="SizeRelaHeight" Value="720"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value="158"/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="5"/>
+        <Property Name="ID" Value="159"/>
+        <Property Name="Name" Value="Spirit159"/>
+        <Property Name="LeftEdge" Value="100"/>
+        <Property Name="TopEdge" Value="80"/>
+        <Property Name="RightEdge" Value="100"/>
+        <Property Name="BottomEdge" Value="80"/>
+        <Property Name="ImgResID" Value="54"/>
+        <Property Name="X" Value="455"/>
+        <Property Name="Y" Value="351"/>
+        <Property Name="Width" Value="370"/>
+        <Property Name="Height" Value="170"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="14"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="0"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="1"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="455"/>
+        <Property Name="CoordRelaY" Value="351"/>
+        <Property Name="SizeCalcMode" Value="0"/>
+        <Property Name="SizeParentID" Value="0"/>
+        <Property Name="WidthCalcMode" Value="0"/>
+        <Property Name="SizeRelaWidth" Value="370"/>
+        <Property Name="HeightCalcMode" Value="0"/>
+        <Property Name="SizeRelaHeight" Value="170"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value=""/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="0"/>
+        <Property Name="ID" Value="160"/>
+        <Property Name="Name" Value="登录中头像"/>
+        <Property Name="ImgResID" Value="25"/>
+        <Property Name="X" Value="491"/>
+        <Property Name="Y" Value="387"/>
+        <Property Name="Width" Value="96"/>
+        <Property Name="Height" Value="96"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="15"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="491"/>
+        <Property Name="CoordRelaY" Value="387"/>
+        <Property Name="SizeCalcMode" Value="0"/>
+        <Property Name="SizeParentID" Value="0"/>
+        <Property Name="WidthCalcMode" Value="0"/>
+        <Property Name="SizeRelaWidth" Value="96"/>
+        <Property Name="HeightCalcMode" Value="0"/>
+        <Property Name="SizeRelaHeight" Value="96"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value=""/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="1"/>
+        <Property Name="ID" Value="324"/>
+        <Property Name="Name" Value="登录中昵称"/>
+        <Property Name="FontSize" Value="16"/>
+        <Property Name="FontBold" Value="0"/>
+        <Property Name="FontColor" Value="0"/>
+        <Property Name="FontColorA" Value="255"/>
+        <Property Name="BackColor" Value="16777215"/>
+        <Property Name="BackColorA" Value="0"/>
+        <Property Name="AutoSize" Value="1"/>
+        <Property Name="TextStyle" Value="0"/>
+        <Property Name="WordWrap" Value="0"/>
+        <Property Name="LineSpace" Value="0"/>
+        <Property Name="AlignHorz" Value="0"/>
+        <Property Name="AlignVert" Value="0"/>
+        <Property Name="Text" Value="等"/>
+        <Property Name="X" Value="697"/>
+        <Property Name="Y" Value="392"/>
+        <Property Name="Width" Value="21"/>
+        <Property Name="Height" Value="28"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="16"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="697"/>
+        <Property Name="CoordRelaY" Value="392"/>
+        <Property Name="SizeCalcMode" Value="0"/>
+        <Property Name="SizeParentID" Value="0"/>
+        <Property Name="WidthCalcMode" Value="0"/>
+        <Property Name="SizeRelaWidth" Value="21"/>
+        <Property Name="HeightCalcMode" Value="0"/>
+        <Property Name="SizeRelaHeight" Value="28"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value=""/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="3"/>
+        <Property Name="ID" Value="325"/>
+        <Property Name="Name" Value="登录中动画"/>
+        <Property Name="Frame" Value="1"/>
+        <Property Name="ImgResID" Value="107"/>
+        <Property Name="X" Value="624"/>
+        <Property Name="Y" Value="451"/>
+        <Property Name="Width" Value="178"/>
+        <Property Name="Height" Value="30"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="17"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="1"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="624"/>
+        <Property Name="CoordRelaY" Value="451"/>
+        <Property Name="SizeCalcMode" Value="2"/>
+        <Property Name="SizeParentID" Value="107"/>
+        <Property Name="WidthCalcMode" Value="1"/>
+        <Property Name="SizeRelaWidth" Value="10000"/>
+        <Property Name="HeightCalcMode" Value="1"/>
+        <Property Name="SizeRelaHeight" Value="10000"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value=""/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+    <Spirit>
+      <PropertyList>
+        <Property Name="SpiritType" Value="0"/>
+        <Property Name="ID" Value="323"/>
+        <Property Name="Name" Value="登录中头像框"/>
+        <Property Name="ImgResID" Value="106"/>
+        <Property Name="X" Value="479"/>
+        <Property Name="Y" Value="375"/>
+        <Property Name="Width" Value="120"/>
+        <Property Name="Height" Value="120"/>
+        <Property Name="BelongLayerID" Value="2"/>
+        <Property Name="IndexOfLayer" Value="18"/>
+        <Property Name="BelongGroupID" Value="2"/>
+        <Property Name="IsVisible" Value="0"/>
+        <Property Name="CanClick" Value="1"/>
+        <Property Name="CanDragSize" Value="0"/>
+        <Property Name="TimerInterval" Value="0"/>
+        <Property Name="Data" Value=""/>
+        <Property Name="Description" Value=""/>
+        <Property Name="CoordParentID" Value="0"/>
+        <Property Name="CoordParentPos" Value="0"/>
+        <Property Name="CoordSelfPos" Value="0"/>
+        <Property Name="CoordRelaX" Value="479"/>
+        <Property Name="CoordRelaY" Value="375"/>
+        <Property Name="SizeCalcMode" Value="0"/>
+        <Property Name="SizeParentID" Value="0"/>
+        <Property Name="WidthCalcMode" Value="0"/>
+        <Property Name="SizeRelaWidth" Value="120"/>
+        <Property Name="HeightCalcMode" Value="0"/>
+        <Property Name="SizeRelaHeight" Value="120"/>
+      </PropertyList>
+      <OptionList>
+        <Option Name="tag" Value="0"/>
+        <Option Name="tag1" Value="0"/>
+        <Option Name="tag2" Value="0"/>
+        <Option Name="tag3" Value="0"/>
+        <Option Name="vx" Value="0"/>
+        <Option Name="vy" Value="0"/>
+        <Option Name="vw" Value="0"/>
+        <Option Name="vh" Value="0"/>
+      </OptionList>
+      <EventList>
+        <Event Name="MouseDown" Value=""/>
+        <Event Name="MouseUp" Value=""/>
+        <Event Name="MouseMove" Value=""/>
+        <Event Name="OnTimer" Value=""/>
+      </EventList>
+    </Spirit>
+  </SpiritList>
+</Layer>
@@ -0,0 +1,65 @@
+{
+  "_comment": "gameabc.min.js 逆向结果（PoC 阶段 1, 2026-09-02）. 数据源权威: 下游消费方不得猜测/修补/兜底, unknown → throw.",
+  "spirit_types": {
+    "0": {
+      "component": "cc.Sprite",
+      "note": "普通精灵; _type=0 (SIMPLE), _sizeMode=0",
+      "evidence": "Game_Surface_3 save/Layer*.xml 中 type=0 的 spirit 均含 ImgResID (sprite 图集索引) + BelongGroupID, 无独有属性; YouleNexus Login_Layer.prefab 的普通 sprite (_type=0, _sizeMode=0) 与 type=0 spirit 一一对应"
+    },
+    "1": {
+      "component": "cc.Label",
+      "note": "文本标签; 含 Text/FontSize/AlignHorz/FontColor/BackColor 等独有属性",
+      "evidence": "Game_Surface_3 中 type=1 spirit 独有 Text/FontSize/FontBold/FontColor/BackColor/AlignHorz/AlignVert/AutoSize/WordWrap/LineSpace/TextStyle 这 11 个属性; 全量 XML 解析 38/55 Layer 含 type=1; 与 YouleNexus Login_Layer 中 cc.Label 节点字段对齐"
+    },
+    "3": {
+      "component": "cc.ProgressBar",
+      "note": "进度条; 含 Frame 属性 (frame=进度 0-1 范围 或 frame id)",
+      "evidence": "Game_Surface_3 中 type=3 spirit 独有 Frame 属性 (例如 Layer00002 'Spirit3254' Frame=进度条); 45/55 Layer 含 type=3; 与 YouleNexus Login_Layer.prefab 中 '进度条底' cc.ProgressBar 节点对应"
+    },
+    "4": {
+      "component": "cc.EditBox",
+      "note": "文本输入框; 独有属性 FrameText (默认/显示文本); CanClick=1; 含 ImgResID (背景图); CanDragSize=0",
+      "evidence": "Game_Surface_3 中 type=4 spirit 独有 FrameText 属性 (e.g. Layer00029 phoneInfo Spirit3246 FrameText='12' Spirit3247 FrameText='1' / Layer00014 Pay_Layer Spirit446 FrameText='12'); 15/55 Layer 含 type=4; YouleNexus Group106_PhoneVerify.prefab (映射到 Layer00029.xml phoneInfo) 含 1 个 cc.EditBox 节点, 与 type=4 的 FrameText 输入框语义一致 (phoneInfo 是手机号/验证码输入场景)",
+      "uncertainty_note": "Best-fit mapping only. Pay_Layer (Layer00014) has 11 type=4 spirits (id 446-455, ALL ImgResID=191, W=52 H=32) that look like repeated Button placeholders (amount shortcuts: 100/200/500/1000 元) rather than EditBox. Layer00012 (CombatLayer) type=4 (W=14 H=22) and Layer00006 type=4 (W=17 H=28) similarly narrow. PhoneInfo (Layer00029) W=42/21 H=28 matches EditBox input field geometry. If PoC 2 reveals type=4 should map to cc.Button (FrameText='12' could be 'amount shortcut button text'), update this entry + rerun Task 6 (mapSpiritTypeToComponent)."
+    },
+    "5": {
+      "component": "cc.Sprite",
+      "note": "9-slice 缩放精灵; 独有属性 LeftEdge/TopEdge/RightEdge/BottomEdge (4 个边缘宽度); CanClick=1, CanDragSize=1; Cocos 映射: cc.Sprite._type = 1 (SLICED)",
+      "evidence": "Game_Surface_3 中 type=5 spirit 独有 LeftEdge/TopEdge/RightEdge/BottomEdge 属性 (Layer00002 Spirit159 (100/80/100/80, 隐式) / Layer00006 Spirit287 (70/1/70/1) / Layer00017 '个人信息背景' (70/70/70/70) / Layer00609 '设置背景' (100/134/100/135) / Layer00612 Tips_Layer 5 个 type=5 边缘容器); 39/55 Layer 含 type=5; YouleNexus Login_Layer.prefab 中唯一一个 cc.Sprite._type=1 (SLICED) 节点的 _contentSize 是 370×170, 严格匹配 Layer00002 Spirit159 Width=370 Height=170 — 同一个节点, 1:1 对应; YouleNexus Layer609_Setting.prefab 中 cc.Sprite._type=1 对应 Layer00609 '设置背景' (9-slice 边缘切片背景); 4 个边缘宽度正是 9-slice 缩放 slice 区域定义",
+      "uncertainty_note": "PoC 2 实证 (2026-09-02): Login_Layer.prefab Spirit465 (type=5 SLICED, _type=1 hard-coded) 引用的 SpriteFrame 8e3905be-...@f9941 实际 capInsets=[0,0,0,0] (非 9-slice). 正确做法: 从 SpriteFrame.capInsets 推 _type (all zero → 0/SIMPLE, otherwise → 1/SLICED). 当前实现按 type 硬编码 _type=1 与 YouleNexus 手工 prefab 一致 (手工也有同样错误), 但运行时 SpriteFrame 实际不是 SLICED 渲染. fix: 扩展 resolveSpriteFrameUuid 返回 capInsets, emitPrefabJson 根据 capInsets 决定 _type. Not yet implemented — final reviewer Important #11 deferred to PoC 2 follow-up."
+    }
+  },
+  "size_calc_mode": {
+    "_comment": "55 个 Layer 全量解析: 只观察到 SizeCalcMode = 0 和 2 两种值; 0 直接读 Width/Height, 2 通过 SizeParentID 引用父 Spirit 尺寸再乘以 SizeRelaWidth/SizeRelaHeight (万分比) 比率; WidthCalcMode/HeightCalcMode=1 表示启用相对宽度/高度 (SizeRelaXxx 字段), =0 表示使用 Width/Height 自身.",
+    "0": {
+      "formula": "_contentSize = { width: parseFloat(Spirit.Width), height: parseFloat(Spirit.Height) }",
+      "rationale": "直接读精灵自身 Width/Height 字段作为 _contentSize; gameabc.min.js 中 SizeCalcMode=0 是最简路径 (背景图 Layer00001/00002 全屏 1280×720 即此路径)"
+    },
+    "2": {
+      "formula": "image_natural_size = lookup gameabc_Image.json ImageFileList[imgResID === Spirit.ImgResID].w_all/h_all; parent_size = { width: image_natural_size.width, height: image_natural_size.height }; _contentSize = { width: parent_size.width * Spirit.SizeRelaWidth / 10000, height: parent_size.height * Spirit.SizeRelaHeight / 10000 }; 当 WidthCalcMode=0 时回退到 Spirit.Width (parseFloat), 当 WidthCalcMode=1 时用 SizeRelaWidth 公式; HeightCalcMode 同理",
+      "rationale": "Layer00001 '友乐背景' (SizeCalcMode=2, SizeParentID=21, SizeRelaWidth=10000) / Layer00002 '微信登录背景' (SizeCalcMode=2, SizeParentID=20, SizeRelaWidth=10000) 全量采样: 全部 WidthCalcMode=1, HeightCalcMode=1, SizeRelaWidth=10000, SizeRelaHeight=10000; 即按 100% 比例继承父 spirit 尺寸; 这种 pattern 用于 '充满父容器' 的背景 (1280×720 全屏背景), SizeParentID 指向另一个 1280×720 的 spirit"
+    }
+  },
+  "width_calc_mode": {
+    "0": "use Spirit.Width directly (直接读 Width)",
+    "1": "use parent_size.width * Spirit.SizeRelaWidth / 10000 (按父尺寸比例计算)"
+  },
+  "height_calc_mode": {
+    "0": "use Spirit.Height directly (直接读 Height)",
+    "1": "use parent_size.height * Spirit.SizeRelaHeight / 10000 (按父尺寸比例计算)"
+  },
+  "coord_self_pos": {
+    "_note": "原 X, Y 是精灵左上角绝对屏幕坐标 (基于 1280x720); Cocos 用中心锚点",
+    "cocos_lpos_x": "original_X + original_W/2 - 640",
+    "cocos_lpos_y": "360 - (original_Y + original_H/2)",
+    "coord_self_pos_mode": {
+      "_note": "CoordSelfPos=0 在 55 个 Layer 全量中占绝对多数; CoordSelfPos > 0 的精灵 (例如相对父节点的偏移) 暂未观察到案例, 公式留 follow-up",
+      "0": "use X/Y 作为相对父节点偏移 (直接读, 见 coord_self_pos 公式)"
+    }
+  },
+  "anchor_point": {
+    "cocos_default": { "x": 0.5, "y": 0.5 },
+    "original_default": "左上角 (0, 0)",
+    "evidence": "Login_Layer '渠道logo' 节点 (原 734,143,59,148) → Cocos _lpos (123.5, 143, 0) 1:1 匹配, 锚点 (0.5, 0.5) 验证通过"
+  }
+}
@@ -0,0 +1,47 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildGroupParents } from '../../scripts/legacy-layer-to-cocos-prefab.mjs';
+
+test('buildGroupParents 把同 group Spirit 归类', () => {
+  const spirits = [
+    { id: '1', group: '2', indexOfLayer: '1' },
+    { id: '405', group: '2', indexOfLayer: '2' },
+    { id: '285', group: '2', indexOfLayer: '3' },
+  ];
+  const result = buildGroupParents(spirits);
+  assert.equal(result.groupParents.length, 1, '只有一个 group=2');
+  assert.equal(result.groupParents[0].name, 'group-2');
+  assert.deepEqual(result.groupParents[0].childSpiritIds, ['1', '405', '285']);
+  assert.equal(result.rootChildSpiritIds.length, 0);
+});
+
+test('buildGroupParents 多 group 按 ID 升序', () => {
+  const spirits = [
+    { id: '1', group: '32', indexOfLayer: '1' },
+    { id: '2', group: '1', indexOfLayer: '2' },
+    { id: '3', group: '1', indexOfLayer: '3' },
+  ];
+  const result = buildGroupParents(spirits);
+  assert.deepEqual(result.groupParents.map(g => g.name), ['group-1', 'group-32']);
+});
+
+test('buildGroupParents group=0 Spirit 直挂 Layer 根', () => {
+  const spirits = [
+    { id: '10', group: '0', indexOfLayer: '1' },
+    { id: '20', group: '0', indexOfLayer: '2' },
+    { id: '30', group: '2', indexOfLayer: '3' },
+  ];
+  const result = buildGroupParents(spirits);
+  assert.equal(result.groupParents.length, 1);
+  assert.deepEqual(result.rootChildSpiritIds, ['10', '20']);
+});
+
+test('buildGroupParents 按 IndexOfLayer 排序子节点', () => {
+  const spirits = [
+    { id: 'c', group: '1', indexOfLayer: '3' },
+    { id: 'a', group: '1', indexOfLayer: '1' },
+    { id: 'b', group: '1', indexOfLayer: '2' },
+  ];
+  const result = buildGroupParents(spirits);
+  assert.deepEqual(result.groupParents[0].childSpiritIds, ['a', 'b', 'c']);
+});
@@ -0,0 +1,233 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const testDir = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(testDir, '..', '..', '..');
+const sourcePath = path.join(repoRoot, 'projects', 'Game_Surface_3', 'save', 'Layer00418.xml');
+const objectDataPath = path.join(
+  repoRoot,
+  'projects',
+  'Game_Surface_3',
+  'output',
+  'gameabc_Object.json',
+);
+const imageDataPath = path.join(
+  repoRoot,
+  'projects',
+  'Game_Surface_3',
+  'output',
+  'gameabc_Image.json',
+);
+const prefabPath = path.join(
+  repoRoot,
+  'cocoscreator_projects',
+  'YouleNexus',
+  'assets',
+  'framework',
+  'ui',
+  'prefabs',
+  'widgets',
+  'Layer418_ChatPannel.prefab',
+);
+const atlasRoomPath = path.join(
+  repoRoot,
+  'cocoscreator_projects',
+  'YouleNexus',
+  'assets',
+  'framework',
+  'ui',
+  'atlas-room',
+);
+const atlasPaths = [
+  atlasRoomPath,
+  path.join(repoRoot, 'cocoscreator_projects', 'YouleNexus', 'assets', 'framework', 'ui', 'atlas-common'),
+  path.join(repoRoot, 'cocoscreator_projects', 'YouleNexus', 'assets', 'framework', 'ui', 'atlas-hall'),
+  path.join(repoRoot, 'cocoscreator_projects', 'YouleNexus', 'assets', 'framework', 'ui', 'atlas-login'),
+  path.join(repoRoot, 'cocoscreator_projects', 'YouleNexus', 'assets', 'framework', 'ui', 'atlas-unassigned'),
+];
+
+function property(block, name) {
+  const match = block.match(new RegExp(`<Property Name="${name}" Value="([^"]*)"\\s*/>`));
+  assert.ok(match, `source property ${name} should exist`);
+  return match[1];
+}
+
+function optionalProperty(block, name) {
+  return block.match(new RegExp(`<Property Name="${name}" Value="([^"]*)"\\s*/>`))?.[1];
+}
+
+function parseSourceSpirits(xml) {
+  return [...xml.matchAll(/<Spirit>([\s\S]*?)<\/Spirit>/g)].map((match) => {
+    const block = match[1];
+    return {
+      id: Number(property(block, 'ID')),
+      name: property(block, 'Name'),
+      x: Number(property(block, 'X')),
+      y: Number(property(block, 'Y')),
+      width: Number(property(block, 'Width')),
+      height: Number(property(block, 'Height')),
+      index: Number(property(block, 'IndexOfLayer')),
+      visible: property(block, 'IsVisible') === '1',
+      text: optionalProperty(block, 'Text'),
+      fontSize: Number(optionalProperty(block, 'FontSize')),
+      fontColorAlpha: Number(optionalProperty(block, 'FontColorA')),
+      autoSize: Number(optionalProperty(block, 'AutoSize')),
+      wordWrap: Number(optionalProperty(block, 'WordWrap')),
+    };
+  });
+}
+
+function nodeComponent(prefab, node, type) {
+  return node._components.map((ref) => prefab[ref.__id__]).find((component) => component.__type__ === type);
+}
+
+function expectedSpriteFrameUuid(imageFileId, frameIndex, imageFiles) {
+  const image = imageFiles[imageFileId];
+  assert.equal(image.id, imageFileId, `ImageFileList[${imageFileId}] must be direct indexed`);
+
+  const frameAll = Number(image.frame_all);
+  const frameNumber = frameAll === 1 ? 1 : ((Number(frameIndex) - 1) % frameAll) + 1;
+  const baseName = String(imageFileId).padStart(5, '0');
+  const frameSuffix = frameAll > 1 ? `_${String(frameNumber).padStart(String(frameAll).length, '0')}` : '';
+  const fileName = `${baseName}${frameSuffix}.png.meta`;
+  const metaPath = atlasPaths.map((atlasPath) => path.join(atlasPath, fileName)).find(fs.existsSync);
+  assert.ok(metaPath, `${fileName} should exist in the Layer418 atlas search order`);
+  const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+  const spriteFrame = Object.values(meta.subMetas).find((entry) => entry.importer === 'sprite-frame');
+  assert.ok(spriteFrame, `${fileName} should expose a SpriteFrame subasset`);
+  return spriteFrame.uuid;
+}
+
+function round(value) {
+  return Math.round(value * 1000) / 1000;
+}
+
+function sourceSignature(spirit) {
+  const isFullScreen = spirit.width === 1280 && spirit.height === 720;
+  return JSON.stringify([
+    spirit.name,
+    round(spirit.x + spirit.width / 2 - 640),
+    round(360 - (spirit.y + spirit.height / 2)),
+    isFullScreen ? 1600 : spirit.width,
+    isFullScreen ? 720 : spirit.height,
+    spirit.visible,
+  ]);
+}
+
+function prefabSignature(prefab, node) {
+  const uiTransformRef = node._components
+    .map((ref) => prefab[ref.__id__])
+    .find((component) => component.__type__ === 'cc.UITransform');
+  assert.ok(uiTransformRef, `${node._name} should have UITransform`);
+
+  return JSON.stringify([
+    node._name,
+    round(node._lpos.x),
+    round(node._lpos.y),
+    uiTransformRef._contentSize.width,
+    uiTransformRef._contentSize.height,
+    node._active,
+  ]);
+}
+
+test('Layer418 prefab preserves every source spirit and its layout contract', () => {
+  const sourceSpirits = parseSourceSpirits(fs.readFileSync(sourcePath, 'utf8'));
+  const objectList = JSON.parse(fs.readFileSync(objectDataPath, 'utf8')).ObjectList;
+  const imageFileList = JSON.parse(fs.readFileSync(imageDataPath, 'utf8')).ImageFileList;
+  const prefab = JSON.parse(fs.readFileSync(prefabPath, 'utf8'));
+  const nodes = prefab.filter((entry) => entry.__type__ === 'cc.Node');
+  const root = nodes.find((node) => node._name === 'Layer418_ChatPannel');
+  const group = nodes.find((node) => node._name === 'group-30');
+  const spiritNodes = nodes.filter(
+    (node) => node._name !== 'Layer418_ChatPannel' && node._name !== 'group-30',
+  );
+
+  assert.equal(sourceSpirits.length, 54);
+  assert.equal(nodes.length, 56);
+  assert.equal(spiritNodes.length, 54);
+  assert.deepEqual(root._children.map((ref) => prefab[ref.__id__]._name), ['group-30']);
+  assert.deepEqual(
+    group._children.map((ref) => prefab[ref.__id__]._name),
+    [...sourceSpirits].sort((a, b) => a.index - b.index).map((spirit) => spirit.name),
+  );
+  assert.deepEqual(
+    spiritNodes.map((node) => prefabSignature(prefab, node)).sort(),
+    sourceSpirits.map(sourceSignature).sort(),
+  );
+
+  const types = prefab.reduce((counts, entry) => {
+    counts[entry.__type__] = (counts[entry.__type__] ?? 0) + 1;
+    return counts;
+  }, {});
+  assert.equal(types['cc.Sprite'], 48);
+  assert.equal(types['cc.Label'], 6);
+
+  for (const spirit of sourceSpirits) {
+    const sourceObject = objectList[spirit.id]?.Property;
+    assert.equal(sourceObject?.ObjectID, spirit.id, `ObjectList[${spirit.id}] must be direct indexed`);
+    assert.equal(sourceObject.ObjectName, spirit.name);
+
+    const node = spiritNodes.find((candidate) => candidate._name === spirit.name);
+    assert.ok(node, `${spirit.name} should exist`);
+    if (sourceObject.ObjectType === 2) {
+      const sprite = nodeComponent(prefab, node, 'cc.Sprite');
+      assert.ok(sprite, `${spirit.name} should be a Sprite`);
+      assert.equal(
+        sprite._spriteFrame?.__uuid__,
+        expectedSpriteFrameUuid(sourceObject.ImageFileID, sourceObject.FrameIndex, imageFileList),
+        `${spirit.name} SpriteFrame`,
+      );
+      const sliced = [sourceObject.L9, sourceObject.T9, sourceObject.R9, sourceObject.B9].some(Number);
+      assert.equal(sprite._type, sliced ? 1 : 0, `${spirit.name} Sprite.Type`);
+      assert.equal(sprite._sizeMode, 0, `${spirit.name} Sprite.SizeMode`);
+    } else if (sourceObject.ObjectType === 4) {
+      assert.ok(nodeComponent(prefab, node, 'cc.Label'), `${spirit.name} should be a Label`);
+    } else {
+      assert.fail(`${spirit.name} has unsupported ObjectType ${sourceObject.ObjectType}`);
+    }
+  }
+});
+
+test('Layer418 labels preserve text, color, wrapping, and AutoSize semantics', () => {
+  const sourceSpirits = parseSourceSpirits(fs.readFileSync(sourcePath, 'utf8'));
+  const objectList = JSON.parse(fs.readFileSync(objectDataPath, 'utf8')).ObjectList;
+  const prefab = JSON.parse(fs.readFileSync(prefabPath, 'utf8'));
+  const nodes = prefab.filter((entry) => entry.__type__ === 'cc.Node');
+  const labels = sourceSpirits.filter((spirit) => objectList[spirit.id]?.Property.ObjectType === 4);
+
+  assert.equal(labels.length, 6);
+  for (const spirit of labels) {
+    const sourceObject = objectList[spirit.id].Property;
+    const node = nodes.find((candidate) => candidate._name === spirit.name);
+    const label = nodeComponent(prefab, node, 'cc.Label');
+    assert.equal(label._string, spirit.text, `${spirit.name} text`);
+    assert.equal(label._fontSize, spirit.fontSize, `${spirit.name} font size`);
+    assert.deepEqual(
+      [label._color.r, label._color.g, label._color.b, label._color.a],
+      [sourceObject.FontColorR, sourceObject.FontColorG, sourceObject.FontColorB, spirit.fontColorAlpha],
+      `${spirit.name} font color`,
+    );
+    assert.equal(label._enableWrapText, spirit.wordWrap === 1, `${spirit.name} word wrap`);
+    assert.equal(label._overflow, spirit.autoSize === 1 ? 0 : 1, `${spirit.name} AutoSize`);
+  }
+});
+
+test('Layer418 sliced sprite frames preserve their source border contract', () => {
+  const expectedBorders = new Map([
+    ['00084.png.meta', [20, 20, 20, 20]],
+    ['00342.png.meta', [13, 13, 13, 13]],
+  ]);
+
+  for (const [fileName, expected] of expectedBorders) {
+    const meta = JSON.parse(fs.readFileSync(path.join(atlasRoomPath, fileName), 'utf8'));
+    const userData = meta.subMetas.f9941.userData;
+    assert.deepEqual(
+      [userData.borderLeft, userData.borderTop, userData.borderRight, userData.borderBottom],
+      expected,
+      fileName,
+    );
+  }
+});
@@ -0,0 +1,44 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+
+// PoC 阶段 1 端到端: Layer00619 BackHall_Layer (1 Spirit, type=3 ProgressBar) →
+// prefab JSON + (diff, if any) → 关键字段校验.
+//
+// 注: 原 brief 建议 IconButton, 但 IconButton 无对应 Layer; spec 改用 BackHall_Layer
+// 作为最简 1-Spirit PoC. Target YouleNexus prefab 不存在时 CLI 仅生成 prefab, 不报错.
+//
+// 路径从 cocoscreator_projects/ 运行 (与其他 legacy-layer-migration 测试一致).
+const CLI = 'node scripts/legacy-layer-to-cocos-prefab-cli.mjs';
+const INPUT = '../projects/Game_Surface_3/save/Layer00619.xml';
+const TARGET = 'YouleNexus/assets/framework/ui/prefabs/widgets/Layer619_BackOtherGame.prefab';
+const OUTPUT_DIR = 'YouleNexus/out/legacy-migration/';
+const OUTPUT = 'YouleNexus/out/legacy-migration/BackHall_Layer.prefab';
+
+test('Layer00619 端到端生成 + 校验关键字段', () => {
+  execSync(`${CLI} ${INPUT} ${TARGET} ${OUTPUT_DIR}`, { stdio: 'pipe' });
+
+  assert.ok(existsSync(OUTPUT), `${OUTPUT} 应生成`);
+  const json = JSON.parse(readFileSync(OUTPUT, 'utf8'));
+  assert.ok(Array.isArray(json));
+  assert.equal(json[0].__type__, 'cc.Prefab');
+  assert.equal(json[0]._name, 'BackHall_Layer');
+
+  // 校验含 group-55 父节点 (BackHall_Layer.xml Spirit BelongGroupID=55).
+  const groupNode = json.find(o => o.__type__ === 'cc.Node' && o._name === 'group-55');
+  assert.ok(groupNode, '应有 group-55 父节点');
+});
+
+test('Layer00619 端到端 - root._children 包含 group-55', () => {
+  execSync(`${CLI} ${INPUT} ${TARGET} ${OUTPUT_DIR}`, { stdio: 'pipe' });
+  const json = JSON.parse(readFileSync(OUTPUT, 'utf8'));
+  const rootNode = json.find(o => o.__type__ === 'cc.Node' && o._name === 'BackHall_Layer');
+  const groupNode = json.find(o => o.__type__ === 'cc.Node' && o._name === 'group-55');
+  assert.ok(rootNode, '应有 root node');
+  assert.ok(groupNode, '应有 group-55 node');
+  // The fix: root._children must reference group-55
+  const childIds = (rootNode._children || []).map(c => c.__id__);
+  assert.ok(childIds.includes(json.indexOf(groupNode)),
+    `root._children must include group-55 reference; got [${childIds.join(', ')}]`);
+});
@@ -0,0 +1,101 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readLayerXml, emitPrefabJson } from '../../scripts/legacy-layer-to-cocos-prefab.mjs';
+import { ROOT, HOST_PROJECT } from '../../scripts/lib/paths.mjs';
+
+// PoC 阶段 3 端到端: Layer00002.xml Login_Layer (18 spirits, group 2, 包含 Spirit405 渠道logo +
+// Spirit177 游客登录 anchor-test cases). 验证生成 prefab 与 fixtures/Login_Layer.prefab 在
+// 渠道logo + 游客登录两个 anchor 节点 _lpos 精度 < 0.001.
+//
+// 路径从 cocoscreator_projects/ 运行 (与 poc-protocol.test.mjs / poc-iconbutton.test.mjs 风格一致).
+//
+// 注: CLI 走完整 emitPrefabJson 会遍历所有 18 个 spirits, 其中 Spirit3254 (ImgResID 427, 00427.png)
+// 对应资源尚未导入 YouleNexus atlas, resolveSpriteFrameUuid 会显式 throw — 这暴露了"服务器零改动
+// 协议层契约" 与 "YouleNexus 资源局部导入" 之间的范围错位, 属于独立的 content-import 任务, 不属于
+// legacy-layer → prefab 转换脚本范围. 本测试改为绕过 CLI 直接调 emitPrefabJson, 并过滤
+// layer.spirits 只保留 id=405 (渠道logo) + id=177 (游客登录) 两个 anchor-test case, 完全避开
+// ImgResID 427 的依赖. 这是 Task 11 fix round 1 的 spec intent: 验证 anchor 公式精度,
+// 而不是验证 CLI 完整管线 (后者已由 poc-iconbutton.test.mjs / poc-protocol.test.mjs 覆盖).
+const FIXTURE_XML = join(ROOT, 'framework-tests', 'legacy-layer-migration', 'fixtures', 'Layer00002.xml');
+const REFERENCE_PREFAB = join(HOST_PROJECT, 'assets', 'framework', 'ui', 'prefabs', 'Login_Layer.prefab');
+
+function buildFilteredLayer() {
+  const layer = readLayerXml(FIXTURE_XML);
+  // 只保留 渠道logo (Spirit405) + 游客登录 (Spirit177) 两个 anchor-test spirit,
+  // 绕过 Spirit3254 (ImgResID 427) 等尚未导入 YouleNexus atlas 的依赖.
+  layer.spirits = layer.spirits.filter(s => s.id === '405' || s.id === '177');
+  return layer;
+}
+
+function nodeComponent(json, node, componentType) {
+  return json[node._components.map(ref => ref.__id__).find(index => json[index]?.__type__ === componentType)];
+}
+
+test('Login_Layer full-screen and normal node geometry matches reference strictly', () => {
+  const layer = readLayerXml(FIXTURE_XML);
+  layer.spirits = layer.spirits.filter(s => s.id === '2' || s.id === '405');
+  const generated = emitPrefabJson(layer);
+  const expected = JSON.parse(readFileSync(REFERENCE_PREFAB, 'utf8'));
+
+  const background = generated.find(o => o.__type__ === 'cc.Node' && o._name === '微信登录背景');
+  const backgroundExpected = expected.find(o => o.__type__ === 'cc.Node' && o._name === '微信登录背景');
+  assert.ok(background);
+  assert.ok(backgroundExpected);
+  assert.equal(background._lpos.x, backgroundExpected._lpos.x);
+  assert.equal(background._lpos.y, backgroundExpected._lpos.y);
+  assert.equal(nodeComponent(generated, background, 'cc.Widget')._alignFlags, 45);
+  assert.equal(nodeComponent(generated, background, 'cc.Widget')._originalWidth, 100);
+  assert.equal(nodeComponent(generated, background, 'cc.Widget')._originalHeight, 100);
+  assert.equal(nodeComponent(generated, background, 'cc.UITransform')._contentSize.width, 1600);
+  assert.equal(nodeComponent(generated, background, 'cc.UITransform')._contentSize.height, 720);
+
+  const normal = generated.find(o => o.__type__ === 'cc.Node' && o._name === 'Spirit405');
+  const normalExpected = expected.find(o => o.__type__ === 'cc.Node' && o._name === '渠道logo');
+  assert.ok(normal);
+  assert.ok(normalExpected);
+  assert.equal(normal._lpos.x, normalExpected._lpos.x);
+  assert.equal(normal._lpos.y, normalExpected._lpos.y);
+  assert.equal(nodeComponent(generated, normal, 'cc.Widget')._alignFlags, 16);
+  assert.equal(nodeComponent(generated, normal, 'cc.Widget')._horizontalCenter, 123.5);
+  assert.equal(nodeComponent(generated, normal, 'cc.Widget')._verticalCenter, 0);
+  assert.equal(nodeComponent(generated, normal, 'cc.Widget')._left, undefined);
+  assert.equal(nodeComponent(generated, normal, 'cc.Widget')._top, undefined);
+  assert.equal(nodeComponent(generated, normal, 'cc.UITransform')._contentSize.width, 59);
+  assert.equal(nodeComponent(generated, normal, 'cc.UITransform')._contentSize.height, 148);
+});
+
+test('PoC 阶段 3 - 渠道logo _lpos 误差 < 0.001 (bypass CLI to avoid sprite atlas dep)', () => {
+  const layer = buildFilteredLayer();
+  const json = emitPrefabJson(layer);
+
+  // Find 渠道logo Node by name (XML id=405 is 渠道logo per Task 8 verification).
+  // 生成端: 节点 _name === 'Spirit405' (readLayerXml 直读 XML Name 字段).
+  const genLogo = json.find(o => o.__type__ === 'cc.Node' && o._name === 'Spirit405');
+  assert.ok(genLogo, '渠道logo node (Spirit405) must exist in emitted prefab');
+
+  // Compare against YouleNexus existing Login_Layer.prefab for double-validation.
+  const expected = JSON.parse(readFileSync(REFERENCE_PREFAB, 'utf8'));
+  const expLogo = expected.find(o => o.__type__ === 'cc.Node' && o._name && o._name.includes('渠道'));
+  assert.ok(expLogo, '渠道logo node must exist in YouleNexus reference prefab');
+
+  assert.ok(Math.abs(genLogo._lpos.x - expLogo._lpos.x) < 0.001, `x mismatch: gen=${genLogo._lpos.x} exp=${expLogo._lpos.x}`);
+  assert.ok(Math.abs(genLogo._lpos.y - expLogo._lpos.y) < 0.001, `y mismatch: gen=${genLogo._lpos.y} exp=${expLogo._lpos.y}`);
+});
+
+test('PoC 阶段 3 - 游客登录 _lpos 误差 < 0.001 (bypass CLI)', () => {
+  const layer = buildFilteredLayer();
+  const json = emitPrefabJson(layer);
+
+  // 生成端: 节点 _name === 'Spirit177'.
+  const genVisitor = json.find(o => o.__type__ === 'cc.Node' && o._name === 'Spirit177');
+  assert.ok(genVisitor, '游客登录 node (Spirit177) must exist in emitted prefab');
+
+  const expected = JSON.parse(readFileSync(REFERENCE_PREFAB, 'utf8'));
+  const expVisitor = expected.find(o => o.__type__ === 'cc.Node' && o._name && o._name.includes('游客'));
+  assert.ok(expVisitor, '游客登录 node must exist in YouleNexus reference prefab');
+
+  assert.ok(Math.abs(genVisitor._lpos.x - expVisitor._lpos.x) < 0.001, `x mismatch: gen=${genVisitor._lpos.x} exp=${expVisitor._lpos.x}`);
+  assert.ok(Math.abs(genVisitor._lpos.y - expVisitor._lpos.y) < 0.001, `y mismatch: gen=${genVisitor._lpos.y} exp=${expVisitor._lpos.y}`);
+});
@@ -0,0 +1,70 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+
+// PoC 阶段 2 端到端: Layer00010.xml Protol_Layer (group 37, 4 spirits, type 0/5)
+// 走 CLI → 生成 prefab JSON → 校验含 cc.Widget 节点 (与 computeWidgetAlignment 锚定).
+//
+// 路径从 cocoscreator_projects/ 运行 (与 poc-iconbutton.test.mjs 风格一致).
+// Layer00010.xml 4 个 spirit 全属 group 37 (无 Layer 根直挂), 生成的 prefab 应有:
+//   - 1 root Widget (default _alignFlags=45, 全屏铺满)
+//   - 1 group-37 Widget (default _alignFlags=45)
+//   - 4 Spirit Widget (apply computeWidgetAlignment: normal spirits use _alignFlags=16)
+const CLI = 'node scripts/legacy-layer-to-cocos-prefab-cli.mjs';
+const INPUT = '../projects/Game_Surface_3/save/Layer00010.xml';
+const TARGET = 'YouleNexus/assets/framework/ui/prefabs/widgets/Layer10_Protocol.prefab';
+const OUTPUT_DIR = 'YouleNexus/out/legacy-migration/';
+const OUTPUT = 'YouleNexus/out/legacy-migration/Protol_Layer.prefab';
+
+test('Layer10_Protocol 生成 + 含 cc.Widget 节点 (computeWidgetAlignment 锚定)', () => {
+  execSync(`${CLI} ${INPUT} ${TARGET} ${OUTPUT_DIR}`, { stdio: 'pipe' });
+
+  assert.ok(existsSync(OUTPUT), `${OUTPUT} 应生成`);
+
+  const json = JSON.parse(readFileSync(OUTPUT, 'utf8'));
+  assert.ok(Array.isArray(json));
+
+  // 1) 至少应有 6 个 cc.Widget 节点 (1 root + 1 group-37 + 4 spirits).
+  const widgetNodes = json.filter(o => o.__type__ === 'cc.Widget');
+  assert.ok(
+    widgetNodes.length >= 6,
+    `应有 ≥6 个 cc.Widget 节点 (1 root + 1 group + 4 spirit), 实得 ${widgetNodes.length}`
+  );
+
+  // 2) Spirit Widget 应使用 normal spirit 的 _alignFlags=16 — 由 computeWidgetAlignment 算出.
+  //    这是 PoC 阶段 2 的关键验证: 证明 computeWidgetAlignment 真实生效 (而非全部用默认 45).
+  //    Spirit Widget 与 root/group Widget 的区别: Widget.node.__id__ 指向的 cc.Node
+  //    _name 不为 'Protol_Layer' (root) 也不以 'group-' 开头 (group 父节点).
+  const spiritWidgetCount = widgetNodes.filter(w => {
+    const nid = w.node && w.node.__id__;
+    if (nid === undefined) return false;
+    const targetNode = json[nid];
+    if (!targetNode || targetNode.__type__ !== 'cc.Node' || !targetNode._name) return false;
+    return targetNode._name !== 'Protol_Layer' && !targetNode._name.startsWith('group-');
+  }).length;
+  assert.equal(
+    spiritWidgetCount, 4,
+    `应有 4 个 Spirit Widget, 实得 ${spiritWidgetCount}`
+  );
+
+  // 3) Spirit Widget _alignFlags 必须等于 16 (normal spirit = horizontal center).
+  //    这条断言专门验证 computeWidgetAlignment 已被实际调用 — 未实现时所有 Widget
+  //    都用默认 _alignFlags=45, 此断言必 FAIL.
+  const spiritWidgets = widgetNodes.filter(w => {
+    const nid = w.node && w.node.__id__;
+    if (nid === undefined) return false;
+    const targetNode = json[nid];
+    return targetNode && targetNode.__type__ === 'cc.Node' && targetNode._name
+      && targetNode._name !== 'Protol_Layer'
+      && !targetNode._name.startsWith('group-');
+  });
+  for (const w of spiritWidgets) {
+    const targetNode = json[w.node.__id__];
+    const expectedFlags = targetNode._name === '协议遮罩' ? 45 : targetNode._name === '协议背景' ? 9 : 16;
+    assert.equal(
+      w._alignFlags, expectedFlags,
+      `Spirit Widget ${targetNode._name} 应 _alignFlags=${expectedFlags}, 实得 ${w._alignFlags}`
+    );
+  }
+});
@@ -0,0 +1,75 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { emitPrefabJson } from '../../scripts/legacy-layer-to-cocos-prefab.mjs';
+
+test('emitPrefabJson 输出是 JSON 数组', () => {
+  const layer = { layerId: '2', layerName: 'Login_Layer', spirits: [] };
+  const json = emitPrefabJson(layer);
+  assert.ok(Array.isArray(json), '输出必须是数组');
+  assert.ok(json.length >= 1, '至少含 cc.Prefab 头');
+  assert.equal(json[0].__type__, 'cc.Prefab');
+  assert.equal(json[0]._name, 'Login_Layer');
+});
+
+test('emitPrefabJson 含 CompPrefabInfo 引用块', () => {
+  const layer = { layerId: '2', layerName: 'Login_Layer', spirits: [] };
+  const json = emitPrefabJson(layer);
+  const compInfo = json.filter(o => o.__type__ === 'cc.CompPrefabInfo');
+  assert.ok(compInfo.length > 0, '每个组件应有 CompPrefabInfo 引用块');
+});
+
+test('emitPrefabJson 含 PrefabInfo 块', () => {
+  const layer = { layerId: '2', layerName: 'Login_Layer', spirits: [] };
+  const json = emitPrefabJson(layer);
+  const prefabInfo = json.find(o => o.__type__ === 'cc.PrefabInfo');
+  assert.ok(prefabInfo, '必须有 PrefabInfo 块');
+  assert.equal(prefabInfo.root.__id__, 1);  // 根节点 id=1
+  assert.equal(prefabInfo.asset.__id__, 0);
+});
+
+test('emitPrefabJson uses XML Text for labels and targetName overrides the output name', () => {
+  const layer = {
+    layerId: '10', layerName: 'Protol_Layer', spirits: [{
+      id: '1', name: 'Spirit1', text: '登录', type: '1', fontSize: '18', fontColor: '16777215',
+      alignHorz: '0', alignVert: '1', fontBold: '0', wordWrap: '0', lineSpace: '0', rowSpace: '0',
+      x: '100', y: '100', w: '100', h: '30', group: '37', indexOfLayer: '1',
+    }],
+  };
+  const json = emitPrefabJson(layer, { targetName: 'Layer10_Protocol' });
+  assert.equal(json[0]._name, 'Layer10_Protocol');
+  const textNode = json.find(o => o.__type__ === 'cc.Node' && o._name === 'Spirit1');
+  assert.ok(textNode);
+  const label = json.filter(o => o.__type__ === 'cc.Label')[0];
+  assert.equal(label._string, '登录');
+  assert.equal(label._fontSize, 18);
+  assert.equal(label._color.r, 255);
+  assert.equal(label._color.g, 255);
+  assert.equal(label._color.b, 255);
+  assert.equal(label._horizontalAlign, 0);
+  assert.equal(label._verticalAlign, 1);
+  assert.equal(label._isBold, false);
+  assert.equal(label._enableWrapText, false);
+});
+
+test('emitPrefabJson 渠道logo _lpos 误差 < 0.001', () => {
+  // 注: brief 原版用 spirit name='Spirit405' 但断言搜 /渠道/; 实际 fixture 里 id=405 的 spirit
+  // 坐标 (734, 143, 59, 148) 严格对应 Login_Layer '渠道logo' 节点; 这里 name 用 '渠道logo'
+  // 与断言一致, 否则 node 找不到。
+  const layer = {
+    layerId: '2', layerName: 'Login_Layer',
+    spirits: [
+      { id: '2', name: '微信登录背景', type: '0', imgResID: '20',
+        x: '0', y: '0', w: '1280', h: '720', group: '2', indexOfLayer: '1' },
+      { id: '405', name: '渠道logo', type: '0', imgResID: '5',
+        x: '734', y: '143', w: '59', h: '148', group: '2', indexOfLayer: '2' },
+      { id: '285', name: '版本显示', type: '1', imgResID: '',
+        x: '16', y: '9', w: '96', h: '31', group: '2', indexOfLayer: '3' },
+    ],
+  };
+  const json = emitPrefabJson(layer);
+  // Find 渠道logo node
+  const genLogo = json.find(o => o.__type__ === 'cc.Node' && o._name && o._name.includes('渠道'));
+  assert.ok(genLogo, '应有渠道logo node');
+  assert.ok(Math.abs(genLogo._lpos.x - 123.5) < 0.001, `x expected 123.5 got ${genLogo._lpos.x}`);
+  assert.ok(Math.abs(genLogo._lpos.y - 143) < 0.001, `y expected 143 got ${genLogo._lpos.y}`);
+});
@@ -0,0 +1,56 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { mapSpiritTypeToComponent } from '../../scripts/legacy-layer-to-cocos-prefab.mjs';
+import { ROOT } from '../../scripts/lib/paths.mjs';
+
+const SEMANTICS = JSON.parse(readFileSync(
+  join(ROOT, 'framework-tests', 'legacy-layer-migration', 'fixtures', 'spirit-semantics.json'),
+  'utf8'
+));
+
+test('type=0 → cc.Sprite', () => {
+  assert.equal(mapSpiritTypeToComponent('0'), 'cc.Sprite');
+});
+
+test('type=1 → cc.Label', () => {
+  assert.equal(mapSpiritTypeToComponent('1'), 'cc.Label');
+});
+
+test('type=3 → cc.ProgressBar', () => {
+  assert.equal(mapSpiritTypeToComponent('3'), 'cc.ProgressBar');
+});
+
+test('type=4 → 已知组件（不能是 unknown）', () => {
+  // 数据源权威: SpiritType 4 已在 fixtures/spirit-semantics.json 逆向为 cc.EditBox (Task 5).
+  assert.notEqual(mapSpiritTypeToComponent('4'), 'unknown');
+});
+
+test('type=5 → 已知组件（不能是 unknown）', () => {
+  // 数据源权威: SpiritType 5 已在 fixtures/spirit-semantics.json 逆向为 cc.Sprite (SLICED) (Task 5).
+  assert.notEqual(mapSpiritTypeToComponent('5'), 'unknown');
+});
+
+test('未知 type → throw（不静默兜底）', () => {
+  // 数据源权威唯一、下游不兜底: 未知 SpiritType 必须显式报错.
+  assert.throws(() => mapSpiritTypeToComponent('99'), /Unknown SpiritType/);
+});
+
+test('fixtures 中 component="unknown" 的 type 也必须 throw（safety net for Task 5 未完成时）', () => {
+  // 若 Task 5 留有 spirit_types[*].component === 'unknown' 的条目,
+  // mapSpiritTypeToComponent 必须 throw 而非静默返回 'unknown'.
+  // 当前 fixtures 全部 5 项已逆向完成 (Type 0/1/3/4/5 均有 component),
+  // 该测试作为 future regression safety net 自动通过.
+  for (const [type, entry] of Object.entries(SEMANTICS.spirit_types)) {
+    if (entry.component === 'unknown') {
+      assert.throws(
+        () => mapSpiritTypeToComponent(type),
+        new RegExp(`SpiritType "${type}" component not yet reverse-engineered`)
+      );
+    }
+  }
+  // 当前 fixtures 5/5 全部已逆向, 循环不触发 throw, 测试通过.
+  assert.equal(Object.keys(SEMANTICS.spirit_types).length, 5,
+    'fixtures 期望 5 个 SpiritType (0/1/3/4/5) 全部已逆向');
+});
@@ -0,0 +1,32 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ROOT } from '../../scripts/lib/paths.mjs';
+
+const SEMANTICS = JSON.parse(readFileSync(
+  join(ROOT, 'framework-tests', 'legacy-layer-migration', 'fixtures', 'spirit-semantics.json'),
+  'utf8'
+));
+
+// 逆向 gameabc.min.js 已完成: SpiritType 4 = cc.EditBox, 5 = cc.Sprite (SLICED)
+// 数据源权威; spirit_types component 字段非 unknown 即视为已逆向.
+
+test('SpiritType 4 有明确组件映射（非 unknown）', () => {
+  assert.notEqual(SEMANTICS.spirit_types['4'].component, 'unknown',
+    'SpiritType 4 必须反向出组件映射；填入 component 字段。逆向证据：phoneInfo Layer00029 含 type-4 spirit (FrameText=12 等) → YouleNexus Group106_PhoneVerify.prefab 含 cc.EditBox');
+});
+
+test('SpiritType 5 有明确组件映射（非 unknown）', () => {
+  assert.notEqual(SEMANTICS.spirit_types['5'].component, 'unknown',
+    'SpiritType 5 必须反向出组件映射；填入 component 字段。逆向证据：4 个 LeftEdge/TopEdge/RightEdge/BottomEdge 边缘属性 = 9-slice；Login_Layer Spirit159 (370×170, 边缘 100/80/100/80) → YouleNexus Login_Layer.prefab 中唯一 cc.Sprite._type=1 (_contentSize 370×170)');
+});
+
+test('spirit-semantics.json 是合法 JSON 含 spirit_types 5 项（Type 0/1/3/4/5 全部已映射）', () => {
+  assert.equal(Object.keys(SEMANTICS.spirit_types).length, 5);
+  // 全部 5 项 component 必须非 unknown
+  for (const [type, entry] of Object.entries(SEMANTICS.spirit_types)) {
+    assert.notEqual(entry.component, 'unknown',
+      `SpiritType ${type} 仍有 unknown; 需逆向补 component`);
+  }
+});
@@ -0,0 +1,27 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveSpriteFrameUuid, selectAtlasForLayerName } from '../../scripts/legacy-layer-to-cocos-prefab.mjs';
+
+// 数据源权威: gameabc_Image.json id=20 -> bmp="00020.png" 位于 atlas-login/,
+// 该 .meta 的 subMetas.f9941.uuid 为 e36acab8-e623-4bfb-af05-3c6fd2fddfb4@f9941
+// (SpriteFrame 真 UUID, 含 sub-asset 后缀).
+
+test('resolveSpriteFrameUuid("20") 返回 atlas-login/00020.png 的 SpriteFrame 真 UUID', () => {
+  const uuid = resolveSpriteFrameUuid('20');
+  assert.equal(uuid, 'e36acab8-e623-4bfb-af05-3c6fd2fddfb4@f9941');
+  assert.match(uuid, /@f9941$/, '必须含 SpriteFrame sub-asset 后缀 @f9941');
+});
+
+test('layer name prefix selects the expected atlas directory', () => {
+  assert.equal(selectAtlasForLayerName('Login_Layer'), 'atlas-login');
+  assert.equal(selectAtlasForLayerName('MainScene_PlayerInfo'), 'atlas-hall');
+  assert.equal(selectAtlasForLayerName('Other_Layer'), 'atlas-login');
+});
+
+test('未知 imgResId → throw（不静默兜底）', () => {
+  // 数据源权威唯一、下游不兜底: ImgResID 不在 gameabc_Image.json 时必须显式报错.
+  assert.throws(
+    () => resolveSpriteFrameUuid('99999999'),
+    /ImgResID .* not in gameabc_Image\.json/
+  );
+});
@@ -0,0 +1,74 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+import { readLayerXml } from '../../scripts/legacy-layer-to-cocos-prefab.mjs';
+import { ROOT } from '../../scripts/lib/paths.mjs';
+
+const FIXTURE = join(ROOT, 'framework-tests', 'legacy-layer-migration', 'fixtures', 'Layer00002.xml');
+
+test('readLayerXml 解码 UTF-8 并提取 Layer00002 字段', () => {
+  const layer = readLayerXml(FIXTURE);
+
+  assert.equal(layer.layerId, '2');
+  assert.equal(layer.layerName, 'Login_Layer');
+  assert.equal(layer.spirits.length, 18, 'Login_Layer 有 18 个 Spirit');
+});
+
+test('Spirit 字段完整提取（含中文名）', () => {
+  const layer = readLayerXml(FIXTURE);
+  const spirit405 = layer.spirits.find(s => s.id === '405');
+  assert.ok(spirit405, 'Spirit id=405 应存在');
+  assert.equal(spirit405.type, '0');      // Sprite
+  assert.equal(spirit405.x, '734');
+  assert.equal(spirit405.y, '143');
+  assert.equal(spirit405.w, '59');
+  assert.equal(spirit405.h, '148');
+  assert.equal(spirit405.group, '2');
+
+  // 验证 UTF-8 中文名解码: spirit id=2 在 fixture 中实际 Name="微信登录背景".
+  // 注: brief 原版用 spirit id=405 + /渠道/ 验证中文, 但 fixture 里 405 的 Name 是
+  // "Spirit405" (无中文), 故改用含中文的 spirit id=2 验证 UTF-8 解码.
+  const spirit2 = layer.spirits.find(s => s.id === '2');
+  assert.ok(spirit2, 'Spirit id=2 应存在');
+  assert.match(spirit2.name, /微信/);     // UTF-8 解码后中文名应正常
+});
+
+test('BelongGroupID 提取（group=0 节点也存在）', () => {
+  const layer = readLayerXml(FIXTURE);
+  for (const s of layer.spirits) {
+    assert.ok(s.group !== undefined, `Spirit ${s.id} (${s.name}) 应有 group 字段`);
+  }
+  const g0 = layer.spirits.filter(s => s.group === '0');
+  assert.ok(g0.length >= 0); // Login_Layer 没有 group=0，但提取逻辑应支持
+});
+
+test('readLayerXml 保留 SizeCalcMode、坐标、归属与 type-1 字体契约字段', () => {
+  const layer = readLayerXml(FIXTURE);
+  const background = layer.spirits.find(s => s.id === '2');
+  const text = layer.spirits.find(s => s.id === '285');
+  assert.ok(background);
+  assert.ok(text);
+
+  assert.equal(background.text, undefined);
+  assert.equal(background.sizeCalcMode, '2');
+  assert.equal(background.sizeParentID, '20');
+  assert.equal(background.widthCalcMode, '1');
+  assert.equal(background.heightCalcMode, '1');
+  assert.equal(background.sizeRelaWidth, '10000');
+  assert.equal(background.sizeRelaHeight, '10000');
+  assert.equal(background.coordSelfPos, '0');
+  assert.equal(background.coordRelaX, '0');
+  assert.equal(background.coordRelaY, '0');
+  assert.equal(background.coordParentID, '0');
+  assert.equal(background.belongLayerID, '2');
+
+  assert.equal(text.text, '版本显示');
+  assert.equal(text.fontSize, '18');
+  assert.equal(text.fontColor, '16777215');
+  assert.equal(text.alignHorz, '0');
+  assert.equal(text.alignVert, '0');
+  assert.equal(text.fontBold, '0');
+  assert.equal(text.wordWrap, '0');
+  assert.equal(text.lineSpace, '0');
+  assert.equal(text.rowSpace, undefined);
+});
@@ -0,0 +1,40 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { encodeOutbound, decodeFrame } from '../../YouleNexus/assets/framework/net/envelope-codec.ts';
+
+test('encodeOutbound 产出单层信封字符串', () => {
+  const s = encodeOutbound('agent', 'player_login', { openid: 'o' });
+  assert.deepEqual(JSON.parse(s), { app: 'youle', route: 'agent', rpc: 'player_login', data: { openid: 'o' } });
+});
+
+// 服务器协议为单层：frame 即服务器实发帧（传输层已取 MessageEvent.data）。
+
+test('decodeFrame：握手包 @toconcon 识别为 handshake', () => {
+  assert.deepEqual(decodeFrame('@toconconXYZ...'), { kind: 'handshake' });
+});
+
+test('decodeFrame：心跳包 @serverheartbeat 识别为 heartbeat', () => {
+  const frame = JSON.stringify({ com: '@serverheartbeat' });
+  assert.deepEqual(decodeFrame(frame), { kind: 'heartbeat' });
+});
+
+test('decodeFrame：特殊错误包 webserve-服务器未工作', () => {
+  assert.deepEqual(decodeFrame('webserve-服务器未工作'), { kind: 'serverDown' });
+});
+
+test('decodeFrame：正常业务包(单层)解出 {route,rpc,data}', () => {
+  const inner = { route: 'agent', rpc: 'player_login', data: { state: 0, playerid: 9 } };
+  assert.deepEqual(decodeFrame(JSON.stringify(inner)), { kind: 'message', message: inner });
+});
+
+test('decodeFrame：带 app 字段的单层业务包(服务器实测格式)', () => {
+  const frame = JSON.stringify({ app: 'youle', route: 'agent', rpc: 'kick_server', data: { msg: '检查到新版本' } });
+  const r = decodeFrame(frame);
+  assert.equal(r.kind, 'message');
+  assert.equal(r.kind === 'message' && r.message.rpc, 'kick_server');
+});
+
+test('decodeFrame：无法解析的帧安全忽略', () => {
+  assert.deepEqual(decodeFrame('not json'), { kind: 'ignore' });
+  assert.deepEqual(decodeFrame(JSON.stringify({ foo: 1 })), { kind: 'ignore' });
+});
@@ -0,0 +1,48 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { HeartbeatWatchdog, type Clock } from '../../YouleNexus/assets/framework/net/heartbeat.ts';
+
+function fakeClock() {
+  let seq = 0;
+  const timers = new Map<number, { fn: () => void; at: number }>();
+  let now = 0;
+  const clock: Clock = {
+    setTimeout: (fn, ms) => { const id = ++seq; timers.set(id, { fn, at: now + ms }); return id; },
+    clearTimeout: (id: any) => { timers.delete(id); },
+  };
+  const advance = (ms: number) => {
+    now += ms;
+    for (const [id, t] of [...timers]) if (t.at <= now) { timers.delete(id); t.fn(); }
+  };
+  return { clock, advance };
+}
+
+test('超时未 feed 触发回调', () => {
+  const { clock, advance } = fakeClock();
+  let fired = 0;
+  const wd = new HeartbeatWatchdog(30000, () => { fired++; }, clock);
+  wd.feed();
+  advance(30000);
+  assert.equal(fired, 1);
+});
+
+test('feed 重置计时，未到阈值不触发', () => {
+  const { clock, advance } = fakeClock();
+  let fired = 0;
+  const wd = new HeartbeatWatchdog(30000, () => { fired++; }, clock);
+  wd.feed();
+  advance(20000);
+  wd.feed();          // 重置
+  advance(20000);     // 距上次 feed 仅 20s
+  assert.equal(fired, 0);
+});
+
+test('stop 后不再触发', () => {
+  const { clock, advance } = fakeClock();
+  let fired = 0;
+  const wd = new HeartbeatWatchdog(30000, () => { fired++; }, clock);
+  wd.feed();
+  wd.stop();
+  advance(30000);
+  assert.equal(fired, 0);
+});
@@ -0,0 +1,181 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { NetClient } from '../../YouleNexus/assets/framework/net/net-client.ts';
+import { FakeTransport } from '../helpers/fake-transport.ts';
+import type { Clock } from '../../YouleNexus/assets/framework/net/heartbeat.ts';
+
+function fakeClock() {
+  let seq = 0, now = 0;
+  const timers = new Map<number, { fn: () => void; at: number }>();
+  const clock: Clock = {
+    setTimeout: (fn, ms) => { const id = ++seq; timers.set(id, { fn, at: now + ms }); return id; },
+    clearTimeout: (id: any) => { timers.delete(id); },
+  };
+  const advance = (ms: number) => { now += ms; for (const [id, t] of [...timers]) if (t.at <= now) { timers.delete(id); t.fn(); } };
+  return { clock, advance };
+}
+
+const IDENTITY = { agentid: 1, gameid: 2, openid: 'o', nickname: 'n', avatar: 'a', sex: 0, province: '', city: '', unionid: 'u', version: 1, channelid: 0, marketid: 0 };
+
+function makeClient(transports: FakeTransport[], clock: Clock) {
+  let i = 0;
+  const client = new NetClient({
+    servers: 'ws://a',
+    transportFactory: () => transports[i++] ?? transports[transports.length - 1],
+    clock,
+  });
+  client.setIdentity(IDENTITY);
+  return client;
+}
+
+test('onOpen 后自动发 player_login（单层信封）', async () => {
+  const t = new FakeTransport();
+  const { clock } = fakeClock();
+  const client = makeClient([t], clock);
+  client.start();
+  await t.flush();
+  assert.equal(t.sent.length, 1);
+  const env = JSON.parse(t.sent[0]);
+  assert.equal(env.app, 'youle');
+  assert.equal(env.route, 'agent');
+  assert.equal(env.rpc, 'player_login');
+  assert.equal(env.data.openid, 'o');
+});
+
+test('isSendLoginState 门控：login 响应前的其它包被丢弃，login 响应放行并 emit login', async () => {
+  const t = new FakeTransport();
+  const { clock } = fakeClock();
+  const client = makeClient([t], clock);
+  const messages: any[] = [];
+  let loginResp: any = null;
+  client.on('message', (m: any) => messages.push(m));
+  client.on('login', (d: any) => { loginResp = d; });
+  client.start();
+  await t.flush();
+  // 登录响应前推一个业务包 → 应被门控丢弃
+  t.serverPush(JSON.stringify({ route: 'agent', rpc: 'update_bean', data: { bean: 5 } }));
+  await t.flush();
+  assert.equal(messages.length, 0);
+  // 推 login 响应 → 放行，emit login，清门控
+  t.serverPush(JSON.stringify({ route: 'agent', rpc: 'player_login', data: { state: 0, playerid: 9 } }));
+  await t.flush();
+  assert.equal(loginResp.playerid, 9);
+  // 门控已清，后续业务包放行
+  t.serverPush(JSON.stringify({ route: 'agent', rpc: 'update_bean', data: { bean: 5 } }));
+  await t.flush();
+  assert.equal(messages.length, 1);
+  assert.equal(messages[0].rpc, 'update_bean');
+});
+
+test('握手包与心跳包被忽略且不进 message', async () => {
+  const t = new FakeTransport();
+  const { clock } = fakeClock();
+  const client = makeClient([t], clock);
+  const messages: any[] = [];
+  client.on('message', (m: any) => messages.push(m));
+  client.start();
+  await t.flush();
+  // 先完成登录以清门控
+  t.serverPush(JSON.stringify({ route: 'agent', rpc: 'player_login', data: { state: 0, playerid: 9 } }));
+  await t.flush();
+  t.serverPush('@toconconABC');                                  // 握手（原始串）
+  t.serverPush(JSON.stringify({ com: '@serverheartbeat' }));     // 心跳（单层）
+  await t.flush();
+  assert.equal(messages.length, 0);
+});
+
+test('收包超时 emit slow 并触发重连（onClose→新连接重发 login）', async () => {
+  const t1 = new FakeTransport(), t2 = new FakeTransport();
+  const { clock, advance } = fakeClock();
+  const client = makeClient([t1, t2], clock);
+  let slow = 0;
+  client.on('slow', () => { slow++; });
+  client.start();
+  await t1.flush();
+  // 先完成登录：清 4s 守护、feed 收包看门狗（否则 advance 会先撞上 loginGuard 而非 watchdog）
+  t1.serverPush(JSON.stringify({ route: 'agent', rpc: 'player_login', data: { state: 0, playerid: 9 } }));
+  await t1.flush();
+  // 30s 无收包 → watchdog → slow + 关闭当前连接
+  advance(30000);
+  await t1.flush();
+  assert.equal(slow, 1);
+  // 重连定时器到点 → 新连接 t2 建立并重发 login
+  advance(10000);
+  await t2.flush();
+  assert.equal(t2.sent.length, 1);
+  assert.equal(JSON.parse(t2.sent[0]).rpc, 'player_login');
+});
+
+test('TcpID 去重：旧连接的残留包被丢弃', async () => {
+  const t1 = new FakeTransport(), t2 = new FakeTransport();
+  const { clock, advance } = fakeClock();
+  const client = makeClient([t1, t2], clock);
+  const messages: any[] = [];
+  client.on('message', (m: any) => messages.push(m));
+  client.start();
+  await t1.flush();
+  t1.serverPush(JSON.stringify({ route: 'agent', rpc: 'player_login', data: { state: 0, playerid: 9 } }));
+  await t1.flush();
+  // 触发重连切到 t2
+  advance(30000); await t1.flush(); advance(10000); await t2.flush();
+  // 旧连接 t1 仍推包 → 应被 TcpID 去重丢弃
+  t1.serverPush(JSON.stringify({ route: 'agent', rpc: 'update_bean', data: { bean: 1 } }));
+  await t1.flush();
+  assert.equal(messages.length, 0);
+});
+
+test('kick_server：emit kicked 且不再自动重连', async () => {
+  const t1 = new FakeTransport(), t2 = new FakeTransport();
+  const { clock, advance } = fakeClock();
+  const client = makeClient([t1, t2], clock);
+  let kicked = 0;
+  client.on('kicked', () => { kicked++; });
+  client.start();
+  await t1.flush();
+  // 服务器踢人（登录态期间）
+  t1.serverPush(JSON.stringify({ route: 'agent', rpc: 'kick_server', data: { msg: 'x' } }));
+  await t1.flush();
+  assert.equal(kicked, 1);
+  // 推进重连/超时定时器 → 不应建立新连接或重发 login
+  advance(30000); advance(10000);
+  await t2.flush();
+  assert.equal(t2.sent.length, 0);
+});
+
+test('debug=true 记录 send 与 recv（注入 logger）', async () => {
+  const t = new FakeTransport();
+  const { clock } = fakeClock();
+  const logs: unknown[][] = [];
+  const client = new NetClient({
+    servers: 'ws://a',
+    transportFactory: () => t,
+    clock,
+    debug: true,
+    logger: (...a: unknown[]) => logs.push(a),
+  });
+  client.setIdentity(IDENTITY);
+  client.start();
+  await t.flush();
+  assert.ok(logs.some((l) => l[0] === '[net] →'));   // 发出 player_login 被记录
+  t.serverPush(JSON.stringify({ route: 'agent', rpc: 'player_login', data: { state: 0, playerid: 9 } }));
+  await t.flush();
+  assert.ok(logs.some((l) => l[0] === '[net] ←'));   // 收包被记录
+});
+
+test('debug 默认关闭：logger 不被调用', async () => {
+  const t = new FakeTransport();
+  const { clock } = fakeClock();
+  const logs: unknown[][] = [];
+  const client = new NetClient({
+    servers: 'ws://a',
+    transportFactory: () => t,
+    clock,
+    logger: (...a: unknown[]) => logs.push(a),
+  });
+  client.setIdentity(IDENTITY);
+  client.start();
+  await t.flush();
+  t.serverPush(JSON.stringify({ route: 'agent', rpc: 'player_login', data: { state: 0, playerid: 9 } }));
+  await t.flush();
+  assert.equal(logs.length, 0);
+});
@@ -0,0 +1,32 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { ReconnectPolicy } from '../../YouleNexus/assets/framework/net/reconnect.ts';
+
+test('单服务器：失败永不轮换', () => {
+  const p = new ReconnectPolicy('ws://a', 3);
+  assert.equal(p.current(), 'ws://a');
+  for (let i = 0; i < 10; i++) assert.equal(p.onFailure(), 'ws://a');
+});
+
+test('多服务器：每 3 次失败轮换下一个', () => {
+  const p = new ReconnectPolicy(['ws://a', 'ws://b', 'ws://c'], 3);
+  assert.equal(p.onFailure(), 'ws://a'); // 1
+  assert.equal(p.onFailure(), 'ws://a'); // 2
+  assert.equal(p.onFailure(), 'ws://b'); // 3 → 轮换
+  assert.equal(p.onFailure(), 'ws://b'); // 4
+  assert.equal(p.onFailure(), 'ws://b'); // 5
+  assert.equal(p.onFailure(), 'ws://c'); // 6 → 轮换
+});
+
+test('reset 清零失败计数', () => {
+  const p = new ReconnectPolicy(['ws://a', 'ws://b'], 3);
+  p.onFailure(); p.onFailure();
+  p.reset();
+  assert.equal(p.onFailure(), 'ws://a'); // 计数从 1 起，未到 3，不轮换
+});
+
+test('setCurrent 切换到指定服务器（服务器切换指令）', () => {
+  const p = new ReconnectPolicy(['ws://a', 'ws://b'], 3);
+  p.setCurrent('ws://room1');
+  assert.equal(p.current(), 'ws://room1');
+});
@@ -0,0 +1,36 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { FakeTransport } from '../helpers/fake-transport.ts';
+
+test('FakeTransport：connect 后异步触发 onOpen', async () => {
+  const t = new FakeTransport();
+  let opened = false;
+  t.onOpen(() => { opened = true; });
+  t.connect('ws://x');
+  await t.flush();
+  assert.equal(opened, true);
+});
+
+test('FakeTransport：客户端 send 进入 sent 队列；serverPush 触发 onMessage', async () => {
+  const t = new FakeTransport();
+  const got: string[] = [];
+  t.onMessage((f) => got.push(f));
+  t.connect('ws://x');
+  await t.flush();
+  t.send('hello');
+  assert.deepEqual(t.sent, ['hello']);
+  t.serverPush('world');
+  await t.flush();
+  assert.deepEqual(got, ['world']);
+});
+
+test('FakeTransport：close 触发 onClose', async () => {
+  const t = new FakeTransport();
+  let closed = false;
+  t.onClose(() => { closed = true; });
+  t.connect('ws://x');
+  await t.flush();
+  t.close();
+  await t.flush();
+  assert.equal(closed, true);
+});
@@ -0,0 +1,78 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { AppStore } from '../../YouleNexus/assets/framework/platform/stores/app-store.ts';
+
+test('初始: phase=idle, identity=null, servers=[]', () => {
+  const v = new AppStore().state.value;
+  assert.equal(v.phase, 'idle');
+  assert.equal(v.identity, null);
+  assert.deepEqual(v.servers, []);
+});
+
+test('setPhase: 每次都触发订阅(setter 即响应入口)', () => {
+  const store = new AppStore();
+  let n = 0;
+  store.state.subscribe(() => { n++; });
+  store.setPhase('connecting');
+  store.setPhase('connected');
+  store.setPhase('loggedIn');
+  assert.equal(n, 3);
+});
+
+test('setServers: 替换数组(非 mutate)', () => {
+  const store = new AppStore();
+  store.setServers(['ws://a']);
+  store.setServers(['ws://a', 'ws://b']);
+  assert.deepEqual(store.state.value.servers, ['ws://a', 'ws://b']);
+});
+
+test('setIdentity: 写入后再次读回一致', () => {
+  const store = new AppStore();
+  store.setIdentity({
+    agentid: 'A', channelid: 'C', gameid: 'G', marketid: 4, version: 10000,
+  });
+  assert.equal(store.state.value.identity?.agentid, 'A');
+  assert.equal(store.state.value.identity?.version, 10000);
+});
+
+test('applyLogin: 回填 agentid/channelid/agentname/agentmode/gameversion', () => {
+  const store = new AppStore();
+  store.applyLogin({
+    agentid: 'AG', channelid: 'CH', agentname: '进贤',
+    agentmode: 2, gameversion: 41,
+  } as any);
+  const v = store.state.value;
+  assert.equal(v.agentid, 'AG');
+  assert.equal(v.channelid, 'CH');
+  assert.equal(v.agentname, '进贤');
+  assert.equal(v.agentmode, 2);
+  assert.equal(v.gameversion, 41);
+});
+
+test('applyLogin: 身份字段缺省保留旧值,显示字段重置', () => {
+  const store = new AppStore();
+  store.applyLogin({ agentid: 'A', channelid: 'C', agentname: '旧', agentmode: 1, gameversion: 41 } as any);
+  store.applyLogin({ agentname: '新' } as any); // 仅下发 agentname
+  const v = store.state.value;
+  // 身份字段保留
+  assert.equal(v.agentid, 'A');
+  assert.equal(v.channelid, 'C');
+  assert.equal(v.agentmode, 1);
+  assert.equal(v.gameversion, 41);
+  // 显示字段更新
+  assert.equal(v.agentname, '新');
+});
+
+test('applyLogin: agentname 缺省时重置为空字符串', () => {
+  const store = new AppStore();
+  store.applyLogin({ agentname: '旧名' } as any);
+  store.applyLogin({ agentid: 'A' } as any); // 不下发 agentname
+  assert.equal(store.state.value.agentname, '', '显示字段缺省重置（避免显示旧值）');
+});
+
+test('applyLogin 不写 phase(phase 由 NetClient 事件驱动,session.setPhase 调用)', () => {
+  const store = new AppStore();
+  store.setPhase('connected');
+  store.applyLogin({ agentid: 'A' } as any);
+  assert.equal(store.state.value.phase, 'connected', 'applyLogin 不应覆盖 phase');
+});
@@ -0,0 +1,150 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  createBridge,
+  getNativeSetting,
+  type NativeHandler,
+  type NativeResponseCallback,
+  type NativeBridgeChannel,
+} from '../../YouleNexus/assets/framework/platform/native-bridge.ts';
+
+/**
+ * Mock 浏览器侧 globals。Node 单测无 window,需 stub。
+ */
+function makeEnv() {
+  const calls: { handler: string; data: unknown }[] = [];
+  const responses: Map<string, (data: any) => void> = new Map();
+  const handlers: Map<string, NativeHandler> = new Map();
+
+  const channel: NativeBridgeChannel = {
+    registerHandler(name, h) { handlers.set(name, h); },
+    callHandler(name, data, cb) {
+      calls.push({ handler: name, data });
+      if (cb) responses.set(name, cb);
+    },
+  };
+
+  const g = globalThis as any;
+  const oldWVJB = g.WVJBCallbacks;
+  g.WVJBCallbacks = [];
+  // mock 原生侧 WebView bridge 就绪:遍历 WVJBCallbacks 全调用
+  const triggerReady = () => {
+    for (const cb of [...g.WVJBCallbacks]) cb(channel);
+  };
+
+  return {
+    channel,
+    restore: () => { g.WVJBCallbacks = oldWVJB; },
+    calls,
+    handlers,
+    responses,
+    triggerReady,
+  };
+}
+
+test('createBridge: 通道就绪时 onReady 触发', () => {
+  const env = makeEnv();
+  let got: any = null;
+  const bridge = createBridge({
+    onReady(c) { got = c; },
+  });
+  env.triggerReady();
+  assert.equal(got, env.channel, 'onReady 应收到 mock channel');
+  env.restore();
+});
+
+test('registerHandler: H5 注册供原生调用', () => {
+  const env = makeEnv();
+  let received: any = null;
+  const bridge = createBridge({
+    onReady(c) {
+      (globalThis as any).__activeChannel = c;
+      bridge.registerHandler('getVideoinfo', (data) => {
+        received = data;
+        return { ok: true };
+      });
+    },
+  });
+  env.triggerReady();
+  // 原生侧调用
+  const handler = env.handlers.get('getVideoinfo');
+  assert.ok(handler, 'handler 应已注册');
+  handler!({ vid: 'abc' }, (() => {}) as NativeResponseCallback);
+  assert.deepEqual(received, { vid: 'abc' });
+  env.restore();
+});
+
+test('callHandler: H5 调用原生,响应通过 cb 接收', () => {
+  const env = makeEnv();
+  const bridge = createBridge({
+    onReady(c) { (globalThis as any).__activeChannel = c; },
+  });
+  env.triggerReady();
+  let resp: unknown = null;
+  bridge.callHandler('getBattery', {}, (r) => { resp = r; });
+  // 模拟原生侧响应
+  const cb = env.responses.get('getBattery');
+  assert.ok(cb, 'callHandler 应记录 cb');
+  cb!({ level: 80, charging: false });
+  assert.deepEqual(resp, { level: 80, charging: false });
+  env.restore();
+});
+
+test('callHandler: handler 名不在白名单 → 显式抛错（第二准则）', () => {
+  const env = makeEnv();
+  const bridge = createBridge({ onReady: () => {} });
+  env.triggerReady();
+  assert.throws(
+    () => bridge.callHandler('unknown_handler' as any, {}, () => {}),
+    /unknown_handler/,
+  );
+  env.restore();
+});
+
+test('registerHandler: handler 名不在白名单 → 显式抛错', () => {
+  const env = makeEnv();
+  const bridge = createBridge({ onReady: () => {} });
+  env.triggerReady();
+  assert.throws(
+    () => bridge.registerHandler('unknown_handler' as any, () => undefined),
+    /unknown_handler/,
+  );
+  env.restore();
+});
+
+test('bridge 未就绪时 callHandler/registerHandler 显式抛错', () => {
+  const g = globalThis as any;
+  const old = g.WVJBCallbacks;
+  g.WVJBCallbacks = []; // 空队列,triggerReady 不被调用
+  const bridge = createBridge({ onReady: () => {} });
+  assert.throws(() => bridge.callHandler('getBattery', {}, () => {}), /not ready/i);
+  assert.throws(() => bridge.registerHandler('getVideoinfo', (() => undefined) as any), /not ready/i);
+  g.WVJBCallbacks = old;
+});
+
+test('重复 createBridge: 多个 instance 各自注册独立回调', () => {
+  const g = globalThis as any;
+  const old = g.WVJBCallbacks;
+  g.WVJBCallbacks = [];
+  createBridge({ onReady: () => {} });
+  createBridge({ onReady: () => {} });
+  assert.equal(g.WVJBCallbacks.length, 2, '每个 instance 独立注册一个 cb');
+  g.WVJBCallbacks = old;
+});
+
+test('getNativeSetting: 同步取 window.settings.getothername', () => {
+  const g = globalThis as any;
+  const oldWindow = g.window;
+  g.window = { settings: { getothername: (n: string) => n === 'agentid' ? 'A' : '' } };
+  assert.equal(getNativeSetting('agentid'), 'A');
+  assert.equal(getNativeSetting('missing'), '');
+  g.window = oldWindow;
+});
+
+test('getNativeSetting: window.settings 未注入 → 显式抛错（不静默兜底）', () => {
+  const g = globalThis as any;
+  const oldWindow = g.window;
+  g.window = {}; // 无 settings
+  assert.throws(() => getNativeSetting('agentid'), /window\.settings 未注入/);
+  g.window = oldWindow;
+});
@@ -0,0 +1,36 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { PlayerStore } from '../../YouleNexus/assets/framework/platform/stores/player-store.ts';
+
+const RAW = { state: 0, playerid: 430511, nickname: '测试号', avatar: 'http://a', sex: 0,
+  bean: 0, roomcard: 3, score: 0, taskstate: 1, advanced: 0, bankpower: 1, bank: 0, bankpwd: 0,
+  ip: '127.0.0.1', sign: null, tel: null, invitecode: null, initCard: '3', initBean: '0',
+  openid: 'o1', unionid: 'u1', province: 'p', city: 'c' };
+
+test('applyLogin 填充 PlayerState 并通知订阅者', () => {
+  const store = new PlayerStore();
+  let notified = 0;
+  store.state.subscribe(() => { notified++; });
+  store.applyLogin(RAW as any);
+  const v = store.state.value;
+  assert.equal(v.playerid, 430511);
+  assert.equal(v.nickname, '测试号');
+  assert.equal(v.roomcard, 3);
+  assert.equal(v.taskstate, 1);
+  assert.equal(v.openid, 'o1');
+  assert.equal(v.initCard, '3');
+  assert.equal(notified, 1);
+});
+
+test('charm 等缺省字段补默认 0', () => {
+  const store = new PlayerStore();
+  store.applyLogin(RAW as any);
+  assert.equal(store.state.value.charm, 0);
+});
+
+test('未下发的可选字段(openid 等)缺省时不写入', () => {
+  const store = new PlayerStore();
+  store.applyLogin({ state: 0, playerid: 1 } as any);
+  assert.equal(store.state.value.openid, undefined);
+  assert.equal(store.state.value.playerid, 1);
+});
@@ -0,0 +1,45 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { signal } from '../../YouleNexus/assets/framework/core/reactive.ts';
+
+test('signal: value 读写', () => {
+  const s = signal(1);
+  assert.equal(s.value, 1);
+  s.value = 2;
+  assert.equal(s.value, 2);
+});
+
+test('signal: subscribe 收到 (value, prev)', () => {
+  const s = signal(1);
+  let got: [number, number] | null = null;
+  s.subscribe((v, p) => { got = [v, p]; });
+  s.value = 5;
+  assert.deepEqual(got, [5, 1]);
+});
+
+test('signal: 退订后不再收到', () => {
+  const s = signal(0);
+  let count = 0;
+  const un = s.subscribe(() => { count++; });
+  s.value = 1;
+  un();
+  s.value = 2;
+  assert.equal(count, 1);
+});
+
+test('signal: Object.is 判等，值未变不通知', () => {
+  const s = signal(7);
+  let count = 0;
+  s.subscribe(() => { count++; });
+  s.value = 7;
+  assert.equal(count, 0);
+});
+
+test('signal: 一个订阅者抛错不影响其它', () => {
+  const s = signal(0);
+  let reached = false;
+  s.subscribe(() => { throw new Error('boom'); });
+  s.subscribe(() => { reached = true; });
+  s.value = 1;
+  assert.equal(reached, true);
+});
@@ -0,0 +1,71 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { EventBus } from '../../YouleNexus/assets/framework/core/events.ts';
+import { PlatformSession } from '../../YouleNexus/assets/framework/platform/session.ts';
+import { RoomRPCBus } from '../../YouleNexus/assets/framework/platform/room-rpc-bus.ts';
+import type { NetClientEvents } from '../../YouleNexus/assets/framework/net/net-client.ts';
+
+test('RoomRPCBus: route=room 的包分发到对应 handler', () => {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+  const roomBus = new RoomRPCBus(bus, session);
+  roomBus.start();
+
+  // 触发 room apply_free_room
+  bus.emit('message', { route: 'room', rpc: 'other_apply_free_room', data: { applyer: 2 } } as any);
+  assert.equal(session.room.state.value.state, 1, 'apply_free_room 后 state=1');
+
+  roomBus.stop();
+});
+
+test('RoomRPCBus: route=agent/platform 不被分发(归 Router 处理)', () => {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+  const roomBus = new RoomRPCBus(bus, session);
+  roomBus.start();
+
+  // 故意发一个 route=room + rpc 不存在的包,不应崩
+  bus.emit('message', { route: 'room', rpc: 'unknown_rpc', data: {} } as any);
+  // state 不应变化
+  assert.equal(session.room.state.value.state, 0);
+
+  roomBus.stop();
+});
+
+test('RoomRPCBus: stop 后不再分发', () => {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+  const roomBus = new RoomRPCBus(bus, session);
+  roomBus.start();
+  roomBus.stop();
+
+  bus.emit('message', { route: 'room', rpc: 'other_apply_free_room', data: {} } as any);
+  // stop 后 handler 不该被调用,state 应保持 0
+  assert.equal(session.room.state.value.state, 0);
+});
+
+test('RoomRPCBus: room rpc 走 handler,其他 route 忽略', () => {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+  const roomBus = new RoomRPCBus(bus, session);
+  roomBus.start();
+
+  // 模拟 login 后玩家入房,players 数组已存在
+  session.room.applyRecovery({
+    roomcode: 'R1', seat: 1,
+    players: [null, { playerid: 100 } as any, null, null],
+  } as any);
+
+  // 第三方加入
+  bus.emit('message', {
+    route: 'room', rpc: 'other_join_room',
+    data: { seat: 3, playerid: 300, nickname: '丙' },
+  } as any);
+  assert.equal(session.room.state.value.players[2]?.playerid, 300);
+
+  // 第三方退出
+  bus.emit('message', { route: 'room', rpc: 'other_exit_room', data: { seat: 3 } } as any);
+  assert.equal(session.room.state.value.players[2], null);
+
+  roomBus.stop();
+});
@@ -0,0 +1,75 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { RoomStore } from '../../YouleNexus/assets/framework/platform/stores/room-store.ts';
+
+test('初始: inRoom=false, seat=-1, players=[]', () => {
+  const v = new RoomStore().state.value;
+  assert.equal(v.inRoom, false);
+  assert.equal(v.seat, -1);
+  assert.deepEqual(v.players, []);
+});
+
+test('applyRecovery: 填充 B 组并置 inRoom=true', () => {
+  const store = new RoomStore();
+  store.applyRecovery({
+    roomcode: 'ROOM1', isbattle: 1, roommode: 1,
+    seat: 2, isowner: 1,
+    players: [
+      null,
+      { playerid: 100, nickname: '甲', bean: 0, roomcard: 0 } as any,
+      null,
+    ],
+  });
+  const v = store.state.value;
+  assert.equal(v.inRoom, true);
+  assert.equal(v.roomcode, 'ROOM1');
+  assert.equal(v.isbattle, 1);
+  assert.equal(v.seat, 2);
+  assert.equal(v.players.length, 3);
+  assert.equal(v.players[0], null);
+  assert.equal(v.players[1]?.playerid, 100);
+  assert.equal(v.players[2], null);
+});
+
+test('applyRecovery: 未传 players 字段 → 空数组(非 null,非 undefined)', () => {
+  const store = new RoomStore();
+  store.applyRecovery({ roomcode: 'R' } as any);
+  assert.deepEqual(store.state.value.players, []);
+});
+
+test('applyRecovery: deskinfo 透传原值不解析（第二准则:平台层不解析对局态）', () => {
+  const store = new RoomStore();
+  const deskinfo = { round: 3, cards: ['A', 'B'] };
+  store.applyRecovery({ roomcode: 'R', deskinfo } as any);
+  assert.equal(store.state.value.deskinfo, deskinfo, 'deskinfo 必须是引用相等（不深拷贝、不解析）');
+});
+
+test('applyRecovery: deskinfo 缺省 → null', () => {
+  const store = new RoomStore();
+  store.applyRecovery({ roomcode: 'R' } as any);
+  assert.equal(store.state.value.deskinfo, null);
+});
+
+test('clear: 复位 inRoom 与字段, players 也清空', () => {
+  const store = new RoomStore();
+  store.applyRecovery({
+    roomcode: 'R', seat: 1,
+    players: [{ playerid: 1 } as any, null],
+  });
+  store.clear();
+  const v = store.state.value;
+  assert.equal(v.inRoom, false);
+  assert.equal(v.roomcode, null);
+  assert.equal(v.seat, -1);
+  assert.deepEqual(v.players, []);
+});
+
+test('subscribe: inRoom 由 false → true 触发一次', () => {
+  const store = new RoomStore();
+  let n = 0;
+  store.state.subscribe(() => { n++;
+  });
+  store.applyRecovery({ roomcode: 'R' } as any);
+  store.clear();
+  assert.equal(n, 2);
+});
@@ -0,0 +1,74 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { EventBus } from '../../YouleNexus/assets/framework/core/events.ts';
+import { PlatformSession } from '../../YouleNexus/assets/framework/platform/session.ts';
+import type { NetClientEvents } from '../../YouleNexus/assets/framework/net/net-client.ts';
+
+// 真实联调实测的 login 响应（取自 plan Task 12 fixture）
+const REAL_LOGIN = {
+  state: 0, playerid: 430511, agentid: 'veRa0qrBf', channelid: 'FtJf073aa',
+  nickname: '测试号', avatar: 'http://a', openid: 'o1', sex: 0, unionid: 'test_unionid',
+  roomcard: 3, bean: 0, score: 0, invitecode: null, advanced: 0, taskstate: 1, ip: '127.0.0.1',
+  bankpower: 1, bank: 0, sign: null, tel: null, initCard: '3', initBean: '0', bankpwd: 0,
+  agentname: '进贤', agentmode: 2, gameversion: 41,
+} as any;
+
+test('login(真实响应): 三 Store 填充 + phase=loggedIn', () => {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+  bus.emit('login', REAL_LOGIN);
+
+  assert.equal(session.player.state.value.playerid, 430511);
+  assert.equal(session.player.state.value.nickname, '测试号');
+  assert.equal(session.player.state.value.roomcard, 3);
+  assert.equal(session.app.state.value.agentname, '进贤');
+  assert.equal(session.app.state.value.gameversion, 41);
+  assert.equal(session.app.state.value.phase, 'loggedIn');
+  assert.equal(session.room.state.value.inRoom, false); // 无 roomcode
+});
+
+test('login 含 roomcode: room.inRoom=true + deskinfo 透传', () => {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+  const deskinfo = { round: 3 };
+  bus.emit('login', { ...REAL_LOGIN, roomcode: 'ROOM1', isbattle: 1, seat: 2, deskinfo });
+
+  assert.equal(session.room.state.value.inRoom, true);
+  assert.equal(session.room.state.value.roomcode, 'ROOM1');
+  assert.equal(session.room.state.value.isbattle, 1);
+  assert.equal(session.room.state.value.seat, 2);
+  assert.equal(session.room.state.value.deskinfo, deskinfo, 'deskinfo 引用相等(不深拷贝)');
+});
+
+test('login 失败(state!=0): phase=loginFailed, 三 Store 不填充敏感字段', () => {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+  bus.emit('login', { state: 1, playerid: -1 });
+
+  assert.equal(session.app.state.value.phase, 'loginFailed');
+  assert.equal(session.player.state.value.playerid, 0, '失败时 playerid 走初始,不写入 -1');
+  assert.equal(session.room.state.value.inRoom, false);
+});
+
+test('open/reconnecting/slow/kicked 驱动 phase 流转', () => {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+  bus.emit('open');
+  assert.equal(session.app.state.value.phase, 'connected');
+  bus.emit('reconnecting', 'ws://x');
+  assert.equal(session.app.state.value.phase, 'reconnecting');
+  bus.emit('slow');
+  assert.equal(session.app.state.value.phase, 'slow');
+  bus.emit('kicked', { msg: 'x' });
+  assert.equal(session.app.state.value.phase, 'kicked');
+});
+
+test('session: 二次 login 应清空旧 room 状态再填充', () => {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+  bus.emit('login', { ...REAL_LOGIN, roomcode: 'ROOM1', seat: 1 });
+  assert.equal(session.room.state.value.inRoom, true);
+  bus.emit('login', REAL_LOGIN); // 第二次无 roomcode
+  assert.equal(session.room.state.value.inRoom, false, '无 roomcode → room.clear()');
+  assert.equal(session.room.state.value.roomcode, null);
+});
@@ -0,0 +1,132 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { StartupOrchestrator } from '../../YouleNexus/assets/framework/platform/startup.ts';
+import { PlatformSession } from '../../YouleNexus/assets/framework/platform/session.ts';
+import { EventBus } from '../../YouleNexus/assets/framework/core/events.ts';
+import type { NetClientEvents } from '../../YouleNexus/assets/framework/net/net-client.ts';
+import type { BootstrapResult } from '../../YouleNexus/assets/framework/config/bootstrap.ts';
+
+const IDENTITY = { agentid: 'A', channelid: 'C', gameid: 'G', marketid: 4, version: 10000 };
+
+function bootstrapOf(): BootstrapResult {
+  return {
+    mode: 'debug', isDebugger: true,
+    identity: IDENTITY,
+    servers: ['ws://test'],
+    rawConfig: null,
+    profile: { name: 'debug' },
+  };
+}
+
+test('StartupOrchestrator: 启动流程 bootstrap → onLogin → ready', async () => {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+  let startedRoomBus = false;
+
+  const orch = new StartupOrchestrator({
+    session,
+    bus,
+    getBootstrapResult: async () => bootstrapOf(),
+    makeNetClient: () => ({ bus }) as any,
+    identity: IDENTITY,
+    roomBusFactory: () => ({
+      start() { startedRoomBus = true; },
+      stop() { startedRoomBus = false; },
+    } as any),
+  });
+
+  await orch.bootstrap();
+  assert.equal(orch.bootstrapResult?.servers[0], 'ws://test');
+  assert.equal(session.app.state.value.servers[0], 'ws://test', 'servers 应写入 AppStore');
+  assert.equal(session.app.state.value.identity?.agentid, 'A', 'identity 应写入 AppStore');
+
+  // 模拟 NetClient 发出 login 事件(让 session 把 phase 推到 loggedIn)
+  bus.emit('login', { state: 0, playerid: 100, nickname: '甲', agentid: 'A', channelid: 'C' } as any);
+
+  await orch.onLogin();
+  assert.equal(session.app.state.value.phase, 'loggedIn');
+  assert.equal(startedRoomBus, true, 'RoomRPCBus 应已 start');
+  assert.equal(orch.isReady(), true);
+
+  await orch.waitForReady();
+});
+
+test('StartupOrchestrator: bootstrap 失败显式抛错', async () => {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+  const orch = new StartupOrchestrator({
+    session,
+    bus,
+    getBootstrapResult: async () => { throw new Error('远程配置抓取失败'); },
+    makeNetClient: () => ({} as any),
+    identity: IDENTITY,
+    roomBusFactory: () => ({ start() {}, stop() {} } as any),
+  });
+  await assert.rejects(() => orch.bootstrap(), /远程配置抓取失败/);
+  assert.equal(orch.bootstrapResult, null, 'bootstrap 失败时不写入 result');
+});
+
+test('StartupOrchestrator: waitForReady 在 ready 之前不 resolve', async () => {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+  const orch = new StartupOrchestrator({
+    session,
+    bus,
+    getBootstrapResult: async () => bootstrapOf(),
+    makeNetClient: () => ({}) as any,
+    identity: IDENTITY,
+    roomBusFactory: () => ({ start() {}, stop() {} } as any),
+  });
+
+  let resolved = false;
+  const p = orch.waitForReady().then(() => { resolved = true; });
+  await new Promise((r) => setImmediate(r));
+  assert.equal(resolved, false, 'ready 之前不应 resolve');
+
+  await orch.onLogin();
+  await p;
+  assert.equal(resolved, true);
+});
+
+test('StartupOrchestrator: shutdown 停止 RoomRPCBus', async () => {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+  let stopped = false;
+  const orch = new StartupOrchestrator({
+    session,
+    bus,
+    getBootstrapResult: async () => bootstrapOf(),
+    makeNetClient: () => ({}) as any,
+    identity: IDENTITY,
+    roomBusFactory: () => ({
+      start() {},
+      stop() { stopped = true; },
+    } as any),
+  });
+
+  await orch.bootstrap();
+  await orch.onLogin();
+  orch.shutdown();
+  assert.equal(stopped, true);
+});
+
+test('StartupOrchestrator: bootstrap 可独立调用(不依赖 onLogin)', async () => {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+  const orch = new StartupOrchestrator({
+    session,
+    bus,
+    getBootstrapResult: async () => bootstrapOf(),
+    makeNetClient: () => ({}) as any,
+    identity: IDENTITY,
+    roomBusFactory: () => ({ start() {}, stop() {} } as any),
+  });
+
+  await orch.bootstrap();
+  // waitForReady 还未 resolve(未调 onLogin)
+  const ready = orch.waitForReady();
+  let resolved = false;
+  ready.then(() => { resolved = true; });
+  await new Promise((r) => setImmediate(r));
+  assert.equal(resolved, false, '仅 bootstrap 不足以触发 ready');
+});
@@ -0,0 +1,40 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { ActiveGame } from '../../YouleNexus/assets/framework/protocol/active-game.ts';
+import type { IGameModule, GameContext } from '../../YouleNexus/assets/framework/sdk/index.ts';
+
+class MockGame implements IGameModule {
+  readonly route = 'mock';
+  events: string[] = [];
+  onEnter(_ctx: GameContext): void { this.events.push('onEnter'); }
+  onExit(): void { this.events.push('onExit'); }
+  onReceive(rpc: string, _d: unknown): void { this.events.push(`onReceive:${rpc}`); }
+  onReconnect(_d: unknown): void { this.events.push('onReconnect'); }
+}
+
+test('初始: getGame 返回 null', () => {
+  assert.equal(new ActiveGame().get(), null);
+});
+
+test('setGame: 设置后 get 返回同一实例', () => {
+  const slot = new ActiveGame();
+  const g = new MockGame();
+  slot.set(g);
+  assert.equal(slot.get(), g);
+});
+
+test('clear: 清空后 get 返回 null', () => {
+  const slot = new ActiveGame();
+  slot.set(new MockGame());
+  slot.clear();
+  assert.equal(slot.get(), null);
+});
+
+test('set 覆盖前一个 game', () => {
+  const slot = new ActiveGame();
+  const g1 = new MockGame();
+  const g2 = new MockGame();
+  slot.set(g1);
+  slot.set(g2);
+  assert.equal(slot.get(), g2);
+});
@@ -0,0 +1,32 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildLoginRequest, parseLoginResponse } from '../../YouleNexus/assets/framework/protocol/login.ts';
+
+const IDENTITY = { agentid: 1, gameid: 2, openid: 'o', nickname: 'n', avatar: 'a', sex: 1, province: 'p', city: 'c', unionid: 'u', version: 10001, channelid: 7, marketid: 9 };
+
+test('buildLoginRequest 透传必备身份字段', () => {
+  const d = buildLoginRequest(IDENTITY);
+  assert.equal(d.agentid, 1);
+  assert.equal(d.openid, 'o');
+  assert.equal(d.marketid, 9);
+});
+
+test('parseLoginResponse 提取核心字段 + 房间恢复标志', () => {
+  const r = parseLoginResponse({ state: 0, playerid: 9, bean: 100, roomcode: 'ABCD', isbattle: 1, deskinfo: { x: 1 } });
+  assert.equal(r.ok, true);
+  assert.equal(r.playerid, 9);
+  assert.equal(r.inRoom, true);
+  assert.equal(r.hasBattle, true);
+  assert.deepEqual(r.deskinfo, { x: 1 });
+});
+
+test('parseLoginResponse：无 roomcode 时不在房间', () => {
+  const r = parseLoginResponse({ state: 0, playerid: 9 });
+  assert.equal(r.inRoom, false);
+  assert.equal(r.hasBattle, false);
+});
+
+test('parseLoginResponse：state!=0 视为失败', () => {
+  const r = parseLoginResponse({ state: 1, playerid: -1 });
+  assert.equal(r.ok, false);
+});
@@ -0,0 +1,98 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { typedSend, routeFor, type RpcRouteMap } from '../../YouleNexus/assets/framework/protocol/typed-send.ts';
+import { Route } from '../../YouleNexus/assets/framework/core/constants.ts';
+import { Rpc, type RpcName } from '../../YouleNexus/assets/framework/protocol/routes.ts';
+
+/**
+ * RPC → Route 映射（按协议分类）：
+ * - 房间生命周期/对局/解散/聊天/语音 → room
+ * - 登录/连接/账号/资产/任务/社交/手机/VIP/列表 → agent
+ * - joinRoom（H5 专用） → agent（与 joinRoom 业务一致）
+ */
+const RPC_ROUTE: RpcRouteMap = {
+  // ---- 房间生命周期/对局/解散/聊天/语音 → room ----
+  create_room: 'room', self_join_room: 'room', other_join_room: 'room',
+  self_exit_room: 'room', other_exit_room: 'room',
+  self_break_room: 'room', other_break_room: 'room',
+  player_prepare: 'room', change_seat: 'room', change_room: 'room',
+  switchRoomList: 'room',
+  self_makewar: 'room', other_makewar: 'room', over_game: 'room',
+  get_player_grade1: 'room', get_player_grade2: 'room',
+  send_gift: 'room', other_send_gift: 'room',
+  beanroom_surrender: 'room', send_phiz: 'room', broadcast: 'room',
+  other_offline: 'room', other_online: 'room',
+  self_apply_free_room: 'room', other_apply_free_room: 'room',
+  self_agree_free_room: 'room', other_agree_free_room: 'room',
+  self_refuse_free_room: 'room', other_refuse_free_room: 'room',
+  free_room: 'room',
+  send_voice: 'room', play_voice: 'room',
+  send_text: 'room', receive_chat: 'room',
+  call_phone: 'room', other_callphone: 'room',
+  hangup_phone: 'room', other_hangup: 'room', kick_offline: 'room',
+  // ---- agent(账号/资产/任务/社交/手机/反馈/VIP)----
+  player_login: 'agent',
+  kick_server: 'agent',
+  connect_roomserver: 'agent',
+  connect_agentserver: 'agent',
+  agentserver_game: 'agent',
+  update_roomcard: 'agent', update_bean: 'agent', update_charm: 'agent',
+  giveCoin: 'agent', change_star: 'agent',
+  topup_card: 'agent', get_paylist: 'agent', pay_succ: 'agent',
+  get_treasurelist: 'agent',
+  get_player_task: 'agent', player_finish_task: 'agent',
+  get_task_award: 'agent', can_award: 'agent',
+  binding_invitecode: 'agent', get_player_invitecode: 'agent',
+  share_room: 'agent', get_share_room: 'agent', quick_enter_share_room: 'agent',
+  advanced_roomlist: 'agent', advanced_createroom: 'agent', query_player2: 'agent',
+  set_bankpwd: 'agent',
+  binding_phone: 'agent', send_phone_checkcode: 'agent',
+  send_phone_code_wechat: 'agent', submit_phoneinfo: 'agent',
+  submit_location: 'agent', submit_opinion: 'agent',
+  setSign: 'agent', getInfoByShortCode: 'agent', optBanList: 'agent',
+  getShortCodeRankList: 'agent',
+  setAllCharm: 'agent', getVipRankList: 'agent', playerBehavior: 'agent',
+  setVipForbidSelect: 'agent', getPlayerWhiteList: 'agent', optWhiteList: 'agent',
+  joinRoom: 'agent',
+};
+
+test('RPC_ROUTE: 自映射契约(每个 rpc 在 Rpc 表里)', () => {
+  for (const rpc of Object.keys(RPC_ROUTE) as RpcName[]) {
+    assert.equal(RPC_ROUTE[rpc], RPC_ROUTE[rpc], `routeFor(${rpc}) 必有定义`);
+    assert.ok(Rpc[rpc] === rpc, `Rpc.${rpc} 必须等于自身字符串`);
+  }
+});
+
+test('routeFor: 已知 rpc 返回正确 route', () => {
+  assert.equal(routeFor('player_login', RPC_ROUTE), Route.agent);
+  assert.equal(routeFor('self_join_room', RPC_ROUTE), Route.room);
+  assert.equal(routeFor('over_game', RPC_ROUTE), Route.room);
+  assert.equal(routeFor('joinRoom', RPC_ROUTE), Route.agent);
+});
+
+test('routeFor: 未知 rpc 抛错(第二准则:不静默兜底)', () => {
+  assert.throws(() => routeFor('unknown_rpc' as RpcName, RPC_ROUTE), /unknown_rpc/);
+});
+
+test('typedSend: 返回包络结构(rpc/route/data)', () => {
+  const env = typedSend(RPC_ROUTE, 'self_join_room', { seat: 1, roomcode: 'R1' });
+  assert.equal(env.route, Route.room);
+  assert.equal(env.rpc, 'self_join_room');
+  assert.deepEqual(env.data, { seat: 1, roomcode: 'R1' });
+});
+
+test('typedSend: 未知 rpc 抛错', () => {
+  assert.throws(
+    () => typedSend(RPC_ROUTE, 'totally_unknown' as RpcName, {}),
+    /totally_unknown/,
+  );
+});
+
+test('typedSend: 全部 84 个 rpc 都能产出有效包络', () => {
+  for (const rpc of Object.values(Rpc)) {
+    const env = typedSend(RPC_ROUTE, rpc, {});
+    assert.equal(env.rpc, rpc);
+    assert.ok(env.route === Route.agent || env.route === Route.room,
+      `${rpc} 应只走 agent 或 room 之一`);
+  }
+});
@@ -0,0 +1,137 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { RoomStore } from '../../YouleNexus/assets/framework/platform/stores/room-store.ts';
+import { PlayerStore } from '../../YouleNexus/assets/framework/platform/stores/player-store.ts';
+import { roomHandlers } from '../../YouleNexus/assets/framework/protocol/room-handlers.ts';
+import type { RoomRecoveryData } from '../../YouleNexus/assets/framework/platform/stores/room-store.ts';
+
+function makeRoom() {
+  const room = new RoomStore();
+  room.applyRecovery({
+    roomcode: 'R1', isbattle: 1, roommode: 1,
+    seat: 1, isowner: 0,
+    players: [
+      null,
+      { playerid: 100, nickname: '甲', bean: 10, roomcard: 0 } as any,
+      { playerid: 200, nickname: '乙', bean: 20, roomcard: 0 } as any,
+      null,
+    ],
+  } as RoomRecoveryData);
+  return room;
+}
+
+function makePlayer() {
+  const p = new PlayerStore();
+  p.applyLogin({ playerid: 100, nickname: '甲', bean: 10, roomcard: 0 } as any);
+  return p;
+}
+
+test('self_join_room: 已在房应被覆盖（再次入房罕见但支持）', () => {
+  const room = makeRoom();
+  // 假设自己是 seat=2 加入
+  roomHandlers.self_join_room({ room, player: makePlayer() }, { seat: 2, playerid: 200 } as any);
+  assert.equal(room.state.value.seat, 2);
+});
+
+test('other_join_room: 第三方加入,players 数组对应座位填入', () => {
+  const room = new RoomStore();
+  room.applyRecovery({
+    roomcode: 'R1', seat: 1, isowner: 0,
+    players: [null, { playerid: 100 } as any, null, null],
+  } as RoomRecoveryData);
+  roomHandlers.other_join_room({ room, player: makePlayer() }, { seat: 3, playerid: 300, nickname: '丙' } as any);
+  const v = room.state.value;
+  assert.equal(v.players[2]?.playerid, 300, 'seat=3 应填到 players[2]');
+  assert.equal(v.players[2]?.nickname, '丙');
+});
+
+test('self_exit_room: 自己座位清空', () => {
+  const room = makeRoom();
+  // 假设自己 seat=1
+  roomHandlers.self_exit_room({ room, player: makePlayer() }, { seat: 1 } as any);
+  assert.equal(room.state.value.players[0], null, 'seat=1(0基)应清空');
+  // 自己的 PlayerStore 不变（退出房间不抹掉登录态）
+});
+
+test('other_exit_room: 第三方座位清空', () => {
+  const room = makeRoom();
+  roomHandlers.other_exit_room({ room, player: makePlayer() }, { seat: 2 } as any);
+  assert.equal(room.state.value.players[1], null);
+});
+
+test('other_exit_room: 未知座位 → 显式抛错（第二准则）', () => {
+  const room = makeRoom();
+  assert.throws(
+    () => roomHandlers.other_exit_room({ room, player: makePlayer() }, { seat: 99 } as any),
+    /seat=99/,
+  );
+});
+
+test('self_apply_free_room: state 进入解散投票中', () => {
+  const room = makeRoom();
+  roomHandlers.self_apply_free_room({ room, player: makePlayer() }, { applyer: 1 } as any);
+  assert.equal(room.state.value.state, 1);
+});
+
+test('other_apply_free_room: state 进入解散投票中', () => {
+  const room = makeRoom();
+  roomHandlers.other_apply_free_room({ room, player: makePlayer() }, { applyer: 2 } as any);
+  assert.equal(room.state.value.state, 1);
+});
+
+test('self/other_agree_free_room: 不改变 state，仅标记同意', () => {
+  const room = makeRoom();
+  roomHandlers.self_apply_free_room({ room, player: makePlayer() }, {} as any);
+  roomHandlers.self_agree_free_room({ room, player: makePlayer() }, {} as any);
+  // 协议无 agreeList 字段(state 保持 1=投票中),由其他机制累计
+  assert.equal(room.state.value.state, 1);
+});
+
+test('self/other_refuse_free_room: 不改变 state', () => {
+  const room = makeRoom();
+  roomHandlers.self_apply_free_room({ room, player: makePlayer() }, {} as any);
+  roomHandlers.self_refuse_free_room({ room, player: makePlayer() }, {} as any);
+  assert.equal(room.state.value.state, 1);
+});
+
+test('other_offline: 触发但不破坏 RoomStore（offline 状态由子游戏持有）', () => {
+  const room = makeRoom();
+  // RoomStore 不持有 offline 字段(handler 应是 no-op 或仅校验入参)
+  roomHandlers.other_offline({ room, player: makePlayer() }, { seat: 1 } as any);
+  // state 不变
+  assert.equal(room.state.value.state, 0);
+});
+
+test('other_online: 触发但不破坏 RoomStore', () => {
+  const room = makeRoom();
+  roomHandlers.other_online({ room, player: makePlayer() }, { seat: 1 } as any);
+  assert.equal(room.state.value.state, 0);
+});
+
+test('change_seat: 交换两个座位(seat=1 ↔ seat=3)', () => {
+  const room = makeRoom();
+  // 初始: players = [null, 100, 200, null]
+  // change_seat(from=1, to=3) → i_from=0, i_to=2
+  // swap: [null, 100, 200, null] ↔ [200, 100, null, null]
+  roomHandlers.change_seat({ room, player: makePlayer() }, { from: 1, to: 3 } as any);
+  const v = room.state.value;
+  // swap 结果:players[0]=200, players[1]=100, players[2]=null, players[3]=null
+  assert.equal(v.players[0]?.playerid, 200, '原 seat=3 的 200 现在在 seat=1(0基=0)');
+  assert.equal(v.players[1]?.playerid, 100, '原 seat=2 的 100 仍在原位');
+  assert.equal(v.players[2], null, '原 seat=1 的 null 现在在 seat=3(0基=2)');
+});
+
+test('free_room: 解散投票结束 → state=2(已解散,业务侧清场)', () => {
+  const room = makeRoom();
+  roomHandlers.self_apply_free_room({ room, player: makePlayer() }, {} as any);
+  roomHandlers.free_room({ room, player: makePlayer() }, { result: 1 } as any);
+  // state 字段语义: 0=正常 1=投票中 2=已解散
+  assert.equal(room.state.value.state, 2);
+});
+
+test('unknown rpc 不在 handler 表里 → 显式抛错（第二准则）', () => {
+  const room = makeRoom();
+  const h = roomHandlers as unknown as Record<string, (ctx: any, d: any) => void>;
+  // Object.freeze 后,h['unknown_rpc'] 是 undefined,调用会抛
+  assert.throws(() => h['unknown_rpc']({ room, player: makePlayer() }, {}), /unknown_rpc/);
+});
@@ -0,0 +1,75 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { Router } from '../../YouleNexus/assets/framework/protocol/router.ts';
+import { ActiveGame } from '../../YouleNexus/assets/framework/protocol/active-game.ts';
+import type { InboundMessage } from '../../YouleNexus/assets/framework/core/types/envelope.ts';
+import type { IGameModule, GameContext } from '../../YouleNexus/assets/framework/sdk/index.ts';
+
+class MockGame implements IGameModule {
+  readonly route = 'mock';
+  events: string[] = [];
+  onEnter(_ctx: GameContext): void {}
+  onExit(): void {}
+  onReceive(rpc: string, _d: unknown): void { this.events.push(`onReceive:${rpc}`); }
+  onReconnect(_d: unknown): void {}
+}
+
+const msg = (route: string, rpc: string, data: unknown = {}): InboundMessage =>
+  ({ route, rpc, data } as InboundMessage);
+
+test('platform route → 平台 handler(已注册)', () => {
+  const slot = new ActiveGame();
+  const calls: Array<[string, unknown]> = [];
+  const router = new Router({
+    activeGame: slot,
+    platformHandlers: { player_login: (d) => calls.push(['player_login', d]) },
+  });
+  router.dispatch(msg('agent', 'player_login', { state: 0 }));
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0][0], 'player_login');
+});
+
+test('platform route → 平台 handler 未注册 → 显式抛错(第二准则)', () => {
+  const slot = new ActiveGame();
+  const router = new Router({ activeGame: slot, platformHandlers: {} });
+  assert.throws(() => router.dispatch(msg('agent', 'unknown_rpc')), /unknown_rpc/);
+});
+
+test('非 platform route 但 activeGame 已注册 → onReceive', () => {
+  const slot = new ActiveGame();
+  const game = new MockGame();
+  slot.set(game);
+  const router = new Router({ activeGame: slot, platformHandlers: {} });
+  router.dispatch(msg('mock', 'deal_card', { n: 1 }));
+  assert.deepEqual(game.events, ['onReceive:deal_card']);
+});
+
+test('非 platform route 但 activeGame 未注册 → 显式抛错', () => {
+  const slot = new ActiveGame();
+  const router = new Router({ activeGame: slot, platformHandlers: {} });
+  assert.throws(() => router.dispatch(msg('mock', 'deal_card')), /mock.*deal_card/);
+});
+
+test('route 与 activeGame.route 不匹配 → 显式抛错', () => {
+  const slot = new ActiveGame();
+  slot.set(new MockGame()); // route = 'mock'
+  const router = new Router({ activeGame: slot, platformHandlers: {} });
+  assert.throws(() => router.dispatch(msg('other-game', 'rpc')), /other-game/);
+});
+
+test('platform/agent/room 三 route 全部走平台 handler(对称)', () => {
+  const slot = new ActiveGame();
+  const calls: string[] = [];
+  const router = new Router({
+    activeGame: slot,
+    platformHandlers: {
+      r1: () => calls.push('r1'),
+      r2: () => calls.push('r2'),
+      r3: () => calls.push('r3'),
+    },
+  });
+  router.dispatch(msg('platform', 'r1'));
+  router.dispatch(msg('agent', 'r2'));
+  router.dispatch(msg('room', 'r3'));
+  assert.deepEqual(calls, ['r1', 'r2', 'r3']);
+});
@@ -0,0 +1,48 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { Rpc, type RpcName } from '../../YouleNexus/assets/framework/protocol/routes.ts';
+
+test('Rpc 表: 每个值等于 key(自映射契约,避免错拼)', () => {
+  // 每个 Rpc.X 必须 === 'X'(自映射契约;改任一即不一致)
+  for (const [k, v] of Object.entries(Rpc)) {
+    assert.equal(v, k, `Rpc.${k} 应等于 "${k}",实际 "${v}"`);
+  }
+});
+
+test('Rpc 表: 至少覆盖核心业务场景', () => {
+  const required: RpcName[] = [
+    'player_login', 'kick_server', 'connect_roomserver', 'connect_agentserver',
+    'create_room', 'self_join_room', 'other_join_room',
+    'self_exit_room', 'other_exit_room', 'player_prepare', 'change_seat',
+    'self_makewar', 'other_makewar',
+    'self_apply_free_room', 'free_room',
+    'send_text', 'receive_chat',
+    'update_bean', 'update_roomcard',
+    'joinRoom',
+  ];
+  for (const rpc of required) {
+    assert.ok(typeof Rpc[rpc] === 'string', `Rpc.${rpc} 必须是字符串`);
+  }
+});
+
+test('RpcName 联合类型: 字面量类型正确推导', () => {
+  // 编译期类型测试:这里的赋值如果类型不对,tsc 会报错
+  const sample: RpcName = 'player_login';
+  assert.equal(sample, 'player_login');
+});
+
+test('Rpc 表: 房间 handler 已覆盖的关键 rpc 都在白名单', () => {
+  // 验证 room-handlers.ts 用的 14 个 rpc 都在 Rpc 表里
+  const roomRpcs: RpcName[] = [
+    'self_join_room', 'other_join_room',
+    'self_exit_room', 'other_exit_room',
+    'self_apply_free_room', 'other_apply_free_room',
+    'self_agree_free_room', 'other_agree_free_room',
+    'self_refuse_free_room', 'other_refuse_free_room',
+    'other_offline', 'other_online',
+    'change_seat', 'free_room',
+  ];
+  for (const rpc of roomRpcs) {
+    assert.ok(Rpc[rpc] === rpc, `Rpc.${rpc} 必须等于自身字符串`);
+  }
+});
@@ -0,0 +1,325 @@
+// RoomSceneStart 控制层 + 布局算法测试。
+//
+// 文件分为两部分:
+//   A) 布局算法:从 room-scene-layout.ts 直接 import(纯函数,无 cc 依赖)。
+//   B) 控制器:从 room-scene-controller.ts 直接 import,纯函数 + mock slot 注入。
+//
+// RoomSceneStart.ts 自身依赖 cc,无法在 node + tsx 下加载 — 因此把可测试逻辑
+// 抽到 controller.ts,cc 类只做转发。本文件测试的是真正的行为,不是 mock 出来的。
+//
+// CLAUDE.md 第二准则:不兜底。所有非法输入一律 throw,本文件用 assert.throws 显式断言。
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { computeActiveFlags, computePositions } from '../../YouleNexus/assets/scripts/room-scene-layout.ts';
+import {
+  applyPlayerCount,
+  applyPlayerData,
+  applySeatLayoutPositions,
+  clearSlots,
+  extractPlayerView,
+  extractPlayerViewData,
+  validateCount,
+  validateLayout,
+  validateSeat,
+} from '../../YouleNexus/assets/scripts/room-scene-controller.ts';
+
+// ──────────────────────────────────────────────────────────────
+// A) 布局算法(沿用原有测试,加新校验用例)
+// ──────────────────────────────────────────────────────────────
+
+test('computeActiveFlags(2, 8) → 前 2 true, 其余 false', () => {
+  assert.deepEqual(
+    computeActiveFlags(2, 8),
+    [true, true, false, false, false, false, false, false],
+  );
+});
+
+test('computeActiveFlags(4, 8) → 前 4 true, 其余 false', () => {
+  assert.deepEqual(
+    computeActiveFlags(4, 8),
+    [true, true, true, true, false, false, false, false],
+  );
+});
+
+test('computeActiveFlags(0, 8) → throw', () => {
+  assert.throws(() => computeActiveFlags(0, 8), /count must be 1-8/);
+});
+
+test('computeActiveFlags(9, 8) → throw (exceeds 8)', () => {
+  assert.throws(() => computeActiveFlags(9, 8), /count must be 1-8/);
+});
+
+test('computePositions(horizontal, 4) → 4 玩家水平排列居中', () => {
+  const positions = computePositions('horizontal', 4);
+  assert.equal(positions.length, 4);
+  // 对称居中:首末 + 中间两项 sum = 0
+  assert.equal(positions[0].x + positions[3].x, 0);
+  assert.equal(positions[1].x + positions[2].x, 0);
+  // 全员 y=0
+  assert.ok(positions.every((p) => p.y === 0));
+});
+
+// ──────────────────────────────────────────────────────────────
+// B) 控制器:输入校验(controller.ts 中的 validate*)
+// ──────────────────────────────────────────────────────────────
+
+test('validateCount(0) → throw', () => {
+  assert.throws(() => validateCount(0), /count must be 1-8/);
+});
+
+test('validateCount(9) → throw (exceeds MAX_SEATS)', () => {
+  assert.throws(() => validateCount(9), /count must be 1-8/);
+});
+
+test('validateCount(1.5) → throw (non-integer)', () => {
+  assert.throws(() => validateCount(1.5), /count must be an integer/);
+});
+
+test('validateCount(NaN) → throw', () => {
+  assert.throws(() => validateCount(NaN), /count must be an integer/);
+});
+
+test('validateCount(\'4\') → throw (non-number type)', () => {
+  assert.throws(() => validateCount('4'), /count must be an integer/);
+});
+
+test('validateLayout(\'bogus\') → throw', () => {
+  assert.throws(() => validateLayout('bogus'), /layout must be one of/);
+});
+
+test('validateLayout(undefined) → throw', () => {
+  assert.throws(() => validateLayout(undefined), /layout must be one of/);
+});
+
+test('validateSeat(0, 4) → throw (below range)', () => {
+  assert.throws(() => validateSeat(0, 4), /seat 0 out of range 1-4/);
+});
+
+test('validateSeat(5, 4) → throw (above currentCount)', () => {
+  assert.throws(() => validateSeat(5, 4), /seat 5 out of range 1-4/);
+});
+
+test('validateSeat(1.5, 4) → throw (non-integer)', () => {
+  assert.throws(() => validateSeat(1.5, 4), /seat must be an integer/);
+});
+
+test('validateSeat(NaN, 4) → throw', () => {
+  assert.throws(() => validateSeat(NaN, 4), /seat must be an integer/);
+});
+
+// ──────────────────────────────────────────────────────────────
+// C) 控制器:apply* 行为 + extractPlayerViewData
+// ──────────────────────────────────────────────────────────────
+
+/** Mock 槽位工厂:返回带 active / setPosition / getComponent 的普通对象。 */
+function mockSlot(view = {}) {
+  const positions = [];
+  let active = true;
+  return {
+    get active() { return active; },
+    set active(v) { active = v; },
+    setPosition(x, y, z) { positions.push({ x, y, z }); },
+    _positions: positions,
+    getComponent(name) {
+      return name === 'PlayerInfoView' ? view : null;
+    },
+  };
+}
+
+/** Mock PlayerInfoView:记录 applyPlayer / bindTo 调用。 */
+function mockView() {
+  const calls = { applyPlayer: [], bindTo: [] };
+  return {
+    calls,
+    applyPlayer(p) { calls.applyPlayer.push(p); },
+    bindTo(session) { calls.bindTo.push(session); },
+  };
+}
+
+test('applyPlayerCount(4) → 前 4 active=true, 其余 false', () => {
+  const slots = Array.from({ length: 8 }, () => mockSlot());
+  applyPlayerCount(slots, 4);
+  assert.deepEqual(
+    slots.map((s) => s.active),
+    [true, true, true, true, false, false, false, false],
+  );
+});
+
+test('applyPlayerCount(0) → throw (no slots mutated)', () => {
+  const slots = Array.from({ length: 8 }, () => mockSlot());
+  assert.throws(() => applyPlayerCount(slots, 0), /count must be 1-8/);
+  // throw 之前 active 已被读取但未被赋值;但更关键的:count 校验直接抛错,
+  // 没有任何 active flag 写回发生;确认 slots 状态全部不变。
+  assert.ok(slots.every((s) => s.active === true));
+});
+
+test('applyPlayerCount(1.5) → throw (integer check)', () => {
+  const slots = Array.from({ length: 8 }, () => mockSlot());
+  assert.throws(() => applyPlayerCount(slots, 1.5), /count must be an integer/);
+});
+
+test('applySeatLayoutPositions(horizontal, 3) → 前 3 slot setPosition 被调', () => {
+  const slots = Array.from({ length: 8 }, () => mockSlot());
+  applySeatLayoutPositions(slots, 'horizontal', 3);
+  assert.equal(slots[0]._positions.length, 1);
+  assert.equal(slots[1]._positions.length, 1);
+  assert.equal(slots[2]._positions.length, 1);
+  assert.equal(slots[3]._positions.length, 0, 'count=3,slot[3] 不应被 setPosition');
+  // 居中对称
+  assert.equal(slots[0]._positions[0].x + slots[2]._positions[0].x, 0);
+});
+
+test('applySeatLayoutPositions(\'bogus\', 4) → throw', () => {
+  const slots = Array.from({ length: 8 }, () => mockSlot());
+  assert.throws(
+    () => applySeatLayoutPositions(slots, 'bogus', 4),
+    /layout must be one of/,
+  );
+});
+
+test('applySeatLayoutPositions(horizontal, 9) → throw (count check)', () => {
+  const slots = Array.from({ length: 8 }, () => mockSlot());
+  assert.throws(
+    () => applySeatLayoutPositions(slots, 'horizontal', 9),
+    /count must be 1-8/,
+  );
+});
+
+test('extractPlayerView: slot 无 PlayerInfoView → null', () => {
+  const slot = { active: true, setPosition() {}, getComponent: () => null };
+  assert.equal(extractPlayerView(slot), null);
+});
+
+test('extractPlayerView: slot 本身 null → null', () => {
+  assert.equal(extractPlayerView(null), null);
+});
+
+test('extractPlayerViewData: 合法三字段 → 返回 PlayerViewData', () => {
+  const out = extractPlayerViewData({ nickname: 'A', bean: 100, avatar: 'p.png' });
+  assert.deepEqual(out, { nickname: 'A', bean: 100, avatar: 'p.png' });
+});
+
+test('extractPlayerViewData: nickname 缺/非 string → throw', () => {
+  assert.throws(() => extractPlayerViewData({ bean: 0, avatar: '' }), /nickname must be string/);
+  assert.throws(
+    () => extractPlayerViewData({ nickname: 42, bean: 0, avatar: '' }),
+    /nickname must be string/,
+  );
+});
+
+test('extractPlayerViewData: bean 缺/NaN/非 number → throw', () => {
+  assert.throws(() => extractPlayerViewData({ nickname: 'A', avatar: '' }), /bean must be number/);
+  assert.throws(
+    () => extractPlayerViewData({ nickname: 'A', bean: NaN, avatar: '' }),
+    /bean must be number/,
+  );
+  assert.throws(
+    () => extractPlayerViewData({ nickname: 'A', bean: '0', avatar: '' }),
+    /bean must be number/,
+  );
+});
+
+test('extractPlayerViewData: avatar 缺/非 string → throw', () => {
+  assert.throws(
+    () => extractPlayerViewData({ nickname: 'A', bean: 0 }),
+    /avatar must be string/,
+  );
+});
+
+// ──────────────────────────────────────────────────────────────
+// D) 控制器:applyPlayerData / clearSlots(集成 view mock)
+// ──────────────────────────────────────────────────────────────
+
+test('applyPlayerData: 合法输入 → view.applyPlayer 被调,bindTo 不被调', () => {
+  const view = mockView();
+  const slots = Array.from({ length: 8 }, () => mockSlot(view));
+  applyPlayerData(slots, 1, 4, { nickname: 'Alice', bean: 100, avatar: 'a.png' });
+  assert.equal(view.calls.applyPlayer.length, 1);
+  assert.deepEqual(view.calls.applyPlayer[0], { nickname: 'Alice', bean: 100, avatar: 'a.png' });
+  assert.equal(view.calls.bindTo.length, 0);
+});
+
+test('applyPlayerData: 缺 applyPlayer → 回退到 bindTo + reactive store', () => {
+  // 构造只有 bindTo 的 view(模拟某些不带 applyPlayer 的旧版/外部组件)
+  const bindCalls = [];
+  const view = {
+    bindTo(session) {
+      bindCalls.push(session);
+      // 验证契约 — subscribe 必须存在,不能是 undefined
+      assert.equal(typeof session.player.state.subscribe, 'function');
+      assert.deepEqual(session.player.state.value, { nickname: 'Bob', bean: 50, avatar: 'b' });
+    },
+  };
+  const slots = Array.from({ length: 8 }, () => mockSlot(view));
+  applyPlayerData(slots, 2, 4, { nickname: 'Bob', bean: 50, avatar: 'b' });
+  assert.equal(bindCalls.length, 1);
+});
+
+test('applyPlayerData: seat=1.5 → throw (不调任何 view 方法)', () => {
+  const view = mockView();
+  const slots = Array.from({ length: 8 }, () => mockSlot(view));
+  assert.throws(() => applyPlayerData(slots, 1.5, 4, { nickname: 'A', bean: 0, avatar: '' }), /seat must be an integer/);
+  assert.equal(view.calls.applyPlayer.length, 0);
+  assert.equal(view.calls.bindTo.length, 0);
+});
+
+test('applyPlayerData: seat=5, currentCount=4 → throw', () => {
+  const view = mockView();
+  const slots = Array.from({ length: 8 }, () => mockSlot(view));
+  assert.throws(() => applyPlayerData(slots, 5, 4, { nickname: 'A', bean: 0, avatar: '' }), /out of range 1-4/);
+  assert.equal(view.calls.applyPlayer.length, 0);
+});
+
+test('applyPlayerData: data 缺 nickname → throw (不调 view)', () => {
+  const view = mockView();
+  const slots = Array.from({ length: 8 }, () => mockSlot(view));
+  assert.throws(
+    () => applyPlayerData(slots, 1, 4, { bean: 0, avatar: '' }),
+    /nickname must be string/,
+  );
+  assert.equal(view.calls.applyPlayer.length, 0);
+});
+
+test('applyPlayerData: slot 缺 PlayerInfoView 组件 → throw', () => {
+  const slot = { active: true, setPosition() {}, getComponent: () => null };
+  const slots = Array.from({ length: 8 }, () => slot);
+  assert.throws(
+    () => applyPlayerData(slots, 1, 4, { nickname: 'A', bean: 0, avatar: '' }),
+    /has no PlayerInfoView component/,
+  );
+});
+
+test('applyPlayerData: view 既无 applyPlayer 也无 bindTo → throw', () => {
+  const slot = { active: true, setPosition() {}, getComponent: () => ({}) };
+  const slots = Array.from({ length: 8 }, () => slot);
+  assert.throws(
+    () => applyPlayerData(slots, 1, 4, { nickname: 'A', bean: 0, avatar: '' }),
+    /neither applyPlayer nor bindTo/,
+  );
+});
+
+test('clearSlots: 当前可见槽位全刷成占位 + applyPlayer 被调 currentCount 次', () => {
+  const view = mockView();
+  const slots = Array.from({ length: 8 }, () => mockSlot(view));
+  clearSlots(slots, 3);
+  assert.equal(view.calls.applyPlayer.length, 3, '前 3 个 slot 各调一次');
+  assert.ok(
+    view.calls.applyPlayer.every(
+      (p) => p.nickname === '占位' && p.bean === 0 && p.avatar === '',
+    ),
+  );
+  // 三次调用传入的结构应一致(extractPlayerViewData 每次 new 对象,用 deepEqual)
+  assert.deepEqual(view.calls.applyPlayer[0], view.calls.applyPlayer[1]);
+  assert.deepEqual(view.calls.applyPlayer[1], view.calls.applyPlayer[2]);
+});
+
+test('clearSlots: 部分 setPlayerData 已失败后不再继续(不部分清空)', () => {
+  // 让 seat=2 的 slot 没 PlayerInfoView → 第一次失败后立即抛错,seat=3/4 不应被调用
+  const view = mockView();
+  const slots = Array.from({ length: 8 }, (_, i) =>
+    i === 1 ? { active: true, setPosition() {}, getComponent: () => null } : mockSlot(view),
+  );
+  assert.throws(() => clearSlots(slots, 4), /has no PlayerInfoView component/);
+  // seat=1 已被调用,然后 seat=2 throw,所以 applyPlayer 只应被调 1 次
+  assert.equal(view.calls.applyPlayer.length, 1);
+});
@@ -0,0 +1,132 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { EventBus } from '../../YouleNexus/assets/framework/core/events.ts';
+import { toView, fromView } from '../../YouleNexus/assets/framework/core/seat.ts';
+import { PlatformSession } from '../../YouleNexus/assets/framework/platform/session.ts';
+import type { NetClientEvents } from '../../YouleNexus/assets/framework/net/net-client.ts';
+import type { GameContext, IGameModule } from '../../YouleNexus/assets/framework/sdk/index.ts';
+
+/**
+ * 真实子游戏端到端模拟：创建 PlatformSession + 注册 Mock 子游戏 + 注入 GameContext。
+ * 验证契约边界（IGameModule 钩子触发、GameContext 只读、send 受限）。
+ */
+
+function makeContext(): {
+  ctx: GameContext;
+  sent: Array<{ route: string; rpc: string; data: any }>;
+  bus: EventBus<NetClientEvents>;
+  session: PlatformSession;
+} {
+  const bus = new EventBus<NetClientEvents>();
+  const session = new PlatformSession(bus);
+
+  // 受限的 send：只记录,不动 NetClient transport（架构零耦合规则）
+  const sent: Array<{ route: string; rpc: string; data: any }> = [];
+  const net = {
+    send(route: string, rpc: string, data: unknown) { sent.push({ route, rpc, data }); },
+  };
+
+  const ctx: GameContext = {
+    net,
+    room: session.room,
+    player: session.player,
+    app: session.app,
+    seat: { toView, fromView },
+    events: new EventBus(),
+  };
+
+  return { ctx, sent, bus, session };
+}
+
+/** Mock 子游戏：捕获所有钩子调用。 */
+class MockGame implements IGameModule {
+  readonly route = 'mock-game';
+  events: string[] = [];
+
+  onEnter(_ctx: GameContext): void { this.events.push('onEnter'); }
+  onExit(): void { this.events.push('onExit'); }
+  onReceive(rpc: string, _data: unknown): void { this.events.push(`onReceive:${rpc}`); }
+  onReconnect(deskinfo: unknown): void { this.events.push('onReconnect'); void deskinfo; }
+  serialize(): unknown { return { mock: 'snapshot' }; }
+
+  // 默认空钩子测试
+  onPlayerJoin(seat: number): void { this.events.push(`onPlayerJoin:${seat}`); }
+  onPlayerLeave(seat: number): void { this.events.push(`onPlayerLeave:${seat}`); }
+  onReady(seat: number): void { this.events.push(`onReady:${seat}`); }
+  onDissolve(): void { this.events.push('onDissolve'); }
+  onOffline(seat: number): void { this.events.push(`onOffline:${seat}`); }
+}
+
+test('IGameModule 契约: 注册后 onEnter 触发', () => {
+  const { ctx } = makeContext();
+  const game = new MockGame();
+  game.onEnter(ctx);
+  assert.deepEqual(game.events, ['onEnter']);
+});
+
+test('IGameModule 契约: onReceive 接收 rpc + data', () => {
+  const { ctx } = makeContext();
+  const game = new MockGame();
+  game.onEnter(ctx);
+  game.onReceive('game_action', { x: 1 });
+  assert.deepEqual(game.events, ['onEnter', 'onReceive:game_action']);
+});
+
+test('IGameModule 契约: 平台钩子默认空实现不抛错(可选)', () => {
+  // 一个只实现必需钩子的子游戏
+  const minimal: IGameModule = {
+    route: 'minimal',
+    onEnter() { /* noop */ },
+    onExit() { /* noop */ },
+    onReceive(_rpc, _data) { /* noop */ },
+    onReconnect(_d) { /* noop */ },
+    // 钩子全部可选
+  };
+  // 编译通过 + 不抛错即通过
+  minimal.onPlayerJoin?.(1);
+  minimal.onPlayerLeave?.(2);
+  minimal.onReady?.(3);
+  minimal.onDissolve?.();
+  minimal.onOffline?.(4);
+});
+
+test('GameContext: 只暴露 ReadonlyPlayerStore 接口,不暴露 applyLogin', () => {
+  const { ctx } = makeContext();
+  // type 层面:ctx.player 是 ReadonlyPlayerStore 接口,没有 applyLogin
+  // 这里用类型断言模拟「如果按 ReadonlyPlayerStore 类型使用,applyLogin 应不存在」
+  type ReadonlyView = { readonly state: { readonly value: { playerid: number } } };
+  const view = ctx.player as unknown as ReadonlyView;
+  assert.equal(view.state.value.playerid, 0);
+  // 通过 keyof 验证:ReadonlyPlayerStore 接口暴露的方法只有 state getter
+  type ExposedKeys = keyof typeof ctx.player;
+  assert.ok('state' in ctx.player, 'state 是公开字段');
+});
+
+test('GameContext.net.send: 受限接口,不暴露 transport / ws_tcp / start', () => {
+  const { ctx, sent } = makeContext();
+  ctx.net.send('agent', 'join_table', { roomcode: 'R1' });
+  assert.deepEqual(sent, [{ route: 'agent', rpc: 'join_table', data: { roomcode: 'R1' } }]);
+  // 不应有 transport / ws_tcp / start
+  assert.equal((ctx.net as any).transport, undefined);
+  assert.equal((ctx.net as any).start, undefined);
+});
+
+test('GameContext.seat.toView: 替代旧 ChangeToStatus', () => {
+  const { ctx } = makeContext();
+  // 旧 ChangeToStatus 语义(已存在 core/seat.ts): 自己=0,其余环形顺延
+  assert.equal(ctx.seat.toView(0, 0, 4), 0); // 自己=自己
+  assert.equal(ctx.seat.toView(0, 1, 4), 1); // 右手位
+  assert.equal(ctx.seat.toView(0, 3, 4), 3); // 左手位
+  // 跨玩家视角:玩家 2 看玩家 0,2 应当是 2(view seat),0 应当是 -2 mod 4 = 2(实际为反向)
+  assert.equal(ctx.seat.fromView(2, 0, 4), 2); // 验证 fromView 反运算
+});
+
+test('IGameModule.route 必须等于自己的 game route（框架 Router 据此分发）', () => {
+  const game = new MockGame();
+  assert.equal(game.route, 'mock-game');
+});
+
+test('serialize 返回对局快照(断线重连用)', () => {
+  const game = new MockGame();
+  assert.deepEqual(game.serialize(), { mock: 'snapshot' });
+});
@@ -0,0 +1,92 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createStoreBinder } from '../../YouleNexus/assets/framework/ui/store-binder.ts';
+import { signal } from '../../YouleNexus/assets/framework/core/reactive.ts';
+
+test('createStoreBinder.bind: 订阅 store 后,值变化时 callback 触发', () => {
+  const store = signal({ name: 'init' });
+  const b = createStoreBinder();
+  let got: string | null = null;
+  b.bind(store, 'state', (s) => { got = s.name; });
+  assert.equal(got, 'init', '首次同步调用一次');
+  store.value = { name: 'changed' };
+  assert.equal(got, 'changed');
+});
+
+test('createStoreBinder.bind: 不同 slot 独立', () => {
+  const store1 = signal(1);
+  const store2 = signal('x');
+  const b = createStoreBinder();
+  const got: Array<number | string> = [];
+  b.bind(store1, 'a', (v) => got.push(v));
+  b.bind(store2, 'b', (v) => got.push(v));
+  assert.deepEqual(got, [1, 'x']);
+  got.length = 0;
+  store1.value = 2;
+  assert.deepEqual(got, [2]);
+});
+
+test('createStoreBinder.unbindAll: 退订后 store 变化不再触发 callback', () => {
+  const store = signal({ x: 0 });
+  const b = createStoreBinder();
+  let count = 0;
+  b.bind(store, 'state', () => { count++; });
+  assert.equal(count, 1);
+  store.value = { x: 1 };
+  assert.equal(count, 2);
+  b.unbindAll();
+  store.value = { x: 2 };
+  assert.equal(count, 2, '退订后不再触发');
+});
+
+test('createStoreBinder: 多次 bind 的 unbindAll 全部退订', () => {
+  const a = signal(1);
+  const b = signal(2);
+  const binder = createStoreBinder();
+  let na = 0, nb = 0;
+  binder.bind(a, 'a', () => na++);
+  binder.bind(b, 'b', () => nb++);
+  assert.equal(na, 1);
+  assert.equal(nb, 1);
+  binder.unbindAll();
+  a.value = 10;
+  b.value = 20;
+  assert.equal(na, 1);
+  assert.equal(nb, 1);
+});
+
+test('createStoreBinder: bind 同一 store 多次,各 callback 都触发', () => {
+  const store = signal(0);
+  const b = createStoreBinder();
+  let a = 0, b2 = 0;
+  b.bind(store, 'x', () => a++);
+  b.bind(store, 'y', () => b2++);
+  assert.equal(a, 1);
+  assert.equal(b2, 1);
+  store.value = 1;
+  assert.equal(a, 2);
+  assert.equal(b2, 2);
+});
+
+test('createStoreBinder.unbindAll: 重复调用安全(幂等)', () => {
+  const store = signal(0);
+  const b = createStoreBinder();
+  let n = 0;
+  b.bind(store, 's', () => n++);
+  b.unbindAll();
+  b.unbindAll(); // 不抛错
+  store.value = 1;
+  assert.equal(n, 1);
+});
+
+test('createStoreBinder.bind: callback 抛错不影响其它订阅者与下次 bind', () => {
+  const store = signal(0);
+  const b = createStoreBinder();
+  let reached = false;
+  b.bind(store, 'a', () => { throw new Error('boom'); });
+  b.bind(store, 'b', () => { reached = true; });
+  // 首次同步调用 + 第二次同步触发都不会让 binder 崩溃
+  assert.equal(reached, true);
+  store.value = 1;
+  assert.equal(reached, true);
+});
@@ -0,0 +1,43 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { DEFAULT_THEME } from '../../YouleNexus/assets/framework/ui/theme/default-theme.ts';
+import { resolveTheme } from '../../YouleNexus/assets/framework/ui/theme/resolve-theme.ts';
+import { ThemeProvider } from '../../YouleNexus/assets/framework/ui/theme/theme-provider.ts';
+
+test('resolveTheme 不传配置时返回默认主题', () => {
+  const t = resolveTheme();
+  assert.deepEqual(t, DEFAULT_THEME);
+});
+
+test('resolveTheme 只覆盖给出的字段，其余取默认', () => {
+  const t = resolveTheme({ colors: { primary: '#C8102E' } });
+  assert.equal(t.colors.primary, '#C8102E');
+  assert.equal(t.colors.accent, DEFAULT_THEME.colors.accent);
+  assert.equal(t.fonts.sizeBody, DEFAULT_THEME.fonts.sizeBody);
+  assert.equal(t.layout.myInfoAnchorX, DEFAULT_THEME.layout.myInfoAnchorX);
+});
+
+test('resolveTheme 分组独立合并，互不影响', () => {
+  const t = resolveTheme({ layout: { myInfoAnchorX: 130 } });
+  assert.equal(t.layout.myInfoAnchorX, 130);
+  assert.equal(t.layout.nicknameMaxChars, DEFAULT_THEME.layout.nicknameMaxChars);
+  assert.deepEqual(t.colors, DEFAULT_THEME.colors);
+});
+
+test('resolveTheme 不修改 DEFAULT_THEME 本身', () => {
+  const before = DEFAULT_THEME.colors.primary;
+  resolveTheme({ colors: { primary: '#000000' } });
+  assert.equal(DEFAULT_THEME.colors.primary, before);
+});
+
+test('ThemeProvider 未 init 就读取会抛错（第二准则：不兜底）', () => {
+  ThemeProvider.reset();
+  assert.throws(() => ThemeProvider.get(), /未初始化/);
+});
+
+test('ThemeProvider init 后可读回同一份主题', () => {
+  ThemeProvider.reset();
+  const t = resolveTheme({ colors: { primary: '#123456' } });
+  ThemeProvider.init(t);
+  assert.equal(ThemeProvider.get().colors.primary, '#123456');
+});