clauderipple 0.9.5 → 0.11.0

package/dist/remote/web/conn.ts

@@ -0,0 +1,193 @@
+// The link to the host. It never gives up: after a drop it waits min(30 s, attempt × 1 s) and
+// tries again, forever, and at once when the phone comes back online or the app comes to the
+// front. A half-open socket (the phone switched networks, the Mac went away without a FIN) is
+// caught by the app-level ping, not by TCP. Only a refused token stops it, because retrying a
+// token the host rejects would just say "connecting" forever — which would be a lie.
+import { BACKOFF_CAP_MS, PING_MS, READY_MS, STALE_MS } from "../src/protocol.ts";
+import type { ClientMsg, HostMsg } from "../src/protocol.ts";
+
+/** A socket that opens but never says `ready` is as good as down (through the relay: the handshake counts too). */
+export { READY_MS };
+
+export type LinkState = "connecting" | "open" | "waiting" | "offline" | "denied";
+
+export interface LinkStatus {
+  state: LinkState;
+  /** consecutive failed attempts since the last good connection */
+  attempt: number;
+  /** when the next attempt starts (state "waiting") */
+  nextAt: number | null;
+  /** last time a frame arrived from the host; null if never */
+  lastRx: number | null;
+  /** when the current outage began; null while open */
+  downSince: number | null;
+}
+
+export interface SocketLike {
+  readyState: number;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  onopen: ((ev: unknown) => void) | null;
+  onmessage: ((ev: { data: unknown }) => void) | null;
+  onclose: ((ev: unknown) => void) | null;
+  onerror: ((ev: unknown) => void) | null;
+}
+
+export interface LinkDeps {
+  url: string;
+  token: string;
+  clientId: string;
+  makeSocket: (url: string) => SocketLike;
+  now: () => number;
+  setTimer: (fn: () => void, ms: number) => unknown;
+  clearTimer: (id: unknown) => void;
+  isOnline: () => boolean;
+}
+
+export function backoff(attempt: number): number {
+  return Math.min(BACKOFF_CAP_MS, Math.max(1, attempt) * 1000);
+}
+
+export class Link {
+  status: LinkStatus = { state: "connecting", attempt: 0, nextAt: null, lastRx: null, downSince: null };
+  onMessage: (msg: HostMsg) => void = () => {};
+  /** Called on every status change and once a second while waiting, so countdowns stay true. */
+  onStatus: (s: LinkStatus) => void = () => {};
+  /** Called after the host accepted the token: re-attach sessions, flush the outbox. */
+  onReady: () => void = () => {};
+
+  private deps: LinkDeps;
+  private sock: SocketLike | null = null;
+  private retryTimer: unknown = null;
+  private tickTimer: unknown = null;
+  private pingTimer: unknown = null;
+  private readyTimer: unknown = null;
+  private pingN = 0;
+  private stopped = false;
+
+  constructor(deps: LinkDeps) { this.deps = deps; }
+
+  start(): void { this.stopped = false; this.connect(); }
+
+  stop(): void {
+    this.stopped = true;
+    this.clearAll();
+    this.sock?.close(1000, "stop");
+    this.sock = null;
+  }
+
+  /** Network came back, app came to the front, or the user pressed "retry now". */
+  nudge(): void {
+    if (this.stopped || this.status.state === "denied") return;
+    if (this.status.state === "open") { this.ping(); return; }
+    this.clearAll();
+    this.connect();
+  }
+
+  send(msg: ClientMsg): boolean {
+    if (this.status.state !== "open" || !this.sock) return false;
+    try { this.sock.send(JSON.stringify(msg)); return true; } catch { return false; }
+  }
+
+  private set(patch: Partial<LinkStatus>): void {
+    this.status = { ...this.status, ...patch };
+    this.onStatus(this.status);
+  }
+
+  private clearAll(): void {
+    for (const id of [this.retryTimer, this.tickTimer, this.pingTimer, this.readyTimer]) if (id !== null) this.deps.clearTimer(id);
+    this.retryTimer = this.tickTimer = this.pingTimer = this.readyTimer = null;
+  }
+
+  private connect(): void {
+    if (this.stopped) return;
+    if (!this.deps.isOnline()) {
+      this.set({ state: "offline", nextAt: null, downSince: this.status.downSince ?? this.deps.now() });
+      this.schedule();
+      return;
+    }
+    this.set({ state: "connecting", nextAt: null });
+    let sock: SocketLike;
+    try { sock = this.deps.makeSocket(this.deps.url); } catch { this.fail(); return; }
+    this.sock = sock;
+    let authed = false;
+    sock.onopen = () => {
+      if (this.sock !== sock) return;
+      this.status.lastRx = this.deps.now();
+      sock.send(JSON.stringify({ t: "hello", token: this.deps.token, clientId: this.deps.clientId } satisfies ClientMsg));
+      this.armPing();
+    };
+    // From creation, not from open: a connect that hangs (a dead address after a network switch)
+    // may fire neither open nor close for minutes.
+    this.readyTimer = this.deps.setTimer(() => {
+      this.readyTimer = null;
+      if (authed || this.sock !== sock) return;
+      this.sock = null;
+      try { sock.close(4002, "no ready"); } catch { /* gone */ }
+      this.fail();
+    }, READY_MS);
+    sock.onmessage = (ev) => {
+      if (this.sock !== sock) return;
+      this.status.lastRx = this.deps.now();
+      let msg: HostMsg;
+      try { msg = JSON.parse(String(ev.data)) as HostMsg; } catch { return; }
+      if (msg.t === "denied") {
+        this.clearAll();
+        this.sock = null;
+        sock.close(4001, "denied");
+        this.set({ state: "denied", nextAt: null });
+        return;
+      }
+      if (msg.t === "ready" && !authed) {
+        authed = true;
+        this.set({ state: "open", attempt: 0, nextAt: null, downSince: null });
+        this.onReady();
+      }
+      if (msg.t !== "pong") this.onMessage(msg);
+    };
+    sock.onclose = () => { if (this.sock === sock) this.fail(); };
+    sock.onerror = () => { /* onclose follows */ };
+  }
+
+  private fail(): void {
+    this.sock = null;
+    this.clearAll();
+    if (this.stopped || this.status.state === "denied") return;
+    this.set({ attempt: this.status.attempt + 1, downSince: this.status.downSince ?? this.deps.now() });
+    this.schedule();
+  }
+
+  private schedule(): void {
+    const wait = backoff(this.status.attempt);
+    const nextAt = this.deps.now() + wait;
+    if (this.status.state !== "offline") this.set({ state: "waiting", nextAt });
+    this.retryTimer = this.deps.setTimer(() => { this.retryTimer = null; this.connect(); }, wait);
+    const tick = (): void => {
+      this.onStatus(this.status);
+      this.tickTimer = this.deps.setTimer(tick, 1000);
+    };
+    this.tickTimer = this.deps.setTimer(tick, 1000);
+  }
+
+  private armPing(): void {
+    const loop = (): void => {
+      this.ping();
+      this.pingTimer = this.deps.setTimer(loop, PING_MS);
+    };
+    this.pingTimer = this.deps.setTimer(loop, PING_MS);
+  }
+
+  private ping(): void {
+    const sock = this.sock;
+    if (!sock) return;
+    const last = this.status.lastRx ?? 0;
+    if (this.deps.now() - last > STALE_MS) {
+      // Stale: no frame, not even a pong, for 30 s. Drop it ourselves rather than wait for TCP.
+      this.sock = null;
+      try { sock.close(4000, "stale"); } catch { /* already gone */ }
+      this.fail();
+      return;
+    }
+    try { sock.send(JSON.stringify({ t: "ping", n: ++this.pingN } satisfies ClientMsg)); } catch { /* close follows */ }
+  }
+}

