@thaut/claude-ide 0.0.0-stage → 1.0.0

package/web/src/pages/settings/SkillsPage.tsx

@@ -0,0 +1,142 @@
+import { useState } from "react";
+import { useSearchParams } from "react-router";
+import type { SkillInfo } from "@shared/config.ts";
+import { Markdown } from "../../components/Markdown.tsx";
+import { Button, cx } from "../../ui/Button.tsx";
+import { ArrowLeftIcon, SearchIcon, SparkIcon } from "../../ui/icons.tsx";
+import { Card, Empty, EmptyState, ErrorLine, Loading, PageTitle, SplitView, Tag, inputCls, useCfg, useProjectParam } from "./ui.tsx";
+
+const SOURCE_LABEL: Record<string, string> = {
+  user: "用户级",
+  project: "项目级",
+  plugin: "插件提供",
+  "user-command": "用户级命令（.claude/commands）",
+  "project-command": "项目级命令（.claude/commands）",
+};
+
+export function SkillsPage() {
+  const pid = useProjectParam();
+  const skills = useCfg<SkillInfo[]>("skills", pid);
+  const [sp, setSp] = useSearchParams();
+  const [q, setQ] = useState("");
+  const selected = sp.get("f");
+  const select = (p: string | null) => {
+    const n = new URLSearchParams(sp);
+    if (p) n.set("f", p);
+    else n.delete("f");
+    setSp(n);
+  };
+  const all = skills.data ?? [];
+  const match = (s: SkillInfo) => !q || `${s.name} ${s.description}`.toLowerCase().includes(q.toLowerCase());
+  const groups = Object.keys(SOURCE_LABEL).map((src) => ({ src, items: all.filter((s) => s.source === src && match(s)) }));
+  const current = all.find((s) => s.path === selected);
+
+  const list = (
+    <div className="space-y-4">
+      {all.length > 6 && (
+        <span className="relative block">
+          <SearchIcon className="pointer-events-none absolute left-2.5 top-1/2 -translate-y-1/2 text-muted" />
+          <input aria-label="筛选技能" placeholder={`在 ${all.length} 个技能里筛选`} value={q} onChange={(e) => setQ(e.target.value)} onKeyDown={(e) => e.key === "Escape" && setQ("")} className={`${inputCls} pl-8`} />
+        </span>
+      )}
+      {groups
+        .filter((g) => g.items.length)
+        .map((g) => (
+          <Card key={g.src} title={SOURCE_LABEL[g.src]} count={g.items.length} flush>
+            <ul className="p-1">
+              {g.items.map((s) => (
+                <li key={s.path ?? s.name}>
+                  <button
+                    className={cx(
+                      "block w-full rounded-md px-3 py-2.5 text-left transition-colors disabled:cursor-default",
+                      s.path && s.path === selected ? "bg-accent/10" : "hover:bg-surface-2",
+                    )}
+                    disabled={!s.path}
+                    onClick={() => s.path && select(s.path)}
+                    aria-current={s.path === selected ? "true" : undefined}
+                    data-testid="skill"
+                    data-name={s.name}
+                  >
+                    <div className="flex flex-wrap items-center gap-1.5">
+                      <span className="font-mono text-sm font-medium">/{s.name}</span>
+                      {s.plugin && <Tag>{s.plugin}</Tag>}
+                      {s.state && s.state !== "on" && <Tag tone="warn">{s.state}</Tag>}
+                    </div>
+                    {s.description && <p className="mt-0.5 line-clamp-2 text-xs leading-relaxed text-muted">{s.description}</p>}
+                  </button>
+                </li>
+              ))}
+            </ul>
+          </Card>
+        ))}
+      {q && groups.every((g) => !g.items.length) && <Empty title="没有匹配的技能">换个关键词试试。</Empty>}
+    </div>
+  );
+
+  return (
+    <div>
+      <PageTitle title="技能" desc="用户级 ~/.claude/skills、项目级 .claude/skills 和插件带来的技能。在对话里用 / 调用，Claude 也会按说明自动使用。" />
+      {skills.isPending && <Loading />}
+      <ErrorLine error={skills.error} />
+      {skills.data &&
+        (all.length === 0 ? (
+          <EmptyState icon={<SparkIcon size={16} />} title="还没有技能">
+            在 <code className="font-mono">~/.claude/skills/名称/SKILL.md</code> 或项目的 <code className="font-mono">.claude/skills/</code> 下放一个 SKILL.md，或在“插件”页安装带技能的插件。
+          </EmptyState>
+        ) : (
+          <SplitView
+            showDetail={!!selected}
+            listWidth="lg:w-96"
+            list={list}
+            detail={
+              selected ? (
+                <SkillFile key={selected} pid={pid} path={selected} skill={current} onClose={() => select(null)} />
+              ) : (
+                <EmptyState icon={<SparkIcon size={16} />} title="选择一个技能查看 SKILL.md">
+                  共 {all.length} 个技能。
+                </EmptyState>
+              )
+            }
+          />
+        ))}
+    </div>
+  );
+}
+
+function SkillFile({ pid, path, skill, onClose }: { pid?: string; path: string; skill?: SkillInfo; onClose: () => void }) {
+  const file = useCfg<{ path: string; content: string }>("skills/file", pid, { params: { path } });
+  const body = file.data?.content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "") ?? "";
+  const front = file.data?.content.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
+  const fields = front
+    ?.split("\n")
+    .map((l) => /^([\w-]+):\s*(.*)$/.exec(l))
+    .filter((m): m is RegExpExecArray => !!m && m[1] !== "description");
+  return (
+    <Card
+      icon={<SparkIcon />}
+      title={skill ? `/${skill.name}` : (path.split("/").slice(-2, -1)[0] ?? "SKILL.md")}
+      sub={path}
+      actions={
+        <Button variant="ghost" size="sm" icon={<ArrowLeftIcon />} onClick={onClose} aria-label="返回列表">
+          <span className="lg:hidden">返回</span>
+          <span className="hidden lg:inline">关闭</span>
+        </Button>
+      }
+    >
+      {file.isPending && <Loading rows={5} />}
+      <ErrorLine error={file.error} />
+      {skill?.description && <p className="mb-3 text-sm leading-relaxed text-muted">{skill.description}</p>}
+      {fields && fields.length > 0 && (
+        <dl className="mb-4 grid grid-cols-[auto_1fr] gap-x-4 gap-y-1 rounded-lg bg-surface-2/60 px-3 py-2 text-xs">
+          {fields.map((m) => (
+            <div key={m[1]} className="contents">
+              <dt className="font-mono text-muted">{m[1]}</dt>
+              <dd className="break-all font-mono">{m[2] || "—"}</dd>
+            </div>
+          ))}
+        </dl>
+      )}
+      {file.data && <Markdown text={body} />}
+    </Card>
+  );
+}

