cozyclay 3.1.4 → 3.1.6

package/src/update/UpdateChip.jsx

@@ -0,0 +1,86 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { ko } from "../locale.js";
+import { createUpdatePoller } from "./update-client.js";
+import { noteNoticeShown, noteUpdateClicked, noteUpdatePolled } from "./update-telemetry.js";
+import UpdateDialog from "./UpdateDialog.jsx";
+import "./update.css";
+
+// The update notice (U1): a quiet top-bar chip, never a toast and never a dialog
+// that opens by itself. It renders nothing on a hosted page (the poller is a
+// no-op without window.__COZYCLAY_RUNTIME__) and nothing until a poll says so.
+function chipLabel(state) {
+	const v = state.latest;
+	switch (state.view) {
+		case "updating": return ko("Updating…", "업데이트 중…", "正在更新…");
+		case "restart_needed": return ko("Restart to finish", "다시 시작하면 끝나요", "重启以完成");
+		case "failed": return ko("Update failed", "업데이트 실패", "更新失败");
+		default: return ko(`Update ${v}`, `${v} 업데이트`, `更新到 ${v}`);
+	}
+}
+
+export default function UpdateChip() {
+	const [state, setState] = useState(null);
+	const [open, setOpen] = useState(false);
+	const poller = useRef(null);
+	useEffect(() => {
+		const instance = createUpdatePoller({
+			onState: ({ state: next, info }) => {
+				setState(next);
+				noteNoticeShown(next);
+				noteUpdatePolled(info);
+			},
+		});
+		poller.current = instance;
+		return () => { instance.stop(); if (poller.current === instance) poller.current = null; };
+	}, []);
+	const view = state?.view ?? "hidden";
+	const close = useCallback(() => setOpen(false), []);
+	const dismiss = useCallback((action) => {
+		if (!state?.latest) return;
+		noteUpdateClicked(action, state.kind);
+		poller.current?.dismiss(state.latest);
+		setOpen(false);
+	}, [state]);
+	const update = useCallback(() => {
+		if (state) noteUpdateClicked("update_now", state.kind);
+		void poller.current?.update();
+	}, [state]);
+	if (view === "hidden") return null;
+	return (
+		<span className="update-chip-wrap">
+			<button
+				type="button"
+				className="update-chip"
+				data-testid="update-chip"
+				data-update-view={view}
+				aria-haspopup="dialog"
+				aria-expanded={open}
+				onClick={() => setOpen((value) => !value)}
+			>
+				<i className="update-chip-dot" aria-hidden="true" />
+				<span className="update-chip-text">{chipLabel(state)}</span>
+			</button>
+			{view === "available" && (
+				<button
+					type="button"
+					className="update-chip-dismiss"
+					data-testid="update-dismiss"
+					aria-label={ko("Dismiss this version", "이 버전 알림 닫기", "忽略此版本")}
+					title={ko("Dismiss this version", "이 버전 알림 닫기", "忽略此版本")}
+					onClick={() => dismiss("dismiss")}
+				>
+					<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M6 6l12 12M18 6L6 18" /></svg>
+				</button>
+			)}
+			{open && (
+				<UpdateDialog
+					state={state}
+					onClose={close}
+					onLater={() => dismiss("later")}
+					onUpdate={update}
+					onAction={(action) => noteUpdateClicked(action, state.kind)}
+				/>
+			)}
+		</span>
+	);
+}

package/src/update/UpdateDialog.jsx

