dsh-tiddlywiki 0.4.0 → 0.5.0

package/src/client/panel.ts

@@ -115,9 +115,6 @@ export function mountPanel(state: PanelState): () => void {
   let iframe: HTMLIFrameElement | undefined
   let frameArea: HTMLDivElement | undefined
   let errorArea: HTMLDivElement | undefined
-  let chip: HTMLSpanElement | undefined
-  let statusDot: HTMLSpanElement | undefined
-  let statusFloater: HTMLDivElement | undefined
   let refreshTimer: number | undefined
   let refreshAttempts = 0
 
@@ -143,48 +140,6 @@ export function mountPanel(state: PanelState): () => void {
     return view
   }
 
-  /**
-   * Bottom-right floating status/reload buttons (same visual language as the
-   * quick-note toggle) — the top panel bar is gone, so TW's menubar reaches
-   * the very top of the panel and clears the host's top-right buttons. Mount
-   * is gated by `ui.showPanelStatus` (settings page toggle).
-   */
-  const buildStatusFloater = (): HTMLDivElement => {
-    const wrap = document.createElement('div')
-    wrap.className = 'dsh-tw-panel-status'
-
-    const statusBtn = document.createElement('button')
-    statusBtn.type = 'button'
-    statusBtn.className = 'dsh-tw-panel-status-btn'
-    statusBtn.title = '刷新状态'
-    statusDot = document.createElement('span')
-    statusDot.className = 'dsh-tw-status-dot'
-    statusDot.dataset.state = 'unknown'
-    chip = document.createElement('span')
-    chip.className = 'dsh-tw-panel-status-text'
-    chip.textContent = '—'
-    statusBtn.append(statusDot, chip)
-    statusBtn.addEventListener('click', () => { void doRefresh() })
-
-    const reloadBtn = document.createElement('button')
-    reloadBtn.type = 'button'
-    reloadBtn.className = 'dsh-tw-panel-status-btn'
-    reloadBtn.textContent = '重载'
-    reloadBtn.title = '重载 TiddlyWiki 面板'
-    reloadBtn.addEventListener('click', () => {
-      if (iframe !== undefined && !iframe.hidden) iframe.src = iframe.src
-    })
-
-    wrap.append(statusBtn, reloadBtn)
-    document.body.append(wrap)
-    return wrap
-  }
-
-  const setChip = (stateName: string, text: string): void => {
-    if (statusDot !== undefined) statusDot.dataset.state = stateName
-    if (chip !== undefined) chip.textContent = text
-  }
-
   /** Pin the overlay to the center column's current viewport rect. */
   const syncRect = (): void => {
     if (container === undefined || columnEl === undefined) return
@@ -274,18 +229,15 @@ export function mountPanel(state: PanelState): () => void {
     }
     const payload = await fetchStatus()
     if (payload === null) {
-      setChip('failed', '状态不可达')
       showError('无法访问 /dsh-tiddlywiki/status')
       return
     }
     if (payload.status === 'running' && typeof payload.url === 'string') {
-      setChip('running', '在线')
       refreshAttempts = 0
       showFrame(payload.url)
       return
     }
     if (payload.status === 'starting') {
-      setChip('starting', '启动中')
       showStarting()
       // Auto-poll while starting (bounded).
       if (refreshAttempts < 30) {
@@ -294,7 +246,6 @@ export function mountPanel(state: PanelState): () => void {
       }
       return
     }
-    setChip('failed', '离线')
     refreshAttempts = 0
     showError(payload.error ?? `服务状态：${payload.status}`)
   }
@@ -347,12 +298,12 @@ export function mountPanel(state: PanelState): () => void {
   ensure()
   applyActive()
 
-  // Bottom-right status/reload buttons, gated by ui.showPanelStatus.
-  void (async () => {
-    const payload = await fetchStatus()
-    if (payload?.ui?.showPanelStatus === false) return
-    statusFloater = buildStatusFloater()
-  })()
+  // The "知识库" FAB's 重载面板 entry dispatches this event to reload the
+  // iframe (the panel itself no longer owns a floating status/reload button).
+  const onReloadRequest = (): void => {
+    if (iframe !== undefined && !iframe.hidden) iframe.src = iframe.src
+  }
+  document.addEventListener('dsh-tw-panel-reload', onReloadRequest)
 
   return () => {
     if (refreshTimer !== undefined) window.clearTimeout(refreshTimer)
@@ -362,10 +313,10 @@ export function mountPanel(state: PanelState): () => void {
     resizeObserver.disconnect()
     document.removeEventListener('click', onClickSidebarRow, true)
     document.removeEventListener(ACTIVATE_EVENT, onOtherActivate)
+    document.removeEventListener('dsh-tw-panel-reload', onReloadRequest)
     waitObserver.disconnect()
     unsubscribe()
     document.documentElement.removeAttribute(ACTIVE_ATTR)
     container?.remove()
-    statusFloater?.remove()
   }
 }

package/src/client/settings-page.ts

@@ -210,9 +210,9 @@ function renderConfigSection(body: HTMLElement, config: Record<string, unknown>,
   numField('git.debounceMs', '自动 commit 防抖(ms)', typeof git.debounceMs === 'number' ? git.debounceMs : 60_000)
   textField('git.remote', 'git 远端（空=仅本地）', typeof git.remote === 'string' ? git.remote : '')
   textField('git.branch', 'git 分支', typeof git.branch === 'string' ? git.branch : 'main')
-  checkField('ui.showQuickNote', '显示「快速笔记」悬浮按钮', ui.showQuickNote !== false)
-  checkField('ui.showPanelStatus', '显示 TW 面板右下角「状态/重载」悬浮按钮', ui.showPanelStatus !== false)
-  checkField('ui.showSyncButton', '显示右下角「同步」悬浮按钮', ui.showSyncButton !== false)
+  checkField('ui.showQuickNote', '显示「知识库」按钮里的「快速笔记」入口', ui.showQuickNote !== false)
+  checkField('ui.showPanelStatus', '显示「知识库」按钮里的 TW 面板/重载入口与状态行', ui.showPanelStatus !== false)
+  checkField('ui.showSyncButton', '显示「知识库」按钮里的「同步」入口与 git 状态点', ui.showSyncButton !== false)
   // 界面语言在下方「语言管理」区块设置（config 的 uiLanguage 仅供启动时自动应用）。
 
   const save = make('button', 'dsh-tw-settings-btn dsh-tw-settings-primary', '保存配置')

package/src/client/styles.ts

@@ -104,6 +104,9 @@ html[data-dsh-tw-active] .dshDesktopConversationSurface > :not([data-dsh-tw-view
   display: flex; flex-direction: column; align-items: flex-end; gap: 10px;
   font-family: inherit;
 }
+/* The wrapper's display:flex would beat the UA [hidden]{display:none} rule,
+   so the card's show/hide (root.hidden) needs an explicit rule. */
+.dsh-tw-note[hidden] { display: none; }
 .dsh-tw-note-card {
   width: 340px; max-width: calc(100vw - 40px);
   background: var(--dsw-alias-bg-layer-2, #fff); color: var(--dsw-alias-label-primary, #222);
@@ -344,6 +347,113 @@ html[data-dsh-tw-active] .dshDesktopConversationSurface > :not([data-dsh-tw-view
 .dsh-tw-settings-error { color: var(--dsw-alias-state-error-primary, #d13b3b); font-size: 12px; }
 .dsh-tw-settings-search { flex: 0 0 auto; max-width: 220px; }
 .dsh-tw-settings-check { accent-color: var(--dsw-alias-brand-primary, #3e63dd); }
+
+/* ── "知识库" FAB (v0.5: quick-note + sync + panel status merged) ──────────
+   One fixed cluster above the shutdown launcher FAB (bottom:24). The FAB
+   carries a git status dot; the menu pops upward from it. */
+.dsh-tw-fab-wrap {
+  position: fixed; right: 24px; bottom: 88px; z-index: 960;
+  display: flex; flex-direction: column; align-items: flex-end; gap: 8px;
+}
+.dsh-tw-fab {
+  position: relative;
+  width: 46px; height: 46px; border-radius: 50%;
+  border: 1px solid var(--dsw-alias-border-l2, rgba(0,0,0,.18));
+  background: var(--dsw-alias-bg-layer-2, #fff); color: var(--dsw-alias-label-primary, #222);
+  box-shadow: var(--dsw-shadow-lv3, 0 4px 16px rgba(0,0,0,.16)); cursor: pointer;
+  display: inline-flex; align-items: center; justify-content: center;
+  transition: background-color 120ms ease, transform 80ms ease;
+}
+.dsh-tw-fab:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.1)); }
+.dsh-tw-fab:active { transform: scale(.94); }
+.dsh-tw-fab-icon { display: inline-flex; }
+.dsh-tw-fab-dot {
+  position: absolute; right: 0; bottom: 0; width: 11px; height: 11px;
+  border-radius: 50%; border: 2px solid var(--dsw-alias-bg-layer-2, #fff);
+  background: #999; box-sizing: border-box;
+}
+.dsh-tw-fab-dot[data-state="clean"] { background: var(--dsw-alias-state-success-primary, #3eaa5f); }
+.dsh-tw-fab-dot[data-state="dirty"] { background: var(--dsw-alias-state-warning-primary, #d9822b); }
+.dsh-tw-fab-dot[data-state="behind"] { background: var(--dsw-alias-state-error-primary, #d13b3b); }
+.dsh-tw-fab-dot[data-state="syncing"] { background: var(--dsw-alias-brand-primary, #3e63dd); }
+.dsh-tw-fab-menu {
+  min-width: 220px; max-width: calc(100vw - 48px);
+  display: flex; flex-direction: column; gap: 2px; padding: 6px;
+  border-radius: 12px; border: 1px solid var(--dsw-alias-border-l2, rgba(0,0,0,.15));
+  background: var(--dsw-alias-bg-layer-2, #fff); color: var(--dsw-alias-label-primary, #222);
+  box-shadow: var(--dsw-shadow-lv3, 0 8px 30px rgba(0,0,0,.22));
+  font-size: 13px;
+  backdrop-filter: blur(14px); -webkit-backdrop-filter: blur(14px);
+  animation: dsh-tw-note-in 160ms ease;
+}
+.dsh-tw-fab-menu[hidden] { display: none; }
+.dsh-tw-fab-status {
+  display: flex; align-items: center; gap: 7px;
+  padding: 6px 9px; font-size: 12px; color: var(--dsw-alias-label-secondary, #666);
+  border-bottom: 1px solid var(--dsw-alias-border-l1, rgba(0,0,0,.08));
+  margin-bottom: 4px;
+}
+.dsh-tw-fab-status + .dsh-tw-fab-status { border-bottom: 0; margin-bottom: 4px; }
+.dsh-tw-fab-status-text { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.dsh-tw-fab-status-dot { width: 8px; height: 8px; border-radius: 50%; background: #999; flex: none; }
+.dsh-tw-fab-status-dot[data-state="running"] { background: var(--dsw-alias-state-success-primary, #3eaa5f); }
+.dsh-tw-fab-status-dot[data-state="starting"] { background: var(--dsw-alias-state-warning-primary, #d9822b); }
+.dsh-tw-fab-status-dot[data-state="failed"], .dsh-tw-fab-status-dot[data-state="stopped"] { background: var(--dsw-alias-state-error-primary, #d13b3b); }
+.dsh-tw-fab-status-dot[data-state="clean"] { background: var(--dsw-alias-state-success-primary, #3eaa5f); }
+.dsh-tw-fab-status-dot[data-state="dirty"] { background: var(--dsw-alias-state-warning-primary, #d9822b); }
+.dsh-tw-fab-status-dot[data-state="behind"] { background: var(--dsw-alias-state-error-primary, #d13b3b); }
+.dsh-tw-fab-status-dot[data-state="syncing"] { background: var(--dsw-alias-brand-primary, #3e63dd); }
+.dsh-tw-fab-item {
+  display: flex; align-items: center; gap: 6px; text-align: left;
+  border: none; background: transparent; color: inherit; font: inherit; font-size: 13px;
+  padding: 7px 9px; border-radius: 8px; cursor: pointer;
+}
+.dsh-tw-fab-item:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.12)); }
+.dsh-tw-fab-item:active { background: var(--dsw-alias-interactive-bg-active, rgba(128,128,128,.18)); }
+
+/* ── quick-note restored-draft banner ─────────────────────────────────────── */
+.dsh-tw-note-draft {
+  display: flex; align-items: center; justify-content: space-between; gap: 8px;
+  padding: 5px 9px; border-radius: 8px; font-size: 12px;
+  background: color-mix(in srgb, var(--dsw-alias-state-warning-primary, #d9822b) 12%, transparent);
+  color: var(--dsw-alias-label-primary, #222);
+}
+.dsh-tw-note-draft[hidden] { display: none; }
+.dsh-tw-note-draft-text { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.dsh-tw-note-draft-discard {
+  border: 1px solid var(--dsw-alias-border-l2, rgba(0,0,0,.18));
+  background: transparent; color: inherit; font: inherit; font-size: 12px;
+  padding: 2px 10px; border-radius: 999px; cursor: pointer; flex: none;
+}
+.dsh-tw-note-draft-discard:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.12)); }
+
+/* ── quick-note recent-notes picker ───────────────────────────────────────── */
+.dsh-tw-note-recent {
+  position: absolute; right: 0; bottom: calc(100% - 8px); z-index: 70;
+  width: 340px; max-width: calc(100vw - 40px); max-height: 280px; overflow-y: auto;
+  display: flex; flex-direction: column; gap: 2px; padding: 6px;
+  border-radius: 12px; border: 1px solid var(--dsw-alias-border-l2, rgba(0,0,0,.15));
+  background: var(--dsw-alias-bg-layer-2, #fff); color: var(--dsw-alias-label-primary, #222);
+  box-shadow: var(--dsw-shadow-lv3, 0 8px 30px rgba(0,0,0,.22));
+  font-size: 13px;
+}
+.dsh-tw-note-recent[hidden] { display: none; }
+.dsh-tw-note-recent-item {
+  display: flex; align-items: baseline; justify-content: space-between; gap: 10px;
+  padding: 6px 8px; border-radius: 7px; cursor: pointer;
+}
+.dsh-tw-note-recent-item:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.12)); }
+.dsh-tw-note-recent-name { font-weight: 500; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.dsh-tw-note-recent-meta { flex: none; font-size: 11px; color: var(--dsw-alias-label-dimmed, #999); }
+.dsh-tw-note-recent-muted { padding: 8px 10px; font-size: 12px; color: var(--dsw-alias-label-dimmed, #999); }
+.dsh-tw-note-recent-btn {
+  border: 1px solid var(--dsw-alias-border-l2, rgba(0,0,0,.18));
+  background: var(--dsw-alias-bg-layer-2, #fff); color: var(--dsw-alias-label-primary, #222);
+  font: inherit; font-size: 12px; padding: 6px 10px; border-radius: 8px; cursor: pointer;
+  transition: filter 120ms ease, transform 80ms ease;
+}
+.dsh-tw-note-recent-btn:hover { filter: brightness(.96); }
+.dsh-tw-note-recent-btn:active { transform: scale(.96); }
 `
 
 export function injectStyles(): void {

package/src/client/sync-button.ts

@@ -1,188 +1,191 @@
-/**
- * Floating "sync" button (bottom-right) — one click pulls + commits + pushes
- * the wiki git repository and reports the result, with a live status dot so
- * the human always sees whether the knowledge base is in sync.
- *
- * - honors `ui.showSyncButton`: the button is mounted async and never created
- *   when the option is off (settings page toggle);
- * - polls /dsh-tiddlywiki/status every 30s for the git state;
- * - clicking POSTs /dsh-tiddlywiki/sync (pull → commit → push) and toasts the
- *   outcome, then refreshes the dot immediately.
- *
- * Status dot mapping (git summary from /status):
- *   offline → gray   (no repo / service unreachable)
- *   dirty   → amber  (uncommitted changes)
- *   behind  → red    (remote has commits we don't — pull will rebase)
- *   clean   → green  (worktree clean)
- *
- * @module dsh-tiddlywiki/client/sync-button
- */
-import { toast } from './toast.ts'
-
-const STATUS_ENDPOINT = '/dsh-tiddlywiki/status'
-const SYNC_ENDPOINT = '/dsh-tiddlywiki/sync'
-const POLL_MS = 30_000
-
-/** Public git summary shape (mirrors GitStatusViewPublic on the host). */
-interface GitView {
-  exists?: boolean
-  branch?: string
-  dirty?: boolean
-  dirtyFiles?: string[]
-  remote?: string
-  lastCommit?: string
-  ahead?: number
-  behind?: number
-}
-
-interface StatusPayload {
-  ok?: boolean
-  status?: string
-  git?: GitView | null
-  ui?: { showSyncButton?: boolean }
-}
-
-/** Inline sync icon (circular arrows, stroke-based, theme-colored). */
-const SYNC_ICON = '<svg viewBox="0 0 16 16" width="15" height="15" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M13 8a5 5 0 1 1-1.4-3.5"/><path d="M13 2.5v3h-3"/></svg>'
-
-function pad(n: number): string {
-  return n < 10 ? `0${n}` : String(n)
-}
-
-/** Compact local time for the tooltip (e.g. "10:32"). */
-function clock(date: Date): string {
-  return `${pad(date.getHours())}:${pad(date.getMinutes())}`
-}
-
-async function fetchStatus(): Promise<StatusPayload | null> {
-  try {
-    const res = await fetch(STATUS_ENDPOINT, { signal: AbortSignal.timeout(8_000) })
-    if (!res.ok) return null
-    return (await res.json()) as StatusPayload
-  } catch {
-    return null
-  }
-}
-
-/**
- * Mount the floating sync button. Fetches /status first: when
- * `ui.showSyncButton` is off the button is never created. Returns a disposer.
- */
-export function mountSyncButton(): () => void {
-  let disposed = false
-  let root: HTMLButtonElement | undefined
-  let dot: HTMLSpanElement | undefined
-  let label: HTMLSpanElement | undefined
-  let lastSync: Date | undefined
-  let timer: number | undefined
-
-  const build = (): HTMLButtonElement => {
-    const btn = document.createElement('button')
-    btn.type = 'button'
-    btn.className = 'dsh-tw-sync'
-    btn.title = '同步知识库（pull → commit → push）'
-
-    const icon = document.createElement('span')
-    icon.className = 'dsh-tw-sync-icon'
-    icon.innerHTML = SYNC_ICON
-
-    dot = document.createElement('span')
-    dot.className = 'dsh-tw-sync-dot'
-    dot.dataset.state = 'offline'
-
-    label = document.createElement('span')
-    label.className = 'dsh-tw-sync-label'
-    label.textContent = '同步'
-
-    btn.append(icon, label, dot)
-    btn.addEventListener('click', () => { void doSync() })
-    document.body.append(btn)
-    return btn
-  }
-
-  /** Map a git summary onto the dot + label + tooltip. */
-  const applyStatus = (payload: StatusPayload | null): void => {
-    if (root === undefined || dot === undefined || label === undefined) return
-    const git = payload?.git
-    const bits: string[] = ['同步知识库']
-    let state = 'offline'
-    let word = '离线'
-
-    if (git === null || git === undefined || git.exists !== true) {
-      bits.push('git 仓库不可用')
-    } else {
-      bits.push(`分支 ${git.branch ?? '?'}`)
-      if (typeof git.lastCommit === 'string') bits.push(git.lastCommit)
-      const behind = typeof git.behind === 'number' ? git.behind : 0
-      const ahead = typeof git.ahead === 'number' ? git.ahead : 0
-      if (ahead > 0) bits.push(`领先 ${ahead}`)
-      if (behind > 0) bits.push(`落后 ${behind}`)
-      if (git.dirty === true) {
-        state = 'dirty'
-        word = '待提交'
-        bits.push(`有 ${git.dirtyFiles?.length ?? 0} 个未提交改动`)
-      } else if (behind > 0) {
-        state = 'behind'
-        word = '可更新'
-      } else {
-        state = 'clean'
-        word = '已同步'
-      }
-    }
-    if (lastSync !== undefined) bits.push(`上次同步 ${clock(lastSync)}`)
-    root.title = bits.join(' · ')
-    dot.dataset.state = state
-    label.textContent = word
-  }
-
-  const doSync = async (): Promise<void> => {
-    if (root === undefined) return
-    root.disabled = true
-    root.classList.add('dsh-tw-sync-spin')
-    if (label !== undefined) label.textContent = '同步中…'
-    if (dot !== undefined) dot.dataset.state = 'syncing'
-    try {
-      const res = await fetch(SYNC_ENDPOINT, { method: 'POST', signal: AbortSignal.timeout(120_000) })
-      const payload = (await res.json().catch(() => null)) as
-        | { ok?: boolean; message?: string; error?: string; status?: GitView; conflictFiles?: string[]; push?: string; changed?: boolean; restarted?: boolean; restartError?: string }
-        | null
-      lastSync = new Date()
-      if (payload === null || payload.ok !== true) {
-        const msg = payload?.error ?? payload?.message ?? `HTTP ${res.status}`
-        toast(`同步失败：${msg}`)
-      } else {
-        let detail = ''
-        if (payload.push && payload.push !== 'nothing to commit') detail = `（${payload.push}）`
-        if (payload.changed === true) {
-          detail += payload.restarted === true ? '，TW 已重启' : '，TW 未自动重启'
-          if (payload.restartError) detail += `（${payload.restartError}）`
-        }
-        toast(`同步完成：${payload.message ?? 'OK'}${detail}`)
-      }
-      applyStatus(await fetchStatus())
-    } catch (err) {
-      toast(`同步失败：${err instanceof Error ? err.message : String(err)}`)
-    } finally {
-      root.disabled = false
-      root.classList.remove('dsh-tw-sync-spin')
-    }
-  }
-
-  const poll = async (): Promise<void> => {
-    applyStatus(await fetchStatus())
-  }
-
-  void (async () => {
-    const payload = await fetchStatus()
-    if (disposed || payload?.ui?.showSyncButton === false) return
-    root = build()
-    applyStatus(payload)
-    timer = window.setInterval(() => { void poll() }, POLL_MS)
-  })()
-
-  return () => {
-    disposed = true
-    if (timer !== undefined) window.clearInterval(timer)
-    root?.remove()
-  }
-}
+/**
+ * Sync controller — the git pull→commit→push logic + live git status, decoupled
+ * from any DOM. In v0.5 the visual (status dot, 同步 entry, syncing spinner)
+ * lives in the "知识库" FAB (knowledge-fab.ts); this module only owns state,
+ * polling and the one-click sync call.
+ *
+ * - polls /dsh-tiddlywiki/status every 30s for the git state;
+ * - `trigger()` POSTs /dsh-tiddlywiki/sync (pull → commit → push), returns the
+ *   fresh state and notifies subscribers.
+ *
+ * Status dot mapping (git summary from /status):
+ *   offline → gray   (no repo / service unreachable)
+ *   dirty   → amber  (uncommitted changes)
+ *   behind  → red    (remote has commits we don't — pull will rebase)
+ *   clean   → green  (worktree clean)
+ *
+ * @module dsh-tiddlywiki/client/sync-controller
+ */
+import { toast } from './toast.ts'
+
+const STATUS_ENDPOINT = '/dsh-tiddlywiki/status'
+const SYNC_ENDPOINT = '/dsh-tiddlywiki/sync'
+const POLL_MS = 30_000
+
+/** Public git summary shape (mirrors GitStatusViewPublic on the host). */
+interface GitView {
+  exists?: boolean
+  branch?: string
+  dirty?: boolean
+  dirtyFiles?: string[]
+  remote?: string
+  lastCommit?: string
+  ahead?: number
+  behind?: number
+}
+
+interface StatusPayload {
+  ok?: boolean
+  status?: string
+  git?: GitView | null
+  ui?: { showSyncButton?: boolean }
+}
+
+export interface SyncStateView {
+  /** Dot color key: offline | dirty | behind | clean | syncing. */
+  state: 'offline' | 'dirty' | 'behind' | 'clean' | 'syncing'
+  /** Short label for the menu entry ("已同步" / "待提交" / "可更新" / "离线"). */
+  label: string
+  /** Full tooltip line (branch / commits / dirty files / last sync). */
+  tooltip: string
+  lastSync?: Date
+}
+
+function pad(n: number): string {
+  return n < 10 ? `0${n}` : String(n)
+}
+
+/** Compact local time for the tooltip (e.g. "10:32"). */
+function clock(date: Date): string {
+  return `${pad(date.getHours())}:${pad(date.getMinutes())}`
+}
+
+async function fetchStatus(): Promise<StatusPayload | null> {
+  try {
+    const res = await fetch(STATUS_ENDPOINT, { signal: AbortSignal.timeout(8_000) })
+    if (!res.ok) return null
+    return (await res.json()) as StatusPayload
+  } catch {
+    return null
+  }
+}
+
+/** Map a git summary onto a SyncStateView. */
+function buildState(payload: StatusPayload | null, lastSync: Date | undefined): SyncStateView {
+  const git = payload?.git
+  const bits: string[] = ['同步知识库']
+  let state: SyncStateView['state'] = 'offline'
+  let label = '离线'
+
+  if (git === null || git === undefined || git.exists !== true) {
+    bits.push('git 仓库不可用')
+  } else {
+    bits.push(`分支 ${git.branch ?? '?'}`)
+    if (typeof git.lastCommit === 'string') bits.push(git.lastCommit)
+    const behind = typeof git.behind === 'number' ? git.behind : 0
+    const ahead = typeof git.ahead === 'number' ? git.ahead : 0
+    if (ahead > 0) bits.push(`领先 ${ahead}`)
+    if (behind > 0) bits.push(`落后 ${behind}`)
+    if (git.dirty === true) {
+      state = 'dirty'
+      label = '待提交'
+      bits.push(`有 ${git.dirtyFiles?.length ?? 0} 个未提交改动`)
+    } else if (behind > 0) {
+      state = 'behind'
+      label = '可更新'
+    } else {
+      state = 'clean'
+      label = '已同步'
+    }
+  }
+  if (lastSync !== undefined) bits.push(`上次同步 ${clock(lastSync)}`)
+  return { state, label, tooltip: bits.join(' · '), ...(lastSync !== undefined ? { lastSync } : {}) }
+}
+
+export interface SyncController {
+  /** Current state snapshot. */
+  getState(): SyncStateView
+  /** One-click pull → commit → push; returns the fresh state. */
+  trigger(): Promise<SyncStateView>
+  /** Notified whenever the state changes (including during syncing). */
+  subscribe(cb: () => void): () => void
+  dispose(): void
+}
+
+/**
+ * Create the sync controller: starts a 30s status poll immediately and exposes
+ * `trigger()` for the FAB's 同步 entry. No DOM is created here.
+ */
+export function createSyncController(): SyncController {
+  let state: SyncStateView = { state: 'offline', label: '离线', tooltip: '同步知识库' }
+  let lastSync: Date | undefined
+  let timer: number | undefined
+  let syncing = false
+  const listeners = new Set<() => void>()
+
+  const emit = (): void => {
+    for (const cb of [...listeners]) cb()
+  }
+
+  const applyStatus = (payload: StatusPayload | null): void => {
+    const next = buildState(payload, lastSync)
+    if (next.state !== state.state || next.tooltip !== state.tooltip) {
+      state = next
+      emit()
+    }
+  }
+
+  const poll = async (): Promise<void> => {
+    applyStatus(await fetchStatus())
+  }
+
+  const doSync = async (): Promise<SyncStateView> => {
+    if (syncing) return state
+    syncing = true
+    state = { ...state, state: 'syncing', label: '同步中…' }
+    emit()
+    try {
+      const res = await fetch(SYNC_ENDPOINT, { method: 'POST', signal: AbortSignal.timeout(120_000) })
+      const payload = (await res.json().catch(() => null)) as
+        | { ok?: boolean; message?: string; error?: string; status?: GitView; conflictFiles?: string[]; push?: string; changed?: boolean; restarted?: boolean; restartError?: string }
+        | null
+      lastSync = new Date()
+      if (payload === null || payload.ok !== true) {
+        const msg = payload?.error ?? payload?.message ?? `HTTP ${res.status}`
+        toast(`同步失败：${msg}`)
+      } else {
+        let detail = ''
+        if (payload.push && payload.push !== 'nothing to commit') detail = `（${payload.push}）`
+        if (payload.changed === true) {
+          detail += payload.restarted === true ? '，TW 已重启' : '，TW 未自动重启'
+          if (payload.restartError) detail += `（${payload.restartError}）`
+        }
+        toast(`同步完成：${payload.message ?? 'OK'}${detail}`)
+      }
+      await poll()
+    } catch (err) {
+      toast(`同步失败：${err instanceof Error ? err.message : String(err)}`)
+    } finally {
+      syncing = false
+      // Re-sync the label (may still be dirty after a failed sync).
+      await poll()
+    }
+    return state
+  }
+
+  void poll()
+  timer = window.setInterval(() => { void poll() }, POLL_MS)
+
+  return {
+    getState: () => state,
+    trigger: doSync,
+    subscribe(cb) {
+      listeners.add(cb)
+      return () => { listeners.delete(cb) }
+    },
+    dispose() {
+      if (timer !== undefined) { clearInterval(timer); timer = undefined }
+      listeners.clear()
+    },
+  }
+}