@rexvane/piweb 0.3.19 → 0.3.21

package/src/components/SettingsPanel.tsx

@@ -32,9 +32,21 @@ import {
 	type CustomProviderSetup,
 } from "@/components/ProviderSetupModal";
 import { RemoteSection } from "@/components/RemoteSection";
+import { CopyCommand } from "@/components/update/CopyCommand";
+import { checkUpdate, loadUpdates, runUpdate, useUpdates, type UpdateTarget } from "@/components/update/update-store";
 import { useI18n } from "@/i18n";
 import { applyPebrelTheme, loadPebrelTheme, loadThemeMode, type PebrelTheme, type ThemeMode } from "@/lib/theme";
 import { applyFontChoice, CUSTOM_PREFIX, FONT_PRESETS, loadFontChoice } from "@/lib/font";
+import {
+	DEFAULT_STREAM_SETTINGS,
+	getStreamSettings,
+	setStreamSettings,
+	STREAM_SPEED_MAX,
+	STREAM_SPEED_MIN,
+	STREAM_STYLES,
+	type StreamSettings,
+	type StreamStyle,
+} from "@/lib/chat/stream-settings";
 import { modelDraftFromConfig, serializeProviderDraft, validateModelDrafts, type ModelDraft } from "@/lib/model-draft";
 import { customApiOptions } from "@/lib/provider-display";
 import { quotaWindowKind, supportsUsageProbe, type BalanceAmount, type BalanceDetailKey, type ProviderUsage, type QuotaWindow, type XaiUsage } from "@/lib/provider-usage";
