@steerable/agent-shell-web 0.6.48 → 0.6.50

package/src/components/settings/PythonRunnerSettingsPanel.tsx

@@ -0,0 +1,231 @@
+import { useEffect, useState } from 'react';
+import { LuCodeXml } from 'react-icons/lu';
+import {
+  getElectronBridge,
+  type PythonRunnerSnapshot,
+} from '@/lib/electron-bridge';
+
+type Source = PythonRunnerSnapshot['source'];
+
+function formatBytes(value?: number): string {
+  if (value == null) return '';
+  return `${(value / 1024 / 1024).toFixed(1)} MB`;
+}
+
+export function PythonRunnerSettingsPanel() {
+  const [snapshot, setSnapshot] = useState<PythonRunnerSnapshot | null>(null);
+  const [source, setSource] = useState<Source>('default');
+  const [url, setUrl] = useState('');
+  const [localPath, setLocalPath] = useState('');
+
+  useEffect(() => {
+    const runner = getElectronBridge()?.pythonRunner;
+    if (!runner) return;
+    let alive = true;
+    void runner.snapshot().then((next) => {
+      if (!alive) return;
+      setSnapshot(next);
+      setSource(next.source);
+      setUrl(next.configuredUrl ?? '');
+    }).catch(() => {});
+    const off = runner.onState((next) => {
+      if (alive) setSnapshot(next);
+    });
+    return () => {
+      alive = false;
+      off();
+    };
+  }, []);
+
+  if (!snapshot?.supported) return null;
+  const runner = getElectronBridge()?.pythonRunner;
+  const busy =
+    snapshot.phase === 'downloading'
+    || snapshot.phase === 'verifying'
+    || snapshot.phase === 'extracting';
+
+  const update = (task: Promise<PythonRunnerSnapshot>) => {
+    void task.then(setSnapshot).catch((error: unknown) => {
+      setSnapshot({
+        ...snapshot,
+        phase: 'error',
+        message: error instanceof Error ? error.message : String(error),
+      });
+    });
+  };
+
+  const chooseLocal = () => {
+    if (!runner) return;
+    void runner.pickLocal().then((path) => {
+      if (path) setLocalPath(path);
+    });
+  };
+
+  const run = () => {
+    if (!runner || busy) return;
+    if (source === 'local') {
+      update(runner.useLocal(localPath));
+      return;
+    }
+    update(runner.download(source === 'url' ? url : undefined));
+  };
+
+  const actionLabel =
+    source === 'local'
+      ? '使用此 Python'
+      : source === 'url'
+        ? '从此地址下载'
+        : '下载默认运行器';
+  const phaseLabel =
+    snapshot.phase === 'verifying'
+      ? '正在校验'
+      : snapshot.phase === 'extracting'
+        ? '正在解压'
+        : '正在下载';
+
+  return (
+    <section className="space-y-2" data-testid="settings-section-python-runner">
+      <h2 className="flex items-center gap-1.5 text-xs font-semibold text-agent-foreground">
+        <LuCodeXml className="h-3.5 w-3.5 text-agent-muted-foreground" />
+        Python 代码运行器
+      </h2>
+      <div className="space-y-3 rounded-agent-md border border-agent-border bg-agent-card p-3 text-xs">
+        <p className="leading-relaxed text-agent-muted-foreground">
+          run_code 使用独立的 Python 解释器。下载和配置不会阻塞聊天，变更在重启应用后生效。
+        </p>
+
+        <div className="flex flex-wrap gap-3">
+          {([
+            ['default', '默认地址'],
+            ['url', '自定义地址'],
+            ['local', '本地 Python'],
+          ] as const).map(([value, label]) => (
+            <label key={value} className="flex items-center gap-1.5 text-agent-foreground">
+              <input
+                type="radio"
+                name="python-runner-source"
+                value={value}
+                checked={source === value}
+                disabled={busy}
+                onChange={() => setSource(value)}
+              />
+              {label}
+            </label>
+          ))}
+        </div>
+
+        {source === 'default' ? (
+          <p className="break-all text-agent-muted-foreground" data-testid="python-runner-default-url">
+            {snapshot.defaultUrl}
+          </p>
+        ) : null}
+
+        {source === 'url' ? (
+          <div className="space-y-1.5">
+            <input
+              type="url"
+              value={url}
+              disabled={busy}
+              placeholder="https://example.com/python-runner.tar.gz"
+              className="h-8 w-full rounded-agent-sm border border-agent-border bg-agent-canvas px-2 text-agent-foreground outline-none focus:border-agent-foreground/40"
+              onChange={(event) => setUrl(event.target.value)}
+            />
+            <p className="text-agent-destructive">
+              自定义地址不会校验文件完整性，请仅使用可信来源。
+            </p>
+          </div>
+        ) : null}
+
+        {source === 'local' ? (
+          <div className="flex gap-2">
+            <input
+              type="text"
+              value={localPath}
+              disabled={busy}
+              placeholder="Python 可执行文件的绝对路径"
+              className="h-8 min-w-0 flex-1 rounded-agent-sm border border-agent-border bg-agent-canvas px-2 text-agent-foreground outline-none focus:border-agent-foreground/40"
+              onChange={(event) => setLocalPath(event.target.value)}
+            />
+            <button
+              type="button"
+              disabled={busy}
+              className="h-8 shrink-0 rounded-agent-sm border border-agent-border px-3 text-agent-foreground hover:bg-agent-foreground/5 disabled:opacity-50"
+              onClick={chooseLocal}
+            >
+              选择…
+            </button>
+          </div>
+        ) : null}
+
+        {busy ? (
+          <div className="space-y-2" data-testid="python-runner-progress">
+            <div className="h-1.5 overflow-hidden rounded-full bg-agent-foreground/10">
+              <div
+                className="h-full rounded-full bg-agent-foreground transition-[width]"
+                style={{ width: `${snapshot.percent ?? 0}%` }}
+              />
+            </div>
+            <div className="flex items-center justify-between text-agent-muted-foreground">
+              <span>
+                {phaseLabel}
+                {snapshot.percent != null ? ` ${snapshot.percent}%` : ''}
+                {snapshot.downloadedBytes != null
+                  ? ` · ${formatBytes(snapshot.downloadedBytes)}${snapshot.totalBytes ? ` / ${formatBytes(snapshot.totalBytes)}` : ''}`
+                  : ''}
+              </span>
+              <button
+                type="button"
+                className="text-agent-foreground hover:underline"
+                onClick={() => runner && update(runner.cancel())}
+              >
+                取消
+              </button>
+            </div>
+          </div>
+        ) : (
+          <div className="flex gap-2">
+            <button
+              type="button"
+              data-testid="python-runner-action"
+              disabled={
+                (source === 'url' && !url.trim())
+                || (source === 'local' && !localPath.trim())
+              }
+              className="h-8 rounded-agent-sm border border-agent-border px-3 text-agent-foreground hover:bg-agent-foreground/5 disabled:opacity-50"
+              onClick={run}
+            >
+              {actionLabel}
+            </button>
+            {snapshot.restartRequired ? (
+              <button
+                type="button"
+                data-testid="python-runner-restart"
+                className="h-8 rounded-agent-sm bg-agent-foreground px-3 font-medium text-agent-canvas hover:opacity-90"
+                onClick={() => void runner?.restart()}
+              >
+                重启应用
+              </button>
+            ) : null}
+          </div>
+        )}
+
+        {snapshot.message ? (
+          <p
+            className={snapshot.phase === 'error' ? 'text-agent-destructive' : 'text-agent-muted-foreground'}
+            role={snapshot.phase === 'error' ? 'alert' : undefined}
+          >
+            {snapshot.message}
+          </p>
+        ) : null}
+        {snapshot.restartRequired ? (
+          <p className="font-medium text-agent-foreground">已保存，重启应用后生效。</p>
+        ) : null}
+        {snapshot.activeRunner ? (
+          <p className="break-all text-agent-muted-foreground">
+            当前会话：{snapshot.activeRunner}
+          </p>
+        ) : null}
+      </div>
+    </section>
+  );
+}

