dsh-intertidal 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "dsh-intertidal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "潮间（Intertidal）：让 DSH 按设定间隔把屏幕交给一片此刻的海，到点自己退走。天光跟随本地太阳位置，可用自己的图片或视频作海面。不采集数据。",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/host.js",
+  "exports": {
+    ".": "./src/host.js",
+    "./client": "./dist/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "dist",
+    "cordis.patch.yml",
+    "screenshots.json",
+    "assets",
+    "README.md",
+    "README.en.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=20",
+    "dsh": ">=0.2.1-rc.5 <0.3.0"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "dsh-market",
+    "intertidal",
+    "sea",
+    "ambience",
+    "screensaver",
+    "canvas"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "build:check": "node scripts/build.mjs --check",
+    "test": "node --test test/*.test.js",
+    "verify": "node scripts/build.mjs && node --test test/*.test.js",
+    "prepack": "node scripts/build.mjs"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.10"
+  },
+  "author": "winditer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/winditer/dsh-intertidal.git"
+  },
+  "homepage": "https://github.com/winditer/dsh-intertidal#readme",
+  "bugs": {
+    "type": "url",
+    "url": "https://github.com/winditer/dsh-intertidal/issues"
+  }
+}

package/screenshots.json

@@ -0,0 +1,6 @@
+[
+  "assets/screenshots/media-modes.png",
+  "assets/screenshots/procedural-overview.png",
+  "assets/screenshots/overlay-countdown.png",
+  "assets/screenshots/settings-narrow.png"
+]

package/src/cities.js