@@ -174,6 +186,7 @@ function GeneralSection({
 	const [themeMode, setThemeMode] = useState<ThemeMode>("system");
 	const [fontSize, setFontSize] = useState(14);
 	const [chatFontSize, setChatFontSize] = useState(14);
+	const [stream, setStream] = useState<StreamSettings>(DEFAULT_STREAM_SETTINGS);
 	const [enterBehavior, setEnterBehavior] = useState<EnterBehavior>("steer");
 	const [piSettings, setPiSettings] = useState<{ compaction: { enabled: boolean; reserveTokens: number; keepRecentTokens: number }; retry: { enabled: boolean; maxRetries: number; baseDelayMs: number } } | null>(null);
 	const [versions, setVersions] = useState<{ piWeb: string; piEngine: string } | null>(null);
@@ -222,6 +235,8 @@ function GeneralSection({
 		if (!Number.isNaN(fs)) setFontSize(fs);
 		const chatFs = parseInt(localStorage.getItem("piweb.chatFontSize") ?? "14", 10);
 		if (!Number.isNaN(chatFs)) setChatFontSize(chatFs);
+		// 流式输出偏好与主题/字体同源（localStorage），同样等挂载后再读，避免水合不一致
+		setStream(getStreamSettings());
 		setEnterBehavior(getEnterBehavior());
 		void loadRemoteSettings();
 	}, []);
@@ -254,6 +269,9 @@ function GeneralSection({
 		document.documentElement.style.setProperty("--piweb-chat-font-size", `${v}px`);
 	};
 
+	/** 流式输出：样式 / 速度 / 光标。改完即持久化，正在流出的回答下一帧就换（订阅在 MarkdownBlock 里） */
+	const pickStream = (patch: Partial<StreamSettings>) => setStream(setStreamSettings(patch));
+
 	const pickEnter = (v: EnterBehavior) => {
 		setEnterBehavior(v);
 		saveEnterBehavior(v);
@@ -316,6 +334,20 @@ function GeneralSection({
 		{ id: "pebrel", label: t.themePebrel, light: "#F3F4F6", dark: "#0F111A", accent: "#52A8FF" },
 	];
 
+	const streamStyleText: Record<StreamStyle, { label: string; desc: string }> = {
+		smooth: { label: t.streamStyleSmooth, desc: t.streamStyleSmoothDesc },
+		typewriter: { label: t.streamStyleTypewriter, desc: t.streamStyleTypewriterDesc },
+		fade: { label: t.streamStyleFade, desc: t.streamStyleFadeDesc },
+		instant: { label: t.streamStyleInstant, desc: t.streamStyleInstantDesc },
+	};
+	const streamSpeedText: Record<number, string> = {
+		1: t.streamSpeed1,
+		2: t.streamSpeed2,
+		3: t.streamSpeed3,
+		4: t.streamSpeed4,
+		5: t.streamSpeed5,
+	};
+
 	return (
 		<div className="flex flex-col gap-6">
 			{(settingsLoading || settingsError) && (
@@ -405,6 +437,79 @@ function GeneralSection({
 			<Row title={t.fontMonoFamily} desc={t.fontMonoFamilyDesc}>
 				<FontFamilyPicker scope="mono" />
 			</Row>
+			<RowColumn title={t.streamStyleTitle} desc={t.streamStyleDesc}>
+				<div className="flex w-full flex-wrap gap-2">
+					{STREAM_STYLES.map((id) => {
+						const active = stream.style === id;
+						return (
+							<button
+								key={id}
+								type="button"
+								className="flex flex-col items-start gap-1 text-left transition-colors"
+								style={{
+									flex: "1 1 150px",
+									padding: "12px 16px",
+									borderRadius: 14,
+									border: `0.5px solid ${active ? "var(--dsw-border-strong)" : "var(--dsw-border-l4)"}`,
+									background: active ? "var(--dsw-module-platform)" : "transparent",
+									color: "var(--dsw-label-primary)",
+									lineHeight: "18px",
+								}}
+								aria-pressed={active}
+								onClick={() => pickStream({ style: id })}
+							>
+								<span className="flex items-center gap-1.5" style={{ fontSize: 14 }}>
+									{active ? <IconCheckOutline14 size={13} /> : null}
+									{streamStyleText[id].label}
+								</span>
+								<span style={{ fontSize: 11.5, color: "var(--dsw-label-caption)" }}>{streamStyleText[id].desc}</span>
+							</button>
+						);
+					})}
+				</div>
+			</RowColumn>
+			<RowColumn title={t.streamSpeedTitle} desc={t.streamSpeedDesc}>
+				<div className="flex w-full flex-wrap gap-2">
+					{Array.from({ length: STREAM_SPEED_MAX - STREAM_SPEED_MIN + 1 }, (_, i) => STREAM_SPEED_MIN + i).map((level) => {
+						const active = stream.speed === level;
+						return (
+							<button
+								key={level}
+								type="button"
+								className="transition-colors disabled:opacity-50"
+								// 即时样式不排队，速度对它没有意义：置灰，免得以为调了没反应
+								disabled={stream.style === "instant"}
+								style={{
+									flex: "1 1 84px",
+									padding: "10px 8px",
+									borderRadius: 12,
+									border: `0.5px solid ${active ? "var(--dsw-border-strong)" : "var(--dsw-border-l4)"}`,
+									background: active ? "var(--dsw-module-platform)" : "transparent",
+									color: active ? "var(--dsw-label-primary)" : "var(--dsw-label-secondary)",
+									fontSize: 13,
+								}}
+								aria-pressed={active}
+								onClick={() => pickStream({ speed: level })}
+							>
+								{streamSpeedText[level]}
+							</button>
+						);
+					})}
+				</div>
+			</RowColumn>
+			<Row title={t.streamCaretTitle} desc={t.streamCaretDesc}>
+				<button
+					type="button"
+					className="relative h-5 w-9 flex-none rounded-full transition-colors"
+					style={{ background: stream.caret ? "var(--dsw-accent)" : "var(--dsw-border-l3)" }}
+					role="switch"
+					aria-checked={stream.caret}
+					aria-label={t.streamCaretTitle}
+					onClick={() => pickStream({ caret: !stream.caret })}
+				>
+					<span className="absolute top-0.5 h-4 w-4 rounded-full bg-white transition-all" style={{ left: stream.caret ? 18 : 2 }} />
+				</button>
+			</Row>
 			<Row title={t.enterBehavior} desc={t.enterBehaviorDesc}>
 				<SelectOption
 				value={enterBehavior}
@@ -479,61 +584,20 @@ function VersionLink({ href, value }: { href: string; value?: string }) {
 	);
 }
 
-type UpdatePhase = "idle" | "checking" | "available" | "updating" | "latest" | "updated" | "error";
-
 /** 检查更新 / 更新控件：npm 安装的 piweb 走 npm install -g @rexvane/piweb@latest（服务端固定参数），
- *  Git 检出仍走 git pull + 本地构建；pi 走 npm install @latest。 */
-function UpdateControl({ target }: { target: "piweb" | "pi" }) {
+ *  Git 检出仍走 git pull + 本地构建；pi 走 npm install @latest（npm 安装只换依赖、不重建）。
+ *  状态和右下角提示条共用（update-store）：启动检查的结果一到，这里直接显示「更新到 vX」或「已是最新」。 */
+function UpdateControl({ target }: { target: UpdateTarget }) {
 	const { t } = useI18n();
-	const [phase, setPhase] = useState<UpdatePhase>("idle");
-	const [latest, setLatest] = useState("");
-	const [command, setCommand] = useState("");
-	const [error, setError] = useState("");
+	const { phase, latest, command, error, busy: sessionBusy } = useUpdates().targets[target];
 	const busy = phase === "checking" || phase === "updating";
 
-	const post = async (action: "check" | "update") => {
-		const r = await fetch("/api/update", {
-			method: "POST",
-			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify({ target, action }),
-		});
-		return r.json();
-	};
-
-	const check = async () => {
-		setPhase("checking");
-		setError("");
-		try {
-			const j = await post("check");
-			if (!j.success) throw new Error(j.error);
-			if (j.data.canUpdate) {
-				setLatest(j.data.latest);
-				setCommand(j.data.command ?? "");
-				setPhase("available");
-			} else {
-				setPhase("latest");
-			}
-		} catch (e: any) {
-			setError(String(e?.message ?? e));
-			setPhase("error");
-		}
-	};
-
-	const run = async () => {
-		setPhase("updating");
-		try {
-			const j = await post("update");
-			if (!j.success) throw new Error(j.error);
-			setLatest(j.data.version ?? latest);
-			setPhase("updated");
-		} catch (e: any) {
-			setError(String(e?.message ?? e));
-			setPhase("error");
-		}
-	};
+	useEffect(() => {
+		void loadUpdates();
+	}, []);
 
 	if (phase === "idle" || phase === "latest" || phase === "error") {
-		const label = phase === "latest" ? t.upToDate : phase === "error" ? t.updateFailed : t.checkUpdate;
+		const label = phase === "latest" ? t.upToDate : phase === "error" ? (sessionBusy ? t.updateBusy : t.updateFailed) : t.checkUpdate;
 		const color = phase === "latest" ? "var(--dsw-label-tertiary)" : phase === "error" ? "var(--dsw-danger)" : "var(--dsw-label-primary)";
 		return (
 			<button
@@ -542,7 +606,7 @@ function UpdateControl({ target }: { target: "piweb" | "pi" }) {
 				style={{ height: 26, padding: "0 10px", fontSize: 12, color }}
 				title={error || undefined}
 				disabled={busy}
-				onClick={() => void check()}
+				onClick={() => void checkUpdate(target)}
 			>
 				{label}
 			</button>
@@ -553,19 +617,24 @@ function UpdateControl({ target }: { target: "piweb" | "pi" }) {
 		if (command) {
 			return (
 				<span className="flex flex-col items-end gap-0.5" style={{ maxWidth: 300 }}>
-					<code style={{ fontSize: 11, color: "var(--dsw-label-primary)", whiteSpace: "nowrap", overflowX: "auto", maxWidth: "100%" }}>{command}</code>
+					<CopyCommand command={command} />
 					<span style={{ fontSize: 11, color: "var(--dsw-label-tertiary)", textAlign: "right" }}>{t.updateManualHint}</span>
 				</span>
 			);
 		}
 		return (
-			<button type="button" className="btn-primary-white" style={{ height: 26, padding: "0 12px", fontSize: 12 }} onClick={() => void run()}>
+			<button type="button" className="btn-primary-white" style={{ height: 26, padding: "0 12px", fontSize: 12 }} onClick={() => void runUpdate(target)}>
 				{t.updateTo.replace("{v}", latest)}
 			</button>
 		);
 	}
 	if (phase === "updated") {
-		return <span style={{ fontSize: 12, color: "var(--dsw-success)", maxWidth: 260, textAlign: "right" }}>{t.updatedTo.replace("{v}", latest)}</span>;
+		return (
+			<span className="flex flex-col items-end gap-0.5" style={{ maxWidth: 280, textAlign: "right" }}>
+				<span style={{ fontSize: 12, color: "var(--dsw-success)" }}>{t.updatedTo.replace("{v}", latest)}</span>
+				<span style={{ fontSize: 11, color: "var(--dsw-label-tertiary)" }}>{t.updateRestartHint}</span>
+			</span>
+		);
 	}
 	return (
 		<span className="flex items-center gap-1.5" style={{ fontSize: 12, color: "var(--dsw-label-tertiary)" }}>

package/src/components/chat/chat-scroll.ts

@@ -0,0 +1,18 @@
+import { createContext } from "react";
+
+/**
+ * 对话区的贴底状态，交给流式正文用。
+ *
+ * 流式正文每帧往下长一点，长完要不要跟着滚到底，只能听对话区的：它按 96px 判断贴底、
+ * 用户往上翻（或大纲 / 搜索在平滑跳转）就松开。正文自己再量一遍距离、另设阈值，
+ * 两边说法不一，就会把已经翻上去的人拽回来、把刚起步的平滑跳转打断。
+ * 不在对话区里（没有 Provider）就不贴底。
+ */
+export interface ChatScroll {
+	/** 现在是否贴着底部（读的是对话区的同一个 ref，不另做判断） */
+	shouldPin(): boolean;
+	/** 立刻贴到底部 */
+	pin(): void;
+}
+
+export const ChatScrollContext = createContext<ChatScroll | null>(null);

package/src/components/update/CopyCommand.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import { useState } from "react";
+import { useI18n } from "@/i18n";
+import { copyText } from "@/lib/clipboard";
+
+/** 要用户自己在终端执行的命令：等宽显示 + 复制按钮（设置行和右下角提示条共用） */
+export function CopyCommand({ command }: { command: string }) {
+	const { t } = useI18n();
+	const [copied, setCopied] = useState<"" | "ok" | "fail">("");
+	return (
+		<span className="flex min-w-0 items-center gap-1.5">
+			<code
+				className="min-w-0 flex-1"
+				style={{ fontFamily: "var(--font-mono)", fontSize: 11, color: "var(--dsw-label-primary)", whiteSpace: "nowrap", overflowX: "auto" }}
+			>
+				{command}
+			</code>
+			<button
+				type="button"
+				className="btn-outline flex-none"
+				style={{ height: 22, padding: "0 8px", fontSize: 11, color: copied === "fail" ? "var(--dsw-danger)" : undefined }}
+				onClick={() => {
+					void copyText(command).then((ok) => {
+						setCopied(ok ? "ok" : "fail");
+						setTimeout(() => setCopied(""), 1500);
+					});
+				}}
+			>
+				{copied === "ok" ? t.updateCopied : copied === "fail" ? t.copyFailed : t.copy}
+			</button>
+		</span>
+	);
+}

package/src/components/update/UpdateNotice.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+/**
+ * 右下角的更新提示条：每次服务启动提醒一次（按启动标识记在 localStorage，刷新、多开标签页不重复）。
+ *
+ * 只列启动检查时就有新版本的那几项：
+ * - 能直接更新的点「更新」，按 PiWeb → Pi 的顺序逐个装（同一时间只能有一个更新在跑）；
+ * - Windows 上的 npm 安装 PiWeb 不能替换运行中的自己，给命令和复制按钮；
+ * - 装好后提示手动重启，进程不自己重启。
+ * 状态和设置里的版本行共用（update-store），在哪边点都一样。
+ */
+import { useEffect, useState } from "react";
+import { CopyCommand } from "@/components/update/CopyCommand";
+import { loadUpdates, runUpdate, UPDATE_TARGETS, useUpdates, type TargetUpdate, type UpdateTarget } from "@/components/update/update-store";
+import { useI18n } from "@/i18n";
+
+/** 已经关掉过的那次启动的标识 */
+export const UPDATE_NOTICE_KEY = "piweb.updateNotice";
+
+const LABEL: Record<UpdateTarget, string> = { piweb: "PiWeb", pi: "Pi" };
+
+export function UpdateNotice() {
+	const { t } = useI18n();
+	const updates = useUpdates();
+	/** 读过 localStorage 之后才知道这次启动是否已经关掉过（服务端渲染没有 localStorage） */
+	const [dismissed, setDismissed] = useState<string | null | undefined>(undefined);
+	/** 启动检查时就有新版本的项：提示条只管这些，之后它们变成更新中 / 已更新 / 失败也留在条里 */
+	const [offered, setOffered] = useState<UpdateTarget[] | null>(null);
+
+	useEffect(() => {
+		try {
+			setDismissed(localStorage.getItem(UPDATE_NOTICE_KEY));
+		} catch {
+			setDismissed(null);
+		}
+		void loadUpdates();
+	}, []);
+
+	useEffect(() => {
+		if (offered === null && updates.loaded) setOffered(UPDATE_TARGETS.filter((target) => updates.targets[target].phase === "available"));
+	}, [offered, updates]);
+
+	if (dismissed === undefined || !offered?.length || !updates.startId || dismissed === updates.startId) return null;
+	const startId = updates.startId;
+	const items = offered.map((target) => ({ target, ...updates.targets[target] }));
+	const updatable = items.filter((item) => !item.command && (item.phase === "available" || item.phase === "error"));
+	const updating = items.some((item) => item.phase === "updating");
+	const anyUpdated = items.some((item) => item.phase === "updated");
+	const dismiss = () => {
+		try {
+			localStorage.setItem(UPDATE_NOTICE_KEY, startId);
+		} catch {
+			/* 存不下就只关这一页 */
+		}
+		setDismissed(startId);
+	};
+	const updateAll = async () => {
+		// 一个一个来：服务端同一时间只允许一个更新；前一个失败（比如有会话在跑）就停下
+		for (const item of updatable) {
+			if (!(await runUpdate(item.target))) break;
+		}
+	};
+	const title = updating ? t.updateNoticeUpdatingTitle : anyUpdated && !updatable.length ? t.updateNoticeDoneTitle : t.updateNoticeTitle;
+
+	return (
+		<div
+			role="status"
+			className="pointer-events-auto flex flex-col gap-2 rounded-xl px-3 py-2.5"
+			style={{ fontSize: 12.5, background: "var(--dsw-glass-popover)", border: "0.5px solid var(--dsw-border-l2)", boxShadow: "var(--dsw-elevation-soft)", borderLeft: "3px solid var(--dsw-accent)" }}
+			data-testid="update-notice"
+		>
+			<span style={{ fontWeight: 600, color: "var(--dsw-label-primary)" }}>{title}</span>
+			{items.map((item) => (
+				<div key={item.target} className="flex flex-col gap-1">
+					<span className="flex items-center gap-1.5" style={{ color: "var(--dsw-label-secondary)" }}>
+						<span style={{ color: "var(--dsw-label-primary)" }}>{LABEL[item.target]}</span>
+						<ItemStatus item={item} />
+					</span>
+					{item.command && item.phase === "available" ? (
+						<span className="flex flex-col gap-1">
+							<span style={{ fontSize: 11.5, color: "var(--dsw-label-tertiary)" }}>{t.updateRunCommandHint}</span>
+							<CopyCommand command={item.command} />
+						</span>
+					) : null}
+				</div>
+			))}
+			{anyUpdated && !updating ? <span style={{ fontSize: 11.5, color: "var(--dsw-label-tertiary)" }}>{t.updateRestartHint}</span> : null}
+			{!updating ? (
+				<div className="flex justify-end gap-2">
+					<button type="button" className="btn-outline" style={{ height: 26, padding: "0 12px", fontSize: 12 }} onClick={dismiss}>
+						{anyUpdated || !updatable.length ? t.updateNoticeOk : t.updateNoticeLater}
+					</button>
+					{updatable.length ? (
+						<button type="button" className="btn-primary-white" style={{ height: 26, padding: "0 12px", fontSize: 12 }} onClick={() => void updateAll()}>
+							{t.updateNoticeUpdate}
+						</button>
+					) : null}
+				</div>
+			) : null}
+		</div>
+	);
+}
+
+function ItemStatus({ item }: { item: TargetUpdate }) {
+	const { t } = useI18n();
+	if (item.phase === "updating") {
+		return (
+			<span className="flex items-center gap-1.5" style={{ color: "var(--dsw-label-tertiary)" }}>
+				<span className="h-3 w-3 flex-none animate-spin rounded-full border-2 border-current border-t-transparent" />
+				{t.updatingNow}
+			</span>
+		);
+	}
+	if (item.phase === "updated") return <span style={{ color: "var(--dsw-success)" }}>{t.updateNoticeUpdated.replace("{v}", item.latest)}</span>;
+	if (item.phase === "error") {
+		// npm / 构建的报错可能很长：只露三行，完整内容放在悬停提示里
+		return (
+			<span className="line-clamp-3 min-w-0 break-all" style={{ color: "var(--dsw-danger)" }} title={item.error}>
+				{item.busy ? t.updateBusy : `${t.updateFailed}: ${item.error}`}
+			</span>
+		);
+	}
+	return <span>{versionChange(item, t.updateCommits)}</span>;
+}
+
+/** 「0.3.18 → 0.3.20」；Git 检出版本号没变、只有新提交时写提交数 */
+export function versionChange(item: Pick<TargetUpdate, "current" | "latest" | "behind">, commitsText: string): string {
+	if (item.latest === item.current && item.behind > 0) return commitsText.replace("{n}", String(item.behind));
+	return `${item.current} → ${item.latest}`;
+}

package/src/components/update/update-store.ts

@@ -0,0 +1,155 @@
+import { useSyncExternalStore } from "react";
+
+/**
+ * 更新状态的前端单例：设置里的两行「PiWeb 版本 / Pi 版本」和右下角提示条共用一份，
+ * 在一处点了更新，另一处同步显示进度和结果。
+ *
+ * 页面打开时取一次启动检查的结果（GET /api/update，服务启动时已经在查），
+ * 不用先点「检查更新」就知道有没有新版本。
+ */
+
+export type UpdateTarget = "piweb" | "pi";
+export type UpdatePhase = "idle" | "checking" | "available" | "updating" | "latest" | "updated" | "error";
+
+export interface TargetUpdate {
+	phase: UpdatePhase;
+	current: string;
+	latest: string;
+	/** Git 检出：main 上落后的提交数（版本号没变时用它说明「有新提交」） */
+	behind: number;
+	/** 要用户自己执行的命令（Windows 上的 npm 安装 PiWeb 不能替换运行中的自己）；空串表示能直接更新 */
+	command: string;
+	error: string;
+	/** 失败是因为有会话正在运行（409） */
+	busy: boolean;
+}
+
+export interface UpdateState {
+	/** 启动检查的结果取回来了（成功或失败都算） */
+	loaded: boolean;
+	/** 本次服务启动的标识，提示条按它做到「每次启动提醒一次」；关掉启动检查时为 null */
+	startId: string | null;
+	targets: Record<UpdateTarget, TargetUpdate>;
+}
+
+export const UPDATE_TARGETS: readonly UpdateTarget[] = ["piweb", "pi"];
+
+interface CheckData {
+	current: string;
+	latest: string;
+	canUpdate: boolean;
+	behind?: number;
+	command?: string;
+	updatedTo?: string;
+}
+
+const blank = (): TargetUpdate => ({ phase: "idle", current: "", latest: "", behind: 0, command: "", error: "", busy: false });
+const initial = (): UpdateState => ({ loaded: false, startId: null, targets: { piweb: blank(), pi: blank() } });
+
+let state: UpdateState = initial();
+let loading: Promise<void> | null = null;
+const listeners = new Set<() => void>();
+
+function emit(): void {
+	for (const listener of listeners) listener();
+}
+
+function patch(target: UpdateTarget, next: Partial<TargetUpdate>): void {
+	state = { ...state, targets: { ...state.targets, [target]: { ...state.targets[target], ...next } } };
+	emit();
+}
+
+function fromCheck(check: CheckData): Partial<TargetUpdate> {
+	const base = { current: check.current, behind: check.behind ?? 0, error: "", busy: false };
+	if (check.updatedTo) return { ...base, phase: "updated", latest: check.updatedTo, command: "" };
+	if (check.canUpdate) return { ...base, phase: "available", latest: check.latest, command: check.command ?? "" };
+	return { ...base, phase: "latest", latest: check.latest, command: "" };
+}
+
+class UpdateRequestError extends Error {
+	busy: boolean;
+	constructor(message: string, busy: boolean) {
+		super(message);
+		this.busy = busy;
+	}
+}
+
+async function post(target: UpdateTarget, action: "check" | "update") {
+	const response = await fetch("/api/update", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ target, action }),
+	});
+	const json = await response.json();
+	if (!json.success) throw new UpdateRequestError(String(json.error ?? response.status), response.status === 409);
+	return json.data;
+}
+
+function failure(error: unknown): Partial<TargetUpdate> {
+	return { phase: "error", error: error instanceof Error ? error.message : String(error), busy: error instanceof UpdateRequestError && error.busy };
+}
+
+/** 取启动检查的结果；每个页面只取一次（设置面板反复开关不重复请求） */
+export function loadUpdates(): Promise<void> {
+	loading ??= (async () => {
+		try {
+			const response = await fetch("/api/update", { cache: "no-store" });
+			const json = await response.json();
+			if (!json.success) throw new Error(String(json.error));
+			const targets = { ...state.targets };
+			for (const target of UPDATE_TARGETS) {
+				const result = json.data?.results?.[target];
+				// 已经手动查过 / 正在更新的不覆盖；启动检查失败的项留在 idle，照旧手动检查
+				if (targets[target].phase !== "idle" || !result || "error" in result) continue;
+				targets[target] = { ...targets[target], ...fromCheck(result) };
+			}
+			state = { loaded: true, startId: json.data?.startId ?? null, targets };
+		} catch {
+			state = { ...state, loaded: true };
+		}
+		emit();
+	})();
+	return loading;
+}
+
+export async function checkUpdate(target: UpdateTarget): Promise<void> {
+	patch(target, { phase: "checking", error: "", busy: false });
+	try {
+		patch(target, fromCheck(await post(target, "check")));
+	} catch (error) {
+		patch(target, failure(error));
+	}
+}
+
+/** 更新一项；成功返回 true。装好后要用户手动重启，进程不自己重启 */
+export async function runUpdate(target: UpdateTarget): Promise<boolean> {
+	patch(target, { phase: "updating", error: "", busy: false });
+	try {
+		const data = await post(target, "update");
+		patch(target, { phase: "updated", latest: data?.version || state.targets[target].latest, command: "" });
+		return true;
+	} catch (error) {
+		patch(target, failure(error));
+		return false;
+	}
+}
+
+function subscribe(listener: () => void): () => void {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}
+
+const getState = () => state;
+
+export function useUpdates(): UpdateState {
+	return useSyncExternalStore(subscribe, getState, getState);
+}
+
+/** 仅供测试：回到页面刚打开时的状态 */
+export function resetUpdates(): void {
+	state = initial();
+	loading = null;
+	emit();
+}