@@ -0,0 +1,147 @@
+import { useEffect, useId, useRef, useState, useSyncExternalStore } from "react";
+import { createPortal } from "react-dom";
+import { useStudioShell } from "../shell/studio-shell-context.js";
+import { agentTurnRunning, subscribeAgentTurns } from "../workflow/agent-turn-telemetry.js";
+import { ko } from "../locale.js";
+import { updateBlocked } from "./update-client.js";
+
+// The update dialog: the MenuDialog markup (src/shell/MenuBar.jsx) and its
+// menubar-dialog-* classes, copied rather than shared (that file has no LOC room).
+// Every string passes its Chinese text: interpolated strings never match the
+// English-keyed ZH dictionary (src/locale.js).
+const failureCopy = {
+	permission: () => ko("npm can't write to its global folder. Copy the command and run it yourself, or fix the folder permissions.", "npm이 전역 폴더에 쓸 수 없어요. 명령을 복사해 직접 실행하거나 폴더 권한을 고치세요.", "npm 无法写入其全局文件夹。请复制命令自行运行，或修复文件夹权限。"),
+	network: () => ko("Couldn't reach the npm registry. Check your connection and try again.", "npm 레지스트리에 연결하지 못했어요. 연결을 확인하고 다시 시도하세요.", "无法连接 npm 注册表。请检查网络连接后重试。"),
+	node_version: () => ko("This version needs Node.js 22.19 or newer. Update Node, then run the command.", "이 버전은 Node.js 22.19 이상이 필요해요. Node를 업데이트한 뒤 명령을 실행하세요.", "此版本需要 Node.js 22.19 或更高版本。请先更新 Node，再运行该命令。"),
+	npm_missing: () => ko("npm isn't on your PATH. Copy the command and run it in a terminal that has npm.", "PATH에서 npm을 찾을 수 없어요. npm이 있는 터미널에서 명령을 실행하세요.", "PATH 中找不到 npm。请复制命令，在装有 npm 的终端中运行。"),
+	other: () => ko("The update didn't finish. Copy the command and run it in a terminal.", "업데이트가 끝나지 않았어요. 명령을 복사해 터미널에서 실행하세요.", "更新未完成。请复制命令并在终端中运行。"),
+};
+
+function titleOf(state) {
+	const v = state.latest;
+	if (state.view === "updating") return ko("Updating…", "업데이트 중…", "正在更新…");
+	if (state.view === "restart_needed") return ko("Restart to finish", "다시 시작하면 끝나요", "重启以完成");
+	if (state.view === "failed") return ko("Update failed", "업데이트 실패", "更新失败");
+	return ko(`CozyClay ${v} is available`, `CozyClay ${v} 버전이 나왔어요`, `CozyClay ${v} 已发布`);
+}
+
+function bodyOf(state) {
+	const v = state.latest;
+	if (state.view === "updating") return ko(`Installing ${v}. This takes about a minute.`, `${v} 설치 중이에요. 1분쯤 걸려요.`, `正在安装 ${v}，大约需要一分钟。`);
+	if (state.view === "restart_needed") {
+		return ko(`Updated to ${v}. Quit CozyClay in the terminal (Ctrl+C), then run \`cclay\` again.`,
+			`${v} 설치 완료. 터미널에서 CozyClay를 종료(Ctrl+C)하고 \`cclay\`를 다시 실행하세요.`,
+			`已更新到 ${v}。请在终端中退出 CozyClay（Ctrl+C），然后重新运行 \`cclay\`。`);
+	}
+	if (state.view === "failed") return (failureCopy[state.errorClass] ?? failureCopy.other)();
+	if (state.kind === "npx") {
+		return ko("Quit CozyClay in the terminal and run `npx cozyclay` again. npx fetches the newest version each time (internet needed).",
+			"터미널에서 CozyClay를 종료하고 `npx cozyclay`를 다시 실행하세요. npx가 매번 최신 버전을 받아요 (인터넷 필요).",
+			"请在终端中退出 CozyClay，然后重新运行 `npx cozyclay`。npx 每次都会获取最新版本（需要联网）。");
+	}
+	return null;
+}
+
+/** navigator.clipboard, else a hidden textarea and execCommand("copy"). Resolves true when copied. */
+async function copyText(text) {
+	try {
+		await navigator.clipboard.writeText(text);
+		return true;
+	} catch {
+		try {
+			const area = document.createElement("textarea");
+			area.value = text;
+			area.setAttribute("readonly", "");
+			area.style.position = "fixed";
+			area.style.opacity = "0";
+			document.body.appendChild(area);
+			area.select();
+			const ok = document.execCommand("copy");
+			area.remove();
+			return ok;
+		} catch {
+			return false;
+		}
+	}
+}
+
+export default function UpdateDialog({ state, onClose, onLater, onUpdate, onAction }) {
+	const closeRef = useRef(null);
+	const titleId = useId();
+	// "Copied" belongs to the view it was pressed in: a later phase shows its own command afresh.
+	const [copiedView, setCopiedView] = useState(null);
+	const copied = copiedView === state.view;
+	const { exportStatus, recState } = useStudioShell();
+	const agentRunning = useSyncExternalStore(subscribeAgentTurns, agentTurnRunning, () => false);
+	const blocked = updateBlocked({ agentRunning, exportStatus, recState });
+	useEffect(() => {
+		closeRef.current?.focus();
+		const onKey = (event) => {
+			if (event.key !== "Escape") return;
+			event.preventDefault();
+			onClose();
+		};
+		document.addEventListener("keydown", onKey);
+		return () => document.removeEventListener("keydown", onKey);
+	}, [onClose]);
+	const copy = async () => {
+		onAction("copy_command");
+		const view = state.view;
+		setCopiedView((await copyText(state.command)) ? view : null);
+	};
+	const startsInstall = state.actions.includes("update_now") || state.actions.includes("retry");
+	const body = bodyOf(state);
+	return createPortal(
+		<div className="menubar-dialog-backdrop" onPointerDown={(event) => { if (event.target === event.currentTarget) onClose(); }}>
+			<div className="menubar-dialog update-dialog" role="dialog" aria-modal="true" aria-labelledby={titleId} data-dialog="update" data-testid="update-dialog" data-update-view={state.view}>
+				<header className="menubar-dialog-head">
+					<h2 id={titleId}>{titleOf(state)}</h2>
+					<button type="button" ref={closeRef} className="menubar-dialog-close" aria-label={ko("Close", "닫기", "关闭")} onClick={onClose}>
+						<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M6 6l12 12M18 6L6 18" /></svg>
+					</button>
+				</header>
+				<div className="menubar-dialog-body">
+					{state.view === "available" && state.current && (
+						<p className="menubar-dialog-meta">{ko(`You have ${state.current}.`, `지금은 ${state.current} 버전이에요.`, `当前版本为 ${state.current}。`)}</p>
+					)}
+					{body && <p className="update-dialog-text">{body}</p>}
+					{state.actions.includes("copy_command") && <code className="update-dialog-command">{state.command}</code>}
+					{state.view === "available" && state.notesUrl && (
+						<p>
+							<a className="update-dialog-notes" data-testid="update-notes" href={state.notesUrl} target="_blank" rel="noopener noreferrer" onClick={() => onAction("release_notes")}>
+								{ko("What's new", "바뀐 내용 보기", "更新内容")}
+							</a>
+						</p>
+					)}
+					{startsInstall && blocked && (
+						<p className="update-dialog-busy" data-testid="update-busy">{ko("Finish the current turn or export first.", "진행 중인 턴이나 내보내기를 먼저 마치세요.", "请先完成当前的回合或导出。")}</p>
+					)}
+					<div className="update-dialog-actions">
+						{state.actions.includes("update_now") && (
+							<button type="button" className="update-dialog-primary" data-testid="update-now" disabled={blocked} onClick={onUpdate}>
+								{ko("Update now", "지금 업데이트", "立即更新")}
+							</button>
+						)}
+						{state.actions.includes("retry") && (
+							<button type="button" className="update-dialog-primary" data-testid="update-retry" disabled={blocked} onClick={onUpdate}>
+								{ko("Try again", "다시 시도", "重试")}
+							</button>
+						)}
+						{state.actions.includes("copy_command") && (
+							<button type="button" data-testid="update-copy" data-copied={copied || undefined} onClick={() => void copy()}>
+								{copied ? ko("Copied", "복사했어요", "已复制") : ko("Copy command", "명령 복사", "复制命令")}
+							</button>
+						)}
+						{state.actions.includes("later") && (
+							<button type="button" data-testid="update-later" onClick={onLater}>{ko("Later", "나중에", "稍后")}</button>
+						)}
+						{state.view === "restart_needed" && (
+							<button type="button" onClick={onClose}>{ko("Close", "닫기", "关闭")}</button>
+						)}
+					</div>
+				</div>
+			</div>
+		</div>,
+		document.body,
+	);
+}