@@ -0,0 +1,165 @@
+/**
+ * 潮间 · 内置城市表（≥ 40）与按系统时区猜城市
+ *
+ * 零依赖、零 IO。城市表只含「经纬度 + IANA 时区」，不含任何气候/水温等外部数据。
+ */
+
+/** 内置城市表：id 用拉丁小写，zh/en 给 i18n 用 */
+export const CITIES = Object.freeze(
+  [
+    { id: 'shanghai', zh: '上海', en: 'Shanghai', lat: 31.23, lon: 121.47, tz: 'Asia/Shanghai' },
+    { id: 'beijing', zh: '北京', en: 'Beijing', lat: 39.9, lon: 116.41, tz: 'Asia/Shanghai' },
+    { id: 'guangzhou', zh: '广州', en: 'Guangzhou', lat: 23.13, lon: 113.26, tz: 'Asia/Shanghai' },
+    { id: 'shenzhen', zh: '深圳', en: 'Shenzhen', lat: 22.54, lon: 114.06, tz: 'Asia/Shanghai' },
+    { id: 'chengdu', zh: '成都', en: 'Chengdu', lat: 30.57, lon: 104.07, tz: 'Asia/Shanghai' },
+    { id: 'hangzhou', zh: '杭州', en: 'Hangzhou', lat: 30.27, lon: 120.15, tz: 'Asia/Shanghai' },
+    { id: 'nanjing', zh: '南京', en: 'Nanjing', lat: 32.06, lon: 118.8, tz: 'Asia/Shanghai' },
+    { id: 'wuhan', zh: '武汉', en: 'Wuhan', lat: 30.59, lon: 114.31, tz: 'Asia/Shanghai' },
+    { id: 'xian', zh: '西安', en: "Xi'an", lat: 34.34, lon: 108.94, tz: 'Asia/Shanghai' },
+    { id: 'chongqing', zh: '重庆', en: 'Chongqing', lat: 29.56, lon: 106.55, tz: 'Asia/Shanghai' },
+    { id: 'qingdao', zh: '青岛', en: 'Qingdao', lat: 36.07, lon: 120.38, tz: 'Asia/Shanghai' },
+    { id: 'xiamen', zh: '厦门', en: 'Xiamen', lat: 24.48, lon: 118.09, tz: 'Asia/Shanghai' },
+    { id: 'harbin', zh: '哈尔滨', en: 'Harbin', lat: 45.8, lon: 126.53, tz: 'Asia/Shanghai' },
+    { id: 'kunming', zh: '昆明', en: 'Kunming', lat: 25.04, lon: 102.71, tz: 'Asia/Shanghai' },
+    { id: 'urumqi', zh: '乌鲁木齐', en: 'Urumqi', lat: 43.83, lon: 87.62, tz: 'Asia/Shanghai' },
+    { id: 'lhasa', zh: '拉萨', en: 'Lhasa', lat: 29.65, lon: 91.14, tz: 'Asia/Shanghai' },
+    { id: 'hongkong', zh: '香港', en: 'Hong Kong', lat: 22.32, lon: 114.17, tz: 'Asia/Hong_Kong' },
+    { id: 'macau', zh: '澳门', en: 'Macau', lat: 22.2, lon: 113.54, tz: 'Asia/Macau' },
+    { id: 'taipei', zh: '台北', en: 'Taipei', lat: 25.03, lon: 121.57, tz: 'Asia/Taipei' },
+    { id: 'tokyo', zh: '东京', en: 'Tokyo', lat: 35.68, lon: 139.69, tz: 'Asia/Tokyo' },
+    { id: 'osaka', zh: '大阪', en: 'Osaka', lat: 34.69, lon: 135.5, tz: 'Asia/Tokyo' },
+    { id: 'seoul', zh: '首尔', en: 'Seoul', lat: 37.57, lon: 126.98, tz: 'Asia/Seoul' },
+    { id: 'singapore', zh: '新加坡', en: 'Singapore', lat: 1.35, lon: 103.82, tz: 'Asia/Singapore' },
+    { id: 'bangkok', zh: '曼谷', en: 'Bangkok', lat: 13.76, lon: 100.5, tz: 'Asia/Bangkok' },
+    { id: 'hochiminh', zh: '胡志明市', en: 'Ho Chi Minh City', lat: 10.82, lon: 106.63, tz: 'Asia/Ho_Chi_Minh' },
+    { id: 'jakarta', zh: '雅加达', en: 'Jakarta', lat: -6.21, lon: 106.85, tz: 'Asia/Jakarta' },
+    { id: 'kualalumpur', zh: '吉隆坡', en: 'Kuala Lumpur', lat: 3.14, lon: 101.69, tz: 'Asia/Kuala_Lumpur' },
+    { id: 'manila', zh: '马尼拉', en: 'Manila', lat: 14.6, lon: 120.98, tz: 'Asia/Manila' },
+    { id: 'mumbai', zh: '孟买', en: 'Mumbai', lat: 19.08, lon: 72.88, tz: 'Asia/Kolkata' },
+    { id: 'delhi', zh: '新德里', en: 'New Delhi', lat: 28.61, lon: 77.21, tz: 'Asia/Kolkata' },
+    { id: 'dubai', zh: '迪拜', en: 'Dubai', lat: 25.2, lon: 55.27, tz: 'Asia/Dubai' },
+    { id: 'istanbul', zh: '伊斯坦布尔', en: 'Istanbul', lat: 41.01, lon: 28.98, tz: 'Europe/Istanbul' },
+    { id: 'moscow', zh: '莫斯科', en: 'Moscow', lat: 55.76, lon: 37.62, tz: 'Europe/Moscow' },
+    { id: 'athens', zh: '雅典', en: 'Athens', lat: 37.98, lon: 23.73, tz: 'Europe/Athens' },
+    { id: 'rome', zh: '罗马', en: 'Rome', lat: 41.9, lon: 12.5, tz: 'Europe/Rome' },
+    { id: 'berlin', zh: '柏林', en: 'Berlin', lat: 52.52, lon: 13.4, tz: 'Europe/Berlin' },
+    { id: 'paris', zh: '巴黎', en: 'Paris', lat: 48.86, lon: 2.35, tz: 'Europe/Paris' },
+    { id: 'madrid', zh: '马德里', en: 'Madrid', lat: 40.42, lon: -3.7, tz: 'Europe/Madrid' },
+    { id: 'lisbon', zh: '里斯本', en: 'Lisbon', lat: 38.72, lon: -9.14, tz: 'Europe/Lisbon' },
+    { id: 'amsterdam', zh: '阿姆斯特丹', en: 'Amsterdam', lat: 52.37, lon: 4.9, tz: 'Europe/Amsterdam' },
+    { id: 'london', zh: '伦敦', en: 'London', lat: 51.51, lon: -0.13, tz: 'Europe/London' },
+    { id: 'stockholm', zh: '斯德哥尔摩', en: 'Stockholm', lat: 59.33, lon: 18.07, tz: 'Europe/Stockholm' },
+    { id: 'oslo', zh: '奥斯陆', en: 'Oslo', lat: 59.91, lon: 10.75, tz: 'Europe/Oslo' },
+    { id: 'helsinki', zh: '赫尔辛基', en: 'Helsinki', lat: 60.17, lon: 24.94, tz: 'Europe/Helsinki' },
+    { id: 'reykjavik', zh: '雷克雅未克', en: 'Reykjavik', lat: 64.15, lon: -21.94, tz: 'Atlantic/Reykjavik' },
+    { id: 'tromso', zh: '特罗姆瑟', en: 'Tromso', lat: 69.65, lon: 18.96, tz: 'Europe/Oslo' },
+    { id: 'longyearbyen', zh: '朗伊尔城', en: 'Longyearbyen', lat: 78.22, lon: 15.65, tz: 'Arctic/Longyearbyen' },
+    { id: 'newyork', zh: '纽约', en: 'New York', lat: 40.71, lon: -74.01, tz: 'America/New_York' },
+    { id: 'losangeles', zh: '洛杉矶', en: 'Los Angeles', lat: 34.05, lon: -118.24, tz: 'America/Los_Angeles' },
+    { id: 'sanfrancisco', zh: '旧金山', en: 'San Francisco', lat: 37.77, lon: -122.42, tz: 'America/Los_Angeles' },
+    { id: 'seattle', zh: '西雅图', en: 'Seattle', lat: 47.61, lon: -122.33, tz: 'America/Los_Angeles' },
+    { id: 'chicago', zh: '芝加哥', en: 'Chicago', lat: 41.88, lon: -87.63, tz: 'America/Chicago' },
+    { id: 'denver', zh: '丹佛', en: 'Denver', lat: 39.74, lon: -104.99, tz: 'America/Denver' },
+    { id: 'anchorage', zh: '安克雷奇', en: 'Anchorage', lat: 61.22, lon: -149.9, tz: 'America/Anchorage' },
+    { id: 'toronto', zh: '多伦多', en: 'Toronto', lat: 43.65, lon: -79.38, tz: 'America/Toronto' },
+    { id: 'vancouver', zh: '温哥华', en: 'Vancouver', lat: 49.28, lon: -123.12, tz: 'America/Vancouver' },
+    { id: 'mexicocity', zh: '墨西哥城', en: 'Mexico City', lat: 19.43, lon: -99.13, tz: 'America/Mexico_City' },
+    { id: 'bogota', zh: '波哥大', en: 'Bogota', lat: 4.71, lon: -74.07, tz: 'America/Bogota' },
+    { id: 'lima', zh: '利马', en: 'Lima', lat: -12.05, lon: -77.04, tz: 'America/Lima' },
+    { id: 'saopaulo', zh: '圣保罗', en: 'Sao Paulo', lat: -23.55, lon: -46.63, tz: 'America/Sao_Paulo' },
+    { id: 'buenosaires', zh: '布宜诺斯艾利斯', en: 'Buenos Aires', lat: -34.6, lon: -58.38, tz: 'America/Argentina/Buenos_Aires' },
+    { id: 'santiago', zh: '圣地亚哥', en: 'Santiago', lat: -33.45, lon: -70.67, tz: 'America/Santiago' },
+    { id: 'cairo', zh: '开罗', en: 'Cairo', lat: 30.04, lon: 31.24, tz: 'Africa/Cairo' },
+    { id: 'nairobi', zh: '内罗毕', en: 'Nairobi', lat: -1.29, lon: 36.82, tz: 'Africa/Nairobi' },
+    { id: 'lagos', zh: '拉各斯', en: 'Lagos', lat: 6.52, lon: 3.38, tz: 'Africa/Lagos' },
+    { id: 'capetown', zh: '开普敦', en: 'Cape Town', lat: -33.92, lon: 18.42, tz: 'Africa/Johannesburg' },
+    { id: 'sydney', zh: '悉尼', en: 'Sydney', lat: -33.87, lon: 151.21, tz: 'Australia/Sydney' },
+    { id: 'melbourne', zh: '墨尔本', en: 'Melbourne', lat: -37.81, lon: 144.96, tz: 'Australia/Melbourne' },
+    { id: 'brisbane', zh: '布里斯班', en: 'Brisbane', lat: -27.47, lon: 153.03, tz: 'Australia/Brisbane' },
+    { id: 'perth', zh: '珀斯', en: 'Perth', lat: -31.95, lon: 115.86, tz: 'Australia/Perth' },
+    { id: 'auckland', zh: '奥克兰', en: 'Auckland', lat: -36.85, lon: 174.76, tz: 'Pacific/Auckland' },
+    { id: 'wellington', zh: '惠灵顿', en: 'Wellington', lat: -41.29, lon: 174.78, tz: 'Pacific/Auckland' },
+    { id: 'honolulu', zh: '檀香山', en: 'Honolulu', lat: 21.31, lon: -157.86, tz: 'Pacific/Honolulu' },
+  ].map(Object.freeze),
+);
+
+/** 兜底城市：猜不到就回上海（契约要求 guessCity 永不返回 undefined） */
+const FALLBACK_CITY = CITIES[0];
+
+const REGION_CITY = Object.freeze({
+  CN: 'shanghai', TW: 'taipei', HK: 'hongkong', MO: 'macau',
+  JP: 'tokyo', KR: 'seoul', SG: 'singapore', TH: 'bangkok',
+  VN: 'hochiminh', ID: 'jakarta', MY: 'kualalumpur', PH: 'manila',
+  IN: 'mumbai', AE: 'dubai', TR: 'istanbul', RU: 'moscow',
+  GR: 'athens', IT: 'rome', DE: 'berlin', FR: 'paris',
+  ES: 'madrid', PT: 'lisbon', NL: 'amsterdam', GB: 'london',
+  SE: 'stockholm', NO: 'oslo', FI: 'helsinki', IS: 'reykjavik',
+  US: 'newyork', CA: 'toronto', MX: 'mexicocity', BR: 'saopaulo',
+  AR: 'buenosaires', CL: 'santiago', CO: 'bogota', PE: 'lima',
+  EG: 'cairo', KE: 'nairobi', NG: 'lagos', ZA: 'capetown',
+  AU: 'sydney', NZ: 'auckland',
+});
+
+/** 球面距离（km） */
+function distanceKm(lat1, lon1, lat2, lon2) {
+  const R = 6371;
+  const toRad = Math.PI / 180;
+  const dLat = (lat2 - lat1) * toRad;
+  const dLon = (lon2 - lon1) * toRad;
+  const a =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(lat1 * toRad) * Math.cos(lat2 * toRad) * Math.sin(dLon / 2) ** 2;
+  return 2 * R * Math.asin(Math.min(1, Math.sqrt(a)));
+}
+
+function nearestOf(list, lat, lon) {
+  let best = list[0];
+  let bestD = Infinity;
+  for (const city of list) {
+    const d = distanceKm(lat, lon, city.lat, city.lon);
+    if (d < bestD) {
+      bestD = d;
+      best = city;
+    }
+  }
+  return best;
+}
+
+/**
+ * 按 tz / locale / 坐标猜城市。永不返回 undefined（猜不到就返回上海）。
+ * 优先级：tz 精确命中 → 坐标最近 → locale 区域 → 上海。
+ */
+export function guessCity(input) {
+  const opts = input && typeof input === 'object' ? input : {};
+  const { tz, locale } = opts;
+  const lat = Number(opts.lat);
+  const lon = Number(opts.lon);
+  const hasCoords =
+    Number.isFinite(lat) && Number.isFinite(lon) && Math.abs(lat) <= 90 && Math.abs(lon) <= 180;
+
+  if (typeof tz === 'string' && tz) {
+    const sameTz = CITIES.filter((c) => c.tz === tz);
+    if (sameTz.length > 0) return hasCoords ? nearestOf(sameTz, lat, lon) : sameTz[0];
+  }
+
+  if (hasCoords) return nearestOf(CITIES, lat, lon);
+
+  if (typeof locale === 'string' && locale) {
+    const region = locale.split(/[-_]/)[1];
+    const id = region ? REGION_CITY[region.toUpperCase()] : undefined;
+    const hit = id ? findCity(id) : undefined;
+    if (hit) return hit;
+  }
+
+  return FALLBACK_CITY;
+}
+
+/** 按 id / 中文名 / 英文名查城市（忽略大小写与首尾空格） */
+export function findCity(id) {
+  if (typeof id !== 'string') return undefined;
+  const key = id.trim().toLowerCase();
+  if (!key) return undefined;
+  return CITIES.find(
+    (c) => c.id === key || c.zh === id.trim() || c.en.toLowerCase() === key,
+  );
+}

