@sleep2agi/agent-network-dashboard 0.6.3-preview.50 → 0.6.3-preview.52

package/app/components/ChatPane.tsx

@@ -1,7 +1,10 @@
 'use client';
 
+import { useState } from 'react';
 import { AliasAvatar } from './AliasAvatar';
 import { TaskChatPanel } from './TaskChatPanel';
+import { NodeSettingsPanel } from './NodeSettingsPanel';
+import { useSessions } from '../lib/hooks';
 import { t } from '../lib/ui-lang';
 
 // #Stage B (dashboard 3-col): the persistent right chat column on /nodes.
@@ -14,44 +17,157 @@ import { t } from '../lib/ui-lang';
 // renders (NodesView.chatOpenDesktop), so the pane takes all width right
 // of the rail instead of being squeezed to a fixed sliver by the table.
 //
-// Test-hook contract: `data-testid="chat-pane"` + `data-chat-alias` are the
-// Stage B assertions' anchors. Deliberately does NOT render any
-// [data-node-card] / [data-node-alias] — those belong exclusively to the
-// table in NodesView (#492 exact-count contract).
+// Batch (07-31 通信龙) segment 4: chat top-bar right adds ⋮ (overflow /
+// settings entry), 📅 (view task), 🔍 (search — disabled v1), + existing
+// ✕ (close). Settings entry opens NodeSettingsPanel as a 360px right-
+// drawer SCOPED to the chat pane (positioning='absolute'), so opening
+// settings doesn't cover the sidebar or rail — SPEC §12 + 通信龙 判定.
+// TaskChatPanel stays mounted while the drawer opens (renders as a
+// sibling, not a replacement) so draft / scroll / SSE state survives —
+// Vincent's "只发生一次就再也不敢用" red-line.
+//
+// Test-hook contract:
+//   - Root: data-testid="chat-pane", data-chat-alias
+//   - Buttons: data-testid="chat-pane-{settings,view-tasks,search,close}"
+//   - Settings dialog inherits NodeSettingsPanel's role="dialog"
 export interface ChatPaneProps {
   /** Node alias to chat with. Changing it swaps the conversation in place. */
   alias: string;
   /** Close the pane (unselect + URL back to /nodes — parent owns both). */
   onClose: () => void;
+  /** #Mobile two-level nav: 'page' renders full-width/full-height with a
+   *  back arrow (Feishu phone form — chat is a page, not a column).
+   *  Default 'column' keeps the desktop right-column behavior. */
+  variant?: 'column' | 'page';
+  /** Back arrow handler (page variant). Falls back to onClose. */
+  onBack?: () => void;
 }
 
