dsh-intertidal 0.0.0-stage → 0.1.4

package/src/client/i18n.js

@@ -0,0 +1,250 @@
+// 潮间 —— 文案。zh-CN 与 en 各一份，键集合必须完全一致（test/i18n.test.js 会查）。
+
+export const NS = 'intertidal'
+
+export const zh = {
+  'panel.title': '潮间',
+  'panel.caption': '此刻',
+  'panel.remaining': '剩余',
+  'panel.paused': '已暂停',
+  'panel.crashed': '潮间出了点问题，点此关闭',
+  'action.open': '涨一次潮',
+  'action.close': '关闭',
+  'action.pip': '缩成小窗',
+  'action.expand': '展开整屏',
+  'action.pause': '暂停计时',
+  'action.resume': '继续计时',
+  'action.skip': '今天跳过',
+  'action.preview': '看一眼海',
+  'hint.keys': 'Esc 关闭 · C 缩窗 · Space 暂停',
+  'hint.offline': '暂时无法保存设置',
+  'sound.unlock': '点一下才能播放海浪声',
+
+  'settings.title': '潮间',
+  'settings.group.rhythm': '节奏',
+  'settings.group.form': '形态',
+  'settings.group.place': '地点',
+  'settings.group.sound': '声音',
+  'settings.group.access': '无障碍',
+  'settings.auto': '自动浮现',
+  'settings.auto.hint': '到点自己浮起来，到点自己退走',
+  'settings.interval': '间隔',
+  'settings.interval.hint': '两次浮现之间隔多久',
+  'settings.duration': '每次时长',
+  'settings.firstDelay': '首次投放延迟',
+  'settings.firstDelay.hint': '装完先安静一会儿，别一装就糊一脸',
+  'settings.quiet': '静默时段',
+  'settings.quiet.hint': '这段时间内不自动浮现（手动不受限）',
+  'settings.deferTyping': '输入中推迟',
+  'settings.deferTyping.hint': '正在打字时等你停手 20 秒；最多等 10 分钟则跳过本次',
+  'settings.manualExtends': '手动看过后顺延',
+  'settings.manualExtends.hint': '你主动看一眼，下一次定时就往后挪',
+  'settings.form': '浮现形式',
+  'settings.form.full': '整屏',
+  'settings.form.pip': '右下角小窗',
+  'settings.rememberForm': '记住上次形态',
+  'settings.caption': '角落小字',
+  'settings.caption.hint': '「此刻 · 上海 · 17:18」，不显示任何数据源',
+  'settings.city': '城市',
+  'settings.city.custom': '自定义经纬度',
+  'settings.lat': '纬度',
+  'settings.lon': '经度',
+  'settings.tz': '时区',
+  'settings.sound': '海浪声',
+  'settings.volume': '音量',
+  'settings.sound.hint': '程序化合成，不需要任何素材文件',
+  'settings.group.media': '画面素材',
+  'settings.media.mode': '素材来源',
+  'settings.media.off': '程序化海（默认）',
+  'settings.media.dir': '本地目录',
+  'settings.media.url': '网页 / 图片链接',
+  'settings.media.hint': '用真实照片或视频当海的底子；不选就还是程序化海。素材加载失败会自动退回程序化海。',
+  'settings.media.dir.hint': '从目录里随机取一张图片或视频，全程不联网',
+  'settings.media.dir.empty': '还没选目录',
+  'settings.media.pick': '选择目录',
+  'settings.media.scan': '检查目录',
+  'settings.media.scanOk': '目录里有素材',
+  'settings.media.scanEmpty': '目录里没有图片或视频',
+  'settings.media.scanFail': '读不到这个目录',
+  'settings.media.urls': '链接',
+  'settings.media.urls.hint': '一行一条，最多 8 条。直链图片/视频直接用；网页会尝试取 og:image 首图。',
+  'settings.media.fetch': '抓取并缓存',
+  'settings.media.fetchOk': '已缓存，下次浮现就会用',
+  'settings.media.fetchFail': '抓不到，检查链接或网络',
+  'settings.media.grade': '天光着色',
+  'settings.media.grade.hint': '按此刻的太阳给素材压暗/提亮、偏暖/偏冷；0 = 保持原图',
+  'settings.media.motion': '缓慢推拉',
+  'settings.media.motion.hint': 'Ken Burns，让静图不像壁纸；0 = 完全静止',
+  'settings.media.shuffle': '每次浮现换一张',
+  'settings.reducedMotion': '减少动态',
+  'settings.reducedMotion.auto': '跟随系统',
+  'settings.reducedMotion.on': '强制开',
+  'settings.reducedMotion.off': '强制关',
+  'settings.reducedMotion.hint': '开启后画面静止，且自动浮现默认关闭',
+  'settings.next': '下一次浮现',
+  'settings.next.soon': '马上就到',
+  'settings.next.off': '自动已关闭',
+  'settings.stateFile': '状态文件',
+
+  'unit.minutes': '分钟',
+  'unit.seconds': '秒',
+  'phase.dawn': '晨曦',
+  'phase.noon': '正午',
+  'phase.afternoon': '午后',
+  'phase.dusk': '黄昏',
+  'phase.night': '夜',
+}
+
+export const en = {
+  'panel.title': 'Intertidal',
+  'panel.caption': 'now',
+  'panel.remaining': 'remaining',
+  'panel.paused': 'paused',
+  'panel.crashed': 'Intertidal hit a problem — click to close',
+  'action.open': 'Raise the tide',
+  'action.close': 'Close',
+  'action.pip': 'Shrink to corner',
+  'action.expand': 'Expand',
+  'action.pause': 'Pause timer',
+  'action.resume': 'Resume timer',
+  'action.skip': 'Skip today',
+  'action.preview': 'Look at the sea',
+  'hint.keys': 'Esc close · C shrink · Space pause',
+  'hint.offline': 'Settings cannot be saved right now',
+  'sound.unlock': 'Click once to allow surf audio',
+
+  'settings.title': 'Intertidal',
+  'settings.group.rhythm': 'Rhythm',
+  'settings.group.form': 'Form',
+  'settings.group.place': 'Place',
+  'settings.group.sound': 'Sound',
+  'settings.group.access': 'Accessibility',
+  'settings.auto': 'Automatic',
+  'settings.auto.hint': 'It comes up on its own and leaves on its own',
+  'settings.interval': 'Interval',
+  'settings.interval.hint': 'How long between two appearances',
+  'settings.duration': 'Duration',
+  'settings.firstDelay': 'First appearance delay',
+  'settings.firstDelay.hint': 'Stay quiet right after install',
+  'settings.quiet': 'Quiet hours',
+  'settings.quiet.hint': 'No automatic appearance in this window (manual still works)',
+  'settings.deferTyping': 'Defer while typing',
+  'settings.deferTyping.hint': 'Waits 20s after you stop typing; gives up after 10 minutes',
+  'settings.manualExtends': 'Manual viewing pushes the next one',
+  'settings.manualExtends.hint': 'Looking on purpose moves the next timed appearance later',
+  'settings.form': 'Appearance',
+  'settings.form.full': 'Full screen',
+  'settings.form.pip': 'Corner window',
+  'settings.rememberForm': 'Remember last form',
+  'settings.caption': 'Corner caption',
+  'settings.caption.hint': '“Now · Shanghai · 17:18” — no data source involved',
+  'settings.city': 'City',
+  'settings.city.custom': 'Custom coordinates',
+  'settings.lat': 'Latitude',
+  'settings.lon': 'Longitude',
+  'settings.tz': 'Time zone',
+  'settings.sound': 'Surf sound',
+  'settings.volume': 'Volume',
+  'settings.sound.hint': 'Synthesised, no asset files',
+  'settings.group.media': 'Scenery',
+  'settings.media.mode': 'Source',
+  'settings.media.off': 'Procedural sea (default)',
+  'settings.media.dir': 'Local folder',
+  'settings.media.url': 'Web / image links',
+  'settings.media.hint': 'Use real photos or video as the sea bed; leave it off for the procedural sea. Falls back automatically if a file fails to load.',
+  'settings.media.dir.hint': 'Picks a random image or video from the folder. No network at all.',
+  'settings.media.dir.empty': 'No folder chosen',
+  'settings.media.pick': 'Choose folder',
+  'settings.media.scan': 'Check folder',
+  'settings.media.scanOk': 'Files found',
+  'settings.media.scanEmpty': 'No images or videos in that folder',
+  'settings.media.scanFail': 'Cannot read that folder',
+  'settings.media.urls': 'Links',
+  'settings.media.urls.hint': 'One per line, up to 8. Direct image/video URLs are used as-is; pages are scraped for og:image.',
+  'settings.media.fetch': 'Fetch and cache',
+  'settings.media.fetchOk': 'Cached — the next appearance will use it',
+  'settings.media.fetchFail': 'Could not fetch; check the link or network',
+  'settings.media.grade': 'Time-of-day grade',
+  'settings.media.grade.hint': 'Darkens/brightens and warms/cools the photo to match the sun right now; 0 keeps the original',
+  'settings.media.motion': 'Slow push',
+  'settings.media.motion.hint': 'Ken Burns, so a still photo does not look like wallpaper; 0 is perfectly still',
+  'settings.media.shuffle': 'New one every appearance',
+  'settings.reducedMotion': 'Reduced motion',
+  'settings.reducedMotion.auto': 'Follow system',
+  'settings.reducedMotion.on': 'Force on',
+  'settings.reducedMotion.off': 'Force off',
+  'settings.reducedMotion.hint': 'Static frame, and automatic appearance defaults to off',
+  'settings.next': 'Next appearance',
+  'settings.next.soon': 'any moment',
+  'settings.next.off': 'automatic is off',
+  'settings.stateFile': 'State file',
+
+  'unit.minutes': 'min',
+  'unit.seconds': 's',
+  'phase.dawn': 'dawn',
+  'phase.noon': 'noon',
+  'phase.afternoon': 'afternoon',
+  'phase.dusk': 'dusk',
+  'phase.night': 'night',
+}
+
+/** 当前语言：优先 document.documentElement.lang / navigator.language。 */
+export function detectLang(doc = globalThis.document, nav = globalThis.navigator) {
+  const fromDoc = doc?.documentElement?.lang
+  const raw = String(fromDoc || nav?.language || 'zh')
+  return raw.toLowerCase().startsWith('zh') ? 'zh' : 'en'
+}
+
+/** 造一个 t：找不到键就退中文，再退键名本身。 */
+export function makeT(dict, fallback = zh) {
+  return (key) => dict[key] ?? fallback[key] ?? key
+}
+
+/** 'zh-CN' / 'zh' / 'zh-Hant' → 'zh'；其余 → 'en'。 */
+export function normalizeLang(value) {
+  return String(value ?? '').toLowerCase().startsWith('zh') ? 'zh' : 'en'
+}
+
+/**
+ * 造一个**跟随 DSH 当前语言**的 t。
+ *
+ * 为什么不用 `locale.bind(NS)`：`apply` 执行时 `ctx.get('locale')` 可能还没就绪
+ * （cordis 服务是后来才 provide 的，`get` 拿到 undefined 后不会重试），这时 bind 根本不存在，
+ * 只能走兜底语言——那正是"DSH 是中文、插件却是英文"的现场。
+ *
+ * 这里直接读 `locale.getSnapshot().active`（temp-chat 也用它），拿不到才退
+ * documentElement.lang / navigator.language。每次翻译时现算，所以语言切换即时生效。
+ */
+export function createTranslator(locale, doc = globalThis.document, nav = globalThis.navigator) {
+  const active = () => {
+    try {
+      const snapshot = locale?.getSnapshot?.()
+      if (snapshot && snapshot.active) return normalizeLang(snapshot.active)
+    } catch {
+      /* 服务还没起来 / API 变了 */
+    }
+    try {
+      const attr = doc?.documentElement?.getAttribute?.('lang')
+      if (attr) return normalizeLang(attr)
+    } catch {
+      /* ignore */
+    }
+    return normalizeLang(nav?.language ?? 'zh')
+  }
+  const t = (key) => {
+    const dict = active() === 'en' ? en : zh
+    return dict[key] ?? zh[key] ?? key
+  }
+  return {
+    t,
+    getLang: active,
+    /** 语言变化时通知组件重渲染（拿得到 subscribe 才有）。 */
+    subscribe(callback) {
+      try {
+        return locale?.subscribe?.(() => callback(active())) ?? (() => {})
+      } catch {
+        return () => {}
+      }
+    },
+  }
+}