package/src/layouts/AgentLayout.tsx

@@ -10,6 +10,7 @@ import { InsightsConsentBanner } from '@/components/settings/InsightsSettingsPan
 import { trackBehavior } from '@/lib/insights';
 import { getElectronBridge, isElectron } from '@/lib/electron-bridge';
 import { deleteChatIfEmpty, pruneEmptyChats } from '@/lib/local-api';
+import { PORTABLE_CHATS_CHANGED_EVENT } from '@/lib/portable';
 import { getPackChatSlots, type PackChatSlotContribution } from '@/packs/registry';
 import {
   useChatsAndAgents,
@@ -186,6 +187,13 @@ function AgentLayoutContent() {
     });
     return unsubscribe;
   }, []);
+  useEffect(() => {
+    const onImported = () => {
+      void refreshChatsRef.current();
+    };
+    window.addEventListener(PORTABLE_CHATS_CHANGED_EVENT, onImported);
+    return () => window.removeEventListener(PORTABLE_CHATS_CHANGED_EVENT, onImported);
+  }, []);
 
   // 空会话不进侧栏：启动时清掉从未发过消息的残骸；离开一段空对话时丢掉它。
   // except / 离开检测都避开当前打开的 chatId，避免和首页首条发送抢跑。
@@ -402,6 +410,21 @@ function AgentLayoutContent() {
     [setRightPanel],
   );
 