package/src/update/update-client.js

@@ -0,0 +1,188 @@
+// The in-Studio update notice (U1): the launcher's GET/POST /__cozyclay/update
+// (bin/update-routes.mjs) read and driven from the page. Pure apart from the
+// injected fetch, timers, storage and window, so test/verify-update-client.mjs
+// drives it under Node. A page without window.__COZYCLAY_RUNTIME__ (the hosted
+// site, Vite dev) makes no request at all.
+export const UPDATE_URL = "/__cozyclay/update";
+export const DISMISS_KEY = "cozyclay:update-dismissed";
+export const POLL_MS = 6 * 60 * 60 * 1000;
+export const VISIBLE_STALE_MS = 60 * 60 * 1000;
+export const UPDATING_POLL_MS = 2000;
+
+const VERSION = /^\d+\.\d+\.\d+$/;
+const KINDS = new Set(["global", "npx", "clone"]);
+const STATUSES = new Set(["latest", "outdated", "unknown"]);
+const PHASES = new Set(["idle", "updating", "restart_needed", "failed"]);
+const ERROR_CLASSES = new Set(["permission", "network", "node_version", "npm_missing", "other"]);
+const NOTES_PREFIX = "https://github.com/NomaDamas/CozyClay/releases/tag/v";
+const GLOBAL_COMMAND = "npm install -g cozyclay@latest";
+const NPX_COMMAND = "npx cozyclay";
+const RESTART_COMMAND = "cclay";
+
+/** True on a page the npm launcher served (it injects window.__COZYCLAY_RUNTIME__). */
+function hasLauncherRuntime(win = globalThis.window) {
+	try { return Boolean(win?.__COZYCLAY_RUNTIME__); } catch { return false; }
+}
+
+const version = (value) => (typeof value === "string" && VERSION.test(value) ? value : null);
+
+/** The route body as the client trusts it: closed values only; anything else reads as "unknown". */
+export function normalizeUpdateInfo(body) {
+	if (!body || typeof body !== "object") return null;
+	const kind = KINDS.has(body.kind) ? body.kind : "clone";
+	const latest = version(body.latest);
+	const phase = PHASES.has(body.phase) ? body.phase : "idle";
+	return {
+		enabled: body.enabled === true,
+		current: version(body.current),
+		latest,
+		status: STATUSES.has(body.status) ? body.status : "unknown",
+		kind,
+		canSelfUpdate: body.canSelfUpdate === true,
+		phase,
+		errorClass: phase === "failed" ? (ERROR_CLASSES.has(body.errorClass) ? body.errorClass : "other") : null,
+		durationMs: Number.isFinite(body.durationMs) && body.durationMs >= 0 ? body.durationMs : null,
+		// Opened in a new tab, so only the project's own release page is accepted.
+		notesUrl: latest && body.notesUrl === `${NOTES_PREFIX}${latest}` ? body.notesUrl : null,
+		command: kind === "npx" ? NPX_COMMAND : GLOBAL_COMMAND,
+	};
+}
+
+async function request(fetchImpl, init, win) {
+	if (!hasLauncherRuntime(win) || typeof fetchImpl !== "function") return null;
+	try {
+		const response = await fetchImpl(UPDATE_URL, { cache: "no-store", credentials: "same-origin", ...init });
+		if (!response?.ok) return null;
+		return normalizeUpdateInfo(await response.json());
+	} catch {
+		return null;
+	}
+}
+
+/** GET the launcher's update state; null on a hosted page or any failure (the notice fails silently). */
+export const fetchUpdateInfo = (fetchImpl = globalThis.fetch?.bind(globalThis), win = globalThis.window) => request(fetchImpl, { method: "GET" }, win);
+
+/** POST: ask the launcher to install `latest`. The 202 body, or null (403/409/network). No body is sent. */
+export const startUpdate = (fetchImpl = globalThis.fetch?.bind(globalThis), win = globalThis.window) => request(fetchImpl, { method: "POST" }, win);
+
+/** patch | minor | major: how far `current` is behind `latest`. */
+export function behindOf(current, latest) {
+	const [a, b] = [current, latest].map((value) => (version(value) ?? "0.0.0").split(".").map(Number));
+	if (a[0] !== b[0]) return "major";
+	return a[1] !== b[1] ? "minor" : "patch";
+}
+
+// The in-progress export phases (App.jsx updateExportStatus; StatusBar.jsx BUSY). completed, failed and
+// cancelled stay in exportStatus after the job ends, so a non-null status alone is not "exporting".
+const EXPORT_BUSY_PHASES = new Set(["preparing", "encoding", "finalizing"]);
+
+/** "Update now" waits while an agent turn, an export or a recording runs: they would cross the file swap. */
+export function updateBlocked({ agentRunning = false, exportStatus = null, recState = "idle" } = {}) {
+	return Boolean(agentRunning) || EXPORT_BUSY_PHASES.has(exportStatus?.phase) || recState === "recording";
+}
+
+const HIDDEN = Object.freeze({ view: "hidden", actions: [] });
+
+/** The chip and dialog view for one poll result and the local dismiss state ({ dismissed }). */
+export function nextUpdateState(info, local = {}) {
+	if (!info || !info.enabled) return HIDDEN;
+	const base = {
+		current: info.current, latest: info.latest, kind: info.kind, notesUrl: info.notesUrl,
+		command: info.command, canSelfUpdate: info.canSelfUpdate, errorClass: null,
+	};
+	const oneClick = info.kind === "global" && info.canSelfUpdate;
+	if (info.phase === "updating") return { ...base, view: "updating", actions: [] };
+	if (info.phase === "restart_needed") return { ...base, view: "restart_needed", command: RESTART_COMMAND, actions: ["copy_command"] };
+	if (info.phase === "failed") {
+		return { ...base, view: "failed", errorClass: info.errorClass ?? "other", command: GLOBAL_COMMAND,
+			actions: oneClick ? ["retry", "copy_command"] : ["copy_command"] };
+	}
+	const shown = info.status === "outdated" && (info.kind === "global" || info.kind === "npx") && info.latest && local.dismissed !== info.latest;
+	if (!shown) return HIDDEN;
+	return { ...base, view: "available", behind: behindOf(info.current, info.latest), actions: [oneClick ? "update_now" : "copy_command", "later"] };
+}
+
+// Reading window.localStorage itself throws when site data is blocked, so even the default is guarded.
+const safeStorage = () => { try { return globalThis.localStorage; } catch { return null; } };
+
+/** The dismissed version, or null. Storage that throws reads as "nothing dismissed". */
+export function readDismissed(storage = safeStorage()) {
+	try { return version(storage?.getItem(DISMISS_KEY)); } catch { return null; }
+}
+
+/** Hide `latest` for good (per version). False when storage refused; the notice still hides for this page. */
+export function writeDismissed(latest, storage = safeStorage()) {
+	try { storage.setItem(DISMISS_KEY, latest); return true; } catch { return false; }
+}
+
+const defaultTimers = {
+	set: (fn, ms) => setTimeout(fn, ms),
+	clear: (timer) => clearTimeout(timer),
+	now: () => Date.now(),
+	// After the Studio's first frame, then idle: the check never competes with boot.
+	afterFirstFrame(fn) {
+		const idle = globalThis.requestIdleCallback ?? ((run) => setTimeout(run, 200));
+		const frame = globalThis.requestAnimationFrame ?? ((run) => setTimeout(run, 16));
+		frame(() => idle(fn));
+	},
+};
+
+/**
+ * The poll loop: once after the first frame and idle, every 6 h, on a visible
+ * tab whose last check is over 1 h old, every 2 s while installing. `onState`
+ * gets { state, info } after every change. Returns { dismiss, update, stop }.
+ */
+export function createUpdatePoller({
+	fetchImpl = globalThis.fetch?.bind(globalThis), onState = () => {}, timers = defaultTimers,
+	storage = safeStorage(), win = globalThis.window, doc = globalThis.document,
+} = {}) {
+	const noop = { dismiss() {}, update: async () => null, stop() {} };
+	if (!hasLauncherRuntime(win)) return noop;
+	let info = null, timer = null, stopped = false, inflight = null, lastCheck = -Infinity;
+	let dismissed = readDismissed(storage);
+	const emit = () => { if (!stopped) onState({ state: nextUpdateState(info, { dismissed }), info }); };
+	const schedule = () => {
+		if (stopped) return;
+		if (timer !== null) timers.clear(timer);
+		timer = timers.set(check, info?.phase === "updating" ? UPDATING_POLL_MS : POLL_MS);
+	};
+	const apply = (next) => { if (next) { info = next; emit(); } };
+	function check() {
+		if (stopped) return Promise.resolve(info);
+		if (inflight) return inflight;
+		// An early check (a visible tab) replaces the pending poll; the schedule never doubles.
+		if (timer !== null) { timers.clear(timer); timer = null; }
+		lastCheck = timers.now();
+		inflight = fetchUpdateInfo(fetchImpl, win);
+		return inflight.then((next) => { inflight = null; apply(next); schedule(); return info; });
+	}
+	const onVisible = () => {
+		if (doc?.visibilityState === "visible" && timers.now() - lastCheck > VISIBLE_STALE_MS) void check();
+	};
+	const onStorage = (event) => {
+		if (event?.key !== DISMISS_KEY && event?.key !== null) return;
+		dismissed = readDismissed(storage);
+		emit();
+	};
+	try { doc?.addEventListener?.("visibilitychange", onVisible); win?.addEventListener?.("storage", onStorage); } catch { /* no listeners: the 6 h poll still runs */ }
+	timers.afterFirstFrame(() => { if (!stopped) void check(); });
+	return {
+		dismiss(latest) {
+			if (!version(latest)) return;
+			writeDismissed(latest, storage);
+			dismissed = latest;
+			emit();
+		},
+		async update() {
+			const next = await startUpdate(fetchImpl, win);
+			apply(next);
+			schedule();
+			return next;
+		},
+		stop() {
+			stopped = true;
+			if (timer !== null) timers.clear(timer);
+			try { doc?.removeEventListener?.("visibilitychange", onVisible); win?.removeEventListener?.("storage", onStorage); } catch { /* best effort */ }
+		},
+	};
+}