-export function ChatPane({ alias, onClose }: ChatPaneProps) {
+export function ChatPane({ alias, onClose, variant = 'column', onBack }: ChatPaneProps) {
+  const [settingsOpen, setSettingsOpen] = useState(false);
+  // Look up session for NodeSettingsPanel — it requires the full row.
+  // useSessions is SWR-cached (same key as NodesView), so no extra
+  // network cost.
+  const { sessions } = useSessions();
+  const session = sessions.find(s => s.alias === alias);
+
   return (
     <aside
       data-testid="chat-pane"
       data-chat-alias={alias}
-      className="hidden md:flex md:flex-col flex-1 min-w-0 h-full bg-[#141826]"
+      // `relative` so the settings drawer (positioning='absolute')
+      // scopes to this <aside>, not the viewport. Without this the
+      // drawer would cover the whole page — the exact regression
+      // 通信龙's judgment ("settings-as-right-drawer, not 4th column
+      // and not fullscreen") is designed to prevent.
+      // page variant (#mobile two-level nav): full-bleed chat page below md.
+      // pb keeps the composer above the fixed MobileNav (visible < lg) —
+      // same offset AppShell reserves for normal pages.
+      className={variant === 'page'
+        ? 'relative flex flex-col w-full min-w-0 h-full bg-[#141826] pb-[calc(5rem+env(safe-area-inset-bottom))] lg:pb-0'
+        : 'relative hidden md:flex md:flex-col flex-1 min-w-0 h-full bg-[#141826] pb-[calc(5rem+env(safe-area-inset-bottom))] lg:pb-0'}
     >
       <div className="flex items-center justify-between gap-2 px-3 py-2.5 border-b border-[rgba(255,255,255,0.06)] bg-[#141826] shrink-0">
         <div className="flex items-center gap-2 min-w-0">
+          {variant === 'page' && (
+            <button
+              type="button"
+              onClick={onBack ?? onClose}
+              aria-label={t('返回列表', 'Back to list')}
+              data-testid="chat-back"
+              className="inline-flex h-8 w-8 -ml-1 items-center justify-center rounded-lg text-gray-400 hover:text-gray-100 hover:bg-[#1c1c1f] transition-colors shrink-0"
+            >
+              <svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                <path strokeLinecap="round" strokeLinejoin="round" d="M15 19l-7-7 7-7" />
+              </svg>
+            </button>
+          )}
           <AliasAvatar alias={alias} size={26} />
           <span className="truncate text-sm font-semibold text-white">{alias}</span>
         </div>
-        <button
-          type="button"
-          onClick={onClose}
-          aria-label={t('关闭会话', 'Close chat')}
-          data-testid="chat-pane-close"
-          className="inline-flex h-8 w-8 items-center justify-center rounded-lg text-gray-500 hover:text-gray-200 hover:bg-[#1c1c1f] transition-colors"
-        >
-          <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-            <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
-          </svg>
-        </button>
+        {/* SPEC §12: right-side icon row. ⋮ IS the settings entry
+            (opens NodeSettingsPanel directly rather than expanding an
+            overflow menu — spec calls for both, but MVP folds them
+            into one click since the only overflow item that has a
+            wired backend right now IS settings; other items in the
+            spec's 5-item overflow are not yet implemented, per
+            INVENTORY.md). Script accepts either
+            data-testid="chat-pane-settings" or "chat-pane-more" or
+            aria-label containing "设置" — we set testid=settings,
+            aria-label contains "设置", and add data-chat-pane-more so
+            all three script matchers hit. */}
+        <div className="flex items-center gap-1 shrink-0">
+          <button
+            type="button"
+            onClick={() => setSettingsOpen(true)}
+            aria-label={t('打开会话设置', 'Open conversation settings')}
+            title={t('会话设置', 'Conversation settings')}
+            data-testid="chat-pane-settings"
+            data-chat-pane-more
+            className="inline-flex h-8 w-8 items-center justify-center rounded-md text-gray-500 hover:text-gray-200 hover:bg-[#1c1c1f] transition-colors"
+          >
+            {/* ⋮ vertical dots — spec §12 "overflow menu" glyph. */}
+            <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+              <circle cx="12" cy="5" r="1.5" fill="currentColor" />
+              <circle cx="12" cy="12" r="1.5" fill="currentColor" />
+              <circle cx="12" cy="19" r="1.5" fill="currentColor" />
+            </svg>
+          </button>
+          <a
+            href={`/tasks?alias=${encodeURIComponent(alias)}`}
+            aria-label={t(`查看 ${alias} 的任务`, `View ${alias} tasks`)}
+            title={t('查看任务', 'View tasks')}
+            data-testid="chat-pane-view-tasks"
+            className="inline-flex h-8 w-8 items-center justify-center rounded-md text-gray-500 hover:text-gray-200 hover:bg-[#1c1c1f] transition-colors"
+          >
+            <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+              <path strokeLinecap="round" strokeLinejoin="round" d="M8 7V3M16 7V3M4 11h16M5 21h14a2 2 0 002-2V7a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z" />
+            </svg>
+          </a>
+          <button
+            type="button"
+            disabled
+            aria-label={t('会话内搜索（即将支持）', 'In-chat search (coming soon)')}
+            title={t('即将支持', 'Coming soon')}
+            data-testid="chat-pane-search"
+            className="inline-flex h-8 w-8 items-center justify-center rounded-md text-gray-700 cursor-not-allowed"
+          >
+            <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+              <path strokeLinecap="round" strokeLinejoin="round" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
+            </svg>
+          </button>
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label={t('关闭会话', 'Close chat')}
+            data-testid="chat-pane-close"
+            className="inline-flex h-8 w-8 items-center justify-center rounded-md text-gray-500 hover:text-gray-200 hover:bg-[#1c1c1f] transition-colors"
+          >
+            <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+              <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+            </svg>
+          </button>
+        </div>
       </div>
       <div className="flex-1 min-h-0">
+        {/* TaskChatPanel stays mounted regardless of settingsOpen —
+            it's a SIBLING of the settings drawer, not a child. React
+            preserves its state (draft / scroll / SSE) across drawer
+            toggle because the tree position doesn't change. */}
         <TaskChatPanel alias={alias} onClose={onClose} inline />
       </div>
+      {/* Settings drawer — mounts as sibling of TaskChatPanel, scoped
+          to this aside via positioning='absolute'. session may be
+          undefined briefly during SWR revalidation; guard so the
+          drawer doesn't open with no data (button was clicked before
+          sessions loaded — rare but possible). */}
+      {settingsOpen && session && (
+        <NodeSettingsPanel
+          session={session}
+          onClose={() => setSettingsOpen(false)}
+          positioning="absolute"
+        />
+      )}
     </aside>
   );
 }

package/app/components/NodeList.tsx

@@ -1,11 +1,21 @@
 'use client';
 
+import { useEffect, useRef, useState } from 'react';
 import { AliasAvatar } from './AliasAvatar';
 import { useChatUnread } from '../lib/chat-unread';
 import { useHasDraft } from '../lib/chat-drafts';
+import { usePinned } from '../lib/chat-pin';
+import { useMuted } from '../lib/chat-mute';
+import { NodeListContextMenu } from './NodeListContextMenu';
 import type { Session } from './types';
 import { t } from '../lib/ui-lang';
 
+// Batch (07-31 通信龙): wire chat-pin / chat-mute into the rail. Pattern
+// copied from AgentCard.tsx (usePinned + useMuted per row) so behavior
+// matches the existing table view — pinned rows sort first (inherited
+// from NodesView's sort chain), and muted rows suppress the unread
+// badge (but keep the underlying count correct — muted ≠ marked-read).
+
 // #Stage A (dashboard 3-col): persistent narrow node list rail —
 // WeChat-style entries (avatar + alias + activity preview + unread badge)
 // that stay visible while user reads/interacts with the table on the
@@ -48,6 +58,118 @@ export interface NodeListProps {
   onSearchChange: (v: string) => void;
 }
 
+// Extracted so per-row hooks (usePinned / useMuted / useHasDraft) attach
+// per-alias. Rules-of-hooks means we can't call them inside a .map()
+// callback conditionally; each row is its own component so React
+// mounts a fresh hook state per alias.
+interface NodeListRowProps {
+  session: SessionRow;
+  selected: boolean;
+  unread: number;
+  onSelect: (alias: string) => void;
+  onContextMenu: (alias: string, e: React.MouseEvent) => void;
+}
+function NodeListRow({ session: s, selected, unread, onSelect, onContextMenu }: NodeListRowProps) {
+  const pinned = usePinned(s.alias);
+  const muted = useMuted(s.alias);
+  return (
+    <button
+      key={s.alias}
+      type="button"
+      data-node-list-item
+      data-node-list-alias={s.alias}
+      data-selected={selected ? 'true' : 'false'}
+      // 通信龙 07-31: attribute is ALWAYS present ('true'|'false'),
+      // never removed. This separates capability (attr exists on every
+      // row → wire is intact) from state (attr === 'true' → user did
+      // pin/mute this one). Prior form (undefined when false) made a
+      // gate script's "at least one on page" check indistinguishable
+      // from "wire got ripped out" — both looked like `[data-node-pinned]`
+      // empty. See feedback_tolerant_assertion_accepts_noncompliance.
+      data-node-pinned={pinned ? 'true' : 'false'}
+      data-node-muted={muted ? 'true' : 'false'}
+      onClick={() => onSelect(s.alias)}
+      onContextMenu={e => onContextMenu(s.alias, e)}
+      // SPEC §11.1: pinned row = whole-row light background
+      // rgba(125,211,252,0.04) (hover 0.08); no pin ICON (Feishu
+      // pattern). Selected wins over both.
+      className={`w-full flex items-center gap-2.5 px-3 py-2.5 text-left transition-colors border-b border-[#1a1a1d] ${
+        selected
+          ? 'bg-cyan-500/8'
+          : pinned
+            ? 'bg-[rgba(125,211,252,0.04)] hover:bg-[rgba(125,211,252,0.08)]'
+            : 'hover:bg-[#161618]'
+      }`}
+    >
+      <div className="relative shrink-0">
+        <AliasAvatar alias={s.alias} size={32} />
+        {s.online && (
+          <span
+            aria-hidden
+            className="absolute -bottom-0.5 -right-0.5 w-2.5 h-2.5 rounded-full bg-green-400 ring-2 ring-[#0F1320]"
+          />
+        )}
+      </div>
+      <div className="flex-1 min-w-0">
+        <div className="flex items-center justify-between gap-2">
+          {/* SPEC §11: alias + optional bell-slash icon at RIGHT of
+              alias when muted (12×12, #64748B). NO pin icon — pinned
+              state is signaled by row background per §11.1. */}
+          <span className={`text-[13px] truncate flex items-center gap-1.5 min-w-0 ${selected ? 'text-cyan-200 font-medium' : 'text-gray-200'}`}>
+            <span className="truncate">{s.alias}</span>
+            {muted && (
+              <svg
+                aria-label={t('已免打扰', 'Muted')}
+                data-mute-icon
+                width="12"
+                height="12"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="#64748B"
+                strokeWidth={1.5}
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className="shrink-0"
+              >
+                <path d="M15 17h5l-1.4-1.4A2 2 0 0118 14.2V11a6 6 0 00-4-5.7" />
+                <path d="M6 8v3.2c0 .5-.2 1-.6 1.4L4 14h9" />
+                <path d="M13.7 21a2 2 0 01-3.4 0" />
+                <path d="M3 3l18 18" />
+              </svg>
+            )}
+          </span>
+          {/* SPEC §11.3: unread badge color depends on mute:
+              - not-muted → red (#EF4444 / white)
+              - muted    → gray (#475569 / #CBD5E1) — count still shown,
+                           per "static + silent" (mute ≠ mark-read).
+              Kept as one <span> with data-unread-badge on both
+              variants so tests can find it regardless of state. */}
+          {unread > 0 && (
+            <span
+              aria-label={muted
+                ? t(`已免打扰，未读 ${unread}`, `Muted, ${unread} unread`)
+                : t(`${unread} 条未读`, `${unread} unread`)
+              }
+              data-unread-badge
+              data-badge-variant={muted ? 'muted' : 'default'}
+              className={`shrink-0 min-w-[16px] h-4 px-1 rounded-full text-[9px] font-semibold leading-4 text-center ${
+                muted
+                  ? 'bg-[#475569] text-[#CBD5E1]'
+                  : 'bg-[#EF4444] text-white'
+              }`}
+            >
+              {unread > 99 ? '99+' : unread}
+            </span>
+          )}
+        </div>
+        <div className="mt-0.5 flex items-center gap-1.5">
+          <LastLine alias={s.alias} session={s} />
+        </div>
+      </div>
+    </button>
+  );
+}
+
 function LastLine({ alias, session }: { alias: string; session: SessionRow }) {
   const draft = useHasDraft(alias);
   if (draft) {
@@ -68,6 +190,72 @@ function LastLine({ alias, session }: { alias: string; session: SessionRow }) {
 
 export function NodeList({ sessions, selectedAlias, onSelect, search, onSearchChange }: NodeListProps) {
   const { unreadCount } = useChatUnread();
+  // Batch (07-31) segment 2: right-click context menu state. `null` when
+  // closed; `{alias, x, y}` when open. Positioning is at the mouse
+  // coords from the contextmenu event so the menu appears where the
+  // user right-clicked, not at a static offset.
+  const [menu, setMenu] = useState<{ alias: string; x: number; y: number } | null>(null);
+
+  // Batch (07-31) segment 3: keyboard ↑↓ walks the list, Enter opens
+  // the focused entry (URL changes via parent's onSelect → router.push).
+  //
+  // Focus discipline: window-level keydown, guarded to skip when the
+  // user is typing in a text control — the "chat input" case Vincent
+  // explicitly named, plus any generic input/textarea/contenteditable
+  // so we don't hijack keystrokes anywhere in the app.
+  //
+  // Ref pattern: parent's `onSelect` and `sessions` change reference
+  // every render (arrow fn / filtered array). If we used them in the
+  // deps array, the effect would re-attach the listener on every
+  // render — brief windows with no listener could miss keydowns.
+  // Instead: attach ONCE (empty deps), read latest values via ref.
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+  const stateRef = useRef({ sessions, selectedAlias, onSelect });
+  // (was a bare write during render — react-hooks/refs violation caught by
+  // the pre-commit gate; an effect keeps the same "listener reads latest
+  // values" semantics, updated post-render.)
+  useEffect(() => { stateRef.current = { sessions, selectedAlias, onSelect }; });
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== 'ArrowUp' && e.key !== 'ArrowDown' && e.key !== 'Enter') return;
+      const active = document.activeElement as HTMLElement | null;
+      if (active) {
+        const tag = active.tagName;
+        if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return;
+        if (active.isContentEditable) return;
+      }
+      const { sessions: s, selectedAlias: sel, onSelect: pick } = stateRef.current;
+      if (s.length === 0) return;
+      const currentIdx = sel ? s.findIndex(x => x.alias === sel) : -1;
+      if (e.key === 'Enter') {
+        if (currentIdx === -1) {
+          e.preventDefault();
+          pick(s[0].alias);
+        }
+        return;
+      }
+      e.preventDefault();
+      const nextIdx = currentIdx === -1
+        ? (e.key === 'ArrowDown' ? 0 : s.length - 1)
+        : (e.key === 'ArrowDown'
+            ? Math.min(s.length - 1, currentIdx + 1)
+            : Math.max(0, currentIdx - 1));
+      if (nextIdx !== currentIdx) pick(s[nextIdx].alias);
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, []);
+
+  // Auto-scroll: after selection change, bring the selected entry into
+  // the rail's viewport. Runs on every render — cheap and safe. Uses
+  // scrollIntoView block:'nearest' so it doesn't jerk the list when
+  // the selected entry is already visible.
+  useEffect(() => {
+    if (!selectedAlias) return;
+    const el = scrollRef.current?.querySelector(`[data-node-list-alias="${CSS.escape(selectedAlias)}"]`) as HTMLElement | null;
+    if (el) el.scrollIntoView({ block: 'nearest' });
+  }, [selectedAlias]);
 
   return (
     <div
@@ -90,7 +278,15 @@ export function NodeList({ sessions, selectedAlias, onSelect, search, onSearchCh
       <div className="px-3 py-2 text-[11px] text-gray-500 tracking-wide uppercase border-b border-[#1e1e22] shrink-0">
         {t(`节点 ${sessions.length}`, `Nodes · ${sessions.length}`)}
       </div>
-      <div data-testid="node-list-scroll" className="flex-1 min-h-0 overflow-y-auto">
+      {menu && (
+        <NodeListContextMenu
+          alias={menu.alias}
+          x={menu.x}
+          y={menu.y}
+          onClose={() => setMenu(null)}
+        />
+      )}
+      <div ref={scrollRef} data-testid="node-list-scroll" className="flex-1 min-h-0 overflow-y-auto pb-[calc(5rem+env(safe-area-inset-bottom))] lg:pb-0">
         {sessions.length === 0 ? (
           search ? (
             /* #Stage D (Vincent ③ 判据): a no-match search MUST look
@@ -112,51 +308,17 @@ export function NodeList({ sessions, selectedAlias, onSelect, search, onSearchCh
           </div>
           )
         ) : (
-          sessions.map(s => {
-            const selected = s.alias === selectedAlias;
-            const unread = unreadCount(s.alias);
-            return (
-              <button
-                key={s.alias}
-                type="button"
-                data-node-list-item
-                data-node-list-alias={s.alias}
-                data-selected={selected ? 'true' : 'false'}
-                onClick={() => onSelect(s.alias)}
-                className={`w-full flex items-center gap-2.5 px-3 py-2.5 text-left transition-colors border-b border-[#1a1a1d] ${
-                  selected ? 'bg-cyan-500/8' : 'hover:bg-[#161618]'
-                }`}
-              >
-                <div className="relative shrink-0">
-                  <AliasAvatar alias={s.alias} size={32} />
-                  {s.online && (
-                    <span
-                      aria-hidden
-                      className="absolute -bottom-0.5 -right-0.5 w-2.5 h-2.5 rounded-full bg-green-400 ring-2 ring-[#0F1320]"
-                    />
-                  )}
-                </div>
-                <div className="flex-1 min-w-0">
-                  <div className="flex items-center justify-between gap-2">
-                    <span className={`text-[13px] truncate ${selected ? 'text-cyan-200 font-medium' : 'text-gray-200'}`}>
-                      {s.alias}
-                    </span>
-                    {unread > 0 && (
-                      <span
-                        aria-label={t(`${unread} 条未读`, `${unread} unread`)}
-                        className="shrink-0 min-w-[16px] h-4 px-1 rounded-full bg-red-500 text-white text-[9px] font-semibold leading-4 text-center"
-                      >
-                        {unread > 99 ? '99+' : unread}
-                      </span>
-                    )}
-                  </div>
-                  <div className="mt-0.5 flex items-center gap-1.5">
-                    <LastLine alias={s.alias} session={s} />
-                  </div>
-                </div>
-              </button>
-            );
-          })
+          sessions.map(s => <NodeListRow
+            key={s.alias}
+            session={s}
+            selected={s.alias === selectedAlias}
+            unread={unreadCount(s.alias)}
+            onSelect={onSelect}
+            onContextMenu={(alias, e) => {
+              e.preventDefault();
+              setMenu({ alias, x: e.clientX, y: e.clientY });
+            }}
+          />)
         )}
       </div>
     </div>

package/app/components/NodeListContextMenu.tsx

@@ -0,0 +1,187 @@
+'use client';
+
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { togglePin, usePinned } from '../lib/chat-pin';
+import { toggleMute, useMuted } from '../lib/chat-mute';
+import { markChatRead, useChatUnread } from '../lib/chat-unread';
+import { useNetworkId } from '../lib/network-context';
+import { t } from '../lib/ui-lang';
+
+// SPEC §10 (dashboard-ui-ref/SPEC.md): right-click context menu for
+// NodeList rail entries. Actions: 置顶 / 免打扰 / 标记已读.
+//
+// Positioning (SPEC §10 "贴边行为"):
+//   - default: right-and-down of cursor
+//   - if rect.bottom + menuHeight > viewport.bottom → flip up
+//   - if rect.right  + menuWidth  > viewport.right  → flip left
+//   - at least 8px margin from every viewport edge
+//   - useLayoutEffect measures menu then adjusts position (menu size
+//     is bounded but not fixed — item labels change per state)
+//
+// Deep-styling: NO shadow (SPEC §2 conclusion — dark theme shadow
+// renders as gray haze). Use brighter bg (#1E293B vs chat's #141826)
+// + 1px border for shape.
+//
+// Test-hook contract:
+//   - Root: data-testid="node-context-menu", data-target-alias, role="menu"
+//   - Items: data-testid="ctx-pin"|"ctx-mute"|"ctx-mark-read", role="menuitem"
+//   - data-flipped-{y,x}="true" when position was flipped for tests.
+
+export interface NodeListContextMenuProps {
+  alias: string;
+  x: number;  // cursor clientX at right-click
+  y: number;  // cursor clientY at right-click
+  onClose: () => void;
+}
+
+const MENU_W = 200;   // SPEC §10: 200px fixed width
+const EDGE = 8;       // SPEC §10: ≥8px margin from viewport edge
+
+export function NodeListContextMenu({ alias, x, y, onClose }: NodeListContextMenuProps) {
+  const pinned = usePinned(alias);
+  const muted = useMuted(alias);
+  const { networkId } = useNetworkId();
+  const { unreadCount } = useChatUnread();
+  const unread = unreadCount(alias);
+  const ref = useRef<HTMLDivElement | null>(null);
+  const [pos, setPos] = useState<{ top: number; left: number; flippedY: boolean; flippedX: boolean }>({
+    top: y,
+    left: x,
+    flippedY: false,
+    flippedX: false,
+  });
+
+  // SPEC §10 "贴边行为" — measure after paint, flip axis if would
+  // overflow. useLayoutEffect so users don't see a paint at the
+  // wrong location before the flip.
+  useLayoutEffect(() => {
+    if (typeof window === 'undefined') return;
+    const el = ref.current;
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    const menuH = rect.height || 120;  // fallback if getBoundingClientRect races
+    const menuW = MENU_W;
+    const vh = window.innerHeight;
+    const vw = window.innerWidth;
+    let top = y;
+    let left = x;
+    let flippedY = false;
+    let flippedX = false;
+    if (y + menuH + EDGE > vh) {
+      top = Math.max(EDGE, y - menuH);
+      flippedY = true;
+    }
+    if (x + menuW + EDGE > vw) {
+      left = Math.max(EDGE, x - menuW);
+      flippedX = true;
+    }
+    // Final clamp — in case the flip still overflows on tiny viewports.
+    top = Math.max(EDGE, Math.min(top, vh - menuH - EDGE));
+    left = Math.max(EDGE, Math.min(left, vw - menuW - EDGE));
+    setPos({ top, left, flippedY, flippedX });
+  }, [x, y]);
+
+  useEffect(() => {
+    // mousedown-capture so a right-click INSIDE the menu doesn't dismiss.
+    const onClick = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) onClose();
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') { e.stopPropagation(); onClose(); }
+    };
+    document.addEventListener('mousedown', onClick, true);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onClick, true);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [onClose]);
+
+  const runAndClose = (fn: () => void) => () => { fn(); onClose(); };
+
+  // SPEC §10 三态色值 (Tailwind can't do arbitrary custom hex on
+  // pseudo-classes easily; the group-hover + `data-*` selectors on the
+  // Menu item below drive the state colors via inline CSS variables to
+  // keep both bg + text + icon flipping together on hover.)
+  const itemCls =
+    'group w-full text-left flex items-center gap-2.5 px-2.5 py-1.5 text-[13px] font-medium text-[#E2E8F0] ' +
+    'hover:bg-[rgba(125,211,252,0.10)] hover:text-white active:bg-[rgba(125,211,252,0.18)] ' +
+    'disabled:text-[#475569] disabled:cursor-not-allowed disabled:hover:bg-transparent';
+
+  const menu = (
+    <div
+      ref={ref}
+      role="menu"
+      aria-label={t(`节点 ${alias} 操作菜单`, `Actions for node ${alias}`)}
+      data-testid="node-context-menu"
+      data-target-alias={alias}
+      data-flipped-y={pos.flippedY ? 'true' : undefined}
+      data-flipped-x={pos.flippedX ? 'true' : undefined}
+      style={{ position: 'fixed', top: pos.top, left: pos.left, width: MENU_W, zIndex: 60 }}
+      className="rounded-lg border border-[rgba(255,255,255,0.10)] bg-[#1E293B] py-1"
+      onContextMenu={e => e.preventDefault()}
+    >
+      <button
+        type="button"
+        role="menuitem"
+        data-testid="ctx-pin"
+        onClick={runAndClose(() => togglePin(alias))}
+        className={itemCls}
+      >
+        <IconPin className="shrink-0 w-5 h-5 text-[#94A3B8] group-hover:text-[#7DD3FC]" />
+        {pinned ? t('取消置顶', 'Unpin') : t('置顶会话', 'Pin conversation')}
+      </button>
+      <button
+        type="button"
+        role="menuitem"
+        data-testid="ctx-mute"
+        onClick={runAndClose(() => toggleMute(alias))}
+        className={itemCls}
+      >
+        <IconBell muted className="shrink-0 w-5 h-5 text-[#94A3B8] group-hover:text-[#7DD3FC]" />
+        {muted ? t('取消免打扰', 'Unmute') : t('免打扰', 'Mute')}
+      </button>
+      <button
+        type="button"
+        role="menuitem"
+        data-testid="ctx-mark-read"
+        onClick={runAndClose(() => markChatRead(alias, networkId))}
+        disabled={unread === 0}
+        className={itemCls}
+      >
+        <IconCheck className="shrink-0 w-5 h-5 text-[#94A3B8] group-hover:text-[#7DD3FC] group-disabled:text-[#475569]" />
+        {t(unread > 0 ? `标记已读 (${unread})` : '标记已读', unread > 0 ? `Mark ${unread} read` : 'Mark read')}
+      </button>
+    </div>
+  );
+
+  if (typeof document === 'undefined') return null;
+  return createPortal(menu, document.body);
+}
+
+function IconPin({ className }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round">
+      <path d="M12 17v5" />
+      <path d="M5 10l7 7 7-7" />
+      <path d="M5 10l3-8h8l3 8z" />
+    </svg>
+  );
+}
+function IconBell({ className, muted }: { className?: string; muted?: boolean }) {
+  return (
+    <svg className={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round">
+      <path d="M15 17h5l-1.4-1.4A2 2 0 0118 14.2V11a6 6 0 00-12 0v3.2c0 .5-.2 1-.6 1.4L4 17h5" />
+      <path d="M13.7 21a2 2 0 01-3.4 0" />
+      {muted && <path d="M3 3l18 18" />}
+    </svg>
+  );
+}
+function IconCheck({ className }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round">
+      <path d="M5 13l4 4L19 7" />
+    </svg>
+  );
+}