+  // Cmd+T from the app menu — wired in src/main.ts:createMenu (sends
+  // `menu:open-terminal`). The terminal is a toggleable panel beside the chat,
+  // so this flips the layout state owned by AgentLayout.
+  useEffect(() => {
+    if (!hostToolChrome('terminal')) return;
+    const bridge = getElectronBridge();
+    if (!bridge?.onMenuOpenTerminal) return;
+    bridge.onMenuOpenTerminal(() => {
+      toggleRightPanel('terminal');
+    });
+    return () => {
+      bridge.offMenuOpenTerminal?.();
+    };
+  }, [toggleRightPanel]);
+
   // dock 里当前显示的任务（null = 显示终端）。recentTask 在切回终端后仍
   // 保留，终端头部的「后台任务」按钮据此切回来——任务的挑选入口只有一个，
   // 就是 chat 头部的后台任务弹层。

package/src/lib/electron-bridge.ts

@@ -48,6 +48,7 @@ export interface ApprovalPromptRequest {
   mode: string;
   category: string;
   round: number;
+  chatId?: string;
 }
 
 /**
@@ -110,6 +111,29 @@ export interface AppReleaseSnapshot {
   message?: string;
 }
 
+export type PythonRunnerPhase =
+  | 'idle'
+  | 'downloading'
+  | 'verifying'
+  | 'extracting'
+  | 'ready'
+  | 'error';
+
+export interface PythonRunnerSnapshot {
+  supported: boolean;
+  source: 'default' | 'url' | 'local';
+  phase: PythonRunnerPhase;
+  percent?: number;
+  downloadedBytes?: number;
+  totalBytes?: number;
+  message?: string;
+  defaultUrl?: string;
+  configuredUrl?: string;
+  activeRunner?: string;
+  configuredRunner?: string;
+  restartRequired: boolean;
+}
+
 export interface HostBridge {
   runtime: 'local';
   platform: NodeJS.Platform;
@@ -169,6 +193,15 @@ export interface HostBridge {
    */
   onMenuOpenTerminal?: (callback: () => void) => void;
   offMenuOpenTerminal?: () => void;
+  /**
+   * App menu IPC — `Cmd+V` / 编辑 → 粘贴 fires `menu:paste`.
+   * WKWebView does not expose that pasteboard to the page, so the renderer
+   * reads it through `readClipboardText`.
+   */
+  onMenuPaste?: (callback: () => void) => void;
+  offMenuPaste?: () => void;
+  /** Plain text from the OS pasteboard. Empty when the clipboard has no text. */
+  readClipboardText?: () => Promise<string>;
   /**
    * 异步 AI 标题就绪通知。Backend 在每条 chat 首条助手回复完成后 fire-and-forget
    * 跑 LLM 生成标题；完成时通过这个通道把 `{chatId, title}` 推过来。返回的函数
@@ -277,6 +310,17 @@ export interface HostBridge {
     install: () => Promise<AppReleaseSnapshot>;
     onState: (callback: (snapshot: AppReleaseSnapshot) => void) => () => void;
   };
+  /** Desktop-only Python child interpreter management for run_code. */
+  pythonRunner?: {
+    snapshot: () => Promise<PythonRunnerSnapshot>;
+    download: (url?: string) => Promise<PythonRunnerSnapshot>;
+    cancel: () => Promise<PythonRunnerSnapshot>;
+    pickLocal: () => Promise<string | null>;
+    useLocal: (path: string) => Promise<PythonRunnerSnapshot>;
+    useDefault: () => Promise<PythonRunnerSnapshot>;
+    restart: () => Promise<void>;
+    onState: (callback: (snapshot: PythonRunnerSnapshot) => void) => () => void;
+  };
   // 场景包的 invoke 命名空间（如包 preload 贡献的 `<pack>` / `<pack>Mock`）
   // 不进本接口——包用自己的结构化收窄访问器（见各包 web/bridge.ts），
   // shell 桥接口保持产品中立（3.1）。

