Merge branch 'codex/dev' into codex/backend-rewrite-spacetimedb

# Conflicts:
#	docs/technical/README.md
#	server-node/src/modules/assets/qwenSpriteRoutes.ts
#	src/components/CustomWorldResultView.test.tsx
#	src/components/CustomWorldResultView.tsx
#	src/components/custom-world-agent/CustomWorldAgentDraftDetailPanel.tsx
#	src/components/game-shell/PreGameSelectionFlow.agent.interaction.test.tsx
#	src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModalImpl.tsx
#	src/components/rpg-creation-editor/RpgCreationEntityEditorShared.tsx
#	src/components/rpg-entry/RpgEntryCharacterSelectView.tsx
#	src/components/rpg-entry/RpgEntryHomeView.tsx
#	src/services/apiClient.ts
#	src/tools/QwenSpriteSheetTool.tsx

src/services/apiClient.test.ts

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import {
+  AUTH_STATE_EVENT,
   ApiClientError,
   clearStoredAccessToken,
   fetchWithApiAuth,
@@ -9,21 +10,21 @@ import {
   setStoredAccessToken,
 } from './apiClient';
 
-function createMemoryStorage() {
-  const values = new Map<string, string>();
+function createLocalStorageMock() {
+  const store = new Map<string, string>();
 
   return {
     getItem(key: string) {
-      return values.has(key) ? values.get(key)! : null;
+      return store.has(key) ? store.get(key)! : null;
     },
     setItem(key: string, value: string) {
-      values.set(key, value);
+      store.set(key, String(value));
     },
     removeItem(key: string) {
-      values.delete(key);
+      store.delete(key);
     },
     clear() {
-      values.clear();
+      store.clear();
     },
   };
 }
@@ -54,50 +55,21 @@ function createResponseMock(params: {
 
 describe('apiClient', () => {
   const fetchMock = vi.fn();
+  const dispatchEventMock = vi.fn();
 
   beforeEach(() => {
     vi.stubGlobal('fetch', fetchMock);
     vi.stubGlobal('window', {
-      localStorage: createMemoryStorage(),
-      dispatchEvent: vi.fn(),
+      dispatchEvent: dispatchEventMock,
+      localStorage: createLocalStorageMock(),
     });
     fetchMock.mockReset();
-    clearStoredAccessToken();
+    dispatchEventMock.mockReset();
+    clearStoredAccessToken({ emit: false });
   });
 
-  it('attaches auth headers and clears stale tokens on unauthorized responses', async () => {
-    setStoredAccessToken('jwt-token');
-    fetchMock
-      .mockResolvedValueOnce(createResponseMock({ status: 401 }))
-      .mockResolvedValueOnce(createResponseMock({ status: 401 }));
-
-    const response = await fetchWithApiAuth('/api/protected', { method: 'GET' });
-
-    expect(response.status).toBe(401);
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(fetchMock).toHaveBeenCalledWith(
-      '/api/protected',
-      expect.objectContaining({
-        credentials: 'same-origin',
-        headers: expect.objectContaining({
-          Authorization: 'Bearer jwt-token',
-          'x-genarrative-response-envelope': 'v1',
-        }),
-      }),
-    );
-    expect(fetchMock).toHaveBeenNthCalledWith(
-      2,
-      '/api/auth/refresh',
-      expect.objectContaining({
-        method: 'POST',
-        credentials: 'same-origin',
-      }),
-    );
-    expect(getStoredAccessToken()).toBe('');
-  });
-
-  it('refreshes the access token once and retries the original request', async () => {
-    setStoredAccessToken('expired-token');
+  it('refreshes bearer token once and retries the original request', async () => {
+    setStoredAccessToken('expired-token', { emit: false });
     fetchMock
       .mockResolvedValueOnce(createResponseMock({ status: 401 }))
       .mockResolvedValueOnce(
@@ -106,6 +78,7 @@ describe('apiClient', () => {
           body: JSON.stringify({
             ok: true,
             data: {
+              ok: true,
               token: 'fresh-token',
             },
             error: null,
@@ -138,41 +111,113 @@ describe('apiClient', () => {
     );
 
     expect(result).toEqual({ value: 7 });
-    expect(getStoredAccessToken()).toBe('fresh-token');
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      1,
+      '/api/runtime/protected',
+      expect.objectContaining({
+        credentials: 'same-origin',
+        headers: expect.objectContaining({
+          Authorization: 'Bearer expired-token',
+          'x-genarrative-response-envelope': 'v1',
+        }),
+      }),
+    );
     expect(fetchMock).toHaveBeenNthCalledWith(
       2,
       '/api/auth/refresh',
       expect.objectContaining({
         method: 'POST',
+        credentials: 'same-origin',
       }),
     );
     expect(fetchMock).toHaveBeenNthCalledWith(
       3,
       '/api/runtime/protected',
       expect.objectContaining({
+        credentials: 'same-origin',
         headers: expect.objectContaining({
           Authorization: 'Bearer fresh-token',
         }),
       }),
     );
+    expect(dispatchEventMock).toHaveBeenCalledTimes(1);
+    expect(dispatchEventMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: AUTH_STATE_EVENT,
+      }),
+    );
+    expect(getStoredAccessToken()).toBe('fresh-token');
   });
 
-  it('does not refresh or emit auth changes for 401 responses without auth context', async () => {
+  it('does not emit auth change events when 401 probe requests opt into silent mode', async () => {
     fetchMock.mockResolvedValueOnce(createResponseMock({ status: 401 }));
 
+    const response = await fetchWithApiAuth(
+      '/api/auth/me',
+      {
+        method: 'GET',
+      },
+      {
+        notifyAuthStateChange: false,
+        skipRefresh: true,
+      },
+    );
+
+    expect(response.status).toBe(401);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(dispatchEventMock).not.toHaveBeenCalled();
+  });
+
+  it('emits auth change events when refresh fails on protected requests', async () => {
+    setStoredAccessToken('expired-token', { emit: false });
+    fetchMock
+      .mockResolvedValueOnce(createResponseMock({ status: 401 }))
+      .mockResolvedValueOnce(createResponseMock({ status: 401 }));
+
     const response = await fetchWithApiAuth('/api/runtime/protected', {
       method: 'GET',
     });
 
     expect(response.status).toBe(401);
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-    expect(fetchMock).toHaveBeenCalledWith(
-      '/api/runtime/protected',
-      expect.objectContaining({
-        credentials: 'same-origin',
-      }),
-    );
-    expect(window.dispatchEvent).not.toHaveBeenCalled();
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(dispatchEventMock).toHaveBeenCalledTimes(1);
+    expect(getStoredAccessToken()).toBe('');
+  });
+
+  it('rejects refresh responses that do not return a renewed bearer token', async () => {
+    setStoredAccessToken('expired-token', { emit: false });
+    fetchMock
+      .mockResolvedValueOnce(createResponseMock({ status: 401 }))
+      .mockResolvedValueOnce(
+        createResponseMock({
+          status: 200,
+          body: JSON.stringify({
+            ok: true,
+            data: {
+              ok: true,
+            },
+            error: null,
+            meta: {
+              apiVersion: '2026-04-08',
+            },
+          }),
+        }),
+      );
+
+    await expect(
+      requestJson<{ value: number }>(
+        '/api/runtime/protected',
+        { method: 'GET' },
+        '读取受保护数据失败',
+      ),
+    ).rejects.toMatchObject({
+      status: 401,
+      message: '读取受保护数据失败',
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(getStoredAccessToken()).toBe('');
+    expect(dispatchEventMock).toHaveBeenCalledTimes(1);
   });
 
   it('keeps the current access token when a public request explicitly skips auth', async () => {
@@ -191,6 +236,14 @@ describe('apiClient', () => {
 
     expect(response.status).toBe(401);
     expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock).toHaveBeenCalledWith(
+      '/api/runtime/custom-world-gallery',
+      expect.objectContaining({
+        headers: expect.not.objectContaining({
+          Authorization: expect.any(String),
+        }),
+      }),
+    );
     expect(getStoredAccessToken()).toBe('still-valid-token');
     expect(window.dispatchEvent).not.toHaveBeenCalled();
   });