package/web/src/pages/settings/ui.tsx

@@ -0,0 +1,165 @@
+import type { ReactNode } from "react";
+import { useSearchParams } from "react-router";
+import { useMutation, useQuery, useQueryClient, type QueryKey } from "@tanstack/react-query";
+import { SCOPE_LABEL, type SettingsScope } from "@shared/config.ts";
+import { api, ApiError } from "../../api.ts";
+import { cx } from "../../ui/Button.tsx";
+import { Select } from "../../ui/Select.tsx";
+import { EmptyState, Skeleton, Tag, type TagTone } from "../../ui/Form.tsx";
+import { AlertIcon, FolderIcon } from "../../ui/icons.tsx";
+
+export { ConfirmButton, Field, inputCls, monoInputCls, monoTextareaCls, textareaCls, Toggle, Tag, EmptyState } from "../../ui/Form.tsx";
+
+/** The project whose project-level config is shown (`?p=<pid>`); undefined = user level only. */
+export function useProjectParam(): string | undefined {
+  const [sp] = useSearchParams();
+  return sp.get("p") || undefined;
+}
+
+export function cfgUrl(path: string, pid: string | undefined, params: Record<string, string> = {}) {
+  const sp = new URLSearchParams({ ...(pid ? { project: pid } : {}), ...params });
+  const s = sp.toString();
+  return `/api/config/${path}${s ? `?${s}` : ""}`;
+}
+
+export function useCfg<T>(path: string, pid: string | undefined, opts: { enabled?: boolean; params?: Record<string, string> } = {}) {
+  return useQuery({
+    queryKey: ["cfg", path, pid ?? "", opts.params ?? {}],
+    queryFn: () => api<T>(cfgUrl(path, pid, opts.params)),
+    enabled: opts.enabled ?? true,
+    staleTime: 5_000,
+  });
+}
+
+/** A mutation against /api/config that refreshes the given config listings afterwards. */
+export function useCfgMutation<V, R = unknown>(fn: (v: V) => Promise<R>, invalidate: string[], onSuccess?: (r: R, v: V) => void) {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: fn,
+    onSuccess: (r, v) => {
+      for (const p of invalidate) qc.invalidateQueries({ queryKey: ["cfg", p] as QueryKey });
+      onSuccess?.(r, v);
+    },
+  });
+}
+
+export const errText = (e: unknown) => (e instanceof ApiError ? e.message : e instanceof Error ? e.message : e ? String(e) : "");
+
+export function ErrorLine({ error }: { error: unknown }) {
+  if (!error) return null;
+  return (
+    <p role="alert" className="my-2 flex items-start gap-2 whitespace-pre-wrap break-words rounded-md border border-danger/30 bg-danger/5 px-3 py-2 text-sm text-danger">
+      <AlertIcon className="mt-0.5 shrink-0" />
+      <span className="min-w-0">{errText(error)}</span>
+    </p>
+  );
+}
+
+export function PageTitle({ title, desc, children }: { title: string; desc?: ReactNode; children?: ReactNode }) {
+  return (
+    <div className="mb-5 flex flex-wrap items-end gap-x-4 gap-y-3">
+      <div className="min-w-0 flex-1 basis-64">
+        <h2 className="text-2xl">{title}</h2>
+        {desc && <p className="mt-1 text-sm leading-relaxed text-muted">{desc}</p>}
+      </div>
+      {children && <div className="flex flex-wrap items-center gap-2">{children}</div>}
+    </div>
+  );
+}
+
+export function Card({
+  title,
+  sub,
+  children,
+  actions,
+  testId,
+  icon,
+  count,
+  flush,
+  className,
+}: {
+  title?: ReactNode;
+  sub?: ReactNode;
+  children: ReactNode;
+  actions?: ReactNode;
+  testId?: string;
+  icon?: ReactNode;
+  count?: number;
+  /** No body padding (for lists that draw their own row padding). */
+  flush?: boolean;
+  className?: string;
+}) {
+  return (
+    <section className={cx("mb-4 min-w-0 rounded-xl border border-border bg-surface shadow-sm", className)} data-testid={testId}>
+      {(title || actions) && (
+        <header className="flex flex-wrap items-center gap-x-2 gap-y-1.5 border-b border-border py-2 pl-4 pr-2">
+          <div className="min-w-0 flex-1 basis-40">
+            {title && (
+              <h3 className="flex items-center gap-2 text-base">
+                {icon && <span className="text-muted">{icon}</span>}
+                <span className="min-w-0 truncate">{title}</span>
+                {count !== undefined && <span className="rounded-full bg-surface-2 px-1.5 font-sans text-[11px] font-medium tabular-nums text-muted">{count}</span>}
+              </h3>
+            )}
+            {sub && <p className="truncate font-mono text-[11px] text-muted" title={typeof sub === "string" ? sub : undefined}>{sub}</p>}
+          </div>
+          {actions && <div className="flex flex-wrap items-center gap-1.5">{actions}</div>}
+        </header>
+      )}
+      <div className={flush ? "" : "px-4 py-3"}>{children}</div>
+    </section>
+  );
+}
+
+const SCOPE_TONE: Record<string, TagTone> = { user: "neutral", project: "accent", local: "warn" };
+
+export function ScopeBadge({ scope }: { scope: string }) {
+  const label = SCOPE_LABEL[scope as SettingsScope] ?? scope;
+  return <Tag tone={SCOPE_TONE[scope] ?? "neutral"}>{label}</Tag>;
+}
+
+const SCOPE_HINT: Record<SettingsScope, string> = {
+  user: "~/.claude，所有项目",
+  project: ".claude/settings.json，随仓库共享",
+  local: ".claude/settings.local.json，只在本机",
+};
+
+export function ScopeSelect({ value, onChange, scopes, label = "层级", className }: { value: string; onChange: (v: SettingsScope) => void; scopes: SettingsScope[]; label?: string; className?: string }) {
+  return (
+    <Select<SettingsScope>
+      label={label}
+      value={value as SettingsScope}
+      onChange={onChange}
+      className={cx("w-full", className)}
+      options={scopes.map((s) => ({ value: s, label: SCOPE_LABEL[s], text: SCOPE_LABEL[s], hint: SCOPE_HINT[s] }))}
+    />
+  );
+}
+
+export function Empty({ children, title = "这里还没有内容", icon, action }: { children?: ReactNode; title?: string; icon?: ReactNode; action?: ReactNode }) {
+  return <EmptyState compact title={title} icon={icon} action={action}>{children}</EmptyState>;
+}
+
+export function Loading({ rows = 3 }: { rows?: number }) {
+  return <Skeleton rows={rows} />;
+}
+
+/** Note for project-level sections when no project is selected. */
+export function NeedProject() {
+  return (
+    <p className="mb-4 flex items-center gap-2 rounded-lg border border-dashed border-border px-3 py-2.5 text-sm text-muted">
+      <FolderIcon className="shrink-0" />
+      在页面顶部选择一个项目，即可查看和修改项目级配置。
+    </p>
+  );
+}
+
+/** Two-column work area: a list on the left and the selected item on the right (stacked on phones). */
+export function SplitView({ list, detail, showDetail, listWidth = "lg:w-80" }: { list: ReactNode; detail: ReactNode; showDetail: boolean; listWidth?: string }) {
+  return (
+    <div className="lg:flex lg:items-start lg:gap-5">
+      <div className={cx(showDetail && "hidden lg:block", "min-w-0 lg:shrink-0", listWidth)}>{list}</div>
+      <div className={cx(!showDetail && "hidden lg:block", "min-w-0 lg:sticky lg:top-4 lg:flex-1")}>{detail}</div>
+    </div>
+  );
+}