package/src/lib/host-paste.ts

@@ -0,0 +1,85 @@
+/**
+ * WKWebView paste does not carry clipboard text into the page. The Edit menu
+ * shortcut emits `menu:paste`; this module reads the OS pasteboard and writes
+ * it into the focused field.
+ */
+import { getHostBridge } from './electron-bridge';
+
+let pending = false;
+let lastEditable: HTMLElement | null = null;
+let installed = false;
+
+/** Remember the field that should receive a menu paste after focus moves. */
+export function installHostPaste(): void {
+  if (installed || typeof document === 'undefined') return;
+  installed = true;
+  document.addEventListener('focusin', (event) => {
+    const target = event.target;
+    if (isEditable(target)) lastEditable = target;
+  });
+  const bridge = getHostBridge();
+  bridge?.onMenuPaste?.(() => {
+    requestHostPaste();
+  });
+}
+
+/** Read the OS pasteboard and insert it into `target` or the focused field. */
+export function requestHostPaste(target?: HTMLElement | null): void {
+  const read = getHostBridge()?.readClipboardText;
+  if (!read || pending) return;
+  pending = true;
+  void read()
+    .then((text) => {
+      if (text) insertHostText(text, target ?? null);
+    })
+    .catch((error: unknown) => {
+      console.warn('[host-paste] clipboard read failed', error);
+    })
+    .finally(() => {
+      pending = false;
+    });
+}
+
+export function hostClipboardAvailable(): boolean {
+  return typeof getHostBridge()?.readClipboardText === 'function';
+}
+
+function isEditable(target: EventTarget | null): target is HTMLElement {
+  return (
+    target instanceof HTMLInputElement ||
+    target instanceof HTMLTextAreaElement ||
+    (target instanceof HTMLElement && target.isContentEditable)
+  );
+}
+
+function focusedEditable(): HTMLElement | null {
+  if (isEditable(document.activeElement)) return document.activeElement;
+  if (lastEditable?.isConnected) return lastEditable;
+  return null;
+}
+
+function insertHostText(text: string, preferred: HTMLElement | null): void {
+  const el = preferred?.isConnected ? preferred : focusedEditable();
+  if (!el) return;
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+    if (el.readOnly || el.disabled) return;
+    writeFormValue(el, text);
+    return;
+  }
+  if (el.isContentEditable || el.getAttribute('contenteditable') === 'true') {
+    el.dispatchEvent(new CustomEvent('hostpaste', { detail: text }));
+  }
+}
+
+function writeFormValue(el: HTMLInputElement | HTMLTextAreaElement, text: string): void {
+  const start = el.selectionStart ?? el.value.length;
+  const end = el.selectionEnd ?? start;
+  const next = `${el.value.slice(0, start)}${text}${el.value.slice(end)}`;
+  const caret = start + text.length;
+  const prototype =
+    el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+  const setter = Object.getOwnPropertyDescriptor(prototype, 'value')?.set;
+  setter?.call(el, next);
+  el.setSelectionRange(caret, caret);
+  el.dispatchEvent(new Event('input', { bubbles: true }));
+}

package/src/lib/local-api.ts

@@ -25,6 +25,10 @@ export interface LocalChat {
   isPinned: boolean;
   systemPrompt: string | null;
   pinnedRefs: unknown;
+  /** 是否正在流式生成/对话中。 */
+  isStreaming?: boolean;
+  /** 是否存在需要用户回答或审批的问题。 */
+  needsUserInput?: boolean;
 }
 
 /** 智能体的工具准入策略；`all` = 不限制。 */
@@ -133,6 +137,20 @@ export async function deleteChat(chatId: string) {
   });
 }
 
