koring-launcher/AGENTS.md

# koring-launcher

Minecraft launcher built with Electron + React 19 + TypeScript + Node.js (@xmcl).

## Quick commands

```bash
pnpm dev                # full app dev (renderer + main process)
pnpm dev:renderer       # frontend only (vite, port 1420)
pnpm dev:main           # electron main process only
pnpm build              # production build (vite + tsc)
pnpm dist:dev           # dev icon + Windows installer
pnpm dist:beta          # beta icon + Windows installer
pnpm dist:run           # production icon + Windows installer
```

## Architecture

- **Frontend** (`src/`): React 19 + Vite 7 + Tailwind v4 + shadcn/ui + Zustand stores
- **Main Process** (`electron/`): Node.js/TypeScript, manages windows, IPC handlers, @xmcl/* packages
- **Icon System** (`public/icons/{dev,beta,run}/`): Mode-specific icons, copied to `build/` at build time
- IPC: Frontend → `ipcRenderer.invoke()` → `ipcMain.handle()` → main process → `webContents.send()` → Frontend

## Key gotchas

- **Electron main process**: `electron/main.ts` is the entry point. All @xmcl/* packages run here.
- **Preload script**: `electron/preload.ts` exposes `window.electronAPI` via context bridge.
- **IPC handlers**: All handlers are in `electron/handlers/` directory.
- **Mutable win ref**: `electron/main.ts` uses a mutable `win` object — handlers read `win.mainWindow` at runtime, not at registration time.
- **Config**: YAML format (`Koring.yml`) stored in userData (packaged) / project root (dev). Sparse save (only non-default values). ⚠️ 不可放安装目录：NSIS 重装/升级会经旧卸载器删除整个安装目录。
- **Auth**: JSON file (`koring-auth.json`) stored in userData (packaged) / project root (dev).
- **Path alias**: `@/` maps to `src/` (configured in `vite.config.ts` and `tsconfig.json`).
- **Dev mode**: Vite runs on port 1420, Electron loads from localhost.
- **Asset paths**: Use `import.meta.env.BASE_URL` prefix for public assets. Absolute paths break in packaged app.

## Build & bundle

```bash
pnpm build              # Vite build + TypeScript compile
pnpm dist:dev           # switch-icon dev + electron-builder Windows installer
pnpm dist:beta          # switch-icon beta + electron-builder Windows installer
pnpm dist:run           # switch-icon run + electron-builder Windows installer
```

Each `dist:*` command runs: `pnpm build` → `pnpm icon:{mode}` → `electron-builder --win`

## Icon switching

```
public/icons/
  dev/icon.ico, icon.png
  beta/icon.ico, icon.png
  run/icon.ico, icon.png

build/                   ← generated by switch-icon.js (gitignored)
  icon.ico
  icon.png
```

`electron-builder.yml` uses `buildResources: build` to read icons from `build/`.

## Electron notes

- `electron/main.ts`: App entry, window management, splash→main transition (ready-to-show + 1.5s min)
- `electron/preload.ts`: Context bridge for secure IPC
- `electron/config.ts`: YAML config management (sparse save)
- `electron/auth.ts`: Auth data persistence (JSON file)
- `electron/core/`: @xmcl/* integrations (auth, installer, launcher, modrinth, instance)
- `electron/core/background-image.ts`: 背景图处理服务 —— 自选壁纸复制到 userData 并按屏幕尺寸降采样/重编码**落盘**，配置文件只存**文件路径**（不使用 BASE64）
- `electron/core/logger.ts`: 统一日志 —— 全局包装 `ipcMain.handle`（channel/耗时/成败）；开启 debug 模式（`config.advanced.debugMode`）后写 `userData/koring.log`（5MB 轮转），否则仅控制台；**dev（未打包）运行下日志直接写进程 stdout/stderr 输出到启动终端**；渲染端经 `log:write` 桥汇入
- `electron/resource-protocol.ts`: `koring-res://` 特权自定义协议 —— 渲染进程以「资源引用」流式读取本地壁纸；仅服务 userData 内 `background-custom*` 白名单文件（realpath 二次校验，防目录穿越）
- `electron/handlers/`: IPC handlers (config, auth, install, launch, mods, instance, background, task, system, window)

## Frontend notes

- `src/api/ipc.ts`: Core IPC utilities (invoke, onIpcEvent)
- `src/api/*.ts`: API modules wrapping IPC calls
- `src/stores/`: Zustand state management
- `src/resources/`: 启动器程序本体「资源管理」子系统（与游戏无关）：
  - `registry.ts` 资源注册表服务（acquire/release、引用计数、预算 + LRU 逐出、onRelease 释放回调）
  - `store.ts` 注册表 → zustand 镜像（调试面板消费）
  - `image.ts` 图片解码管线（按显示尺寸降采样）、`hooks.ts`/`ManagedImage.tsx` 复用组件（供列表缩略图）
  - 当前接线点：`BackgroundLayer` 把当前背景（dataURL 或 koring-res 引用）登记为 `background` 类资源；自选壁纸经 `background:import` 落盘、配置存文件路径、渲染端经 `background:resolve` 拿 `koring-res://` 引用（全程无 base64）
  - 监控入口：debug 页「资源与内存」(`debug-resource`)
- `src/hooks/useTheme.ts`: Dark mode sync with Electron theme
- `src/components/system/WindowControls.tsx`: Custom window controls (min/max/close), uses `<button>` with `WebkitAppRegion: "no-drag"`
- `src/components/system/TitleBar.tsx`: Custom title bar with navigation, uses `WebkitAppRegion: "drag"`
- `src/lib/mode.ts`: Build mode constants (`DEFAULT_BG`, `LOGO_SVG`, `APP_ICON`, `BUILD_MODE`)