package/web/src/preference-document.ts

@@ -0,0 +1,133 @@
+export type PreferenceStorage = Pick<Storage, "getItem" | "setItem">;
+type SavedDocument<T> = { key: string; revision: number; value: T };
+const DATABASE = "claude-ide:preferences", STORE = "documents", SIGNAL = "claude-ide:preferences:changed";
+let database: Promise<IDBDatabase> | undefined;
+
+function openDatabase() {
+  return database ??= new Promise<IDBDatabase>((resolve, reject) => {
+    const request = indexedDB.open(DATABASE, 1);
+    let abandoned = false;
+    request.onupgradeneeded = () => { request.result.createObjectStore(STORE, { keyPath: "key" }); };
+    request.onerror = () => { database = undefined; reject(request.error); };
+    request.onblocked = () => { abandoned = true; database = undefined; reject(new Error("Preference database is blocked")); };
+    request.onsuccess = () => {
+      const db = request.result;
+      if (abandoned) { db.close(); return; }
+      db.onversionchange = () => { db.close(); database = undefined; };
+      resolve(db);
+    };
+  });
+}
+
+/** Read, migrate and change inside one read/write transaction shared by all windows. */
+async function transact<T>(key: string, seed: T, normalize: (raw: unknown) => T, change?: (current: T) => T): Promise<SavedDocument<T>> {
+  const db = await openDatabase();
+  return new Promise((resolve, reject) => {
+    const transaction = db.transaction(STORE, "readwrite"), store = transaction.objectStore(STORE);
+    const request = store.get(key);
+    let result: SavedDocument<T>, failure: unknown;
+    request.onsuccess = () => {
+      try {
+        const previous = request.result as SavedDocument<T> | undefined;
+        const current = normalize(previous?.value ?? seed), next = change ? change(current) : current;
+        const changed = !previous || JSON.stringify(previous.value) !== JSON.stringify(next);
+        result = { key, revision: (previous?.revision ?? 0) + (changed ? 1 : 0), value: next };
+        if (changed) store.put(result);
+      } catch (error) { failure = error; transaction.abort(); }
+    };
+    transaction.oncomplete = () => resolve(result);
+    transaction.onabort = () => reject(failure ?? transaction.error ?? new Error("Preference transaction aborted"));
+    transaction.onerror = () => { /* onabort reports the final transaction failure. */ };
+  });
+}
+
+let channel: BroadcastChannel | undefined;
+const watchers = new Map<string, Set<() => void>>();
+let watching = false;
+function watch(key: string, refresh: () => void) {
+  if (!watching) {
+    watching = true;
+    const changed = (key: unknown) => { if (typeof key === "string") watchers.get(key)?.forEach((refresh) => refresh()); };
+    try { channel = new BroadcastChannel(SIGNAL); channel.onmessage = (event) => changed(event.data); } catch { /* Storage events also work on ordinary HTTP origins. */ }
+    window.addEventListener("storage", (event) => {
+      if (event.key !== SIGNAL || !event.newValue) return;
+      try { changed(JSON.parse(event.newValue).key); } catch { /* Ignore unrelated or malformed signals. */ }
+    });
+  }
+  const listeners = watchers.get(key) ?? new Set();
+  listeners.add(refresh); watchers.set(key, listeners);
+}
+function signal(key: string) {
+  try {
+    if (channel) channel.postMessage(key);
+    else localStorage.setItem(SIGNAL, JSON.stringify({ key, nonce: `${Date.now()}:${Math.random()}` }));
+  } catch { /* A notification failure cannot undo a committed transaction. */ }
+}
+
+/** Optimistic UI over an atomic document. Pending pure operations are rebased on
+ * each committed value; remote refreshes wait for local writes to finish. An
+ * explicitly supplied synchronous storage is useful for isolated store tests. */
+export function createPreferenceDocument<T>(key: string, empty: T, normalize: (raw: unknown) => T, suppliedStorage?: PreferenceStorage) {
+  let storage = suppliedStorage;
+  try { storage ??= typeof localStorage === "undefined" ? undefined : localStorage; } catch { /* In-memory fallback. */ }
+  const readLegacy = () => {
+    try { const raw = storage?.getItem(key); return raw ? normalize(JSON.parse(raw)) : undefined; } catch { return undefined; }
+  };
+  let base = readLegacy() ?? empty, snapshot = base, revision = -1;
+  let immediate = suppliedStorage !== undefined || typeof window === "undefined" || typeof indexedDB === "undefined";
+  let writing = false, refreshWanted = false, failedWrite = false;
+  const seed = base, pending: ((current: T) => T)[] = [], listeners = new Set<() => void>();
+  const publish = () => {
+    const next = pending.reduce((current, change) => change(current), base);
+    if (JSON.stringify(next) === JSON.stringify(snapshot)) return;
+    snapshot = next; listeners.forEach((notify) => notify());
+  };
+  const persistFallback = () => {
+    try { storage?.setItem(key, JSON.stringify(base)); failedWrite = false; } catch { failedWrite = true; }
+  };
+  const fallback = () => {
+    base = snapshot; pending.length = 0; immediate = true; persistFallback();
+  };
+  const refresh = async () => {
+    if (immediate) { if (!failedWrite) { base = readLegacy() ?? base; publish(); } return; }
+    if (writing || pending.length) { refreshWanted = true; return; }
+    try {
+      const result = await transact(key, seed, normalize);
+      if (immediate) return;
+      if (writing || pending.length) { refreshWanted = true; return; }
+      if (result.revision >= revision) { revision = result.revision; base = result.value; publish(); }
+    } catch { fallback(); }
+  };
+  const drain = async () => {
+    if (writing) return;
+    writing = true;
+    try {
+      while (pending.length) {
+        const result = await transact(key, seed, normalize, pending[0]);
+        if (immediate) return;
+        pending.shift(); base = result.value; revision = result.revision;
+        publish(); signal(key);
+      }
+    } catch {
+      // Preserve all edits already shown if persistence becomes unavailable.
+      fallback();
+    } finally {
+      writing = false;
+      if (refreshWanted) { refreshWanted = false; void refresh(); }
+    }
+  };
+  if (!immediate) { watch(key, () => { void refresh(); }); void refresh(); }
+  return {
+    get: () => snapshot,
+    subscribe(notify: () => void) { listeners.add(notify); return () => { listeners.delete(notify); }; },
+    change(change: (current: T) => T) {
+      if (immediate) {
+        if (!failedWrite) base = readLegacy() ?? base;
+        const next = change(base);
+        if (JSON.stringify(next) === JSON.stringify(base)) { publish(); return; }
+        base = next; persistFallback(); publish();
+      } else { pending.push(change); publish(); void drain(); }
+    },
+    refresh,
+  };
+}