+/** 置顶或取消置顶指定会话。 */
+export async function setChatPinned(chatId: string, isPinned: boolean) {
+  return bridge().localBackend.request<{
+    success: boolean;
+    chatId: string;
+    isPinned: boolean;
+    message: string;
+  }>({
+    method: 'PUT',
+    path: `/api/v2/chats/${encodeURIComponent(chatId)}/pin`,
+    body: { isPinned },
+  });
+}
+
 /** 没有消息的会话才删；已有内容或会话不存在都返回 `deleted: false`。 */
 export async function deleteChatIfEmpty(chatId: string) {
   return bridge().localBackend.request<{

package/src/lib/portable.ts

@@ -0,0 +1,229 @@
+/**
+ * 对话包与配置包的渲染层。产品须把 VITE_PORTABLE 打成 'true' 才出现入口。
+ * 界面档位和命令权限存在 localStorage，由这里并进配置包；其余段走本地后端。
+ */
+
+import { getElectronBridge } from '@/lib/electron-bridge';
+import { listChats } from '@/lib/local-api';
+import { persistExecPolicy, readStoredExecPolicy, type ExecPolicy } from '@/lib/exec-policy';
+import {
+  isThinkingDisplayMode,
+  persistThinkingDisplay,
+  readThinkingDisplay,
+  type ThinkingDisplayMode,
+} from '@/lib/show-thinking-content';
+
+export function isPortableEnabled(): boolean {
+  return import.meta.env.VITE_PORTABLE === 'true';
+}
+
+export interface PortablePreviewSection {
+  id: string;
+  label: string;
+  detail: string;
+  clientOnly: boolean;
+  hasSecret: boolean;
+}
+
+export const PORTABLE_CHATS_CHANGED_EVENT = 'steerable-portable-chats-changed';
+
+export interface PortablePreview {
+  kind: 'steerable-config' | 'steerable-chat' | 'steerable-chats';
+  includeSecrets: boolean;
+  sections: PortablePreviewSection[];
+  chat?: {
+    title: string;
+    messageCount: number;
+    attachmentCount: number;
+    omittedAttachmentCount: number;
+    truncated: boolean;
+    count?: number;
+    projectName?: string;
+    projectCount?: number;
+  };
+}
+
+export interface PortableConfigDocument {
+  kind: 'steerable-config';
+  schemaVersion: number;
+  exportedAt: string;
+  includeSecrets: boolean;
+  sections: Record<string, unknown>;
+}
+
+export interface PortableImportResult {
+  applied: string[];
+  skipped: Array<{ id: string; reason: string }>;
+  notes: string[];
+  missingSkills: string[];
+  clientSections: string[];
+}
+
+export interface PortableChatImportResult {
+  chatId: string;
+  title: string;
+  messageCount: number;
+  attachmentsSaved: number;
+}
+
+const CLIENT_SECTION_IDS = ['appearance', 'execPolicy'] as const;
+
+export function portableErrorMessage(err: unknown): string {
+  if (!(err instanceof Error)) return '操作失败';
+  const message = err.message.trim();
+  if (!message) return '操作失败';
+  try {
+    const parsed = JSON.parse(message) as { detail?: unknown; error?: unknown };
+    if (typeof parsed.detail === 'string' && parsed.detail.trim()) return parsed.detail;
+    if (typeof parsed.error === 'string' && parsed.error.trim()) return parsed.error;
+  } catch {
+    // 后端在浏览器模式直接给出文案；桌面模式把 JSON 放进 message。
+  }
+  return message;
+}
+
+export function parsePortableText(text: string): { ok: true; value: unknown } | { ok: false; error: string } {
+  try {
+    return { ok: true, value: JSON.parse(text) as unknown };
+  } catch {
+    return { ok: false, error: '文件不是 JSON' };
+  }
+}
+
+export function safeDownloadName(stem: string, suffix: string): string {
+  const cleaned = stem.replace(/[\\/:*?"<>|]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 40);
+  return `${cleaned || '导出'}-${suffix}.json`;
+}
+
+export function readLocalSections(): { appearance: { thinkingDisplay: ThinkingDisplayMode }; execPolicy: { policy: ExecPolicy } } {
+  return {
+    appearance: { thinkingDisplay: readThinkingDisplay() },
+    execPolicy: { policy: readStoredExecPolicy() },
+  };
+}
+
+/** 把勾选的本机段并进服务端导出的配置包，并删掉没勾的段。 */
+export function finishConfigDocument(
+  document: PortableConfigDocument,
+  selected: ReadonlySet<string>,
+): PortableConfigDocument {
+  const sections: Record<string, unknown> = {};
+  for (const [id, value] of Object.entries(document.sections)) {
+    if (selected.has(id)) sections[id] = value;
+  }
+  const local = readLocalSections();
+  if (selected.has('appearance')) sections.appearance = local.appearance;
+  if (selected.has('execPolicy')) sections.execPolicy = local.execPolicy;
+  return { ...document, sections };
+}
+
+export function applyClientSections(
+  sections: Record<string, unknown>,
+  selected: ReadonlySet<string>,
+): void {
+  if (selected.has('appearance')) {
+    const appearance = sections.appearance as { thinkingDisplay?: unknown } | undefined;
+    if (isThinkingDisplayMode(appearance?.thinkingDisplay)) {
+      persistThinkingDisplay(appearance.thinkingDisplay);
+    }
+  }
+  if (selected.has('execPolicy')) {
+    const policy = (sections.execPolicy as { policy?: unknown } | undefined)?.policy;
+    if (policy === 'workspace' || policy === 'full') persistExecPolicy(policy);
+  }
+}
+
+export function isClientSection(id: string): boolean {
+  return (CLIENT_SECTION_IDS as readonly string[]).includes(id);
+}
+
+async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
+  const bridge = getElectronBridge();
+  if (!bridge) throw new Error('当前环境没有本地后端');
+  return bridge.localBackend.request<T>(body === undefined ? { method, path } : { method, path, body });
+}
+
+export async function fetchConfigDocument(includeSecrets: boolean): Promise<PortableConfigDocument> {
+  const flag = includeSecrets ? '1' : '0';
+  return request<PortableConfigDocument>('GET', `/api/v2/portable/config?includeSecrets=${flag}`);
+}
+
+export async function fetchChatDocument(chatId: string): Promise<unknown> {
+  return request('GET', `/api/v2/chats/${encodeURIComponent(chatId)}/portable`);
+}
+
+/** 设置页导出对话用。按更新时间分页拉全，避免只导出第一页。 */
+export async function listPortableChats(): Promise<Array<{ id: string; title: string }>> {
+  const rows: Array<{ id: string; title: string }> = [];
+  let page = 1;
+  for (;;) {
+    const res = await listChats({ page, limit: 100 });
+    for (const chat of res.chats) {
+      rows.push({ id: chat.id, title: chat.title.trim() || '未命名对话' });
+    }
+    if (!res.pagination.hasMore || page >= 50) break;
+    page += 1;
+  }
+  return rows;
+}
+
+export async function previewPortableDocument(document: unknown): Promise<PortablePreview> {
+  return request<PortablePreview>('POST', '/api/v2/portable/preview', { document });
+}
+
+export async function importConfigDocument(
+  document: unknown,
+  sections: readonly string[],
+): Promise<PortableImportResult> {
+  return request<PortableImportResult>('POST', '/api/v2/portable/config', { document, sections });
+}
+
+export async function importChatDocument(document: unknown): Promise<PortableChatImportResult> {
+  const result = await request<PortableChatImportResult>('POST', '/api/v2/portable/chats', { document });
+  if (typeof window !== 'undefined') {
+    window.dispatchEvent(new Event(PORTABLE_CHATS_CHANGED_EVENT));
+  }
+  return result;
+}
+
+export async function saveJsonFile(filename: string, data: unknown): Promise<string | null> {
+  const content = `${JSON.stringify(data, null, 2)}\n`;
+  const save = getElectronBridge()?.local?.saveTextFile;
+  if (save) {
+    const saved = await save({ title: '导出', defaultPath: filename, content });
+    if (saved.canceled || !saved.filePath) return null;
+    return saved.filePath;
+  }
+  if (typeof document === 'undefined') return filename;
+  const url = URL.createObjectURL(new Blob([content], { type: 'application/json' }));
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = filename;
+  link.click();
+  URL.revokeObjectURL(url);
+  return filename;
+}
+
+export function pickJsonFile(): Promise<string | null> {
+  return new Promise((resolve) => {
+    if (typeof document === 'undefined') {
+      resolve(null);
+      return;
+    }
+    const input = document.createElement('input');
+    input.type = 'file';
+    input.accept = 'application/json,.json';
+    input.onchange = () => {
+      const file = input.files?.[0];
+      if (!file) {
+        resolve(null);
+        return;
+      }
+      const reader = new FileReader();
+      reader.onload = () => resolve(typeof reader.result === 'string' ? reader.result : null);
+      reader.onerror = () => resolve(null);
+      reader.readAsText(file);
+    };
+    input.click();
+  });
+}