Merge remote-tracking branch 'origin/master' into feat/agc-llm-router-official-chain

apps/ai-game-creator-shell/src/features/ui-editor/components/SpriteImagePreview.tsx

@@ -1,3 +1,6 @@
+export const SPRITE_CHECKERBOARD_CLASS_NAME =
+  'bg-[linear-gradient(45deg,#eee_25%,transparent_25%),linear-gradient(-45deg,#eee_25%,transparent_25%),linear-gradient(45deg,transparent_75%,#eee_75%),linear-gradient(-45deg,transparent_75%,#eee_75%)] bg-[length:14px_14px]';
+
 export function SpriteImagePreview({
   src,
   alt,

apps/ai-game-creator-shell/src/view/ui-editor/components/InputSidebar.tsx

@@ -1,6 +1,7 @@
 import { Image as ImageIcon, Plus, Type } from 'lucide-react';
 import { useMemo } from 'react';
 
+import { SPRITE_CHECKERBOARD_CLASS_NAME } from '../../../features/ui-editor/components/SpriteImagePreview';
 import { visitUiNodes } from '../../../features/ui-editor/treeUtils';
 import type { Node as UiNode } from '../../../features/ui-editor/types/Node';
 import type { NodeId } from '../../../features/ui-editor/types/NodeId';
@@ -184,7 +185,7 @@ export function InputSidebar({ input }: { input: UiEditorInputProjection }) {
             <button
               key={sprite.asset_id}
               type="button"
-              className="relative aspect-square overflow-hidden rounded-lg border border-(--platform-subpanel-border) bg-[linear-gradient(45deg,#eee_25%,transparent_25%),linear-gradient(-45deg,#eee_25%,transparent_25%),linear-gradient(45deg,transparent_75%,#eee_75%),linear-gradient(-45deg,transparent_75%,#eee_75%)] bg-[length:14px_14px]"
+              className={`relative aspect-square overflow-hidden rounded-lg border border-(--platform-subpanel-border) ${SPRITE_CHECKERBOARD_CLASS_NAME}`}
               title={`${sprite.metadata.name} · 引用 ${spriteReferenceCounts[sprite.asset_id] ?? 0}`}
               onClick={() => input.selectSprite(sprite.asset_id)}
             >

apps/ai-game-creator-shell/src/view/ui-editor/components/Inspector/Components/ComponentPanel.tsx

@@ -293,6 +293,7 @@ function renderComponentEditor(
         <ImagePanel
           component={component.Image}
           sprites={props.sprites}
+          previewUrls={props.previewUrls}
           readOnly={readOnly}
           onChange={(next) => updateComponent(index, { Image: next })}
         />

apps/ai-game-creator-shell/src/view/ui-editor/components/Inspector/Components/ImageAssetSelector.tsx

@@ -0,0 +1,165 @@
+import { Check, ImageIcon, X } from 'lucide-react';
+import { useState } from 'react';
+
+import { ThemedModal } from '../../../../../components/modal/ThemedModal';
+import { SPRITE_CHECKERBOARD_CLASS_NAME } from '../../../../../features/ui-editor/components/SpriteImagePreview';
+import type { SpriteAsset } from '../../../../../features/ui-editor/types/SpriteAsset';
+
+export function ImageAssetSelector({
+  value,
+  sprites,
+  previewUrls,
+  readOnly,
+  onChange,
+}: {
+  value: string | null;
+  sprites: Record<string, SpriteAsset>;
+  previewUrls: Record<string, string>;
+  readOnly: boolean;
+  onChange: (value: string | null) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const [failedPreviewUrls, setFailedPreviewUrls] = useState<
+    Record<string, string>
+  >({});
+  const selectedSprite = value ? sprites[value] : undefined;
+  let selectedLabel = '未绑定';
+  if (selectedSprite) {
+    selectedLabel = selectedSprite.metadata.name || value || '未绑定';
+  } else if (value) {
+    selectedLabel = `素材不存在（${value}）`;
+  }
+  const buttonLabel = value ? '更换素材' : '选择素材';
+
+  function close() {
+    setOpen(false);
+  }
+
+  function select(nextValue: string | null) {
+    onChange(nextValue);
+    close();
+  }
+
+  function markPreviewFailed(id: string, url: string) {
+    setFailedPreviewUrls((current) => {
+      if (current[id] === url) return current;
+      return { ...current, [id]: url };
+    });
+  }
+
+  return (
+    <>
+      <div className="block text-[11px] font-semibold text-(--platform-text-soft)">
+        目标素材
+        <div className="mt-1 flex items-center gap-2">
+          <div
+            className={`min-w-0 flex-1 truncate rounded-lg border border-(--platform-subpanel-border) bg-white/65 px-2 py-2 text-xs ${value && !selectedSprite ? 'text-red-600' : 'text-(--platform-text-strong)'}`}
+            title={selectedLabel}
+          >
+            {selectedLabel}
+          </div>
+          <button
+            type="button"
+            className="h-9 shrink-0 rounded-lg border border-orange-200 bg-orange-50 px-3 text-xs font-semibold text-orange-800 disabled:cursor-not-allowed disabled:opacity-40"
+            disabled={readOnly}
+            onClick={() => setOpen(true)}
+          >
+            {buttonLabel}
+          </button>
+        </div>
+      </div>
+
+      <ThemedModal
+        open={open}
+        onClose={close}
+        ariaLabel="选择图片素材"
+        panelClassName="flex max-h-[80vh] w-[720px] max-w-[calc(100vw-2rem)] flex-col rounded-2xl p-5"
+      >
+        <div className="flex items-center justify-between gap-3">
+          <h2 className="m-0 text-base font-semibold">选择图片素材</h2>
+          <button
+            type="button"
+            className="grid size-8 place-items-center rounded-lg text-(--platform-text-soft) hover:bg-black/5"
+            aria-label="关闭素材选择器"
+            onClick={close}
+          >
+            <X size={16} aria-hidden="true" />
+          </button>
+        </div>
+
+        <div className="mt-4 min-h-0 flex-1 overflow-y-auto pr-1">
+          <div className="grid grid-cols-[repeat(auto-fit,minmax(150px,1fr))] gap-3">
+            <button
+              type="button"
+              className={`flex min-h-36 flex-col items-center justify-center rounded-xl border border-dashed p-3 text-xs ${value === null ? 'border-orange-400 bg-orange-50 text-orange-800' : 'border-(--platform-subpanel-border) bg-white/45 text-(--platform-text-soft)'}`}
+              aria-pressed={value === null}
+              onClick={() => select(null)}
+            >
+              <X size={22} aria-hidden="true" />
+              <span className="mt-2 font-semibold">清除选择</span>
+              <span className="mt-1 text-[10px]">不绑定图片素材</span>
+            </button>
+
+            {value && !selectedSprite ? (
+              <div className="flex min-h-36 flex-col items-center justify-center rounded-xl border border-red-200 bg-red-50 p-3 text-center text-xs text-red-700">
+                <ImageIcon size={22} aria-hidden="true" />
+                <span className="mt-2 font-semibold">素材不存在</span>
+                <span className="mt-1 break-all text-[10px]">{value}</span>
+              </div>
+            ) : null}
+
+            {Object.entries(sprites).map(([id, sprite]) => {
+              const previewUrl = previewUrls[id];
+              const hasPreview =
+                Boolean(previewUrl) && failedPreviewUrls[id] !== previewUrl;
+              const selected = value === id;
+              return (
+                <button
+                  key={id}
+                  type="button"
+                  className={`relative overflow-hidden rounded-xl border p-2 text-left transition ${selected ? 'border-orange-400 bg-orange-50 ring-2 ring-orange-200' : 'border-(--platform-subpanel-border) bg-white/45 hover:border-orange-200'}`}
+                  aria-pressed={selected}
+                  onClick={() => select(id)}
+                >
+                  <div
+                    className={`grid aspect-[4/3] place-items-center overflow-hidden rounded-lg ${SPRITE_CHECKERBOARD_CLASS_NAME}`}
+                  >
+                    {hasPreview ? (
+                      <img
+                        src={previewUrl}
+                        alt={sprite.metadata.name || id}
+                        className="size-full object-contain"
+                        onError={() => {
+                          if (previewUrl) markPreviewFailed(id, previewUrl);
+                        }}
+                      />
+                    ) : (
+                      <ImageIcon
+                        size={24}
+                        className="text-(--platform-text-soft)"
+                        aria-hidden="true"
+                      />
+                    )}
+                  </div>
+                  <span className="mt-2 block truncate text-xs font-semibold text-(--platform-text-strong)">
+                    {sprite.metadata.name || id}
+                  </span>
+                  {selected ? (
+                    <span className="absolute right-2 top-2 grid size-6 place-items-center rounded-full bg-orange-500 text-white">
+                      <Check size={14} aria-hidden="true" />
+                    </span>
+                  ) : null}
+                </button>
+              );
+            })}
+          </div>
+          {Object.keys(sprites).length === 0 ? (
+            <p className="m-0 py-10 text-center text-xs text-(--platform-text-soft)">
+              暂无可用素材
+            </p>
+          ) : null}
+        </div>
+      </ThemedModal>
+    </>
+  );
+}

apps/ai-game-creator-shell/src/view/ui-editor/components/Inspector/Components/ImagePanel.tsx

@@ -4,10 +4,12 @@ import type { ImageType } from '../../../../../features/ui-editor/types/ImageTyp
 import type { UiEditorOperationResult } from '../../../../../features/ui-editor/useUiEditorState';
 import type { ImageEditorProps } from './componentEditorTypes';
 import { ComponentNumberInput, ComponentSelect } from './ComponentField';
+import { ImageAssetSelector } from './ImageAssetSelector';
 
 export function ImagePanel({
   component,
   sprites,
+  previewUrls,
   readOnly,
   onChange,
 }: ImageEditorProps) {
@@ -17,24 +19,13 @@ export function ImagePanel({
 
   return (
     <div className="space-y-3">
-      <ComponentSelect
-        label="目标素材"
-        value={component.target_graphic ?? ''}
-        disabled={readOnly}
-        onChange={(event) =>
-          update({
-            ...component,
-            target_graphic: event.target.value || null,
-          })
-        }
-      >
-        <option value="">未绑定</option>
-        {Object.entries(sprites).map(([id, sprite]) => (
-          <option key={id} value={id}>
-            {sprite.metadata.name || id}
-          </option>
-        ))}
-      </ComponentSelect>
+      <ImageAssetSelector
+        value={component.target_graphic}
+        sprites={sprites}
+        previewUrls={previewUrls}
+        readOnly={readOnly}
+        onChange={(target_graphic) => update({ ...component, target_graphic })}
+      />
 
       <ComponentSelect
         label="图片类型"

apps/ai-game-creator-shell/src/view/ui-editor/components/Inspector/Components/componentEditorTypes.ts

@@ -9,6 +9,7 @@ import type { UiEditorOperationResult } from '../../../../../features/ui-editor/
 export type ComponentPanelProps = {
   components: Component[];
   sprites: Record<string, SpriteAsset>;
+  previewUrls: Record<string, string>;
   fonts: Record<string, FontAsset>;
   fontFaces: Record<string, UiEditorFontFaceState>;
   projectPath: string;
@@ -35,6 +36,7 @@ export type ComponentEditorProps<T> = {
 
 export type ImageEditorProps = ComponentEditorProps<ImageComponent> & {
   sprites: Record<string, SpriteAsset>;
+  previewUrls: Record<string, string>;
 };
 
 export type TextEditorProps = ComponentEditorProps<TextComponent> & {

apps/ai-game-creator-shell/src/view/ui-editor/components/Inspector/InspectorSidebar.tsx

@@ -111,6 +111,7 @@ export function InspectorSidebar({
           onTransformChange={inspector.setNodeTransform}
           onLayoutChange={inspector.setNodeLayout}
           sprites={inspector.sprites}
+          previewUrls={inspector.previewUrls}
           fonts={inspector.fonts}
           fontFaces={inspector.fontFaces}
           projectPath={inspector.projectPath}
@@ -288,6 +289,7 @@ function NodeInspector({
   onTransformChange,
   onLayoutChange,
   sprites,
+  previewUrls,
   fonts,
   fontFaces,
   projectPath,
@@ -317,6 +319,7 @@ function NodeInspector({
   onTransformChange: UiEditorInspectorProjection['setNodeTransform'];
   onLayoutChange: UiEditorInspectorProjection['setNodeLayout'];
   sprites: UiEditorInspectorProjection['sprites'];
+  previewUrls: UiEditorInspectorProjection['previewUrls'];
   fonts: UiEditorInspectorProjection['fonts'];
   fontFaces: UiEditorInspectorProjection['fontFaces'];
   projectPath: string;
@@ -497,6 +500,7 @@ function NodeInspector({
       <ComponentPanel
         components={node.components}
         sprites={sprites}
+        previewUrls={previewUrls}
         fonts={fonts}
         fontFaces={fontFaces}
         projectPath={projectPath}

apps/ai-game-creator-shell/tests/imageAssetSelector.test.tsx

@@ -0,0 +1,161 @@
+/** @vitest-environment jsdom */
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  within,
+} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { ImageAssetSelector } from '../src/view/ui-editor/components/Inspector/Components/ImageAssetSelector';
+
+const sprites = {
+  hero: {
+    asset_id: 'hero',
+    metadata: { name: '主角', asset_type: 'sprite' },
+    path: 'assets/hero.png',
+    pixel_size: [32, 32] as [number, number],
+    pixels_per_unit: 1,
+    border: { left: 0, right: 0, top: 0, bottom: 0 },
+  },
+  enemy: {
+    asset_id: 'enemy',
+    metadata: { name: '敌人', asset_type: 'sprite' },
+    path: 'assets/enemy.png',
+    pixel_size: [32, 32] as [number, number],
+    pixels_per_unit: 1,
+    border: { left: 0, right: 0, top: 0, bottom: 0 },
+  },
+};
+
+function renderSelector(
+  value: string | null = null,
+  onChange = vi.fn(),
+  previewUrls: Record<string, string> = {},
+  selectorSprites: typeof sprites = sprites,
+) {
+  return render(
+    <ImageAssetSelector
+      value={value}
+      sprites={selectorSprites}
+      previewUrls={previewUrls}
+      readOnly={false}
+      onChange={onChange}
+    />,
+  );
+}
+
+describe('ImageAssetSelector', () => {
+  afterEach(() => cleanup());
+
+  it('selects a sprite and clears the selection from the modal', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    renderSelector(null, onChange);
+
+    await user.click(screen.getByRole('button', { name: '选择素材' }));
+    expect(screen.getByRole('dialog', { name: '选择图片素材' })).toBeTruthy();
+    await user.click(screen.getByRole('button', { name: /主角/ }));
+    expect(onChange).toHaveBeenCalledWith('hero');
+    expect(screen.queryByRole('dialog')).toBeNull();
+
+    await user.click(screen.getByRole('button', { name: '选择素材' }));
+    await user.click(screen.getByRole('button', { name: /清除选择/ }));
+    expect(onChange).toHaveBeenLastCalledWith(null);
+  });
+
+  it('shows preview images, placeholders, and invalid references', async () => {
+    const user = userEvent.setup();
+    renderSelector('missing', vi.fn(), { hero: 'data:image/png;base64,abc' });
+
+    expect(screen.getByText('素材不存在（missing）')).toBeTruthy();
+    await user.click(screen.getByRole('button', { name: '更换素材' }));
+    const dialog = screen.getByRole('dialog', { name: '选择图片素材' });
+    expect(within(dialog).getByAltText('主角')).toBeTruthy();
+    expect(within(dialog).getByText('素材不存在')).toBeTruthy();
+    expect(
+      within(dialog).getByRole('button', { name: /清除选择/ }),
+    ).toBeTruthy();
+  });
+
+  it('cannot open while read only', () => {
+    render(
+      <ImageAssetSelector
+        value="hero"
+        sprites={sprites}
+        previewUrls={{}}
+        readOnly
+        onChange={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: '更换素材' })).toHaveProperty(
+      'disabled',
+      true,
+    );
+  });
+
+  it('retries a preview when its URL is regenerated', async () => {
+    const user = userEvent.setup();
+    const view = renderSelector(null, vi.fn(), {
+      hero: 'data:image/png;base64,first',
+    });
+
+    await user.click(screen.getByRole('button', { name: '选择素材' }));
+    const dialog = screen.getByRole('dialog', { name: '选择图片素材' });
+    const image = within(dialog).getByAltText('主角');
+    fireEvent.error(image);
+    expect(within(dialog).queryByAltText('主角')).toBeNull();
+
+    view.rerender(
+      <ImageAssetSelector
+        value={null}
+        sprites={sprites}
+        previewUrls={{ hero: 'data:image/png;base64,regenerated' }}
+        readOnly={false}
+        onChange={vi.fn()}
+      />,
+    );
+
+    expect(
+      within(screen.getByRole('dialog', { name: '选择图片素材' })).getByAltText(
+        '主角',
+      ),
+    ).toBeTruthy();
+  });
+
+  it('supports keyboard activation for sprite cards', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    renderSelector(null, onChange);
+    await user.click(screen.getByRole('button', { name: '选择素材' }));
+    const hero = screen.getByRole('button', { name: /主角/ });
+    hero.focus();
+    await user.keyboard('{Enter}');
+    expect(onChange).toHaveBeenCalledWith('hero');
+  });
+
+  it('closes when the modal backdrop is clicked', async () => {
+    const user = userEvent.setup();
+    renderSelector();
+    await user.click(screen.getByRole('button', { name: '选择素材' }));
+    const dialog = screen.getByRole('dialog', { name: '选择图片素材' });
+    const overlay = dialog.parentElement;
+    expect(overlay).toBeTruthy();
+    await user.click(overlay!);
+    expect(screen.queryByRole('dialog', { name: '选择图片素材' })).toBeNull();
+  });
+
+  it('shows an empty state when no sprites are available', async () => {
+    const user = userEvent.setup();
+    renderSelector(null, vi.fn(), {}, {});
+    await user.click(screen.getByRole('button', { name: '选择素材' }));
+    const dialog = screen.getByRole('dialog', { name: '选择图片素材' });
+    expect(within(dialog).getByText('暂无可用素材')).toBeTruthy();
+    expect(
+      within(dialog).getByRole('button', { name: /清除选择/ }),
+    ).toBeTruthy();
+  });
+});

docs/technical/【前端架构】UI编辑会话模块边界-2026-08-19.md

@@ -15,6 +15,8 @@
 
 预览树在会话边界归一化为 `UITree | null`：尚未选择界面图、正在加载或尚未识别树时均以 `null` 表示，不能把 `Array.find` 的 `undefined` 传播到视图接口。
 
+素材缩略图的加载失败状态按“素材 ID + 预览 URL”记录；同一 URL 失败后显示占位图，资源重新加载或重新导入产生新 URL 时必须允许再次尝试，不能把失败永久绑定到素材 ID。
+
 保存与代码生成共享同一份持久化 State/revision。会话层在保存或生成进行期间互斥拦截，且代码生成必须基于已加载的持久化 revision；视图层的保存按钮和“保存并返回”按钮同步遵守该互斥状态。
 
 `UiDesignStateStore` 的 `generateCode(assetId)` 是必需能力，返回成功结果时不得为 nullable；所有注入的 adapter 与测试替身都必须实现该方法。

docs/technical/【前端设计】UI编辑器图片素材选择器-2026-09-03.md

@@ -0,0 +1,41 @@
+# UI 编辑器图片素材选择器
+
+> 更新时间：`2026-09-03`
+
+## 目标
+
+在 UI 编辑器 Inspector 的图片组件中，用独立 modal 图片选择器替换原生素材下拉框，使用户绑定素材时可以看到现有预览图或缩略图。
+
+## 数据来源与边界
+
+- 素材列表继续使用 Inspector 当前的 `sprites`，顺序沿用 `Object.entries(sprites)`。
+- `SpriteAsset` 不新增缩略图字段。预览继续消费 UI 编辑会话已有的 `previewUrls: Record<string, string>`；预览缺失不影响素材绑定。
+- `previewUrls` 由 Inspector projection 沿 `NodeInspector → ComponentPanel → ImagePanel` 传入选择器。
+- 本次不新增后端接口、持久化字段、搜索筛选或二级大图预览。
+
+## 交互合同
+
+### Inspector 触发区域
+
+- 正常绑定显示素材名称。
+- 空值显示 `未绑定`。
+- 引用不存在的素材显示 `素材不存在（<ID>）`，保留原 ID，不在打开面板时自动清除。
+- 未绑定时按钮文案为 `选择素材`；已有绑定或失效引用时为 `更换素材`。
+- `readOnly` 时按钮禁用，不能打开选择器。
+
+### 素材选择 modal
+
+- 使用现有 `ThemedModal`，带遮罩、关闭按钮、Esc 关闭和点击遮罩关闭。
+- modal 内容使用纵向 flex；素材区域占据剩余空间并内部滚动，modal 设置最大高度。
+- 素材以弹性网格展示，卡片包含预览图和素材名称，图片使用 `object-contain`。
+- 有预览时显示 `previewUrls[id]`；无预览或加载失败时显示棋盘格背景与 `ImageIcon` 占位，素材仍可选。
+- 当前绑定项显示选中边框或标记。
+- 第一项为明确的“清除选择”，点击立即写入 `null` 并关闭。
+- 点击任意正常素材立即写入其 ID 并关闭；重复点击当前素材也按相同流程处理。
+- 当前失效引用保留为禁用信息卡，显示 ID；用户仍可使用“清除选择”。
+- 素材为空时显示 `暂无可用素材`，保留关闭操作。
+- 卡片支持 Tab 聚焦以及 Enter/Space 选择；关闭后焦点返回触发按钮。
+
+## 验收
+
+自动化测试覆盖：打开/关闭、按钮和名称状态、当前项高亮、选择 ID、清除 `null`、缺预览占位、失效引用、空列表、`readOnly` 禁止打开、键盘选择和遮罩关闭。实现后运行定向测试、前端类型检查、编码检查及 `git diff --check`。