package/src/update/update-telemetry.js

@@ -0,0 +1,78 @@
+// update:notice_shown, update:clicked and update:finished (the U1 update notice).
+// Only closed values leave: the install kind, how far behind (patch/minor/major),
+// the button, the outcome, the npm error class and a duration bucket. Never a
+// version string, a path, a command or npm's output. All three are passive
+// (analytics-strict.js), so none of them moves action_count_bucket.
+import { initAnalytics, track } from "../analytics.js";
+import { admit } from "../analytics-friction.js";
+import { bucketLong } from "../analytics-strict.js";
+
+const CLICKS_PER_SESSION = 10;
+const FINISHED_PER_SESSION = 3;
+const NOTICE_KINDS = new Set(["global", "npx"]);
+const CLICK_ACTIONS = new Set(["update_now", "copy_command", "later", "dismiss", "release_notes"]);
+// The install this browser already reported, shared by the tabs of one profile:
+// several tabs (and several polls) see the same terminal phase, the event leaves once.
+const REPORTED_KEY = "cozyclay:update-reported";
+
+let send = (event, props) => {
+	initAnalytics().then(() => track(event, props), () => {});
+};
+let storage = () => globalThis.localStorage;
+const reportedHere = new Set();
+
+/** The chip became visible in the "available" view: once per session. */
+export function noteNoticeShown(state) {
+	try {
+		if (state?.view !== "available" || !NOTICE_KINDS.has(state.kind)) return;
+		if (admit("update:notice_shown", 1)) send("update:notice_shown", { kind: state.kind, behind: state.behind });
+	} catch {
+		// Telemetry must never affect the notice.
+	}
+}
+
+/** A notice button: update_now (also Try again), copy_command, later, dismiss or release_notes. */
+export function noteUpdateClicked(action, kind) {
+	try {
+		if (!CLICK_ACTIONS.has(action) || !NOTICE_KINDS.has(kind)) return;
+		if (admit("update:clicked", CLICKS_PER_SESSION)) send("update:clicked", { action, kind });
+	} catch {
+		// Telemetry must never affect the notice.
+	}
+}
+
+function claim(key) {
+	if (reportedHere.has(key)) return false;
+	reportedHere.add(key);
+	try {
+		const store = storage();
+		if (store?.getItem(REPORTED_KEY) === key) return false;
+		store?.setItem(REPORTED_KEY, key);
+	} catch {
+		// No storage: this page's own memory still keeps it to once.
+	}
+	return true;
+}
+
+/** A poll result. A terminal install phase with its duration sends update:finished, once per install. */
+export function noteUpdatePolled(info) {
+	try {
+		if (!info || (info.phase !== "restart_needed" && info.phase !== "failed") || !Number.isFinite(info.durationMs)) return;
+		// The launcher holds one install at a time; its version, phase and wall time name it.
+		if (!claim(`${info.latest}|${info.phase}|${info.durationMs}`)) return;
+		if (!admit("update:finished", FINISHED_PER_SESSION)) return;
+		const failed = info.phase === "failed";
+		send("update:finished", { outcome: failed ? "failed" : "ok", error_class: failed ? info.errorClass ?? "other" : "none", duration: bucketLong(info.durationMs) });
+	} catch {
+		// Telemetry must never affect the poll.
+	}
+}
+
+/** Tests only: capture what is sent and substitute the storage; returns the restore. */
+export function updateTelemetrySeam(capture, store = null) {
+	const previous = { send, storage };
+	send = capture;
+	storage = () => store;
+	reportedHere.clear();
+	return () => { ({ send, storage } = previous); reportedHere.clear(); };
+}

