dsh-obsidian-memo 0.16.3

package/src/client/components/feedback.js

@@ -0,0 +1,50 @@
+/** 空态与 toast 的展示组件；操作由调用方传入。 */
+import { h } from '../react.js';
+
+function CenterState(props) {
+  return h('div', { className: 'SN_center' },
+    props.mark ? h('div', { className: 'SN_centerMark', 'aria-hidden': 'true' }, props.mark) : null,
+    h('h2', { className: 'SN_centerTitle' }, props.title),
+    props.text ? h('p', { className: 'SN_centerText' }, props.text) : null,
+    props.actionLabel
+      ? h('button', {
+        type: 'button',
+        className: 'SN_primaryBtn',
+        onClick: props.onAction,
+        disabled: Boolean(props.actionDisabled),
+      }, props.actionLabel)
+      : null,
+  );
+}
+
+function ToastStack(props) {
+  const { toasts, onDismiss } = props;
+  if (!toasts || toasts.length === 0) return null;
+  return h('div', { className: 'SN_toasts', 'aria-live': 'polite' },
+    toasts.map((item) => {
+      // 0.13：一条 toast 可以带多个操作按钮（如「去设置 / 知道了」）；兼容旧的单个 action。
+      const actions = Array.isArray(item.actions) && item.actions.length > 0
+        ? item.actions
+        : (item.action ? [item.action] : []);
+      return h('div', {
+        key: item.id,
+        className: 'SN_toast',
+        'data-kind': item.kind,
+        role: 'status',
+      },
+        h('span', { className: 'SN_toastText' }, item.text),
+        actions.map((action, index) => h('button', {
+          key: index,
+          type: 'button',
+          className: 'SN_toastAction',
+          onClick: () => {
+            onDismiss(item.id);
+            action.run();
+          },
+        }, action.label)),
+      );
+    }),
+  );
+}
+
+export { CenterState, ToastStack };

package/src/client/components/icons.js