package/dist/remote/web/demo.ts

@@ -0,0 +1,134 @@
+// Fixture states for the design screenshots (`?demo=<name>&theme=light|dark`). They drive the
+// real App renderer with canned data and no socket, so docs/media/remote shows the shipped UI.
+import type { BrowseResult, EventBody, Figures, ProviderGroup, SessionEvent, SessionSummary } from "../src/protocol.ts";
+import { App } from "./app.ts";
+
+const HOME = "/Users/me";
+const now = Date.now();
+const min = 60_000;
+
+const MODELS: ProviderGroup[] = [
+  { provider: "chatgpt", label: "ChatGPT", usable: true, models: [
+    { model: "gpt-6.1-sol", name: "GPT-6.1 Sol", provider: "chatgpt", efforts: ["low", "medium", "high", "xhigh", "max"], usable: true },
+    { model: "gpt-6-astra", name: "GPT-6 Astra", provider: "chatgpt", efforts: ["low", "medium", "high", "xhigh", "max"], usable: true },
+    { model: "gpt-6-luna", name: "GPT-6 Luna", provider: "chatgpt", efforts: ["low", "medium", "high", "xhigh", "max"], usable: true },
+  ] },
+  { provider: "anthropic", label: "Claude", usable: true, models: [
+    { model: "claude-opus-5-5", name: "Opus 5.5", provider: "anthropic", efforts: ["low", "medium", "high", "max"], usable: true },
+    { model: "claude-sonnet-5-5", name: "Sonnet 5.5", provider: "anthropic", efforts: ["low", "medium", "high", "max"], usable: true },
+  ] },
+  { provider: "opencode-go", label: "OpenCode Go", usable: true, models: [
+    { model: "deepseek-v4.1-flash", name: "deepseek-v4.1-flash", provider: "opencode-go", efforts: ["low", "high", "max"], usable: true },
+    { model: "glm-5.3-flash", name: "glm-5.3-flash", provider: "opencode-go", efforts: ["low", "high", "max"], usable: true },
+  ] },
+  { provider: "google-gemini", label: "Google Gemini", usable: false, models: [
+    { model: "gemini-3.8-flash", name: "gemini-3.8-flash", provider: "google-gemini", efforts: ["low", "medium", "high"], usable: false },
+  ] },
+];
+
+const SESSIONS: SessionSummary[] = [
+  { id: "s1", title: "로그인 토큰 갱신이 두 번 도는 버그 고쳐줘", cwd: `${HOME}/code/dayripple`, model: "gpt-6.1-sol", effort: "high", state: "waiting", pending: 1, createdAt: now - 14 * min, updatedAt: now - 1 * min, lastSeq: 40, epoch: "e" },
+  { id: "s2", title: "README 영어판을 한국어판에 맞춰 갱신", cwd: `${HOME}/Documents/ClaudeRipple`, model: "deepseek-v4.1-flash", effort: "high", state: "running", pending: 0, createdAt: now - 6 * min, updatedAt: now - 0.2 * min, lastSeq: 22, epoch: "e" },
+  { id: "s3", title: "결제 웹훅 재시도 로직 설계 검토", cwd: `${HOME}/code/bodyripple`, model: "claude-opus-5-5", effort: "max", state: "idle", pending: 0, createdAt: now - 200 * min, updatedAt: now - 95 * min, lastSeq: 88, epoch: "e" },
+  { id: "s4", title: "테스트 깨진 것 원인만 찾아줘 (수정 금지)", cwd: `${HOME}/code/talkripple`, model: "glm-5.3-flash", effort: "low", state: "stopped", pending: 0, createdAt: now - 3000 * min, updatedAt: now - 1500 * min, lastSeq: 31, epoch: "e" },
+];
+
+const FIG: Figures = { effort: "high", cachePct: 94, contextPct: 38, fiveHourPct: 12, fiveHourResetAt: now + 130 * min, workers: [{ model: "deepseek-v4.1-flash", provider: "opencode-go", requests: 12 }, { model: "gpt-6-luna", provider: "chatgpt", requests: 3 }], at: now - 20_000 };
+
+function events(bodies: EventBody[], start = now - 9 * min): SessionEvent[] {
+  return bodies.map((b, i) => ({ ...b, seq: i + 1, at: start + i * 9000 } as SessionEvent));
+}
+
+const ANSWER = "원인을 찾았습니다. `refreshToken()`이 **두 곳**에서 불립니다.\n\n1. `useSession` 훅이 마운트될 때\n2. `apiClient`의 401 인터셉터가 같은 순간에\n\n둘이 동시에 돌면 첫 번째가 받은 토큰을 두 번째가 무효로 만듭니다. 인터셉터 쪽에 진행 중인 갱신을 공유하는 잠금을 두겠습니다.";
+
+const CHAT = (streaming: boolean, perm: boolean): EventBody[] => [
+  { kind: "user", text: "로그인 토큰 갱신이 두 번 도는 버그 고쳐줘. 앱을 켜자마자 가끔 로그아웃돼.", clientMsgId: "c1" },
+  { kind: "turn", model: "gpt-6.1-sol", effort: "high" },
+  { kind: "state", state: "running" },
+  { kind: "figures", figures: FIG },
+  { kind: "assistant", msg: "m1", model: "gpt-6.1-sol", text: "먼저 토큰을 갱신하는 곳을 모두 찾아보겠습니다.", tools: [
+    { id: "t1", name: "Grep", summary: "refreshToken  src/" },
+    { id: "t2", name: "Read", summary: "src/api/client.ts" },
+  ] },
+  { kind: "tool_result", toolUseId: "t1", ok: true, text: "src/hooks/useSession.ts:42\nsrc/api/client.ts:88" },
+  { kind: "tool_result", toolUseId: "t2", ok: true, text: "…" },
+  { kind: "subagent", toolUseId: "t3", sub: "sub-t3", description: "갱신 경쟁 상태를 재현하는 테스트 작성", model: "deepseek-v4.1-flash", status: "done", steps: 7 },
+  ...(streaming
+    ? [{ kind: "delta", msg: "m2", text: ANSWER.slice(0, 150) } as EventBody]
+    : [
+      { kind: "assistant", msg: "m2", model: "gpt-6.1-sol", text: ANSWER, tools: [{ id: "t4", name: "Edit", summary: "src/api/client.ts  +14 −3" }] } as EventBody,
+      { kind: "tool_result", toolUseId: "t4", ok: true, text: "ok" } as EventBody,
+    ]),
+  ...(!streaming && !perm ? [
+    { kind: "result", ok: true, ms: 74_000, turns: 6 } as EventBody,
+    { kind: "state", state: "idle" } as EventBody,
+  ] : []),
+  ...(perm ? [
+    { kind: "state", state: "waiting" } as EventBody,
+    { kind: "permission", id: "p1", tool: "Bash", title: "테스트를 실행해도 될까요?", summary: "npm test -- src/api", input: "npm test -- src/api/client.test.ts --reporter=dot", canAlways: true } as EventBody,
+  ] : []),
+];
+
+const BROWSE: BrowseResult = { path: `${HOME}/code`, parent: HOME, home: HOME, truncated: false, entries: ["bodyripple", "carlog", "dayripple", "mambo", "talkripple"].map((n) => ({ path: `${HOME}/code/${n}`, name: n })) };
+
+export function runDemo(name: string, params: URLSearchParams): void {
+  const theme = params.get("theme");
+  if (theme) document.documentElement.dataset.theme = theme;
+  const open = { state: "open" as const, attempt: 0, nextAt: null, lastRx: now - 2000, downSince: null };
+  const app = new App(open);
+  app.ui.now = now;
+  app.ui.host = { name: "MacBook Pro", version: "0.8.10", routerOk: true };
+  app.ui.home = HOME;
+  app.ui.models = MODELS;
+  app.ui.sessions = SESSIONS;
+  app.ui.draft = { cwd: `${HOME}/Documents/ClaudeRipple`, model: "gpt-6.1-sol", effort: "high" };
+  app.recentModels = ["gpt-6.1-sol", "deepseek-v4.1-flash", "claude-opus-5-5"];
+  app.outbox = [];
+  const session = (evs: EventBody[], state: SessionSummary["state"] = "running"): void => {
+    app.ui.sessions = [{ ...SESSIONS[0]!, state, pending: 0 }];
+    const c = app.cache("s1");
+    c.events = events(evs);
+    c.epoch = "e";
+    app.screen = { name: "session", id: "s1" };
+  };
+  switch (name) {
+    case "pair": app.screen = { name: "pair" }; break;
+    case "home": app.screen = { name: "home" }; break;
+    case "home-empty": app.ui.sessions = []; app.screen = { name: "home" }; break;
+    case "folder":
+      app.screen = { name: "home" };
+      app.ui.sheet = { kind: "folder", loading: false, filter: "", browse: BROWSE, recent: [
+        { path: `${HOME}/Documents/ClaudeRipple`, name: "ClaudeRipple", lastUsed: now - 6 * min },
+        { path: `${HOME}/code/dayripple`, name: "dayripple", lastUsed: now - 14 * min },
+        { path: `${HOME}/code/bodyripple`, name: "bodyripple", lastUsed: now - 95 * min },
+      ] };
+      break;
+    case "model":
+      app.screen = { name: "home" };
+      app.ui.sheet = { kind: "model", groups: MODELS, recent: app.recentModels, model: "gpt-6.1-sol", effort: "high", forSession: null };
+      break;
+    case "stream": session(CHAT(true, false)); break;
+    case "permission": session(CHAT(false, true), "waiting"); break;
+    case "workers": session(CHAT(false, false), "idle"); app.ui.workersOpen = true; break;
+    case "reconnecting":
+      session(CHAT(true, false));
+      app.ui.link = { state: "waiting", attempt: 3, nextAt: now + 3000, lastRx: now - 9000, downSince: now - 9000 };
+      break;
+    case "lost":
+      session(CHAT(true, false));
+      app.ui.link = { state: "waiting", attempt: 9, nextAt: now + 9000, lastRx: now - 134_000, downSince: now - 134_000 };
+      app.outbox = [{ clientMsgId: "q1", session: "s1", text: "잠금 말고 단일 비행(single-flight)으로 해줘", at: now - 40_000, state: "pending" }];
+      break;
+    case "offline":
+      app.screen = { name: "home" };
+      app.ui.link = { state: "offline", attempt: 2, nextAt: null, lastRx: now - 50_000, downSince: now - 50_000 };
+      break;
+  }
+  app.render();
+  if (name === "stream" || name === "reconnecting" || name === "lost") {
+    // Clock pinned so "working for" reads the same on every render.
+    app.cache("s1").events.forEach((e) => { if (e.kind === "turn") e.at = now - 42_000; });
+    app.renderSession();
+  }
+  document.body.dataset.ready = "1";
+}

