dsh-tiddlywiki 0.7.3 → 0.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-tiddlywiki",
   "description": "TiddlyWiki 5 as the DSH persistent knowledge base: tiddlywiki_* agent tools (search with filters/recent/tags/batch/rename + git sync & conflict resolve), a full TiddlyWiki editor embedded in the GUI center column (same-origin proxy, works over Tailscale/LAN/domain), a quick-note card with draft auto-save & recent-notes picker behind a single knowledge FAB, and git-based sync with auto-commit. Mounts via the official dsh plugin system — no DSH source changes.",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "type": "module",
   "keywords": [
     "dsh",

package/src/client/editor-popup.ts

@@ -1,121 +1,127 @@
-/**
- * Floating popup iframe that loads TiddlyWiki's NATIVE editor for a draft
- * (quick-note "✏️ 在 TW 中编辑"). A small draggable + resizable overlay with its
- * own iframe pointed at `twUrl#<draftTitle>`: the fragment-only navigation
- * triggers TW's hashchange, which opens the draft in the story, and because the
- * draft tiddler carries `draft.of` the story renders the native EditTemplate.
- *
- * Independent of the center panel — a separate floating window so the user can
- * edit a note without leaving the chat context.
- *
- * @module dsh-tiddlywiki/client/editor-popup
- */
-
-let root: HTMLDivElement | undefined
-let frame: HTMLIFrameElement | undefined
-let titleEl: HTMLSpanElement | undefined
-
-/** Open (create on first use) the popup and load `url` (twUrl#draftTitle). */
-export function openEditorPopup(url: string, label: string): void {
-  ensurePopup()
-  if (root === undefined || frame === undefined) return
-  if (titleEl !== undefined) titleEl.textContent = `TiddlyWiki 编辑器 · ${label}`
-  root.style.display = ''
-  // Same-base fragment navigation reloads nothing; a changed base (restart on a
-  // new port) reloads the app and TW still opens the draft from the hash.
-  frame.src = url
-}
-
-/** Remove the popup DOM entirely (plugin dispose). */
-export function disposeEditorPopup(): void {
-  root?.remove()
-  root = undefined
-  frame = undefined
-  titleEl = undefined
-}
-
-function ensurePopup(): void {
-  if (root !== undefined && frame !== undefined) return
-
-  root = document.createElement('div')
-  root.className = 'dsh-tw-editor-popup'
-  root.style.display = 'none'
-
-  const bar = document.createElement('div')
-  bar.className = 'dsh-tw-editor-bar'
-  titleEl = document.createElement('span')
-  titleEl.className = 'dsh-tw-editor-title'
-  titleEl.textContent = 'TiddlyWiki 编辑器'
-  const close = document.createElement('button')
-  close.type = 'button'
-  close.className = 'dsh-tw-editor-close'
-  close.textContent = '✕'
-  close.title = '关闭'
-  bar.append(titleEl, close)
-
-  frame = document.createElement('iframe')
-  frame.className = 'dsh-tw-editor-frame'
-  frame.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-forms allow-popups')
-  frame.title = 'TiddlyWiki 编辑器'
-
-  const resize = document.createElement('div')
-  resize.className = 'dsh-tw-editor-resize'
-  resize.title = '拖拽调整大小'
-
-  root.append(bar, frame, resize)
-  document.body.append(root)
-
-  close.addEventListener('click', () => {
-    if (root !== undefined) root.style.display = 'none'
-  })
-
-  // Drag by the title bar (un-center by setting explicit left/top + margin 0).
-  bar.addEventListener('mousedown', (event) => {
-    if (event.button !== 0 || root === undefined) return
-    event.preventDefault()
-    const rect = root.getBoundingClientRect()
-    const startX = event.clientX
-    const startY = event.clientY
-    const baseLeft = rect.left
-    const baseTop = rect.top
-    const onMove = (ev: MouseEvent): void => {
-      if (root === undefined) return
-      root.style.left = `${baseLeft + ev.clientX - startX}px`
-      root.style.top = `${baseTop + ev.clientY - startY}px`
-      root.style.margin = '0'
-      root.style.right = 'auto'
-      root.style.bottom = 'auto'
-    }
-    const onUp = (): void => {
-      window.removeEventListener('mousemove', onMove)
-      window.removeEventListener('mouseup', onUp)
-    }
-    window.addEventListener('mousemove', onMove)
-    window.addEventListener('mouseup', onUp)
-  })
-
-  // Resize from the bottom-right corner.
-  resize.addEventListener('mousedown', (event) => {
-    if (event.button !== 0 || root === undefined) return
-    event.preventDefault()
-    event.stopPropagation()
-    const rect = root.getBoundingClientRect()
-    const startX = event.clientX
-    const startY = event.clientY
-    const baseW = rect.width
-    const baseH = rect.height
-    const onMove = (ev: MouseEvent): void => {
-      if (root === undefined) return
-      root.style.width = `${Math.max(360, baseW + ev.clientX - startX)}px`
-      root.style.height = `${Math.max(260, baseH + ev.clientY - startY)}px`
-      root.style.right = 'auto'
-      root.style.bottom = 'auto'
-    }
-    const onUp = (): void => {
-      window.removeEventListener('mousemove', onMove)
-      window.removeEventListener('mouseup', onUp)
-    }
-    window.addEventListener('mousemove', onMove)
-    window.addEventListener('mouseup', onUp)
-  })
-}
+/**
+ * Floating popup iframe that loads TiddlyWiki's NATIVE editor for a draft
+ * (quick-note "✏️ 在 TW 中编辑"). A small draggable + resizable overlay with its
+ * own iframe pointed at `twUrl#<draftTitle>`: the fragment-only navigation
+ * triggers TW's hashchange, which opens the draft in the story, and because the
+ * draft tiddler carries `draft.of` the story renders the native EditTemplate.
+ *
+ * Independent of the center panel — a separate floating window so the user can
+ * edit a note without leaving the chat context.
+ *
+ * @module dsh-tiddlywiki/client/editor-popup
+ */
+import { attachThemeSync } from './theme-sync.ts'
+
+let root: HTMLDivElement | undefined
+let frame: HTMLIFrameElement | undefined
+let titleEl: HTMLSpanElement | undefined
+let themeSyncDispose: (() => void) | undefined
+
+/** Open (create on first use) the popup and load `url` (twUrl#draftTitle). */
+export function openEditorPopup(url: string, label: string): void {
+  ensurePopup()
+  if (root === undefined || frame === undefined) return
+  if (titleEl !== undefined) titleEl.textContent = `TiddlyWiki 编辑器 · ${label}`
+  root.style.display = ''
+  // Same-base fragment navigation reloads nothing; a changed base (restart on a
+  // new port) reloads the app and TW still opens the draft from the hash.
+  frame.src = url
+}
+
+/** Remove the popup DOM entirely (plugin dispose). */
+export function disposeEditorPopup(): void {
+  themeSyncDispose?.()
+  themeSyncDispose = undefined
+  root?.remove()
+  root = undefined
+  frame = undefined
+  titleEl = undefined
+}
+
+function ensurePopup(): void {
+  if (root !== undefined && frame !== undefined) return
+
+  root = document.createElement('div')
+  root.className = 'dsh-tw-editor-popup'
+  root.style.display = 'none'
+
+  const bar = document.createElement('div')
+  bar.className = 'dsh-tw-editor-bar'
+  titleEl = document.createElement('span')
+  titleEl.className = 'dsh-tw-editor-title'
+  titleEl.textContent = 'TiddlyWiki 编辑器'
+  const close = document.createElement('button')
+  close.type = 'button'
+  close.className = 'dsh-tw-editor-close'
+  close.textContent = '✕'
+  close.title = '关闭'
+  bar.append(titleEl, close)
+
+  frame = document.createElement('iframe')
+  frame.className = 'dsh-tw-editor-frame'
+  frame.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-forms allow-popups')
+  frame.title = 'TiddlyWiki 编辑器'
+  // Same-origin sandbox keeps $tw reachable; let the popup follow DSH theme.
+  themeSyncDispose = attachThemeSync(frame)
+
+  const resize = document.createElement('div')
+  resize.className = 'dsh-tw-editor-resize'
+  resize.title = '拖拽调整大小'
+
+  root.append(bar, frame, resize)
+  document.body.append(root)
+
+  close.addEventListener('click', () => {
+    if (root !== undefined) root.style.display = 'none'
+  })
+
+  // Drag by the title bar (un-center by setting explicit left/top + margin 0).
+  bar.addEventListener('mousedown', (event) => {
+    if (event.button !== 0 || root === undefined) return
+    event.preventDefault()
+    const rect = root.getBoundingClientRect()
+    const startX = event.clientX
+    const startY = event.clientY
+    const baseLeft = rect.left
+    const baseTop = rect.top
+    const onMove = (ev: MouseEvent): void => {
+      if (root === undefined) return
+      root.style.left = `${baseLeft + ev.clientX - startX}px`
+      root.style.top = `${baseTop + ev.clientY - startY}px`
+      root.style.margin = '0'
+      root.style.right = 'auto'
+      root.style.bottom = 'auto'
+    }
+    const onUp = (): void => {
+      window.removeEventListener('mousemove', onMove)
+      window.removeEventListener('mouseup', onUp)
+    }
+    window.addEventListener('mousemove', onMove)
+    window.addEventListener('mouseup', onUp)
+  })
+
+  // Resize from the bottom-right corner.
+  resize.addEventListener('mousedown', (event) => {
+    if (event.button !== 0 || root === undefined) return
+    event.preventDefault()
+    event.stopPropagation()
+    const rect = root.getBoundingClientRect()
+    const startX = event.clientX
+    const startY = event.clientY
+    const baseW = rect.width
+    const baseH = rect.height
+    const onMove = (ev: MouseEvent): void => {
+      if (root === undefined) return
+      root.style.width = `${Math.max(360, baseW + ev.clientX - startX)}px`
+      root.style.height = `${Math.max(260, baseH + ev.clientY - startY)}px`
+      root.style.right = 'auto'
+      root.style.bottom = 'auto'
+    }
+    const onUp = (): void => {
+      window.removeEventListener('mousemove', onMove)
+      window.removeEventListener('mouseup', onUp)
+    }
+    window.addEventListener('mousemove', onMove)
+    window.addEventListener('mouseup', onUp)
+  })
+}

package/src/client/panel.ts

@@ -22,6 +22,7 @@
  */
 import type { PanelState } from './state.ts'
 import { ENTRY_SELECTOR } from './sidebar-entry.ts'
+import { attachThemeSync, setThemeSyncConfig } from './theme-sync.ts'
 
 export const PANEL_VIEW_SELECTOR = '[data-dsh-tw-view]'
 
@@ -84,7 +85,7 @@ interface StatusPayload {
   wikiPath?: string
   error?: string
   note?: { tag?: string }
-  ui?: { showPanelStatus?: boolean }
+  ui?: { showPanelStatus?: boolean; followDshTheme?: boolean; darkPalette?: string }
 }
 
 function conversationColumn(): HTMLElement | undefined {
@@ -122,6 +123,7 @@ export function mountPanel(state: PanelState): () => void {
   let errorArea: HTMLDivElement | undefined
   let refreshTimer: number | undefined
   let refreshAttempts = 0
+  let themeSyncDispose: (() => void) | undefined
 
   const build = (): HTMLDivElement => {
     const view = document.createElement('div')
@@ -136,6 +138,9 @@ export function mountPanel(state: PanelState): () => void {
     iframe.title = 'TiddlyWiki'
     iframe.hidden = true
     frameArea.append(iframe)
+    // Embedded TW follows the DSH light/dark theme (non-persisting palette
+    // swap inside the same-origin iframe; re-applied on load + theme change).
+    themeSyncDispose = attachThemeSync(iframe)
 
     errorArea = document.createElement('div')
     errorArea.className = 'dsh-tw-panel-error'
@@ -239,6 +244,11 @@ export function mountPanel(state: PanelState): () => void {
     }
     if (payload.status === 'running') {
       refreshAttempts = 0
+      // Keep the embedded TW's theme adaption in step with the settings page.
+      setThemeSyncConfig({
+        enabled: payload.ui?.followDshTheme !== false,
+        darkPalette: payload.ui?.darkPalette,
+      })
       // Same-origin proxy URL: build from the page's own origin so it works no
       // matter which host/domain the user reached DSH on. Fall back to the
       // legacy loopback `url` for older servers that do not send twProxy.
@@ -330,6 +340,7 @@ export function mountPanel(state: PanelState): () => void {
     document.removeEventListener('dsh-tw-panel-reload', onReloadRequest)
     waitObserver.disconnect()
     unsubscribe()
+    themeSyncDispose?.()
     document.documentElement.removeAttribute(ACTIVE_ATTR)
     container?.remove()
   }

package/src/client/settings-page.ts

@@ -213,6 +213,8 @@ function renderConfigSection(body: HTMLElement, config: Record<string, unknown>,
   checkField('ui.showQuickNote', '显示「知识库」按钮里的「快速笔记」入口', ui.showQuickNote !== false)
   checkField('ui.showPanelStatus', '显示「知识库」按钮里的 TW 面板/重载入口与状态行', ui.showPanelStatus !== false)
   checkField('ui.showSyncButton', '显示「知识库」按钮里的「同步」入口与 git 状态点', ui.showSyncButton !== false)
+  checkField('ui.followDshTheme', '嵌入式 TW 跟随 DSH 深浅主题（暗色时自动切深色 palette，不写回 wiki）', ui.followDshTheme !== false)
+  textField('ui.darkPalette', '暗色时 TW palette（tiddler 标题）', typeof ui.darkPalette === 'string' && ui.darkPalette.length > 0 ? ui.darkPalette : '$:/palettes/CupertinoDark')
   // 界面语言在下方「语言管理」区块设置（config 的 uiLanguage 仅供启动时自动应用）。
 
   const save = make('button', 'dsh-tw-settings-btn dsh-tw-settings-primary', '保存配置')

package/src/client/styles.ts

@@ -77,7 +77,9 @@ html[data-dsh-tw-active] .dshDesktopConversationSurface > :not([data-dsh-tw-view
 .dsh-tw-status-dot[data-state="starting"] { background: var(--dsw-alias-state-warning-primary, #d9822b); }
 .dsh-tw-status-dot[data-state="failed"], .dsh-tw-status-dot[data-state="stopped"] { background: var(--dsw-alias-state-error-primary, #d13b3b); }
 
-.dsh-tw-panel-frame { flex: 1; min-height: 0; border: 0; width: 100%; display: block; background: #fff; }
+/* The iframe background follows the DSH theme so a blank/preload frame never
+   flashes pure white in dark mode (TW paints its own palette once loaded). */
+.dsh-tw-panel-frame { flex: 1; min-height: 0; border: 0; width: 100%; display: block; background: var(--dsw-alias-bg-layer-1, #fff); }
 /* [hidden] must beat the author display rules above (UA hidden is overridden). */
 .dsh-tw-panel-frame[hidden],
 .dsh-tw-panel-error[hidden] { display: none !important; }
@@ -257,7 +259,7 @@ html[data-dsh-tw-active] .dshDesktopConversationSurface > :not([data-dsh-tw-view
   color: var(--dsw-alias-label-dimmed, #888); padding: 5px 8px; border-radius: 6px;
 }
 .dsh-tw-editor-close:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.12)); color: var(--dsw-alias-label-primary, #222); }
-.dsh-tw-editor-frame { flex: 1; min-height: 0; width: 100%; border: 0; background: #fff; }
+.dsh-tw-editor-frame { flex: 1; min-height: 0; width: 100%; border: 0; background: var(--dsw-alias-bg-layer-1, #fff); }
 .dsh-tw-editor-resize { position: absolute; right: 0; bottom: 0; width: 16px; height: 16px; cursor: nwse-resize; }
 .dsh-tw-note-toggle {
   border: 1px solid var(--dsw-alias-border-l2, rgba(0,0,0,.18));

package/src/client/theme-sync.ts

@@ -0,0 +1,312 @@
+/**
+ * Adaptive DSH theme for the embedded TiddlyWiki iframes (design doc §12).
+ *
+ * Both the center-column panel and the quick-note editor popup embed the
+ * SAME-ORIGIN TW proxy, so this module can reach the TW runtime directly
+ * (`iframe.contentWindow.$tw`) and drive its native theming.
+ *
+ * How TW theming works
+ * --------------------
+ * TW 5 renders its colours through the ACTIVE palette: `$:/palette` holds the
+ * title of a palette tiddler (`$:/palettes/…`), and every `<<colour x>>` in
+ * the theme stylesheet resolves against that tiddler at render time. TW
+ * re-renders all stylesheets live on any tiddler change, so flipping
+ * `$:/palette` re-themes the whole embedded UI instantly — the exact mechanism
+ * TW's own palette switcher uses. Overriding the rendered CSS variables is a
+ * dead end for the default Vanilla theme because its base stylesheet bakes the
+ * palette values in as literals; switching the palette is the supported path.
+ *
+ * DSH theme detection
+ * -------------------
+ * The DSH shell's ThemePresenter projects the resolved theme onto the page:
+ * `data-ds-dark-theme` on <body> (dark) plus an inline `color-scheme` on
+ * <html> that is always "light"|"dark" (the "system" preference is resolved
+ * upstream). Those two signals are authoritative; `prefers-color-scheme` is
+ * only a fallback when neither is present (no DSH theming projected).
+ *
+ * Non-persistence
+ * ---------------
+ * `$:/palette` IS included in TW's default sync filter, so a naive write would
+ * be PUT back to the TiddlyWeb server and land in the wiki's git history on
+ * every theme toggle. We suppress that: the syncer's dirty check is
+ * `getChangeCount(title) > tiddlerInfo[title].changeCount`, and the change
+ * event that would drive the save is dispatched on a microtask — so after
+ * writing we synchronously re-align the recorded changeCount and the syncer
+ * sees the tiddler as already clean. The flip stays in-memory only; the wiki's
+ * stored palette and the user's choice are never modified.
+ *
+ * @module dsh-tiddlywiki/client/theme-sync
+ */
+
+/** Default dark palette used when DSH is dark (overridable in settings). */
+export const DARK_PALETTE_DEFAULT = '$:/palettes/CupertinoDark'
+/** Fallback light palette when no user palette was ever captured. */
+export const LIGHT_PALETTE_FALLBACK = '$:/palettes/Vanilla'
+
+/** DSH's dark-mode marker (set/removed on <body> by dsh-client-ui-layout). */
+const DARK_ATTR = 'data-ds-dark-theme'
+/** The TW tiddler holding the active palette tiddler title. */
+const PALETTE_TIDDLER = '$:/palette'
+
+/** Minimal structural face over TW's runtime globals inside the iframe. */
+interface TwRuntime {
+  $tw?: {
+    wiki: {
+      getTiddlerText(title: string): string | undefined
+      getTiddler(title: string): { fields?: Record<string, unknown> } | undefined
+      /** TW 5.4.1 has no setTiddlerText; setText(title,'text',…) routes through
+       *  addTiddler and bumps changeCount + dispatches the change event. */
+      setText(title: string, field: string | undefined, index: string | undefined, value: string | undefined): void
+      getChangeCount(title: string): number
+    }
+    syncer?: {
+      tiddlerInfo?: Record<string, { changeCount?: number; revision?: unknown; timestampLastSaved?: Date }>
+      syncadaptor?: {
+        saveTiddler: (tiddler: { fields?: Record<string, unknown> }, callback: (err: unknown, adaptorInfo: unknown, revision: number) => void) => void
+      }
+    }
+  }
+}
+
+/** Appliers registered for live frames; config changes re-apply to all. */
+const frameAppliers = new Set<() => void>()
+/** Syncers already wrapped with the palette save guard (per iframe window). */
+const guardedSyncers = new WeakSet<object>()
+/** Remembered user palette (light) that we restore when leaving dark mode. */
+let userLightPalette = ''
+/** Whether the adaptive feature is on (settings `ui.followDshTheme`). */
+let syncEnabled = true
+/** Configured dark palette (settings `ui.darkPalette`). */
+let darkPalette = DARK_PALETTE_DEFAULT
+
+/**
+ * Resolve the DSH shell's current effective dark state. The body attribute
+ * and the inline root `color-scheme` projected by the ThemePresenter are
+ * authoritative; the OS media query only answers when DSH isn't projecting a
+ * theme snapshot (plain embed / non-DSH page).
+ */
+function readDshDark(): boolean {
+  try {
+    const root = document.documentElement
+    const body = document.body
+    if (body !== null && body.hasAttribute(DARK_ATTR)) return true
+    if (root !== null) {
+      const scheme = root.style.getPropertyValue('color-scheme').trim().toLowerCase()
+      if (scheme === 'dark') return true
+      if (scheme === 'light') return false
+    }
+  } catch {
+    // DOM not ready or not present (e.g. smoke harness) → fall through.
+  }
+  try {
+    return window.matchMedia('(prefers-color-scheme: dark)').matches
+  } catch {
+    return false
+  }
+}
+
+/** Active palette tiddler title (falls back to the light default). */
+function activePaletteTitle($tw: NonNullable<TwRuntime['$tw']>): string {
+  try {
+    const title = $tw.wiki.getTiddlerText(PALETTE_TIDDLER)
+    return typeof title === 'string' && title.trim().length > 0 ? title.trim() : LIGHT_PALETTE_FALLBACK
+  } catch {
+    return LIGHT_PALETTE_FALLBACK
+  }
+}
+
+/** True when the active palette tiddler declares `color-scheme: dark`. */
+function activePaletteIsDark($tw: NonNullable<TwRuntime['$tw']>): boolean {
+  try {
+    const fields = $tw.wiki.getTiddler(activePaletteTitle($tw))?.fields
+    return fields !== undefined && fields['color-scheme'] === 'dark'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Mark `$:/palette` as clean in the syncer's records so a FORCED flip is never
+ * PUT back to the TiddlyWeb server. Runs synchronously right after the write,
+ * before the microtask-dispatched change event lets the syncer evaluate
+ * dirtiness; user-initiated palette changes (bumped afterwards) still sync.
+ */
+function suppressPaletteSync($tw: NonNullable<TwRuntime['$tw']>): void {
+  try {
+    const syncer = $tw.syncer
+    if (syncer?.tiddlerInfo === undefined) return
+    const changeCount = $tw.wiki.getChangeCount(PALETTE_TIDDLER)
+    const info = syncer.tiddlerInfo[PALETTE_TIDDLER]
+    if (info !== undefined) info.changeCount = changeCount
+    else syncer.tiddlerInfo[PALETTE_TIDDLER] = { changeCount }
+  } catch {
+    // Best-effort; the rare worst case is a single persisted flip.
+  }
+}
+
+/**
+ * Install a one-shot guard on this frame's syncadaptor: while a palette WE
+ * forced is active (`userLightPalette` captured), a PUT of `$:/palette` whose
+ * text is still our forced dark palette is swallowed instead of reaching the
+ * TiddlyWeb server. This makes the non-persistence guarantee deterministic —
+ * TW's boot-time sync (which may load `$:/palette` from the server and bump its
+ * changeCount AFTER our re-align) can otherwise queue a save of the forced
+ * palette during the first ~1s. Idempotent per syncer instance.
+ */
+function installPaletteSaveGuard($tw: NonNullable<TwRuntime['$tw']>): void {
+  try {
+    const syncer = $tw.syncer
+    const adaptor = syncer?.syncadaptor
+    if (syncer === undefined || adaptor === undefined || guardedSyncers.has(syncer)) return
+    const origSave = adaptor.saveTiddler.bind(adaptor)
+    adaptor.saveTiddler = (tiddler, callback): void => {
+      const suppressed =
+        syncEnabled &&
+        userLightPalette.length > 0 &&
+        tiddler?.fields?.title === PALETTE_TIDDLER &&
+        tiddler?.fields?.text === darkPalette
+      if (suppressed) {
+        // Fake a successful save (revision 0 = unchanged on the server); the
+        // SaveTiddlerTask re-records tiddlerInfo with the current changeCount,
+        // so the syncer's accounting stays consistent and no task is re-created.
+        callback(null, {}, 0)
+        return
+      }
+      origSave(tiddler, callback)
+    }
+    guardedSyncers.add(syncer)
+  } catch {
+    // Guard is best-effort; the changeCount re-align below still covers steady state.
+  }
+}
+
+/** Write the active palette (no-op when unchanged) without persisting. */
+function setPalette($tw: NonNullable<TwRuntime['$tw']>, target: string): void {
+  try {
+    if (activePaletteTitle($tw) === target) return
+    $tw.wiki.setText(PALETTE_TIDDLER, 'text', undefined, target)
+    suppressPaletteSync($tw)
+  } catch {
+    // TW may be mid-render; the next apply pass will retry.
+  }
+}
+
+/**
+ * Drive `$:/palette` toward the DSH theme. In dark mode a light palette is
+ * swapped for `darkPalette` (remembering the user's palette first); in light
+ * mode a palette WE forced is restored, while a user-chosen dark palette is
+ * left alone.
+ */
+function applyPalette($tw: NonNullable<TwRuntime['$tw']>, dark: boolean): void {
+  const current = activePaletteTitle($tw)
+  if (dark) {
+    if (activePaletteIsDark($tw)) return // user already on a dark palette
+    if (current !== darkPalette) userLightPalette = current // remember their light choice
+    setPalette($tw, darkPalette)
+  } else if (activePaletteIsDark($tw) && current === darkPalette && userLightPalette.length > 0) {
+    // We forced this dark palette (and captured the user's light choice before
+    // doing so) → restore it. A user who picked the dark palette themselves is
+    // never captured, so their choice is left alone.
+    setPalette($tw, userLightPalette)
+  }
+}
+
+/** Keep the iframe's native `color-scheme` in step with the ACTIVE palette. */
+function syncColorScheme($tw: NonNullable<TwRuntime['$tw']>, frame: HTMLIFrameElement): void {
+  try {
+    const html = frame.contentDocument?.documentElement
+    if (html === undefined || html === null) return
+    const paletteIsDark = activePaletteIsDark($tw)
+    const target = paletteIsDark ? 'dark' : 'light'
+    if (html.style.getPropertyValue('color-scheme') !== target) html.style.setProperty('color-scheme', target)
+  } catch {
+    // Cross-frame / not-yet-loaded edge cases are retried on the next pass.
+  }
+}
+
+/** Apply the current DSH theme to one TW iframe (no-op until TW is ready). */
+function applyToFrame(frame: HTMLIFrameElement): void {
+  const $tw = (frame.contentWindow as TwRuntime | null)?.$tw
+  if ($tw === undefined || $tw.wiki === undefined) return
+  installPaletteSaveGuard($tw)
+  if (syncEnabled) {
+    applyPalette($tw, readDshDark())
+  } else {
+    // Feature off → undo any palette we forced (leave the user's own choice).
+    applyPalette($tw, false)
+  }
+  syncColorScheme($tw, frame)
+}
+
+/**
+ * Configure the feature and re-apply to every live frame. `enabled` is the
+ * settings `ui.followDshTheme`; `darkPalette` the settings `ui.darkPalette`.
+ */
+export function setThemeSyncConfig(opts: { enabled?: boolean; darkPalette?: string }): void {
+  const enabled = opts.enabled !== false
+  const palette =
+    typeof opts.darkPalette === 'string' && opts.darkPalette.trim().length > 0 ? opts.darkPalette.trim() : DARK_PALETTE_DEFAULT
+  const changed = enabled !== syncEnabled || palette !== darkPalette
+  syncEnabled = enabled
+  darkPalette = palette
+  if (changed) for (const apply of [...frameAppliers]) apply()
+}
+
+/**
+ * Make one TW iframe follow the DSH theme for as long as the returned
+ * disposer is not called. Re-applies on the iframe's `load` (covers TW
+ * restarts and proxy reloads), on DSH theme changes (body-attribute mutations
+ * and `prefers-color-scheme`), and once immediately for already-loaded frames.
+ */
+export function attachThemeSync(frame: HTMLIFrameElement | null): () => void {
+  if (frame === null) return () => {}
+  const apply = (): void => applyToFrame(frame)
+  frameAppliers.add(apply)
+
+  const onLoad = (): void => apply()
+  frame.addEventListener('load', onLoad)
+
+  const media = window.matchMedia('(prefers-color-scheme: dark)')
+  const onMedia = (): void => apply()
+  try {
+    media.addEventListener('change', onMedia)
+  } catch {
+    media.addListener?.(onMedia)
+  }
+
+  let observer: MutationObserver | undefined
+  try {
+    observer = new MutationObserver(() => apply())
+    if (document.body !== null) observer.observe(document.body, { attributes: true, attributeFilter: [DARK_ATTR] })
+    if (document.documentElement !== null) {
+      observer.observe(document.documentElement, { attributes: true, attributeFilter: ['style'] })
+    }
+  } catch {
+    observer = undefined
+  }
+
+  // TW's boot-time sync can load `$:/palette` from the server shortly after
+  // load (reverting our in-memory flip and bumping its changeCount), so also
+  // re-apply on a few short lags. Each pass is idempotent: it re-flips in
+  // memory if a boot load reverted us, and re-aligns the syncer's changeCount.
+  const timers = [150, 600, 1500, 3000].map((ms) => window.setTimeout(apply, ms))
+
+  // The frame may already be loaded when this is attached late.
+  apply()
+
+  return () => {
+    frameAppliers.delete(apply)
+    frame.removeEventListener('load', onLoad)
+    for (const id of timers) window.clearTimeout(id)
+    try {
+      media.removeEventListener('change', onMedia)
+    } catch {
+      media.removeListener?.(onMedia)
+    }
+    try {
+      observer?.disconnect()
+    } catch {
+      // Already disconnected.
+    }
+  }
+}