package/web/src/project-actions.ts

@@ -0,0 +1,18 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import type { ProjectInfo } from "@shared/protocol.ts";
+import { api } from "./api.ts";
+import { useConfirm } from "./components/Confirmation.tsx";
+
+export function useRemoveProject(onRemoved?: (project: ProjectInfo) => void) {
+  const qc = useQueryClient();
+  const confirm = useConfirm();
+  return useMutation({
+    mutationFn: async (project: ProjectInfo) => {
+      if (!(await confirm({ title: "移除项目？", description: `将“${project.name}”从 Claude IDE 项目列表移除。目录和会话文件都会保留，可以重新添加。`, confirmLabel: "移除项目" })).confirmed) return;
+      await api(`/api/projects/${project.id}`, { method: "DELETE" });
+      qc.setQueryData<ProjectInfo[]>(["projects"], (items) => items?.filter((item) => item.id !== project.id));
+      onRemoved?.(project);
+      await Promise.all([qc.invalidateQueries({ queryKey: ["projects"] }), qc.invalidateQueries({ queryKey: ["overview"] })]);
+    },
+  });
+}

package/web/src/project-files-state.test.ts

@@ -0,0 +1,49 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createProjectFilesPreferences, projectFilesUrl, PROJECT_FILES_STORAGE_KEY } from "./project-files-state.ts";
+
+test("project file state survives reconstruction and remains isolated between projects", () => {
+  const saved = new Map<string, string>();
+  const storage = { getItem: (key: string) => saved.get(key) ?? null, setItem: (key: string, value: string) => { saved.set(key, value); } };
+  const state = createProjectFilesPreferences(storage);
+  state.set("a", { file: "src/a.md", expanded: ["src", "assets"], source: true, search: "needle", searchMode: "content" });
+  state.set("b", { file: "README.md" });
+  const reopened = createProjectFilesPreferences(storage);
+  assert.deepEqual(reopened.get("a"), state.get("a"));
+  assert.equal(reopened.get("b").file, "README.md");
+  assert.equal(reopened.get("b").source, false);
+  reopened.set("a", { expanded: [] });
+  assert.deepEqual(reopened.get("a").expanded, [], "manual collapsing is retained independently of the selected file");
+  assert.equal(reopened.get("a").file, "src/a.md");
+});
+
+test("saved file links encode literal names and reject invalid navigation paths", () => {
+  const state = createProjectFilesPreferences({ getItem: () => JSON.stringify({ version: 1, projects: [
+    ["a", { file: "../escape", expanded: ["src", "src", "/outside"], searchMode: "bad" }],
+  ] }), setItem: () => {} });
+  assert.equal(state.get("a").file, "");
+  assert.deepEqual(state.get("a").expanded, ["src"]);
+  assert.equal(projectFilesUrl("p", "目录/a #1?.md"), "/p/p/files/%E7%9B%AE%E5%BD%95/a%20%231%3F.md");
+  assert.equal(projectFilesUrl("p", ""), "/p/p/files");
+});
+
+test("unavailable storage keeps in-memory state, with a bounded project catalog", () => {
+  const state = createProjectFilesPreferences({ getItem: () => { throw new Error("blocked"); }, setItem: () => { throw new Error("full"); } });
+  for (let i = 0; i < 55; i++) state.set(`p${i}`, { file: `${i}.txt` });
+  assert.equal(state.get("p0").file, "");
+  assert.equal(state.get("p54").file, "54.txt");
+  let persisted = "";
+  createProjectFilesPreferences({ getItem: () => null, setItem: (key, value) => { assert.equal(key, PROJECT_FILES_STORAGE_KEY); persisted = value; } }).set("p", { expanded: Array.from({ length: 600 }, (_, i) => `dir${i}`) });
+  assert.equal(JSON.parse(persisted).projects[0][1].expanded.length, 512);
+});
+
+test("stale preference instances preserve other projects and unrelated fields", () => {
+  const saved = new Map<string, string>();
+  const storage = { getItem: (key: string) => saved.get(key) ?? null, setItem: (key: string, value: string) => { saved.set(key, value); } };
+  const a = createProjectFilesPreferences(storage), b = createProjectFilesPreferences(storage);
+  a.set("a", { file: "a.md", source: true }); b.set("b", { file: "b.md" });
+  b.set("a", { search: "needle" }); a.set("a", (state) => ({ expanded: [...state.expanded, "src"] }));
+  const reopened = createProjectFilesPreferences(storage);
+  assert.deepEqual(reopened.get("a"), { file: "a.md", source: true, search: "needle", expanded: ["src"], searchMode: "name" });
+  assert.equal(reopened.get("b").file, "b.md");
+});