package/src/client/index.jsx

@@ -0,0 +1,163 @@
+// 潮间 —— 浏览器半片入口。
+//
+// 本文件只做"接线"：造 runtime、注入样式、注册四个槽位。任何槽位注册失败都只打告警，
+// 绝不让插件把 DSH 的 web boot 拖垮（spec §11 R5）。
+//
+// 槽位用哪几个、为什么：
+//   shell.overlay            整窗覆盖层（不抢面板、不改变 content 区），是"到点浮现"的唯一载体；
+//   settings.section         设置页（含「看一眼海」「今天跳过」，是主要的手动入口）。
+//
+// v2 起**不再注册** `sidebar.panellist` 与 `main` 面板：用户反馈侧栏那一行"看起来没有作用"
+// （它只是再开一次海，而海本来就会自己来）。手动入口保留在设置页，加上可自配的快捷键。
+
+import Overlay from './overlay.jsx'
+import SettingsPanel from './settings-panel.jsx'
+import { createApi } from './api.js'
+import { createRuntime } from './rhythm.js'
+import { createSurfSound } from './sound.js'
+import { injectStyles } from './styles.js'
+import { NS, createTranslator, en, zh } from './i18n.js'
+
+const logger = {
+  warn: (...args) => console.warn('[dsh-intertidal]', ...args),
+}
+
+const PANEL_ID = 'intertidal'
+
+const plugin = {
+  name: 'dsh-intertidal',
+  // `slots` 与 `locale` 都是 DSH 的常驻服务，一并声明：这样 apply 里拿到的 locale 一定是
+  // 已就绪的那个（早先只 inject slots、用 ctx.get('locale') 现取，曾经拿到 undefined，
+  // 于是插件语言跟着 documentElement.lang 跑 —— 表现就是"DSH 中文、插件英文"）。
+  inject: ['slots', 'locale'],
+  apply(ctx) {
+    const locale = ctx.locale ?? ctx.get?.('locale') ?? null
+    const { t, getLang, subscribe: subscribeLang } = createTranslator(locale)
+
+    if (locale && typeof locale.register === 'function') {
+      ctx.effect(() => {
+        try {
+          return locale.register(NS, { zh, en })
+        } catch (error) {
+          logger.warn('注册文案失败（可能已被注册过）：', error)
+          return () => {}
+        }
+      }, 'dsh-intertidal: dictionaries')
+    }
+
+    ctx.effect(() => {
+      const remove = injectStyles()
+      return () => {
+        remove()
+        for (const node of globalThis.document?.querySelectorAll?.('style[data-plugin-css="dsh-intertidal"]') ?? []) {
+          node.remove()
+        }
+      }
+    }, 'dsh-intertidal: styles')
+
+    // ---- runtime：一次创建，整个插件生命周期共用 -----------------------------
+    const api = createApi({
+      onStatus: (offline) => {
+        if (offline) logger.warn('宿主接口不可用，退镜像设置运行')
+      },
+    })
+    const runtime = createRuntime({ api })
+    ctx.effect(() => {
+      const dropSound = runtime.attachSound(createSurfSound())
+      void runtime.init()
+      return () => {
+        dropSound()
+        runtime.dispose()
+      }
+    }, 'dsh-intertidal: runtime')
+
+    // ---- 槽位 ---------------------------------------------------------------
+    const withRuntime = () => ({
+      runtime,
+      ctx,
+      t,
+      getLang,
+      subscribeLang,
+      // 可选：DSH 的工作区选择器（`uiWorkspace.pickDirectory`），拿不到就让手输路径
+      pickDirectory: () => {
+        try {
+          return ctx.get?.('uiWorkspace')?.pickDirectory?.()
+        } catch {
+          return null
+        }
+      },
+    })
+
+    try {
+      ctx.slots.inject('shell.overlay', () =>
+        ctx.slots.register(
+          {
+            name: 'shell.overlay',
+            id: 'intertidal.sea',
+            order: 500,
+            label: () => t('panel.title'),
+            locale: NS,
+            inject: withRuntime,
+          },
+          Overlay,
+        ),
+      )
+    } catch (error) {
+      logger.warn('注册整窗覆盖层失败：', error)
+    }
+
+
+
+    try {
+      ctx.slots.inject('settings.section', () =>
+        ctx.slots.register(
+          {
+            name: 'settings.section',
+            id: PANEL_ID,
+            order: 88,
+            label: () => t('settings.title'),
+            locale: NS,
+            inject: withRuntime,
+          },
+          SettingsPanel,
+        ),
+      )
+    } catch (error) {
+      logger.warn('注册设置页失败：', error)
+    }
+
+    // ---- 快捷键（可选服务）---------------------------------------------------
+    // 侧栏入口已移除，手动开海除了设置页按钮，还留一个**不带默认绑定**的命令：
+    // 它出现在 设置 → 快捷键 里，用户自己绑定（不给默认值是为了不跟已装插件抢键位）。
+    try {
+      ctx.inject(['shortcuts'], (scope) => {
+        scope.effect(() => {
+          try {
+            const dispose = scope.shortcuts.register({
+              id: 'intertidal.open',
+              label: () => t('action.open'),
+              aliases: ['涨一次潮', 'look at the sea', 'intertidal'],
+              defaults: {},
+              regions: ['page'],
+              modals: [],
+              resolve: () => ({
+                status: 'handled',
+                run: () => void runtime.show('manual'),
+              }),
+            })
+            return () => dispose?.()
+          } catch (error) {
+            logger.warn('注册快捷键命令失败（不影响其他功能）：', error)
+            return () => {}
+          }
+        })
+      })
+    } catch (error) {
+      logger.warn('shortcuts 服务不可用：', error)
+    }
+  },
+}
+
+export const inject = plugin.inject
+export const apply = plugin.apply
+export const name = plugin.name