@@ -0,0 +1,160 @@
+/** 手写 SVG 图标，只负责渲染。 */
+import { h } from '../react.js';
+
+function PanelIcon(props) {
+  const size = props && typeof props.size === 'number' && props.size > 0 ? props.size : 18;
+  const active = Boolean(props && props.active);
+  return h('svg', {
+    width: size,
+    height: size,
+    viewBox: '0 0 24 24',
+    fill: 'none',
+    'aria-hidden': 'true',
+    focusable: 'false',
+    style: { display: 'block', opacity: active ? 1 : 0.92 },
+  },
+    h('path', {
+      d: 'M6 3.25h11.25a2.5 2.5 0 0 1 2.5 2.5v9.1L14.6 20.75H6a2.5 2.5 0 0 1-2.5-2.5V5.75a2.5 2.5 0 0 1 2.5-2.5Z',
+      stroke: 'currentColor', strokeWidth: 1.6, strokeLinejoin: 'round',
+    }),
+    h('path', {
+      d: 'M19.75 14.85h-3.4a2.5 2.5 0 0 0-2.5 2.5v3.4',
+      stroke: 'currentColor', strokeWidth: 1.6, strokeLinejoin: 'round',
+    }),
+    h('path', {
+      d: 'M7.3 8.4h7.4M7.3 11.9h4.9',
+      stroke: 'currentColor', strokeWidth: 1.5, strokeLinecap: 'round', opacity: 0.8,
+    }),
+    h('circle', { cx: 17.9, cy: 6.1, r: 2.15, fill: '#B4472F' }),
+  );
+}
+
+function RefreshIcon(props) {
+  const spinning = Boolean(props && props.spinning);
+  return h('svg', {
+    width: 15, height: 15, viewBox: '0 0 24 24', fill: 'none',
+    'aria-hidden': 'true', focusable: 'false',
+    className: spinning ? 'SN_spin' : undefined,
+    style: { display: 'block' },
+  },
+    h('path', {
+      d: 'M20 11.2a8 8 0 1 0-.9 4.6',
+      stroke: 'currentColor', strokeWidth: 1.7, strokeLinecap: 'round',
+    }),
+    h('path', {
+      d: 'M20.2 4.9v5.2h-5.2',
+      stroke: 'currentColor', strokeWidth: 1.7, strokeLinecap: 'round', strokeLinejoin: 'round',
+    }),
+  );
+}
+
+function GearIcon() {
+  return h('svg', {
+    width: 15, height: 15, viewBox: '0 0 24 24', fill: 'none',
+    'aria-hidden': 'true', focusable: 'false', style: { display: 'block' },
+  },
+    h('circle', { cx: 12, cy: 12, r: 3.1, stroke: 'currentColor', strokeWidth: 1.7 }),
+    h('path', {
+      d: 'M19.4 12c0-.5-.05-1-.15-1.45l2-1.55-1.9-3.3-2.4 1a8.6 8.6 0 0 0-2.5-1.45L14.2 2.6h-4.4l-.25 2.65A8.6 8.6 0 0 0 7.05 6.7l-2.4-1-1.9 3.3 2 1.55a8.7 8.7 0 0 0 0 2.9l-2 1.55 1.9 3.3 2.4-1a8.6 8.6 0 0 0 2.5 1.45l.25 2.65h4.4l.25-2.65a8.6 8.6 0 0 0 2.5-1.45l2.4 1 1.9-3.3-2-1.55c.1-.45.15-.95.15-1.45Z',
+      stroke: 'currentColor', strokeWidth: 1.3, strokeLinejoin: 'round',
+    }),
+  );
+}
+
+function CloseIcon() {
+  return h('svg', {
+    width: 14, height: 14, viewBox: '0 0 24 24', fill: 'none',
+    'aria-hidden': 'true', focusable: 'false', style: { display: 'block' },
+  },
+    h('path', { d: 'M6.5 6.5l11 11M17.5 6.5l-11 11', stroke: 'currentColor', strokeWidth: 1.8, strokeLinecap: 'round' }),
+  );
+}
+
+function FolderTreeIcon() {
+  return h('svg', {
+    width: 15, height: 15, viewBox: '0 0 24 24', fill: 'none',
+    'aria-hidden': 'true', focusable: 'false', style: { display: 'block' },
+  },
+    h('path', {
+      d: 'M3.2 6.4h5.2l1.9 2.2h10.5a1.7 1.7 0 0 1 1.7 1.7v9.1a1.7 1.7 0 0 1-1.7 1.7H3.2a1.7 1.7 0 0 1-1.7-1.7V8.1a1.7 1.7 0 0 1 1.7-1.7Z',
+      stroke: 'currentColor', strokeWidth: 1.5, strokeLinejoin: 'round',
+    }),
+    h('path', {
+      d: 'M7 11.6v5M7 13.9h3.2M7 16.6h3.2',
+      stroke: 'currentColor', strokeWidth: 1.4, strokeLinecap: 'round',
+    }),
+  );
+}
+
+function PinIcon(props) {
+  const pinned = Boolean(props && props.pinned);
+  return h('svg', {
+    width: 15, height: 15, viewBox: '0 0 24 24', fill: 'none',
+    'aria-hidden': 'true', focusable: 'false', style: { display: 'block' },
+  },
+    h('path', {
+      d: 'M9.3 3.6h5.4l-.8 5.1 3 2.7v1.2H7.1v-1.2l3-2.7-.8-5.1Z',
+      fill: pinned ? 'currentColor' : 'none',
+      stroke: 'currentColor', strokeWidth: 1.5, strokeLinejoin: 'round',
+    }),
+    h('path', {
+      d: 'M12 12.6v7.2',
+      stroke: 'currentColor', strokeWidth: 1.6, strokeLinecap: 'round',
+    }),
+  );
+}
+
+function SortIcon() {
+  return h('svg', {
+    width: 15, height: 15, viewBox: '0 0 24 24', fill: 'none',
+    'aria-hidden': 'true', focusable: 'false', style: { display: 'block' },
+  },
+    h('path', { d: 'M4 7h11M4 12h8M4 17h5', stroke: 'currentColor', strokeWidth: 1.7, strokeLinecap: 'round' }),
+    h('path', { d: 'M17.5 7.5v9.5M14.7 14.4l2.8 2.8 2.8-2.8', stroke: 'currentColor', strokeWidth: 1.6, strokeLinecap: 'round', strokeLinejoin: 'round' }),
+  );
+}
+
+function ObsidianIcon() {
+  return h('svg', {
+    width: 12, height: 12, viewBox: '0 0 24 24', fill: 'none',
+    'aria-hidden': 'true', focusable: 'false', style: { display: 'block', flex: 'none' },
+  },
+    h('path', { d: 'M13.4 4.4h6.2v6.2', stroke: 'currentColor', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round' }),
+    h('path', { d: 'M19.6 4.4l-8 8', stroke: 'currentColor', strokeWidth: 2, strokeLinecap: 'round' }),
+    h('path', { d: 'M18.6 14.2v3.8a2 2 0 0 1-2 2H5.4a2 2 0 0 1-2-2V6.8a2 2 0 0 1 2-2h3.8', stroke: 'currentColor', strokeWidth: 2, strokeLinecap: 'round' }),
+  );
+}
+
+function CalendarIcon() {
+  return h('svg', {
+    width: 15, height: 15, viewBox: '0 0 24 24', fill: 'none',
+    'aria-hidden': 'true', focusable: 'false', style: { display: 'block' },
+  },
+    h('rect', {
+      x: 3.2, y: 5.2, width: 17.6, height: 15.6, rx: 2.4,
+      stroke: 'currentColor', strokeWidth: 1.5,
+    }),
+    h('path', {
+      d: 'M3.4 9.6h17.2M8.2 3.4v3.4M15.8 3.4v3.4',
+      stroke: 'currentColor', strokeWidth: 1.5, strokeLinecap: 'round',
+    }),
+    h('path', {
+      d: 'M7.4 13.3h2.1M11.1 13.3h2.1M14.8 13.3h2.1M7.4 16.8h2.1M11.1 16.8h2.1',
+      stroke: 'currentColor', strokeWidth: 1.5, strokeLinecap: 'round', opacity: 0.72,
+    }),
+  );
+}
+
+function ActionIcon({ kind, size = 20 }) {
+  const paths = {
+    delete: 'M4 7h16M9 7V4h6v3M6 7l1 13h10l1-13M10 10v7m4-7v7',
+    archive: 'M4 4h16v4H4zM6 8v12h12V8M10 12h4',
+    project: 'M3 7V5h6l2 2h10v12H3zM12 10v6m-3-3h6',
+    copy: 'M8 8h12v12H8zM16 8V4H4v12h4',
+    up: 'M12 19V5m-6 6 6-6 6 6',
+  };
+  return h('svg', { width: size, height: size, viewBox: '0 0 24 24', fill: 'none', 'aria-hidden': 'true' },
+    h('path', { d: paths[kind], stroke: 'currentColor', strokeWidth: 1.5, strokeLinecap: 'round', strokeLinejoin: 'round' }));
+}
+
+export { PanelIcon, RefreshIcon, GearIcon, CloseIcon, FolderTreeIcon, PinIcon, SortIcon, ObsidianIcon, CalendarIcon, ActionIcon };

package/src/client/components/use-toasts.js

@@ -0,0 +1,58 @@
+/** 持有通知列表与计时器，关闭或卸载时清理资源。 */
+import { MAX_TOASTS, TOAST_MS } from '../constants.js';
+import { React } from '../react.js';
+
+function useToasts() {
+  const [toasts, setToasts] = React.useState([]);
+  const toastSeqRef = React.useRef(0);
+  const toastTimersRef = React.useRef(new Map());
+
+  function dismissToast(id) {
+    const timer = toastTimersRef.current.get(id);
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      toastTimersRef.current.delete(id);
+    }
+    setToasts((list) => list.filter((item) => item.id !== id));
+  }
+
+  function pushToast(toast) {
+    if (!toast || typeof toast.text !== 'string' || toast.text === '') return;
+    toastSeqRef.current += 1;
+    const id = toastSeqRef.current;
+    const item = {
+      id: id,
+      kind: toast.kind || 'info',
+      text: toast.text,
+      action: toast.action || null,
+      actions: Array.isArray(toast.actions) && toast.actions.length > 0 ? toast.actions : null,
+    };
+    setToasts((list) => {
+      const next = list.concat(item);
+      return next.length > MAX_TOASTS ? next.slice(next.length - MAX_TOASTS) : next;
+    });
+    const timeout = typeof toast.timeout === 'number' ? toast.timeout : TOAST_MS;
+    if (timeout > 0) {
+      const timer = setTimeout(() => {
+        toastTimersRef.current.delete(id);
+        setToasts((list) => list.filter((entry) => entry.id !== id));
+      }, timeout);
+      toastTimersRef.current.set(id, timer);
+    }
+  }
+
+  function pushErrorToast(error) {
+    pushToast({
+      text: error && error.message ? error.message : String(error),
+      kind: 'error',
+      timeout: 7000,
+    });
+  }
+  React.useEffect(() => () => {
+    for (const timer of toastTimersRef.current.values()) clearTimeout(timer);
+    toastTimersRef.current.clear();
+  }, []);
+  return { toasts, dismissToast, pushToast, pushErrorToast };
+}
+
+export { useToasts };

package/src/client/constants.js

@@ -0,0 +1,127 @@
+/** 浏览器协议标识、展示默认值与资源限额；跨端限额由 parity 测试约束。 */
+
+
+const NS = 'sticky-notes';
+
+const CHANNEL = '/sticky-notes';
+
+const PANEL_ID = 'sticky-notes';
+
+const POLL_BASE = 4000;
+
+const POLL_MAX = 30000;
+
+const POLL_HIDDEN = 15000;
+
+const TOAST_MS = 5000;
+
+const UNDO_MS = 6000;
+
+const MAX_CARD_COMMENTS = 2;
+
+const MAX_TOASTS = 4;
+
+const CAPTURE_IMAGES = 8;
+
+const CAPTURE_IMAGE_BYTES = 8 * 1024 * 1024;
+
+const CAPTURE_TOTAL_BYTES = 16 * 1024 * 1024;
+
+const CAPTURE_SOURCE_IMAGE_BYTES = 32 * 1024 * 1024;
+
+const CAPTURE_SOURCE_TOTAL_BYTES = 64 * 1024 * 1024;
+
+const CAPTURE_LIMIT_TEXT = Object.freeze({
+  images: CAPTURE_IMAGES,
+  imageLimit: `${CAPTURE_IMAGE_BYTES / 1024 / 1024} MB`,
+  totalLimit: `${CAPTURE_TOTAL_BYTES / 1024 / 1024} MB`,
+  sourceImageLimit: `${CAPTURE_SOURCE_IMAGE_BYTES / 1024 / 1024} MB`,
+  sourceTotalLimit: `${CAPTURE_SOURCE_TOTAL_BYTES / 1024 / 1024} MB`,
+});
+
+const CARD_IMAGES = 3;
+
+const CARD_IMAGE_MAX_BYTES = 1500000;
+
+const IMAGE_CACHE_MAX = 160;
+
+const IMAGE_CACHE_BUDGET = 24 * 1024 * 1024;
+
+const IMAGE_CONCURRENCY = 3;
+
+const WALL_PAGE_SIZE = 50;
+
+const WALL_PRELOAD_PX = 320;
+
+const SORT_KEY = 'dsh-sticky-notes.sort.v2';
+
+const DEFAULT_SORT = 'created-desc';
+
+const SORT_OPTIONS = [
+  { id: 'created-desc', labelKey: 'sort.createdDesc' },
+  { id: 'created-asc', labelKey: 'sort.createdAsc' },
+  { id: 'mtime-desc', labelKey: 'sort.mtimeDesc' },
+  { id: 'name-asc', labelKey: 'sort.nameAsc' },
+];
+
+const DATE_FILTER_KEY = 'dsh-sticky-notes.dateFilter.v1';
+
+const DATE_FILTER_ENABLED_KEY = 'dsh-sticky-notes.dateFilterEnabled.v1';
+
+const DATE_REALTIME_KEY = 'dsh-sticky-notes.dateRealtime.v1';
+
+const DEFAULT_DATE_FILTER = 'today';
+
+const DEFAULT_DATE_FILTER_ENABLED = true;
+
+const DATE_FILTERS = [
+  { id: 'today', labelKey: 'date.today', days: 1 },
+  { id: '3d', labelKey: 'date.3d', days: 3 },
+  { id: 'week', labelKey: 'date.week', days: 7 },
+  { id: 'month', labelKey: 'date.month', days: 30 },
+];
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const DRAWER_WIDTH_KEY = 'dsh-sticky-notes.drawerWidth';
+
+const DRAWER_MIN_WIDTH = 320;
+
+const DRAWER_MAX_WIDTH = 960;
+
+const PINNED_WALL_MIN_WIDTH = 260;
+
+const PINNED_KEY = 'dsh-sticky-notes.panelLocked';
+
+const PINNED_NOTE_KEY = 'dsh-sticky-notes.pinnedNote';
+
+const EMPTY_SETTINGS = {
+  vaultPath: '',
+  notesDir: '',
+  projectDir: '',
+  archiveTargets: [],
+  emojis: [],
+  projectPrompt: '',
+  includeSubfolders: true,
+};
+
+const EMPTY_STATE = {
+  loaded: false,
+  configured: false,
+  revision: null,
+  version: '',
+  notes: [],
+  jobs: [],
+  settings: null,
+  error: null,
+};
+
+export {
+  NS, CHANNEL, PANEL_ID, POLL_BASE, POLL_MAX, POLL_HIDDEN, TOAST_MS, UNDO_MS, MAX_CARD_COMMENTS,
+  MAX_TOASTS, CAPTURE_IMAGES, CAPTURE_IMAGE_BYTES, CAPTURE_TOTAL_BYTES, CAPTURE_SOURCE_IMAGE_BYTES,
+  CAPTURE_SOURCE_TOTAL_BYTES, CAPTURE_LIMIT_TEXT, CARD_IMAGES, CARD_IMAGE_MAX_BYTES, IMAGE_CACHE_MAX,
+  IMAGE_CACHE_BUDGET, IMAGE_CONCURRENCY, WALL_PAGE_SIZE, WALL_PRELOAD_PX, SORT_KEY, DEFAULT_SORT,
+  SORT_OPTIONS, DATE_FILTER_KEY, DATE_FILTER_ENABLED_KEY, DATE_REALTIME_KEY, DEFAULT_DATE_FILTER,
+  DEFAULT_DATE_FILTER_ENABLED, DATE_FILTERS, DAY_MS, DRAWER_WIDTH_KEY, DRAWER_MIN_WIDTH, DRAWER_MAX_WIDTH,
+  PINNED_WALL_MIN_WIDTH, PINNED_KEY, PINNED_NOTE_KEY, EMPTY_SETTINGS, EMPTY_STATE,
+};

package/src/client/data/state.js

@@ -0,0 +1,116 @@
+/** 合并 Host 快照、复用未变对象并叠加运行中任务状态。 */
+import { EMPTY_STATE } from '../constants.js';
+
+function runningCommentJobs(jobs) {
+  const running = new Map();
+  if (!Array.isArray(jobs)) return running;
+  for (const job of jobs) {
+    if (!job || job.kind !== 'comment' || job.status !== 'running') continue;
+    if (typeof job.path !== 'string') continue;
+    running.set(job.path, job);
+  }
+  return running;
+}
+
+function pendingFromJob(job, settings) {
+  const emojis = settings && Array.isArray(settings.emojis) ? settings.emojis : [];
+  const emoji = emojis.find((item) => item && item.id === job.emojiId);
+  if (emoji) return { emoji: emoji.emoji || '✍️', label: emoji.label || '' };
+  return { emoji: '✍️', label: '' };
+}
+
+function decorateNotes(notes, jobs, settings) {
+  if (!Array.isArray(notes)) return [];
+  const running = runningCommentJobs(jobs);
+  let changed = false;
+  const next = notes.map((note) => {
+    if (!note || typeof note.path !== 'string') return note;
+    const job = running.get(note.path);
+    const pending = job ? pendingFromJob(job, settings) : null;
+    const current = note.pending || null;
+    if (pending === null && current === null) return note;
+    if (pending !== null && current !== null && pending.emoji === current.emoji && pending.label === current.label) return note;
+    changed = true;
+    return Object.assign({}, note, { pending: pending });
+  });
+  return changed ? next : notes;
+}
+
+function jobsSignature(jobs) {
+  if (!Array.isArray(jobs)) return '';
+  return jobs
+    .map((job) => {
+      const id = job && job.id != null ? job.id : '';
+      const status = job && job.status ? job.status : '';
+      const error = job && job.error ? job.error : '';
+      const errorCode = job && job.errorCode ? job.errorCode : '';
+      const cut = job && job.truncated === true ? 'cut' : '';
+      return id + ':' + status + ':' + error + ':' + errorCode + ':' + cut;
+    })
+    .sort()
+    .join('|');
+}
+
+function settingsSignature(settings) {
+  if (settings == null) return '';
+  try {
+    return JSON.stringify(settings);
+  } catch (error) {
+    return '';
+  }
+}
+
+function reuseNotes(previous, incoming) {
+  const byPath = new Map(previous.map((note) => [note.path, note]));
+  const notes = incoming.map((note) => {
+    const old = byPath.get(note.path);
+    return old && JSON.stringify(old) === JSON.stringify(note) ? old : note;
+  });
+  return notes.length === previous.length && notes.every((note, index) => note === previous[index]) ? previous : notes;
+}
+
+function mergeState(prev, value) {
+  const base = prev || EMPTY_STATE;
+  if (!value || typeof value !== 'object') return base;
+  const incomingSettings = value.settings && typeof value.settings === 'object' ? value.settings : base.settings;
+  const settings = settingsSignature(incomingSettings) === settingsSignature(base.settings) ? base.settings : incomingSettings;
+  const incomingJobs = Array.isArray(value.jobs) ? value.jobs : base.jobs;
+  const jobs = JSON.stringify(incomingJobs) === JSON.stringify(base.jobs) ? base.jobs : incomingJobs;
+  const configured = value.configured === true;
+  const error = typeof value.error === 'string' && value.error !== '' ? value.error : null;
+  const revision = typeof value.revision === 'string' ? value.revision : base.revision;
+  const version = typeof value.version === 'string' && value.version !== '' ? value.version : (base.version || '');
+  const unchanged = value.unchanged === true;
+
+  // 快路径：unchanged 且 configured/error/revision/version/settings/jobs 签名、notes 引用都没变 → 原样返回。
+  if (unchanged && base.loaded === true
+    && configured === base.configured
+    && error === base.error
+    && revision === base.revision
+    && version === base.version
+    && settingsSignature(settings) === settingsSignature(base.settings)
+    && jobsSignature(jobs) === jobsSignature(base.jobs)) {
+    return base;
+  }
+
+  let notes;
+  if (unchanged) {
+    notes = base.notes;
+  } else {
+    const revisionChanged = base.loaded !== true || revision !== base.revision;
+    notes = revisionChanged && Array.isArray(value.notes) ? reuseNotes(base.notes, value.notes) : base.notes;
+  }
+  if (!configured) notes = [];
+  return {
+    loaded: true,
+    configured,
+    revision,
+    version,
+    notes: decorateNotes(notes, jobs, settings),
+    jobs,
+    settings,
+    error,
+  };
+}
+
+export { pendingFromJob, decorateNotes, jobsSignature, mergeState };

package/src/client/data/use-notes-data.js

@@ -0,0 +1,137 @@
+/** 请求代次、取消和可见性轮询；支持仅加载配置的官方设置页。 */
+import { EMPTY_STATE, POLL_BASE, POLL_HIDDEN } from '../constants.js';
+import { mergeState } from './state.js';
+import { panelIsVisible } from './visibility.js';
+import { nextPollDelay } from '../preferences.js';
+import { React } from '../react.js';
+import { callRpc } from '../runtime.js';
+import { isAbortError } from '../utils.js';
+
+function createStateReader(options) {
+  let generation = 0;
+  let active = null;
+  function invalidate() {
+    generation += 1;
+    if (active) active.abort();
+    active = null;
+  }
+  return {
+    invalidate,
+    async read(forceFull) {
+      invalidate();
+      const ticket = generation;
+      const controller = new AbortController();
+      active = controller;
+      try {
+        const value = await options.call({ knownRevision: forceFull ? null : options.getRevision() }, controller.signal);
+        if (ticket !== generation || controller.signal.aborted) return null;
+        active = null;
+        options.onValue(value);
+        return value;
+      } catch (error) {
+        if (ticket !== generation || controller.signal.aborted) return null;
+        throw error;
+      } finally {
+        if (active === controller) active = null;
+      }
+    },
+  };
+}
+
+function useNotesData(options) {
+  const optionsRef = React.useRef(options);
+  optionsRef.current = options;
+  const [view, setView] = React.useState(EMPTY_STATE);
+  const viewRef = React.useRef(EMPTY_STATE);
+  const [loadError, setLoadError] = React.useState(null);
+  const aliveRef = React.useRef(true);
+  const controllersRef = React.useRef(new Set());
+  const pollDelayRef = React.useRef(POLL_BASE);
+  const lastPollErrorRef = React.useRef(null);
+  const readerRef = React.useRef(null);
+  if (readerRef.current === null) {
+    readerRef.current = createStateReader({
+      call: (payload, signal) => callRpc(optionsRef.current.settingsOnly ? 'settings' : 'state', payload, signal),
+      getRevision: () => viewRef.current.revision,
+      onValue(value) {
+        if (!aliveRef.current) return;
+        lastPollErrorRef.current = null;
+        setLoadError(null);
+        const prev = viewRef.current;
+        const next = mergeState(prev, value);
+        if (next !== prev) {
+          viewRef.current = next;
+          setView(next);
+        }
+        optionsRef.current.onState(next, prev);
+      },
+    });
+  }
+  function updateView(next) {
+    // 乐观写入使已有的读取快照过期，防止随后返回的旧列表覆盖本地结果。
+    readerRef.current.invalidate();
+    viewRef.current = next;
+    setView(next);
+  }
+  async function readState(forceFull) {
+    try {
+      return await readerRef.current.read(forceFull);
+    } catch (error) {
+      if (!aliveRef.current || isAbortError(error)) return null;
+      const message = error && error.message ? error.message : String(error);
+      setLoadError(message);
+      if (lastPollErrorRef.current !== message) optionsRef.current.onError(error);
+      lastPollErrorRef.current = message;
+      return null;
+    }
+  }
+  function refreshNow(forceFull) {
+    pollDelayRef.current = POLL_BASE;
+    return readState(forceFull);
+  }
+  function request(endpoint, payload) {
+    const controller = new AbortController();
+    controllersRef.current.add(controller);
+    return callRpc(endpoint, payload, controller.signal).finally(() => controllersRef.current.delete(controller));
+  }
+  React.useEffect(() => {
+    aliveRef.current = true;
+    let disposed = false;
+    let timer = null;
+    function clearTimer() { if (timer !== null) clearTimeout(timer); timer = null; }
+    function schedule(delay) {
+      if (disposed) return;
+      clearTimer();
+      timer = setTimeout(run, delay);
+    }
+    async function run() {
+      if (disposed) return;
+      if (!panelIsVisible(optionsRef.current.panelRef.current)) { schedule(POLL_HIDDEN); return; }
+      const value = await readState(false);
+      if (disposed) return;
+      if (value) pollDelayRef.current = nextPollDelay(pollDelayRef.current, value.unchanged === true);
+      schedule(pollDelayRef.current);
+    }
+    function onVisibilityChange() {
+      clearTimer();
+      if (typeof document !== 'undefined' && document.hidden) { readerRef.current.invalidate(); return; }
+      pollDelayRef.current = POLL_BASE;
+      optionsRef.current.onVisible();
+      run();
+    }
+    if (typeof document !== 'undefined') document.addEventListener('visibilitychange', onVisibilityChange);
+    run();
+    return () => {
+      disposed = true;
+      aliveRef.current = false;
+      clearTimer();
+      readerRef.current.invalidate();
+      for (const controller of controllersRef.current) controller.abort();
+      controllersRef.current.clear();
+      if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onVisibilityChange);
+    };
+  }, []);
+  return { view, viewRef, loadError, aliveRef, controllersRef, updateView, request, refreshNow };
+}
+
+export { createStateReader, useNotesData };

package/src/client/data/visibility.js

@@ -0,0 +1,14 @@
+/** 判断面板和文档可见性，供轮询与快捷键使用。 */
+
+
+function panelIsVisible(panel) {
+  if (typeof document !== 'undefined' && document.hidden) return false;
+  if (!panel || typeof panel.getClientRects !== 'function') return true;
+  try {
+    return panel.getClientRects().length > 0;
+  } catch (error) {
+    return true;
+  }
+}
+
+export { panelIsVisible };