package/web/src/project-files-state.ts

@@ -0,0 +1,64 @@
+import { useSyncExternalStore } from "react";
+import { createPreferenceDocument, type PreferenceStorage } from "./preference-document.ts";
+
+export type ProjectFilesState = { file: string; expanded: string[]; source: boolean; search: string; searchMode: "name" | "content" };
+export const PROJECT_FILES_STORAGE_KEY = "claude-ide:project-files:v1";
+const empty: ProjectFilesState = { file: "", expanded: [], source: false, search: "", searchMode: "name" };
+const relative = (value: unknown): value is string => typeof value === "string" && value.length <= 4096
+  && !value.startsWith("/") && !value.includes("\0") && !value.split("/").some((part) => part === ".." || part === ".");
+type FilesState = { version: 1; projects: [string, ProjectFilesState][] };
+function normalize(value: Partial<ProjectFilesState>): ProjectFilesState {
+  return {
+    file: relative(value.file) ? value.file : "",
+    expanded: Array.isArray(value.expanded) ? [...new Set(value.expanded.filter((item) => relative(item) && item))].slice(-512) : [],
+    source: value.source === true,
+    search: typeof value.search === "string" ? value.search.slice(0, 1000) : "",
+    searchMode: value.searchMode === "content" ? "content" : "name",
+  };
+}
+
+/** Small project UI state, independent of mounted pages and session caches. */
+function normalizeDocument(raw: unknown): FilesState {
+  const projects = new Map<string, ProjectFilesState>();
+  const saved = raw as Partial<FilesState> | null;
+  if (saved?.version === 1 && Array.isArray(saved.projects)) for (const entry of saved.projects.slice(-50)) {
+    if (Array.isArray(entry) && typeof entry[0] === "string" && entry[1] && typeof entry[1] === "object") projects.set(entry[0], normalize(entry[1]));
+  }
+  return { version: 1, projects: [...projects] };
+}
+
+export function createProjectFilesPreferences(storage?: PreferenceStorage) {
+  const document = createPreferenceDocument<FilesState>(PROJECT_FILES_STORAGE_KEY, { version: 1, projects: [] }, normalizeDocument, storage);
+  const get = (state: FilesState, pid: string) => state.projects.find(([id]) => id === pid)?.[1] ?? empty;
+  return {
+    get: (pid: string) => get(document.get(), pid),
+    subscribe: document.subscribe,
+    refresh: document.refresh,
+    set(pid: string, patch: Partial<ProjectFilesState> | ((state: ProjectFilesState) => Partial<ProjectFilesState>)) {
+      document.change((state) => {
+        const current = get(state, pid);
+        const next = normalize({ ...current, ...(typeof patch === "function" ? patch(current) : patch) });
+        if (JSON.stringify(current) === JSON.stringify(next)) return state;
+        const projects = new Map(state.projects);
+        projects.delete(pid); projects.set(pid, next);
+        while (projects.size > 50) projects.delete(projects.keys().next().value!);
+        return { version: 1, projects: [...projects] };
+      });
+    },
+  };
+}
+
+const preferences = createProjectFilesPreferences();
+export const setProjectFilesState = preferences.set;
+export function useProjectFilesState(pid: string) {
+  return useSyncExternalStore(preferences.subscribe, () => preferences.get(pid), () => empty);
+}
+export function rememberProjectFile(pid: string, file: string) {
+  if (!relative(file) || !file) return;
+  preferences.set(pid, (state) => {
+    if (state.file === file) return {};
+    const parts = file.split("/").slice(0, -1);
+    return { file, expanded: [...state.expanded, ...parts.map((_, index) => parts.slice(0, index + 1).join("/"))] };
+  });
+}
+export const projectFilesUrl = (pid: string, file: string) => `/p/${pid}/files${file ? `/${file.split("/").map(encodeURIComponent).join("/")}` : ""}`;