package/src/client/overlay.jsx

@@ -0,0 +1,260 @@
+// 潮间 —— 覆盖层：形态状态机（full / pip / hidden）的 UI 与键盘处理。
+//
+// 三条硬规则，来自 spec §5：
+//   1. 浮现后**不**因为你打字就自己躲开——只有到点、Esc/关闭、或你按 C 才改变形态；
+//   2. 全窗状态下只接管 Esc / C / Space 三个键，其余一律放行；
+//   3. 整屏与小窗共享同一次浮现的剩余时长，缩窗不重置计时。
+//
+// 这一层不自己计时，也不自己算颜色：计时在 rhythm.js，颜色在 palette.js。这里只做渲染
+// 和交互，出任何错都由 Guarded 兜住，退成一行"潮间出了点问题，点此关闭"，绝不拖垮 DSH。
+
+import { Component, useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import SeaCanvas from './sea-canvas.jsx'
+import { findCity } from '../cities.js'
+import { formatClock, formatRemaining } from './format.js'
+
+/** 覆盖层内部的错误边界：DSH 主流程不能因为一片海而受损。 */
+class Guarded extends Component {
+  constructor(props) {
+    super(props)
+    this.state = { failed: false }
+  }
+
+  static getDerivedStateFromError() {
+    return { failed: true }
+  }
+
+  componentDidCatch(error) {
+    console.warn('[dsh-intertidal] 覆盖层渲染失败：', error)
+  }
+
+  render() {
+    if (!this.state.failed) return this.props.children
+    return (
+      <div className="it-error">
+        <span>{this.props.label}</span>
+        <button type="button" className="it-btn" onClick={() => this.setState({ failed: false })}>
+          {this.props.closeLabel}
+        </button>
+      </div>
+    )
+  }
+}
+
+/** 输入框/可编辑区里按空格是打字，不是暂停。 */
+function isEditableTarget(target) {
+  if (!target || typeof target !== 'object') return false
+  const tag = String(target.tagName ?? '').toLowerCase()
+  if (tag === 'input' || tag === 'textarea' || tag === 'select') return true
+  return target.isContentEditable === true
+}
+
+
+
+function placeName(location, lang) {
+  if (!location) return ''
+  const city = findCity?.(location.city)
+  if (city) return lang === 'en' ? city.en : city.zh
+  return location.city || ''
+}
+
+function useRuntime(runtime) {
+  const [snapshot, setSnapshot] = useState(() => runtime.getState())
+  useEffect(() => runtime.subscribe(setSnapshot), [runtime])
+  return snapshot
+}
+
+/** 小窗拖拽 + 四角吸附。只在 pip 形态下绑定。 */
+function usePipDrag(runtime, form, enabled) {
+  const ref = useRef(null)
+  const [dragging, setDragging] = useState(false)
+  const drag = useRef(null)
+
+  const onPointerDown = useCallback((event) => {
+    if (!enabled || form !== 'pip') return
+    if (event.target?.closest?.('.it-btn')) return
+    const node = ref.current
+    if (!node) return
+    const rect = node.getBoundingClientRect()
+    drag.current = { dx: event.clientX - rect.left, dy: event.clientY - rect.top, w: rect.width, h: rect.height }
+    node.setPointerCapture?.(event.pointerId)
+    setDragging(true)
+  }, [enabled, form])
+
+  const onPointerMove = useCallback((event) => {
+    const info = drag.current
+    const node = ref.current
+    if (!info || !node) return
+    const left = Math.min(Math.max(0, event.clientX - info.dx), window.innerWidth - info.w)
+    const top = Math.min(Math.max(0, event.clientY - info.dy), window.innerHeight - info.h)
+    node.style.left = `${left}px`
+    node.style.top = `${top}px`
+    node.style.right = 'auto'
+    node.style.bottom = 'auto'
+  }, [])
+
+  const onPointerUp = useCallback((event) => {
+    const node = ref.current
+    if (!drag.current || !node) return
+    drag.current = null
+    setDragging(false)
+    node.releasePointerCapture?.(event.pointerId)
+    // 吸附到最近的四角
+    const rect = node.getBoundingClientRect()
+    const gap = 24
+    const centerX = rect.left + rect.width / 2
+    const centerY = rect.top + rect.height / 2
+    const left = centerX < window.innerWidth / 2 ? gap : window.innerWidth - rect.width - gap
+    const top = centerY < window.innerHeight / 2 ? gap : window.innerHeight - rect.height - gap
+    node.style.left = `${Math.max(gap, left)}px`
+    node.style.top = `${Math.max(gap, top)}px`
+    node.style.right = 'auto'
+    node.style.bottom = 'auto'
+  }, [])
+
+  return { ref, dragging, onPointerDown, onPointerMove, onPointerUp }
+}
+
+export default function Overlay({ runtime, t = (k) => k, getLang = () => 'zh', subscribeLang }) {
+  const snapshot = useRuntime(runtime)
+  const lang = typeof getLang === 'function' ? getLang() : 'zh'
+  // 语言切换时重渲染（locale.subscribe 拿不到就只是不跟随，不报错）
+  const [, bumpLang] = useState(0)
+  useEffect(() => {
+    if (typeof subscribeLang !== 'function') return undefined
+    const unsub = subscribeLang(() => bumpLang((value) => value + 1))
+    return () => unsub?.()
+  }, [subscribeLang])
+  const { form, exiting, settings, sky, paused } = snapshot
+  const visible = form !== 'hidden'
+  const drag = usePipDrag(runtime, form, visible)
+
+  // 键盘：只在覆盖层可见时接管 Esc / C / Space，别的一概放行。
+  useEffect(() => {
+    if (!visible) return undefined
+    const onKeyDown = (event) => {
+      if (event.defaultPrevented) return
+      const key = event.key
+      const editable = isEditableTarget(event.target)
+      if (key === 'Escape') {
+        event.preventDefault()
+        runtime.hide('manual')
+        return
+      }
+      if (editable) return
+      if (key === 'c' || key === 'C') {
+        event.preventDefault()
+        runtime.toggleForm()
+      } else if (key === ' ' || key === 'Spacebar') {
+        event.preventDefault()
+        runtime.togglePause()
+      }
+    }
+    window.addEventListener('keydown', onKeyDown, true)
+    return () => window.removeEventListener('keydown', onKeyDown, true)
+  }, [runtime, visible])
+
+  // 从 pip 拖拽回整屏时，必须清掉拖拽写进内联样式的 left/top/right/bottom，
+  // 否则 `inset: 0` 会被内联值盖住，海会停在小窗的位置上。
+  useEffect(() => {
+    const node = drag.ref.current
+    if (!node || form !== 'full' || drag.dragging) return
+    node.style.left = ''
+    node.style.top = ''
+    node.style.right = ''
+    node.style.bottom = ''
+  }, [form, drag.dragging, drag.ref])
+
+  // 覆盖层出现时不要让焦点飘走：不主动 focus，输入框的光标与滚动位置必须原地不动。
+  const caption = useMemo(() => {
+    if (!settings?.caption) return ''
+    const when = formatClock(new Date(), settings?.location?.tz)
+    const where = placeName(settings?.location, lang)
+    const phase = t(`phase.${sky?.phase ?? 'afternoon'}`)
+    return [t('panel.caption'), where, `${when} · ${phase}`].filter(Boolean).join(' · ')
+  }, [settings?.caption, settings?.location?.city, settings?.location?.tz, sky?.phase, lang, t])
+
+  if (!visible) return null
+
+  const exitingAttr = exiting ? (exiting.kind === 'pip' || form === 'pip' ? 'pip' : '1') : '0'
+  const dialogLabel = exiting ? 'closing' : 'open'
+
+  // role 用 region 而不是 dialog：这是氛围层不是模态框，而且 rhythm 里"有对话框就推迟"
+  // 的逻辑会把自己的浮层误判成阻断源。
+  return (
+    <Guarded label={t('panel.crashed')} closeLabel={t('action.close')}>
+      <div
+        ref={drag.ref}
+        className="it-root"
+        data-form={form}
+        data-exit={exitingAttr}
+        data-dragging={drag.dragging ? '1' : '0'}
+        role="region"
+        aria-label={t('panel.title')}
+        data-state={dialogLabel}
+        onPointerDown={drag.onPointerDown}
+        onPointerMove={drag.onPointerMove}
+        onPointerUp={drag.onPointerUp}
+        onPointerCancel={drag.onPointerUp}
+      >
+        <div className="it-canvas-holder">
+          <SeaCanvas
+            now={sky}
+            media={snapshot.media}
+            form={form}
+            paused={paused}
+            reducedMotion={runtime.reducedMotion}
+            onStats={(stats) => runtime.reportStats(stats)}
+          />
+        </div>
+
+        {caption ? <div className="it-caption">{caption}</div> : null}
+        {snapshot.note ? <div className="it-toast">{t(snapshot.note)}</div> : null}
+
+        <div className="it-controls">
+          {/* 倒计时：一直在，不跟着按钮一起淡入淡出 —— 它是"还有多久退干净"的唯一提示 */}
+          <span
+            className="it-countdown"
+            data-paused={paused ? '1' : '0'}
+            title={paused ? t('panel.paused') : t('panel.remaining')}
+            aria-label={paused ? t('panel.paused') : t('panel.remaining')}
+          >
+            {formatRemaining(snapshot.remainingMs)}
+          </span>
+          <span className="it-btnbar">
+          <button
+            type="button"
+            className="it-btn"
+            data-icon="1"
+            title={paused ? t('action.resume') : t('action.pause')}
+            aria-label={paused ? t('action.resume') : t('action.pause')}
+            onClick={() => runtime.togglePause()}
+          >
+            {paused ? '▶' : '❚❚'}
+          </button>
+          <button
+            type="button"
+            className="it-btn"
+            data-icon="1"
+            title={form === 'full' ? t('action.pip') : t('action.expand')}
+            aria-label={form === 'full' ? t('action.pip') : t('action.expand')}
+            onClick={() => runtime.toggleForm()}
+          >
+            {form === 'full' ? '⤡' : '⤢'}
+          </button>
+          <button
+            type="button"
+            className="it-btn"
+            data-icon="1"
+            title={t('action.close')}
+            aria-label={t('action.close')}
+            onClick={() => runtime.hide('manual')}
+          >
+            ✕
+          </button>
+          </span>
+        </div>
+      </div>
+    </Guarded>
+  )
+}