package/src/client/api.js

@@ -0,0 +1,140 @@
+// 潮间 —— `/intertidal/*` 的浏览器侧封装。
+//
+// 三条要求（spec §8）：
+//   1. **永远不抛**：所有方法都 resolve，失败返回 `{ ok:false }`，由 runtime 决定降级；
+//   2. 设置写入失败时用 `localStorage` 镜像，刷新后仍能用你刚改的值；
+//   3. 超时必须有：宿主卡住时不能把 UI 拖住（4 秒）。
+
+const BASE = '/intertidal'
+const MIRROR_KEY = 'dsh-intertidal:settings'
+const TIMEOUT_MS = 4000
+
+/** 读镜像（坏 JSON 就当没有）。 */
+export function readMirror(storage = safeStorage()) {
+  try {
+    const raw = storage?.getItem(MIRROR_KEY)
+    if (!raw) return null
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+export function writeMirror(settings, storage = safeStorage()) {
+  try {
+    storage?.setItem(MIRROR_KEY, JSON.stringify(settings))
+  } catch {
+    /* 隐私模式 / 配额满 → 忽略 */
+  }
+}
+
+function safeStorage() {
+  try {
+    return globalThis.localStorage ?? null
+  } catch {
+    return null
+  }
+}
+
+async function call(path, { method = 'GET', body, signal } = {}, fetchImpl) {
+  const doFetch = fetchImpl ?? globalThis.fetch
+  if (typeof doFetch !== 'function') return { ok: false, status: 0, error: 'no-fetch' }
+  const controller = typeof AbortController === 'function' ? new AbortController() : null
+  const timer = controller ? setTimeout(() => controller.abort(), TIMEOUT_MS) : null
+  try {
+    const init = { method, cache: 'no-store', credentials: 'same-origin', signal: controller?.signal ?? signal }
+    if (body !== undefined) {
+      init.headers = { 'content-type': 'application/json' }
+      init.body = JSON.stringify(body)
+    }
+    const res = await doFetch(`${BASE}${path}`, init)
+    if (!res.ok) return { ok: false, status: res.status, error: `http-${res.status}` }
+    const value = await res.json()
+    return { ok: true, value }
+  } catch (error) {
+    return { ok: false, status: 0, error: String(error?.name === 'AbortError' ? 'timeout' : (error?.message ?? error)) }
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}
+
+/**
+ * 造一个 api。`onStatus` 用来把"宿主是否可用"报给 runtime（设置页据此显示一行告警）。
+ */
+export function createApi({ fetchImpl, storage = safeStorage(), onStatus } = {}) {
+  let offline = false
+  const note = (ok) => {
+    if (offline === !ok) return
+    offline = !ok
+    try {
+      onStatus?.(offline)
+    } catch {
+      /* 回调自己抛了不该影响请求 */
+    }
+  }
+
+  return {
+    get offline() {
+      return offline
+    },
+
+    /** GET /state → `{ settings, rhythm, now }`；失败时退镜像 + null。 */
+    async state() {
+      const result = await call('/state', {}, fetchImpl)
+      note(result.ok)
+      if (result.ok) {
+        writeMirror(result.value?.settings, storage)
+        return result
+      }
+      const mirror = readMirror(storage)
+      return { ok: false, error: result.error, value: mirror ? { settings: mirror, rhythm: null, now: null } : null }
+    },
+
+    /** GET /now；带地点参数就按参数算，不带就用宿主设置。 */
+    async now(location) {
+      const query = location && Number.isFinite(location.lat) && Number.isFinite(location.lon)
+        ? `?lat=${encodeURIComponent(location.lat)}&lon=${encodeURIComponent(location.lon)}&tz=${encodeURIComponent(location.tz ?? '')}`
+        : ''
+      const result = await call(`/now${query}`, {}, fetchImpl)
+      note(result.ok)
+      return result
+    },
+
+    /** POST /settings：整份覆盖式提交（宿主做合并与钳制）。 */
+    async saveSettings(patch) {
+      const result = await call('/settings', { method: 'POST', body: patch }, fetchImpl)
+      note(result.ok)
+      if (result.ok) writeMirror(result.value, storage)
+      else {
+        const mirror = readMirror(storage) ?? {}
+        writeMirror({ ...mirror, ...patch }, storage)
+      }
+      return result
+    },
+
+    /** POST /rhythm：`shown` / `hidden` / `skip-today` / `manual-open`。 */
+    async rhythm(event) {
+      const result = await call('/rhythm', { method: 'POST', body: { event } }, fetchImpl)
+      note(result.ok)
+      return result
+    },
+
+    /** GET /media：这一次浮现用哪张素材（`fresh` 强制重新抽一张）。 */
+    async media(fresh = false) {
+      const result = await call(`/media${fresh ? '?fresh=1' : ''}`, {}, fetchImpl)
+      // 素材失败不影响看海（会退回程序化海），所以不改变 offline 判定
+      return result
+    },
+
+    /** POST /media/scan：设置页验证目录里有多少素材。 */
+    async scanMedia(dir) {
+      return call('/media/scan', { method: 'POST', body: { dir } }, fetchImpl)
+    },
+
+    /** POST /media/resolve：把一个网页/图片链接抓成本地缓存。 */
+    async resolveMedia(url) {
+      return call('/media/resolve', { method: 'POST', body: { url } }, fetchImpl)
+    },
+  }
+}

package/src/client/birds.js

@@ -0,0 +1,112 @@
+// 潮间 · 白天的海鸥。
+//
+// 设计约束（都在 spec 里）：不联网、不加载素材、**不依赖帧数**、随时可停帧、任何分支都不抛。
+// 所以这里不用"状态机 + 随机生成器"，而是**时间函数**：第 i 只鸟的起飞时刻、航线、扇翅相位
+// 全部由 t 和一个整数哈希决定。好处是：
+//   - 同一 t 画出同一帧（可单测、可截图复现）；
+//   - 暂停/隐藏再恢复时不会"补飞"一段突兀的动画；
+//   - 不会因为掉帧而多出或少掉一只鸟。
+//
+// 视觉：远处的小剪影、两段贝塞尔翅膀 + 轻微上下起伏，一队 3 只错开飞过。做成"随机"的观感靠
+// 每只鸟的周期/航线/相位互质，屏幕上不会出现明显规律。
+
+const TAU = Math.PI * 2;
+
+const clamp01 = (v) => (v < 0 ? 0 : v > 1 ? 1 : v);
+
+/** 整数哈希 → [0,1)，用来给每只鸟不同的参数。 */
+function hash(n) {
+  let x = Math.imul(n | 0, 2654435761);
+  x = Math.imul(x ^ (x >>> 15), 2246822507);
+  return ((x ^ (x >>> 13)) >>> 0) / 4294967296;
+}
+
+export const BIRD_CONSTANTS = Object.freeze({
+  slots: 9, //        同时在"档期"里的鸟槽（不是同屏数量）
+  minPeriod: 19, //   最短的一个轮回（秒）
+  periodSpan: 23, //  周期跨度：每只鸟都不同，避免同拍
+  minFlight: 7, //    飞过一整屏需要的秒数（下界）
+  flightSpan: 5,
+});
+
+/**
+ * 白天度：0 = 完全夜里（不出鸟），1 = 大白天。深夜/晨曦微光时自动降到 0。
+ * @param {any} pal paletteFor() 的返回值
+ */
+export function daylightOf(pal) {
+  if (!pal || typeof pal !== 'object') return 0;
+  // 没有 exposure 就当作"不知道天光"——宁可不画鸟，也不要在大半夜画出一群海鸥。
+  if (!Number.isFinite(pal.exposure)) return 0;
+  const stars = Number.isFinite(pal.stars) ? pal.stars : 0;
+  return clamp01((pal.exposure - 0.45) / 0.4) * clamp01(1 - stars * 1.6);
+}
+
+/**
+ * 画一帧海鸥。
+ * @param {CanvasRenderingContext2D} ctx
+ * @param {{ W:number, H:number, horizonY:number, t:number, pal:any }} view
+ * @returns {number} 这一帧画出的鸟数（测试用）
+ */
+export function drawBirds(ctx, view) {
+  const { W, H, horizonY, t } = view;
+  const pal = view.pal ?? {};
+  const daylight = daylightOf(pal);
+  if (daylight <= 0.02) return 0;
+  if (!Number.isFinite(W) || !Number.isFinite(H) || !Number.isFinite(horizonY)) return 0;
+  if (horizonY <= 4 || !ctx || typeof ctx.beginPath !== 'function') return 0;
+
+  const { slots, minPeriod, periodSpan, minFlight, flightSpan } = BIRD_CONSTANTS;
+  const skyH = horizonY; // 鸟只在地平线以上的天空里
+  const scale = Math.max(0.55, Math.min(2.2, H / 720));
+  // 白天越亮，鸟越多；夜里 0
+  const density = 0.55 + 0.45 * daylight;
+
+  let drawn = 0;
+  for (let i = 0; i < slots; i += 1) {
+    const period = minPeriod + hash(i * 3 + 1) * periodSpan;
+    const flight = minFlight + hash(i * 7 + 5) * flightSpan;
+    const offset = hash(i * 11 + 2) * period;
+    // 每一轮里"在飞"的时间占比 = flight/period，其余时间不出现
+    const local = (t + offset) % period;
+    if (local > flight) continue;
+    // 密度筛选：不同的鸟按不同概率出现，视觉上不是固定 3 只
+    if (hash(i * 13 + 9) > density) continue;
+
+    const p = local / flight; // 0 → 1 航线进度
+    const r1 = hash(i * 17 + 3);
+    const r2 = hash(i * 19 + 11);
+    const r3 = hash(i * 23 + 7);
+    const leftToRight = r1 > 0.45;
+    // 从屏幕外飞进来、再飞出屏幕外
+    const x0 = leftToRight ? -0.08 * W : 1.08 * W;
+    const x1 = leftToRight ? 1.08 * W : -0.08 * W;
+    const x = x0 + (x1 - x0) * p;
+    // 高度：地平线以上、偏上；越靠近地平线画得越小（远）
+    const depth = 0.28 + 0.42 * r2; //     0.28(低/远) → 0.70(高/近)
+    const bob = Math.sin((p * 2.0 + r3) * TAU) * skyH * 0.012;
+    const y = horizonY * depth + bob;
+
+    const size = (11 + 9 * r3) * scale * (0.55 + 0.6 * depth);
+    // 翅膀扇动：每只鸟频率不同，period 内做 6–11 次
+    const flaps = 6 + Math.floor(r3 * 5);
+    const wing = Math.sin(p * flaps * TAU + r2 * TAU);
+    // 侧倾：扇翅到极值时翅膀更"平"，中间更"折"，看起来像在滑翔与扇动之间切换
+    const lift = 0.55 + 0.45 * Math.abs(wing);
+    const alpha = clamp01((0.5 + 0.32 * daylight) * (0.7 + 0.3 * Math.sin(p * Math.PI)));
+
+    ctx.save();
+    ctx.strokeStyle = `rgba(28,34,44,${alpha.toFixed(3)})`;
+    ctx.lineWidth = Math.max(1.1, 1.7 * scale);
+    ctx.lineCap = 'round';
+    if (typeof ctx.beginPath === 'function') {
+      // 两段翅膀：左翼 + 右翼，用二次曲线做出"上反角"
+      ctx.beginPath();
+      ctx.moveTo(x - size, y - wing * size * 0.55 * lift);
+      ctx.quadraticCurveTo(x - size * 0.35, y - size * 0.28 - wing * size * 0.35 * lift, x, y);
+      ctx.quadraticCurveTo(x + size * 0.35, y - size * 0.28 - wing * size * 0.35 * lift, x + size, y - wing * size * 0.55 * lift);
+      ctx.stroke();
+    }
+    drawn += 1;
+  }
+  return drawn;
+}

package/src/client/format.js

@@ -0,0 +1,28 @@
+// 潮间 —— 覆盖层里那些"给人看的小格式"。单独放一个纯 JS 文件，好让 node --test 直接 import
+// （.jsx 在 node 里没法直接加载，测试只能绕）。
+
+/** 剩余毫秒 → `m:ss`（不足 1 小时）或 `h:mm:ss`；向上取整，起点显示 3:00 而不是 2:59。 */
+export function formatRemaining(ms) {
+  const total = Math.max(0, Math.ceil(Number(ms) / 1000) || 0)
+  const hours = Math.floor(total / 3600)
+  const minutes = Math.floor((total % 3600) / 60)
+  const seconds = total % 60
+  const pad = (value) => String(value).padStart(2, '0')
+  return hours > 0 ? `${hours}:${pad(minutes)}:${pad(seconds)}` : `${minutes}:${pad(seconds)}`
+}
+
+/** 某个地点的钟面时间（HH:MM）；时区非法就退回本机时区。 */
+export function formatClock(date, tz) {
+  try {
+    return new Intl.DateTimeFormat('en-GB', {
+      hour: '2-digit',
+      minute: '2-digit',
+      hour12: false,
+      timeZone: tz || undefined,
+    }).format(date)
+  } catch {
+    const h = String(date.getHours()).padStart(2, '0')
+    const m = String(date.getMinutes()).padStart(2, '0')
+    return `${h}:${m}`
+  }
+}