package/web/src/project-images.ts

@@ -0,0 +1,13 @@
+import { useSyncExternalStore } from "react";
+
+const versions = new Map<string, number>(), listeners = new Set<() => void>();
+const subscribe = (listener: () => void) => { listeners.add(listener); return () => { listeners.delete(listener); }; };
+
+/** A fresh URL makes the browser revalidate images after an upload. No image bytes are retained. */
+export function refreshProjectImages(pid: string) {
+  versions.set(pid, (versions.get(pid) ?? 0) + 1);
+  listeners.forEach((listener) => listener());
+}
+export function useProjectImageVersion(pid: string) {
+  return useSyncExternalStore(subscribe, () => versions.get(pid) ?? 0, () => 0);
+}

package/web/src/pwa.ts

@@ -0,0 +1,33 @@
+/**
+ * Service worker registration. Browsers only allow service workers (and therefore Web Push) in a
+ * secure context — https or localhost. Over plain http on the LAN we skip quietly.
+ */
+
+let registration: Promise<ServiceWorkerRegistration | undefined> | undefined;
+
+export function swAvailable(): boolean {
+  return typeof window !== "undefined" && window.isSecureContext && "serviceWorker" in navigator;
+}
+
+/** Registers /sw.js once (production builds only; the dev server has no sw.js). Never throws. */
+export function registerServiceWorker(): Promise<ServiceWorkerRegistration | undefined> {
+  if (registration) return registration;
+  if (!import.meta.env.PROD || !swAvailable()) return (registration = Promise.resolve(undefined));
+  registration = navigator.serviceWorker.register("/sw.js", { scope: "/" }).catch((err: unknown) => {
+    console.warn("service worker registration failed", err);
+    return undefined;
+  });
+  return registration;
+}
+
+/** Web Push needs a service worker, PushManager and the Notification API (iOS: only once added to the home screen). */
+export function pushAvailable(): boolean {
+  return swAvailable() && "PushManager" in window && "Notification" in window;
+}
+
+/** The active push subscription of this device, if any. */
+export async function currentPushSubscription(): Promise<PushSubscription | null> {
+  if (!pushAvailable()) return null;
+  const reg = await registerServiceWorker();
+  return (await reg?.pushManager.getSubscription().catch(() => null)) ?? null;
+}

package/web/src/queryClient.ts

@@ -0,0 +1,5 @@
+import { QueryClient } from "@tanstack/react-query";
+
+export const queryClient = new QueryClient({
+  defaultOptions: { queries: { retry: false, refetchOnWindowFocus: false } },
+});