package/src/update/update.css

@@ -0,0 +1,94 @@
+/* The update notice (U1): a quiet top-bar chip beside the MCP state, and the
+   dialog that reuses the Help dialog's menubar-dialog-* frame (topbar.css). */
+@layer regions {
+	.v2-topbar .update-chip-wrap {
+		display: inline-flex;
+		flex: none;
+		align-items: center;
+		gap: 2px;
+	}
+	.v2-topbar .update-chip {
+		display: inline-flex;
+		align-items: center;
+		gap: var(--sp-1, 8px);
+		height: var(--h-row, 24px);
+		padding: 0 var(--sp-1, 8px);
+		border: 0;
+		border-radius: var(--r-1, 4px);
+		background: transparent;
+		color: var(--text-2, #9b9ba1);
+		font: 500 var(--secondary-size, 11px) var(--sans);
+		white-space: nowrap;
+		cursor: pointer;
+	}
+	.v2-topbar .update-chip:hover,
+	.v2-topbar .update-chip[aria-expanded="true"] { background: var(--surface-raised, #1e1e21); color: var(--text-1, #e4e4e7); }
+	.v2-topbar .update-chip-dot {
+		flex: none;
+		width: var(--topbar-dot, 6px);
+		height: var(--topbar-dot, 6px);
+		border-radius: 50%;
+		background: var(--primary, #7258a0);
+	}
+	.v2-topbar .update-chip[data-update-view="failed"] .update-chip-dot { background: var(--danger, #e5484d); }
+	.v2-topbar .update-chip[data-update-view="restart_needed"] .update-chip-dot { background: var(--ok, #4fbf7a); }
+	.v2-topbar .update-chip-dismiss {
+		display: grid;
+		place-items: center;
+		width: 18px;
+		height: 18px;
+		padding: 0;
+		border: 0;
+		border-radius: var(--r-1, 4px);
+		background: transparent;
+		color: var(--text-3, #636369);
+		cursor: pointer;
+	}
+	.v2-topbar .update-chip-dismiss:hover { background: var(--surface-raised, #1e1e21); color: var(--text-1, #e4e4e7); }
+	.v2-topbar .update-chip-dismiss svg {
+		width: 10px;
+		height: 10px;
+		fill: none;
+		stroke: currentColor;
+		stroke-width: 2.5;
+		stroke-linecap: round;
+	}
+
+	.update-dialog .update-dialog-text { color: var(--text-1, #e4e4e7); line-height: 1.45; }
+	.update-dialog .update-dialog-command {
+		display: block;
+		margin: 0 0 var(--sp-1, 8px);
+		padding: 6px var(--sp-1, 8px);
+		border-radius: var(--r-1, 4px);
+		background: var(--surface-bar, #121214);
+		color: var(--text-1, #e4e4e7);
+		font: 400 var(--secondary-size, 11px) var(--mono);
+		user-select: all;
+	}
+	.update-dialog .update-dialog-notes { color: var(--camera, #a78bfa); font-size: var(--secondary-size, 11px); }
+	.update-dialog .update-dialog-busy { color: var(--select, #e8a33d); font-size: var(--secondary-size, 11px); }
+	.update-dialog .update-dialog-actions {
+		display: flex;
+		flex-wrap: wrap;
+		justify-content: flex-end;
+		gap: var(--sp-1, 8px);
+		margin-top: var(--sp-2, 12px);
+	}
+	.update-dialog .update-dialog-actions button {
+		height: var(--topbar-primary-height, 30px);
+		padding: 0 var(--sp-2, 12px);
+		border: 0;
+		border-radius: var(--r-1, 4px);
+		background: var(--surface-raised, #1e1e21);
+		color: var(--text-1, #e4e4e7);
+		font: 500 var(--ui-size, 12px) var(--sans);
+		cursor: pointer;
+	}
+	.update-dialog .update-dialog-actions button:hover:not(:disabled) { background: var(--surface-active, #26262a); }
+	.update-dialog .update-dialog-actions .update-dialog-primary { background: var(--primary, #7258a0); color: var(--text-selected, #fff); }
+	.update-dialog .update-dialog-actions .update-dialog-primary:hover:not(:disabled) {
+		background: color-mix(in srgb, var(--primary, #7258a0) 86%, var(--text-selected, #fff));
+	}
+	.update-dialog .update-dialog-actions button:disabled { color: var(--text-off, #4f4f55); cursor: default; }
+	.update-dialog .update-dialog-actions .update-dialog-primary:disabled { background: var(--surface-raised, #1e1e21); }
+}

package/src/use-webgl-available.js

@@ -0,0 +1,35 @@
+// The stage's one-time WebGL check. It runs in a mount effect, never in render:
+// probing creates a throwaway canvas and a GL context. The result is cached for
+// the page, so a remount does not probe again.
+import { useEffect, useState } from "react";
+import { reportGlLost } from "./crash-telemetry.js";
+
+let cached = null;
+
+function probe() {
+	if (cached !== null) return cached;
+	try {
+		const canvas = document.createElement("canvas");
+		cached = Boolean(canvas.getContext("webgl") || canvas.getContext("experimental-webgl"));
+	} catch {
+		cached = false;
+	}
+	return cached;
+}
+
+/** False once the mount check found no WebGL; true before it runs and when WebGL works. */
+export function useWebGlAvailable() {
+	const [available, setAvailable] = useState(cached ?? true);
+	useEffect(() => {
+		if (typeof document === "undefined") return undefined;
+		// A task after the first commit keeps the throwaway GL context off the
+		// commit path; a StrictMode remount clears the first timer.
+		const timer = setTimeout(() => {
+			const ok = probe();
+			setAvailable(ok);
+			if (!ok) reportGlLost("unavailable");
+		}, 0);
+		return () => clearTimeout(timer);
+	}, []);
+	return available;
+}