@rexvane/piweb 0.3.20 → 0.3.22

package/src/components/TrajectoryView.tsx

@@ -3,6 +3,7 @@
 import { useMemo, useState } from "react";
 import { IconCloseOutline14, IconSearchOutline16 } from "@/components/icons";
 import { useI18n } from "@/i18n";
+import { fmtTokens } from "@/lib/format";
 import type { TrajEntry, TrajTokens } from "@/lib/types";
 import styles from "./TrajectoryAnalyzer.module.css";
 
@@ -26,10 +27,7 @@ const KIND_NAME: Record<TrajEntry["kind"], string> = {
 };
 
 function fmtTok(value?: number): string {
-	if (value == null) return "—";
-	if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`;
-	if (value >= 1_000) return `${(value / 1_000).toFixed(1)}K`;
-	return String(value);
+	return value == null ? "—" : fmtTokens(value);
 }
 
 function fmtTime(ts: number): string {
@@ -45,8 +43,8 @@ function durationOf(entry: TrajEntry): number | undefined {
 
 function fmtDur(ms?: number): string {
 	if (ms == null) return "—";
-	if (ms >= 60_000) return `${(ms / 60_000).toFixed(1)}m`;
-	if (ms >= 1_000) return `${(ms / 1_000).toFixed(ms >= 10_000 ? 0 : 1)}s`;
+	if (ms >= 60_000) return `${(ms / 60_000).toFixed(2)}m`;
+	if (ms >= 1_000) return `${(ms / 1_000).toFixed(2)}s`;
 	return `${Math.round(ms)}ms`;
 }
 

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/composer/ComposerImages.tsx

@@ -0,0 +1,306 @@
+"use client";
+
+/**
+ * 输入卡里待发送的图片。
+ * - 不超过 COLLAPSE_AT 张：平铺缩略图（不裁切），右上角删除。
+ * - 更多时折叠成牌堆：正面那张在最上，后面最多露 4 层 4px 的右边缘；点「展开 N」沿一条向上拱的弧线扇开。
+ *   两种状态是同一批卡片换 transform，所以有从牌堆扇开 / 收拢的动画；扇形按容器实测宽度铺开。
+ *   层级始终是左压右（和牌堆同一个顺序，展开时不会闪一下换层），每张露出来的是右侧那条，
+ *   删除按钮就在那条的右上角——不用悬停也点得到，触屏同样能删；张数多、条带窄到按钮会挤成一排时，
+ *   只在悬停 / 聚焦的那张上显示（触屏点开预览里删）。悬停 / 聚焦的那张抬起来、整张露出。
+ *   牌堆里后面几张只露空白的卡边（不露图），看起来是一叠；扇开时图再淡入。
+ * - 点任意一张进预览：大图、← → 切换、删除当前张（删完自动看下一张）；Esc / 点背景 / 关闭按钮退出，焦点回到原处。
+ *   预览挂到 body 上（祖先的 backdrop-filter 会让 fixed 只盖住输入卡），按键在捕获阶段拦下，不会再关掉页面上的其它面板。
+ */
+import { useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { useI18n } from "@/i18n";
+import type { ImageAttachment } from "@/lib/types";
+
+/** 超过这个数量就折叠（引用 chip 用同一个阈值） */
+export const COLLAPSE_AT = 4;
+/** 牌堆 / 扇形里卡片的边长 */
+const CARD = 96;
+/** 牌堆里后面每层露出的右边缘、最多露几层（再多的叠在最后一层下面、不显示） */
+const DECK_PEEK = 4;
+const DECK_LAYERS = 4;
+/** 扇形所在圆弧的半径（越大弧越平）、相邻两张中心的最大间距（再大就散成一排，不像一手牌了） */
+const FAN_RADIUS = 520;
+const FAN_GAP_MAX = 76;
+/** 悬停 / 聚焦时那张往上抬多少；左右给旋转后探出去的角留的余量 */
+const FAN_LIFT = 12;
+const FAN_SIDE = 8;
+/** 量不到宽度时（首帧、测试环境）按这个宽度排扇形 */
+const FALLBACK_WIDTH = 360;
+
+export interface CardPose {
+	x: number;
+	y: number;
+	angle: number;
+	/** 牌堆里压在最后一层下面、看不见的 */
+	hidden?: boolean;
+}
+
+interface Layout {
+	cards: CardPose[];
+	width: number;
+	height: number;
+	/** 相邻两张露出来的宽度；太窄时删除按钮会挤成一排，只在悬停 / 聚焦那张上显示 */
+	gap: number;
+}
+
+/** 露出的条带至少这么宽，每张的删除按钮才常驻（按钮 22px + 一点间隔） */
+const ROOMY_GAP = 30;
+
+const round = (value: number) => Math.round(value * 10) / 10;
+
+/** 牌堆：只做横向错位，最多露 DECK_LAYERS 层 */
+export function deckLayout(count: number): Layout {
+	const cards = Array.from({ length: count }, (_, i) => ({ x: Math.min(i, DECK_LAYERS) * DECK_PEEK, y: 0, angle: 0, hidden: i > DECK_LAYERS }));
+	return { cards, width: CARD + Math.min(Math.max(count - 1, 0), DECK_LAYERS) * DECK_PEEK, height: CARD, gap: DECK_PEEK };
+}
+
+/**
+ * 扇形：卡片中心落在一段圆弧上（中间最高、两侧顺着弧下垂），每张转到切线方向；
+ * 间距按可用宽度均分、不超过 FAN_GAP_MAX，从左边开始铺（离牌堆原来的位置最近）。
+ */
+export function fanLayout(count: number, width: number): Layout {
+	const gap = count > 1 ? Math.min(FAN_GAP_MAX, Math.max(8, (width - CARD - FAN_SIDE * 2) / (count - 1))) : 0;
+	const step = gap / FAN_RADIUS;
+	const mid = (count - 1) / 2;
+	const edge = -mid * step;
+	// 正方形转过 θ 后比原来高出（也宽出）的那一截，最外侧两张最大
+	const corner = (CARD / 2) * (Math.abs(Math.sin(edge)) + Math.cos(edge) - 1);
+	const top = FAN_LIFT + corner;
+	const cards = Array.from({ length: count }, (_, i) => {
+		const theta = (i - mid) * step;
+		return {
+			x: round(FAN_SIDE + FAN_RADIUS * (Math.sin(theta) - Math.sin(edge))),
+			y: round(top + FAN_RADIUS * (1 - Math.cos(theta))),
+			angle: round((theta * 180) / Math.PI),
+		};
+	});
+	const span = cards.length ? cards[cards.length - 1].x + CARD + FAN_SIDE : 0;
+	return { cards, width: Math.ceil(span), height: Math.ceil(top + FAN_RADIUS * (1 - Math.cos(edge)) + CARD + corner), gap: round(gap) };
+}
+
+/** 每张图一个稳定的 key：前几位 base64 对同格式的图几乎都一样（PNG 都是 iVBORw0KGgo…），不能拿来当 key */
+const imageKeys = new WeakMap<ImageAttachment, string>();
+let nextImageKey = 0;
+function keyOf(image: ImageAttachment): string {
+	let key = imageKeys.get(image);
+	if (!key) {
+		nextImageKey += 1;
+		key = `image-${nextImageKey}`;
+		imageKeys.set(image, key);
+	}
+	return key;
+}
+
+const srcOf = (image: ImageAttachment) => `data:${image.mimeType};base64,${image.data}`;
+
+export function ComposerImages({ images, disabled, onRemove }: { images: ImageAttachment[]; disabled?: boolean; onRemove: (index: number) => void }) {
+	const { t } = useI18n();
+	const collapsible = images.length > COLLAPSE_AT;
+	const [expanded, setExpanded] = useState(false);
+	const fanned = collapsible && expanded;
+	/** 扇形里悬停 / 聚焦的那张：抬起来、放到最上层 */
+	const [lifted, setLifted] = useState<number | null>(null);
+	const [preview, setPreview] = useState<number | null>(null);
+	const railRef = useRef<HTMLDivElement>(null);
+	const [railWidth, setRailWidth] = useState(0);
+
+	useEffect(() => {
+		const rail = railRef.current;
+		if (!rail || !collapsible) return;
+		// 量的是整条附件轨的内容宽度（去掉左右 4px 内边距）：扇形展开后占满这一行
+		const measure = () => setRailWidth(Math.max(0, rail.clientWidth - 8));
+		measure();
+		if (typeof ResizeObserver === "undefined") return;
+		const observer = new ResizeObserver(measure);
+		observer.observe(rail);
+		return () => observer.disconnect();
+	}, [collapsible]);
+
+	const remove = (index: number) => {
+		onRemove(index);
+		setLifted(null);
+		// 预览里删的：还有图就接着看下一张（删的是最后一张就看前一张）
+		setPreview((current) => (current === null ? null : images.length <= 1 ? null : Math.min(current, images.length - 2)));
+	};
+
+	const deleteButton = (index: number) => (
+		<button type="button" className="pw-image-delete" disabled={disabled} aria-label={`${t.delete} ${index + 1}`} onClick={() => remove(index)}>
+			✕
+		</button>
+	);
+
+	const layout = fanned ? fanLayout(images.length, railWidth || FALLBACK_WIDTH) : deckLayout(images.length);
+	const shown = preview !== null && images[preview] ? preview : null;
+
+	return (
+		<>
+			<div ref={railRef} className="mb-2 flex flex-wrap items-center gap-2 px-1" data-testid="composer-images">
+				{collapsible ? (
+					<div
+						className="pw-image-fan"
+						data-testid="image-fan"
+						data-expanded={fanned}
+						data-crowded={fanned && layout.gap < ROOMY_GAP ? true : undefined}
+						style={{ width: fanned ? "100%" : layout.width, height: layout.height }}
+					>
+						{images.map((image, i) => {
+							const pose = layout.cards[i];
+							const up = fanned && lifted === i;
+							// 牌堆里只有正面那张能点、能删；后面那几张只是露个边，不进 Tab 顺序
+							const reachable = fanned || i === 0;
+							// 展开从左往右依次扇出，收起反过来；错开的总时长封顶，张数多也不拖沓
+							const delay = Math.min(fanned ? i * 14 : (images.length - 1 - i) * 10, 140);
+							return (
+								<div
+									key={keyOf(image)}
+									className="pw-image-card"
+									data-hidden={pose.hidden || undefined}
+									data-lifted={up || undefined}
+									style={{
+										zIndex: up ? images.length + 1 : images.length - i,
+										transform: `translate(${pose.x}px, ${pose.y - (up ? FAN_LIFT : 0)}px) rotate(${pose.angle}deg)`,
+										transitionDelay: up || lifted !== null ? "0ms" : `${delay}ms`,
+									}}
+									onMouseEnter={() => fanned && setLifted(i)}
+									onMouseLeave={() => setLifted((current) => (current === i ? null : current))}
+									onFocus={() => fanned && setLifted(i)}
+									onBlur={(event) => {
+										// 焦点从图片挪到同一张的删除按钮不算离开
+										if (!event.currentTarget.contains(event.relatedTarget as Node | null)) setLifted((current) => (current === i ? null : current));
+									}}
+								>
+									<button
+										type="button"
+										className="pw-image-face"
+										tabIndex={reachable ? undefined : -1}
+										aria-hidden={reachable ? undefined : true}
+										title={t.imagePreview}
+										aria-label={t.imagePreview}
+										onClick={() => setPreview(i)}
+									>
+										<img src={srcOf(image)} alt="" className="h-full w-full object-contain" draggable={false} />
+									</button>
+									{reachable ? deleteButton(i) : null}
+								</div>
+							);
+						})}
+					</div>
+				) : (
+					images.map((image, i) => (
+						<div key={keyOf(image)} className="pw-image-thumb">
+							<button type="button" className="block" title={t.imagePreview} aria-label={t.imagePreview} onClick={() => setPreview(i)}>
+								<img src={srcOf(image)} alt="" className="max-h-24 max-w-32 rounded-[10px] object-contain" draggable={false} />
+							</button>
+							{deleteButton(i)}
+						</div>
+					))
+				)}
+				{collapsible ? (
+					<button
+						type="button"
+						className="pw-chip"
+						data-testid="images-toggle"
+						aria-expanded={fanned}
+						onClick={() => {
+							setExpanded((open) => !open);
+							setLifted(null);
+						}}
+					>
+						{fanned ? t.chipCollapse : t.chipExpandMore.replace("{n}", String(images.length - 1))}
+					</button>
+				) : null}
+			</div>
+			{shown !== null
+				? createPortal(
+					<ImageViewer images={images} index={shown} disabled={disabled} onIndex={setPreview} onRemove={remove} onClose={() => setPreview(null)} />,
+					document.body,
+				)
+				: null}
+		</>
+	);
+}
+
+/** 放大预览：手机上没法用本机程序打开图片，应用内看最实在 */
+function ImageViewer({
+	images,
+	index,
+	disabled,
+	onIndex,
+	onRemove,
+	onClose,
+}: {
+	images: ImageAttachment[];
+	index: number;
+	disabled?: boolean;
+	onIndex: (index: number) => void;
+	onRemove: (index: number) => void;
+	onClose: () => void;
+}) {
+	const { t } = useI18n();
+	const dialogRef = useRef<HTMLDivElement>(null);
+	const closeRef = useRef<HTMLButtonElement>(null);
+	const count = images.length;
+	const go = (delta: number) => onIndex((index + delta + count) % count);
+
+	// 打开时把焦点移进来，关掉时还给原来那个元素（还在页面上的话）
+	useEffect(() => {
+		const opener = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+		closeRef.current?.focus();
+		return () => {
+			if (opener?.isConnected) opener.focus();
+		};
+	}, []);
+
+	// 捕获阶段处理：Esc / 方向键不再传给页面上其它监听 document 的面板；Tab 只在预览里转
+	useEffect(() => {
+		const onKey = (event: KeyboardEvent) => {
+			if (event.key === "Escape") onClose();
+			else if (event.key === "ArrowLeft" && count > 1) go(-1);
+			else if (event.key === "ArrowRight" && count > 1) go(1);
+			else if (event.key === "Tab") {
+				const focusable = [...(dialogRef.current?.querySelectorAll<HTMLElement>("button:not(:disabled)") ?? [])];
+				if (!focusable.length) return;
+				const at = focusable.indexOf(document.activeElement as HTMLElement);
+				const next = event.shiftKey ? (at <= 0 ? focusable.length - 1 : at - 1) : at === focusable.length - 1 ? 0 : at + 1;
+				focusable[next].focus();
+			} else return;
+			event.preventDefault();
+			event.stopPropagation();
+		};
+		document.addEventListener("keydown", onKey, true);
+		return () => document.removeEventListener("keydown", onKey, true);
+		// onClose / onIndex 来自父组件的 setState 包装，语义不变；只随张数和当前张重绑
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [count, index]);
+
+	return (
+		<div ref={dialogRef} className="pw-viewer" role="dialog" aria-modal="true" aria-label={t.imageViewer} onClick={onClose}>
+			<div className="pw-viewer-bar" onClick={(event) => event.stopPropagation()}>
+				<span className="pw-viewer-count">{count > 1 ? `${index + 1} / ${count}` : ""}</span>
+				<button type="button" className="pw-viewer-btn" disabled={disabled} onClick={() => onRemove(index)}>
+					{t.delete}
+				</button>
+				<button ref={closeRef} type="button" className="pw-viewer-btn" aria-label={t.close} onClick={onClose}>
+					✕
+				</button>
+			</div>
+			<img src={srcOf(images[index])} alt="" className="pw-viewer-image" onClick={(event) => event.stopPropagation()} />
+			{count > 1 ? (
+				<>
+					<button type="button" className="pw-viewer-nav" data-side="prev" aria-label={t.imagePrev} onClick={(event) => { event.stopPropagation(); go(-1); }}>
+						‹
+					</button>
+					<button type="button" className="pw-viewer-nav" data-side="next" aria-label={t.imageNext} onClick={(event) => { event.stopPropagation(); go(1); }}>
+						›
+					</button>
+				</>
+			) : null}
+		</div>
+	);
+}

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();
+}