package/dist/remote/web/dom.ts

@@ -0,0 +1,124 @@
+import { t } from "./i18n.ts";
+
+export { esc } from "./esc.ts";
+
+const svg = (body: string, size = 20): string =>
+  `<svg class="ic" width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${body}</svg>`;
+
+export const icon = {
+  back: (s?: number) => svg(`<path d="M15 5l-7 7 7 7"/>`, s),
+  chevron: (s?: number) => svg(`<path d="M9 6l6 6-6 6"/>`, s),
+  down: (s?: number) => svg(`<path d="M6 9l6 6 6-6"/>`, s),
+  folder: (s?: number) => svg(`<path d="M3.5 7.5a2 2 0 0 1 2-2h4l2 2.2h7a2 2 0 0 1 2 2v7.8a2 2 0 0 1-2 2h-13a2 2 0 0 1-2-2z"/>`, s),
+  model: (s?: number) => svg(`<path d="M12 3.5l7.5 4.3v8.4L12 20.5l-7.5-4.3V7.8z"/><path d="M12 12l7.3-4.1M12 12v8.3M12 12L4.7 7.9"/>`, s),
+  send: (s?: number) => svg(`<path d="M12 19V5M6 11l6-6 6 6"/>`, s),
+  stop: (s?: number) => `<svg class="ic" width="${s ?? 20}" height="${s ?? 20}" viewBox="0 0 24 24" aria-hidden="true"><rect x="6.5" y="6.5" width="11" height="11" rx="2.2" fill="currentColor"/></svg>`,
+  gear: (s?: number) => svg(`<circle cx="12" cy="12" r="3"/><path d="M19.4 15a1.6 1.6 0 0 0 .3 1.8l.1.1a2 2 0 1 1-2.8 2.8l-.1-.1a1.6 1.6 0 0 0-1.8-.3 1.6 1.6 0 0 0-1 1.5V21a2 2 0 1 1-4 0v-.1a1.6 1.6 0 0 0-1-1.5 1.6 1.6 0 0 0-1.8.3l-.1.1a2 2 0 1 1-2.8-2.8l.1-.1a1.6 1.6 0 0 0 .3-1.8 1.6 1.6 0 0 0-1.5-1H3a2 2 0 1 1 0-4h.1a1.6 1.6 0 0 0 1.5-1 1.6 1.6 0 0 0-.3-1.8l-.1-.1a2 2 0 1 1 2.8-2.8l.1.1a1.6 1.6 0 0 0 1.8.3H9a1.6 1.6 0 0 0 1-1.5V3a2 2 0 1 1 4 0v.1a1.6 1.6 0 0 0 1 1.5 1.6 1.6 0 0 0 1.8-.3l.1-.1a2 2 0 1 1 2.8 2.8l-.1.1a1.6 1.6 0 0 0-.3 1.8V9a1.6 1.6 0 0 0 1.5 1H21a2 2 0 1 1 0 4h-.1a1.6 1.6 0 0 0-1.5 1z"/>`, s),
+  terminal: (s?: number) => svg(`<path d="M5 7l5 5-5 5M12 18h7"/>`, s),
+  file: (s?: number) => svg(`<path d="M14 3.5H7a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8.5z"/><path d="M14 3.5v5h5"/>`, s),
+  pencil: (s?: number) => svg(`<path d="M4 20h4L19 9a2.8 2.8 0 0 0-4-4L4 16z"/><path d="M13.5 6.5l4 4"/>`, s),
+  search: (s?: number) => svg(`<circle cx="11" cy="11" r="6.5"/><path d="M20 20l-4.2-4.2"/>`, s),
+  globe: (s?: number) => svg(`<circle cx="12" cy="12" r="8.5"/><path d="M3.5 12h17M12 3.5c2.4 2.6 3.6 5.4 3.6 8.5s-1.2 5.9-3.6 8.5c-2.4-2.6-3.6-5.4-3.6-8.5s1.2-5.9 3.6-8.5z"/>`, s),
+  check: (s?: number) => svg(`<path d="M5 12.5l4.5 4.5L19 7.5"/>`, s),
+  x: (s?: number) => svg(`<path d="M6 6l12 12M18 6L6 18"/>`, s),
+  clock: (s?: number) => svg(`<circle cx="12" cy="12" r="8.5"/><path d="M12 7.5V12l3 2"/>`, s),
+  shield: (s?: number) => svg(`<path d="M12 3.5l7 2.8v5.2c0 4.4-3 7.8-7 9-4-1.2-7-4.6-7-9V6.3z"/>`, s),
+  task: (s?: number) => svg(`<path d="M8 6h11M8 12h11M8 18h11"/><circle cx="4.5" cy="6" r="1"/><circle cx="4.5" cy="12" r="1"/><circle cx="4.5" cy="18" r="1"/>`, s),
+  home: (s?: number) => svg(`<path d="M4 11l8-6.5 8 6.5"/><path d="M6 9.5V19h12V9.5"/>`, s),
+  bell: (s?: number) => svg(`<path d="M6 16.5V11a6 6 0 0 1 12 0v5.5l1.5 2h-15z"/><path d="M10 20.5a2 2 0 0 0 4 0"/>`, s),
+  up: (s?: number) => svg(`<path d="M12 19V7M7 11l5-5 5 5"/><path d="M5 4.5h14"/>`, s),
+};
+
+export function toolIcon(name: string): string {
+  if (name === "Bash" || name === "BashOutput" || name === "KillShell") return icon.terminal(16);
+  if (name === "Edit" || name === "Write" || name === "MultiEdit" || name === "NotebookEdit") return icon.pencil(16);
+  if (name === "Read" || name === "Glob" || name === "Grep" || name === "LS") return name === "Read" ? icon.file(16) : icon.search(16);
+  if (name === "WebFetch" || name === "WebSearch") return icon.globe(16);
+  if (name === "Task" || name === "Agent") return icon.model(16);
+  if (name === "TodoWrite") return icon.task(16);
+  return icon.chevron(16);
+}
+
+export function relTime(at: number, now: number): string {
+  const s = Math.max(0, Math.round((now - at) / 1000));
+  if (s < 45) return t("time.now");
+  if (s < 3600) return t("time.min", { n: Math.max(1, Math.round(s / 60)) });
+  if (s < 86400) return t("time.hour", { n: Math.round(s / 3600) });
+  return t("time.day", { n: Math.round(s / 86400) });
+}
+
+export function duration(ms: number): string {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return t("dur.s", { n: s });
+  // An hour and up reads as hours and minutes ("1시간 47분"), not "107분".
+  if (s >= 3600) {
+    const m = Math.round(s / 60);
+    return m % 60 === 0 ? t("dur.h", { n: m / 60 }) : t("dur.hm", { h: Math.floor(m / 60), m: m % 60 });
+  }
+  if (s % 60 === 0 || s >= 600) return t("dur.m", { n: Math.round(s / 60) });
+  return t("dur.ms", { m: Math.floor(s / 60), s: s % 60 });
+}
+
+export function clock(at: number): string {
+  const d = new Date(at);
+  return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+}
+
+/** The last path segment, the way a folder is named in speech. `~` for the home folder. */
+export function folderName(path: string, home?: string): string {
+  if (home && path === home) return "~";
+  const parts = path.split("/").filter(Boolean);
+  return parts[parts.length - 1] ?? "/";
+}
+
+export function shortPath(path: string, home?: string): string {
+  return home && (path === home || path.startsWith(home + "/")) ? "~" + path.slice(home.length) : path;
+}
+
+const lastHtml = new WeakMap<Element, string>();
+
+/**
+ * Replace a region only when its markup changed. Regions re-render every second for countdowns;
+ * replacing an unchanged button under a thumb between touch-down and touch-up swallows the tap.
+ */
+export function setHTML(el: Element | null, html: string): void {
+  if (!el || lastHtml.get(el) === html) return;
+  lastHtml.set(el, html);
+  el.innerHTML = html;
+}
+
+/**
+ * Keyed list patch: nodes whose key and version are unchanged stay in place (scroll position,
+ * text selection and expanded state survive a streaming update); changed ones are replaced.
+ */
+export function patchList<T extends { key: string; ver: string }>(parent: HTMLElement, items: readonly T[], render: (item: T) => string): void {
+  const existing = new Map<string, HTMLElement>();
+  for (const child of Array.from(parent.children) as HTMLElement[]) {
+    const k = child.dataset.key;
+    if (k) existing.set(k, child);
+    else child.remove();
+  }
+  let cursor: Element | null = parent.firstElementChild;
+  const tpl = document.createElement("template");
+  for (const item of items) {
+    let node = existing.get(item.key);
+    if (node && node.dataset.ver !== item.ver) {
+      tpl.innerHTML = render(item).trim();
+      const fresh = tpl.content.firstElementChild as HTMLElement;
+      fresh.dataset.key = item.key;
+      fresh.dataset.ver = item.ver;
+      node.replaceWith(fresh);
+      if (cursor === node) cursor = fresh;
+      node = fresh;
+    } else if (!node) {
+      tpl.innerHTML = render(item).trim();
+      node = tpl.content.firstElementChild as HTMLElement;
+      node.dataset.key = item.key;
+      node.dataset.ver = item.ver;
+    }
+    existing.delete(item.key);
+    if (node !== cursor) parent.insertBefore(node, cursor);
+    else cursor = cursor.nextElementSibling;
+  }
+  for (const stale of existing.values()) stale.remove();
+}

package/dist/remote/web/esc.ts

@@ -0,0 +1,4 @@
+// HTML escaping with no DOM, so Node tests and the native app can import what uses it.
+export function esc(s: string): string {
+  return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]!);
+}