@ohmykreee/dsh-remote-control 0.0.0-stage → 1.0.2

package/src/dsh/lib/app-mapping.ts

@@ -0,0 +1,366 @@
+/**
+ * Application-name mapping and history for notifications and media.
+ *
+ * The native probe reports only the raw OS application identity (a Windows
+ * notification handler id / SMTC AUMID, or an MPRIS bus name). This module owns
+ * every display name:
+ *
+ *  - a built-in default table for well-known Windows apps,
+ *  - generic derivation for executable paths, package AUMIDs and MPRIS names,
+ *  - the history of every application the console has seen (first/last seen,
+ *    notification count, which console page reported it),
+ *  - user renames from the "app mapping" settings tab, persisted on disk and
+ *    applied to both notifications and the music player.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { isRecord } from './types.js';
+
+/** Where an application id was observed. */
+export type AppSource = 'notification' | 'music';
+
+/** An application reported by the probe. */
+export interface AppObservation {
+  key: string;
+  /** Notifications seen for this app in one snapshot (max wins). */
+  count?: number;
+}
+
+/** Built-in names for well-known Windows application ids. */
+const DEFAULT_APP_NAMES: Record<string, string> = {
+  qq: 'QQ',
+  'com.bilibili.bilibilipc': '哔哩哔哩',
+  'bilbilipc': '哔哩哔哩',
+  'com.squirrel.discord.discord': 'Discord',
+  'com.oplus.devicespace': 'OPPO 互传',
+  'dev.zcode.app': 'ZCode',
+  'electron.app.zcode': 'ZCode',
+  'firefoxtoast-308046b0af4a39cb': 'Firefox',
+  'microsoft.screensketch_8wekyb3d8bbwe!app': '截图工具',
+  'microsoft.windowsterminal_8wekyb3d8bbwe!app': '终端',
+  'microsoft.visualstudiocode_8wekyb3d8bbwe!vscode': 'Visual Studio Code',
+  'microsoft.microsoftedge.stable_8wekyb3d8bbwe!app': 'Microsoft Edge',
+  'microsoft.outlookforwindows_8wekyb3d8bbwe!microsoft.outlookforwindows': 'Outlook',
+  'microsoft.office.outlook.exe.15': 'Outlook',
+  'microsoft.yourphone_8wekyb3d8bbwe!app': '手机连接',
+  'microsoft.zunemusic_8wekyb3d8bbwe!microsoft.zunemusic': '媒体播放器',
+  'microsoft.windowsstore_8wekyb3d8bbwe!app': 'Microsoft Store',
+  'microsoft.todos_8wekyb3d8bbwe!app': 'Microsoft To Do',
+  'microsoft.paint_8wekyb3d8bbwe!app': '画图',
+  'microsoft.windowsnotepad_8wekyb3d8bbwe!app': '记事本',
+  'microsoft.windowscalculator_8wekyb3d8bbwe!app': '计算器',
+  'microsoft.windows.photos_8wekyb3d8bbwe!app': '照片',
+  'windows.defender.securitycenter': 'Windows 安全中心',
+  'microsoft.zunemusic_8wekyb3d8bbwe': '媒体播放器',
+  'cloudmusic.exe': '网易云音乐',
+  'qqmusic.exe': 'QQ音乐',
+  'kugou.exe': '酷狗音乐',
+  'kgmusic.exe': '酷狗音乐',
+  'kwmusic.exe': '酷我音乐',
+  'kwservice.exe': '酷我音乐',
+  'sodamusic.exe': '汽水音乐',
+  'wesing.exe': '全民K歌',
+  'spotify.exe': 'Spotify',
+  'applemusic.exe': 'Apple Music',
+  'youtube music.exe': 'YouTube Music',
+  'cider.exe': 'Cider',
+};
+
+/** One persisted application entry, as stored in `app-mapping.json`. */
+interface StoredApp {
+  key: string;
+  customName: string | null;
+  firstSeen: number;
+  lastSeen: number;
+  count: number;
+  sources: string[];
+}
+
+/** Browser-facing application entry. */
+export interface MappedApp {
+  key: string;
+  name: string;
+  /** User override, or `null` when the default name is used. */
+  customName: string | null;
+  /** Built-in/derived name, `null` when nothing better than the raw id exists. */
+  defaultName: string | null;
+  count: number;
+  firstSeen: number;
+  lastSeen: number;
+  sources: string[];
+}
+
+/** Storage API returned by {@link createAppMapping}. */
+export interface AppMapping {
+  record(observations: AppObservation[], source: AppSource): void;
+  rename(key: string, name: string | null): MappedApp | null;
+  displayName(key: string): string;
+  list(): MappedApp[];
+  get(key: string): MappedApp | null;
+  flush(): void;
+  dispose(): void;
+}
+
+const MAX_APPS = 300;
+const MAX_NAME_CHARS = 60;
+const MAX_KEY_CHARS = 240;
+
+/** Turn `SomePascalCaseName` into `Some Pascal Case Name`. */
+function spacesBetweenWords(value: string): string {
+  let output = '';
+  let previousLower = false;
+  for (const character of value) {
+    if (character === '-' || character === '_') {
+      output += ' ';
+    } else {
+      if (character === character.toUpperCase() && character !== character.toLowerCase() && previousLower) {
+        output += ' ';
+      }
+      output += character;
+    }
+    previousLower = character === character.toLowerCase() && character !== character.toUpperCase();
+  }
+  return output.trim();
+}
+
+/** Derive a readable name from a raw Windows/Linux application id. */
+export function defaultAppName(rawKey: string): string | null {
+  const key = String(rawKey || '').trim();
+  if (!key) return null;
+  const exact = DEFAULT_APP_NAMES[key.toLowerCase()];
+  if (exact) return exact;
+
+  // Windows executable path (desktop notification handler).
+  if ((key.includes('\\') || key.includes('/')) && key.toLowerCase().endsWith('.exe')) {
+    const base = key.split(/[\\/]/).pop() || key;
+    return base.replace(/\.exe$/i, '') || null;
+  }
+  if (key.startsWith('NotifyIconGeneratedAumid_')) return '桌面应用';
+  if (key.toLowerCase().startsWith('microsoft.microsoftedge')) return 'Microsoft Edge';
+  if (key.toLowerCase().startsWith('microsoft.screensketch')) return '截图工具';
+
+  // Generic media-source heuristics (SMTC AUMIDs and browser processes).
+  if (/bilibili/i.test(key)) return '哔哩哔哩';
+  if (/youtube[-_ ]?music|ytmusic/i.test(key)) return 'YouTube Music';
+  if (/cloudmusic|netease|163music|网易云/i.test(key)) return '网易云音乐';
+  if (/qqmusic|qq音乐/i.test(key)) return 'QQ音乐';
+  if (/kugou|kgmusic|酷狗/i.test(key)) return '酷狗音乐';
+  if (/kwmusic|kwservice|kuwo|酷我/i.test(key)) return '酷我音乐';
+  if (/sodamusic|汽水音乐/i.test(key)) return '汽水音乐';
+  if (/wesing|全民k歌/i.test(key)) return '全民K歌';
+  if (/cider/i.test(key)) return 'Cider';
+  if (/applemusic|apple[ .]music|com\.apple\.music/i.test(key)) return 'Apple Music';
+  if (/spotify/i.test(key)) return 'Spotify';
+  if (/msedge/i.test(key)) return 'Microsoft Edge';
+  if (/brave/i.test(key)) return 'Brave';
+  if (/vivaldi/i.test(key)) return 'Vivaldi';
+  if (/firefox/i.test(key)) return 'Firefox';
+  if (/chrome/i.test(key)) return 'Chrome';
+
+  // MPRIS bus name: org.mpris.MediaPlayer2.<player>
+  if (key.startsWith('org.mpris.MediaPlayer2.')) {
+    const tail = key.slice('org.mpris.MediaPlayer2.'.length).replace(/[._-]+/g, ' ').trim();
+    return tail ? tail.replace(/\b\w/g, (letter) => letter.toUpperCase()) : null;
+  }
+
+  // Windows package AUMID: Package_family!EntryPoint
+  let base = key.split('!')[0];
+  const underscore = base.lastIndexOf('_');
+  if (underscore > 0) {
+    const suffix = base.slice(underscore + 1);
+    if (suffix.length >= 8 && /^[a-z0-9]+$/.test(suffix)) base = base.slice(0, underscore);
+  }
+  const tail = base.split('.').filter(Boolean).pop() || '';
+  const spaced = spacesBetweenWords(tail);
+  return spaced || null;
+}
+
+function sanitizeName(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const name = value.replace(/\s+/g, ' ').trim().slice(0, MAX_NAME_CHARS);
+  return name || null;
+}
+
+function sanitizeSources(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.filter((item): item is AppSource => item === 'notification' || item === 'music'))];
+}
+
+/** Rebuild the persisted entry map, dropping records that make no sense. */
+function readEntries(value: unknown): Record<string, StoredApp> {
+  const apps: Record<string, StoredApp> = {};
+  if (!isRecord(value)) return apps;
+  for (const entry of Object.values(value)) {
+    if (!isRecord(entry) || typeof entry.key !== 'string' || !entry.key) continue;
+    const key = entry.key.slice(0, MAX_KEY_CHARS);
+    apps[key] = {
+      key,
+      customName: sanitizeName(entry.customName),
+      firstSeen: Number(entry.firstSeen) || Number(entry.lastSeen) || 0,
+      lastSeen: Number(entry.lastSeen) || 0,
+      count: Math.max(0, Math.round(Number(entry.count) || 0)),
+      sources: sanitizeSources(entry.sources),
+    };
+  }
+  return apps;
+}
+
+/** Seed the history from the pre-mapping `notification-cache.json`, if any. */
+function readLegacyCache(directory: string): Record<string, StoredApp> {
+  const apps: Record<string, StoredApp> = {};
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(path.join(directory, 'notification-cache.json'), 'utf8'));
+    if (!isRecord(parsed) || !isRecord(parsed.apps)) return apps;
+    for (const entry of Object.values(parsed.apps)) {
+      if (!isRecord(entry) || typeof entry.key !== 'string' || !entry.key) continue;
+      const key = entry.key.slice(0, MAX_KEY_CHARS);
+      apps[key] = {
+        key,
+        customName: null,
+        firstSeen: Number(entry.lastSeen) || 0,
+        lastSeen: Number(entry.lastSeen) || 0,
+        count: Math.max(0, Math.round(Number(entry.count) || 0)),
+        sources: ['notification'],
+      };
+    }
+  } catch {
+    /* no legacy cache */
+  }
+  return apps;
+}
+
+export function createAppMapping(directory: string): AppMapping {
+  const dir = directory;
+  const file = path.join(dir, 'app-mapping.json');
+  fs.mkdirSync(dir, { recursive: true });
+
+  let apps: Record<string, StoredApp> = {};
+  let loaded = false;
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (isRecord(parsed) && isRecord(parsed.apps)) {
+      apps = readEntries(parsed.apps);
+      loaded = true;
+    }
+  } catch {
+    apps = {};
+  }
+  if (!loaded) apps = readLegacyCache(dir);
+
+  let timer: NodeJS.Timeout | null = null;
+
+  function resolve(entry: StoredApp): MappedApp {
+    const defaultName = defaultAppName(entry.key);
+    return {
+      key: entry.key,
+      name: entry.customName || defaultName || entry.key,
+      customName: entry.customName,
+      defaultName,
+      count: entry.count,
+      firstSeen: entry.firstSeen,
+      lastSeen: entry.lastSeen,
+      sources: [...entry.sources],
+    };
+  }
+
+  function flush(): void {
+    timer = null;
+    const temporary = `${file}.tmp-${process.pid}`;
+    try {
+      fs.writeFileSync(temporary, JSON.stringify({ version: 1, updatedAt: Date.now(), apps }, null, 2), 'utf8');
+      fs.renameSync(temporary, file);
+    } catch {
+      /* mapping must never break notifications */
+    }
+  }
+
+  function schedule(): void {
+    if (timer) return;
+    timer = setTimeout(flush, 1200);
+    timer.unref?.();
+  }
+
+  function trimToLimit(): void {
+    const entries = Object.values(apps);
+    if (entries.length <= MAX_APPS) return;
+    entries.sort((left, right) => right.lastSeen - left.lastSeen);
+    apps = Object.fromEntries(entries.slice(0, MAX_APPS).map((entry) => [entry.key, entry]));
+  }
+
+  function record(observations: AppObservation[], source: AppSource): void {
+    if (!Array.isArray(observations) || observations.length === 0) return;
+    let changed = false;
+    const now = Date.now();
+    for (const observation of observations) {
+      if (!isRecord(observation)) continue;
+      const rawKey = typeof observation.key === 'string' ? observation.key.trim() : '';
+      if (!rawKey) continue;
+      const key = rawKey.slice(0, MAX_KEY_CHARS);
+      const count = Math.max(0, Math.round(Number(observation.count) || 0));
+      const previous = apps[key];
+      const sources = new Set(previous?.sources ?? []);
+      sources.add(source);
+      const sourcesChanged = sources.size !== (previous?.sources.length ?? 0);
+      // Only refresh the timestamp when something changed or the last sighting
+      // is old: the console polls notifications every few seconds and the file
+      // should not be rewritten on every poll.
+      const stale = !previous || now - previous.lastSeen > 60_000;
+      if (previous && previous.count === count && !sourcesChanged && !stale) continue;
+      apps[key] = {
+        key,
+        customName: previous?.customName ?? null,
+        firstSeen: previous?.firstSeen || now,
+        lastSeen: now,
+        count: Math.max(count, previous?.count ?? 0),
+        sources: [...sources],
+      };
+      changed = true;
+    }
+    if (changed) {
+      trimToLimit();
+      schedule();
+    }
+  }
+
+  function rename(key: string, name: string | null): MappedApp | null {
+    const rawKey = String(key || '').trim();
+    if (!rawKey) return null;
+    const trimmedKey = rawKey.slice(0, MAX_KEY_CHARS);
+    const previous = apps[trimmedKey];
+    if (!previous) return null;
+    const customName = sanitizeName(name);
+    if (previous.customName === customName) return resolve(previous);
+    apps[trimmedKey] = { ...previous, customName };
+    flush();
+    return resolve(apps[trimmedKey]);
+  }
+
+  function displayName(key: string): string {
+    const trimmedKey = String(key || '').trim().slice(0, MAX_KEY_CHARS);
+    if (!trimmedKey) return '未知应用';
+    const stored = apps[trimmedKey];
+    if (stored?.customName) return stored.customName;
+    return defaultAppName(trimmedKey) || trimmedKey;
+  }
+
+  function list(): MappedApp[] {
+    return Object.values(apps)
+      .map(resolve)
+      .sort((left, right) => right.lastSeen - left.lastSeen || right.count - left.count);
+  }
+
+  function get(key: string): MappedApp | null {
+    const stored = apps[String(key || '').trim().slice(0, MAX_KEY_CHARS)];
+    return stored ? resolve(stored) : null;
+  }
+
+  function dispose(): void {
+    if (timer) {
+      clearTimeout(timer);
+      flush();
+    }
+  }
+
+  return { record, rename, displayName, list, get, flush, dispose };
+}

package/src/dsh/lib/i18n.ts

@@ -0,0 +1,82 @@
+/**
+ * Host-side copy for strings the plugin itself sends to the phone.
+ *
+ * The browser surfaces have their own dictionaries (`src/dsh/client/i18n.ts`
+ * for the DSH panel and `src/svelte/lib/i18n.svelte.ts` for the console). The
+ * Host cannot import either: one is a browser module factory and the other is
+ * a Vite bundle, while this file is compiled into `lib/`. It therefore keeps
+ * the same layout — one flat key -> text object per language plus a DICTS
+ * table — so all three dictionaries stay readable and a new language can be
+ * added the same way in each.
+ *
+ * These keys cover only text the Host generates and ships with a payload
+ * (session fallbacks, answer validation, the pre-app pairing page).
+ */
+
+import type { PluginLocale } from './settings.js';
+
+export const zh = {
+  answerWaiting: '正在等待你的回答',
+  answerCountMismatch: '回答数量不匹配：需要 {expected} 项，收到 {received} 项',
+  answerDuplicate: '回答项重复或缺少问题编号',
+  answerUnknownQuestion: '回答项不属于当前问题',
+  answerSingleChoice: '单选题只能选择一个选项',
+  answerOptionGone: '选择的选项已不在问题中',
+  answerMissingQuestion: '回答缺少问题',
+  answerExpired: '这个问题已经结束或不在等待回答',
+  answerNeedsDsh: '这个问题需要在 DSH 中回答',
+  answerMissingId: '缺少问题编号，无法回答',
+  answerUnsupported: '当前 DSH 不支持远程回答',
+  answerNotWaiting: '这个问题已经不再等待回答',
+  answerPushOff: '推送问询已关闭',
+  answerInvalid: '回答格式无效',
+  approvalPrompt: '需要允许 {tool} 执行',
+  approvalTool: '工具',
+  newSession: '新会话',
+  turnFailed: '本轮运行出错',
+  turnBlocked: '本轮被阻止',
+  pairingTitle: '需要配对',
+  pairingBody: '请从 DSH 侧边栏的远程控制台重新扫码。',
+} as const;
+
+export type HostMessageKey = keyof typeof zh;
+
+export const en: Record<HostMessageKey, string> = {
+  answerWaiting: 'Waiting for your answer',
+  answerCountMismatch: 'Answer count mismatch: expected {expected}, received {received}',
+  answerDuplicate: 'Duplicate answer or missing question id',
+  answerUnknownQuestion: 'An answer does not belong to the current question',
+  answerSingleChoice: 'A single-choice question accepts one option',
+  answerOptionGone: 'A selected option is no longer part of the question',
+  answerMissingQuestion: 'An answer is missing for one question',
+  answerExpired: 'This question has finished or is no longer waiting',
+  answerNeedsDsh: 'Answer this question in DSH',
+  answerMissingId: 'The question id is missing; cannot answer',
+  answerUnsupported: 'This DSH build does not support remote answers',
+  answerNotWaiting: 'This question is no longer waiting for an answer',
+  answerPushOff: 'Pushed inquiries are turned off',
+  answerInvalid: 'The answer format is invalid',
+  approvalPrompt: 'Allow {tool} to run',
+  approvalTool: 'the tool',
+  newSession: 'New session',
+  turnFailed: 'This turn failed',
+  turnBlocked: 'This turn was blocked',
+  pairingTitle: 'Pairing required',
+  pairingBody: 'Scan the QR code again from the Remote control panel in the DSH sidebar.',
+};
+
+/** Every shipped dictionary, keyed by locale code. */
+export const DICTS: Record<PluginLocale, Record<HostMessageKey, string>> = { zh, en };
+
+/** Translate one Host message; unknown placeholders stay verbatim. */
+export function hostMessage(
+  locale: PluginLocale,
+  key: HostMessageKey,
+  params?: Record<string, string | number>,
+): string {
+  const template = DICTS[locale]?.[key] ?? en[key];
+  if (!params) return template;
+  return template.replace(/\{(\w+)\}/g, (match, name: string) =>
+    name in params ? String(params[name]) : match,
+  );
+}

package/src/dsh/lib/media-enrich.ts

@@ -0,0 +1,202 @@
+/**
+ * Shared media enrichment for the Rust probe result.
+ *
+ * It normalises the raw payload, projects the timeline between polls, and
+ * decides whether seeking is trustworthy. NetEase cover/liked data is resolved
+ * in Rust (`vendor::netease`) and arrives already attached to the payload.
+ */
+
+import type { ProbeMediaResult, PublicMedia } from './types.js';
+import { clamp, finiteNumber } from './util.js';
+
+/** Smoothed playback position for one track, carried between polls. */
+interface ProgressState {
+  key: string;
+  position: number;
+  at: number;
+  playing: boolean;
+}
+
+/** A seek this adapter just issued; the player needs a moment to catch up. */
+interface PendingSeek {
+  key: string;
+  position: number;
+  until: number;
+}
+
+/** Whether the current track has ever reported a usable position. */
+interface PositionEvidence {
+  key: string;
+  seen: boolean;
+  playing: boolean;
+}
+
+/** Stateful enricher shared by one media adapter. */
+export interface MediaEnrichment {
+  enrich(result: ProbeMediaResult | null | undefined): Promise<PublicMedia | null>;
+  markSeek(key: string, position: number, until?: number): void;
+  reset(): void;
+}
+
+export function publicMedia(result: ProbeMediaResult | null | undefined): PublicMedia | null {
+  const media = result?.media;
+  if (!result || !media) return null;
+  const provider: PublicMedia['provider'] =
+    media.provider === 'private' || media.provider === 'accessibility' ? media.provider : 'system';
+  return {
+    appId: media.appId || '',
+    appName: '',
+    title: media.title || '未命名媒体',
+    artist: media.artist || '',
+    album: media.album || '',
+    albumArtist: media.albumArtist || '',
+    playbackStatus: media.playbackStatus || 'Closed',
+    autoRepeatMode: media.autoRepeatMode || '',
+    shuffleActive: Boolean(media.shuffleActive),
+    position: Math.max(0, finiteNumber(media.position, 0) || 0),
+    startTime: Math.max(0, finiteNumber(media.startTime, 0) || 0),
+    endTime: Math.max(0, finiteNumber(media.endTime, 0) || 0),
+    minSeekTime: Math.max(0, finiteNumber(media.minSeekTime, 0) || 0),
+    maxSeekTime: Math.max(0, finiteNumber(media.maxSeekTime, 0) || 0),
+    lastUpdatedAt: finiteNumber(media.lastUpdatedAt, null),
+    canPlayPause: media.canPlayPause !== false,
+    canNext: media.canNext !== false,
+    canPrevious: media.canPrevious !== false,
+    canSeek: Boolean(media.canSeek),
+    provider,
+    providerDetail: media.providerDetail ? String(media.providerDetail) : null,
+    thumbnail: media.thumbnail || null,
+    thumbnailUrl: media.thumbnailUrl || null,
+    thumbnailType: media.thumbnailType || null,
+    liked: typeof media.liked === 'boolean' ? media.liked : null,
+    canLike: Boolean(media.canLike),
+    canSetLiked: Boolean(media.canSetLiked),
+    trackId: media.trackId || null,
+    estimatedDuration: Boolean(media.estimatedDuration),
+    sampledAt: finiteNumber(result.sampledAt, Date.now()) || Date.now(),
+  };
+}
+
+export function mediaKey(media: PublicMedia | null | undefined): string {
+  return `${media?.appId || ''}|${media?.title || ''}|${media?.artist || ''}`;
+}
+
+function timelineAnchor(value: number | null, sampledAt: number): number | null {
+  const anchor = finiteNumber(value, null);
+  if (!anchor || anchor <= 0) return null;
+  const age = sampledAt - anchor;
+  return age >= -5000 && age <= 6 * 60 * 60 * 1000 ? anchor : null;
+}
+
+/**
+ * Creates a stateful enricher. One instance per media adapter (the smoothing and
+ * "has this player ever reported a position" evidence are per adapter).
+ */
+export function createMediaEnrichment(): MediaEnrichment {
+  let progress: ProgressState | null = null;
+  let pendingSeek: PendingSeek | null = null;
+  let positionEvidence: PositionEvidence | null = null;
+
+  async function enrich(result: ProbeMediaResult | null | undefined): Promise<PublicMedia | null> {
+    const sampledAt = finiteNumber(result?.sampledAt, Date.now()) || Date.now();
+    let media = publicMedia(result);
+    if (!media) {
+      progress = null;
+      pendingSeek = null;
+      positionEvidence = null;
+      return null;
+    }
+
+    const rawStart = Math.max(0, Number(media.startTime) || 0);
+    const rawEnd = Math.max(0, Number(media.endTime) || 0);
+    const rawPosition = Math.max(0, Number(media.position) || 0);
+    const hasTimeline = rawEnd > rawStart && rawEnd > 0;
+    const systemProvider = media.provider === 'system';
+    const playing = String(media.playbackStatus).toLowerCase() === 'playing';
+    const key = mediaKey(media);
+
+    // A seekable flag can be true even when a player never reports a usable
+    // position (some older clients do this). Only allow seeking after we have
+    // actually seen a non-zero position for this track.
+    if (!positionEvidence || positionEvidence.key !== key) {
+      positionEvidence = { key, seen: rawPosition > 0.01, playing };
+    } else {
+      // Replaying the same track from 0 starts a new position session even if
+      // the title/artist key is unchanged; do not inherit the old seek grant.
+      if (playing && !positionEvidence.playing && rawPosition <= 0.01) positionEvidence.seen = false;
+      if (rawPosition > 0.01) positionEvidence.seen = true;
+      positionEvidence.playing = playing;
+    }
+    const hasPositionReport = positionEvidence.seen;
+    // Only a complete system session (SMTC/MPRIS/MediaRemote) may seek. The
+    // NetEase CDP page supplies progress and transport control, but never a
+    // seekable timeline unless the system session explicitly reports one.
+    const canSeek =
+      Boolean(media.canSeek) && systemProvider && hasTimeline && hasPositionReport;
+    const timelineSource: PublicMedia['timelineSource'] = !hasTimeline
+      ? 'none'
+      : systemProvider
+        ? 'smtc'
+        : media.provider === 'accessibility'
+          ? 'accessibility'
+          : 'private';
+
+    media.canSeek = canSeek;
+    media.positionReported = hasPositionReport;
+    media.timelineSource = timelineSource;
+    media.estimatedDuration = false;
+
+    const end = Math.max(0, Number(media.endTime) || 0);
+    const start = Math.max(0, Number(media.startTime) || 0);
+    const duration = end > start ? end - start : end;
+    const clampPosition = (value: number): number =>
+      (duration > 0 ? clamp(value, start, start + duration) : Math.max(0, value));
+
+    if (pendingSeek && (pendingSeek.key !== key || sampledAt >= pendingSeek.until)) pendingSeek = null;
+
+    // SMTC timelines report Position at LastUpdatedTime. Project it forward for
+    // players that only refresh the timeline a few times per track.
+    const anchor = timelineAnchor(media.lastUpdatedAt, sampledAt);
+    let reported = rawPosition;
+    if (playing && hasTimeline && anchor) reported += (sampledAt - anchor) / 1000;
+    reported = clampPosition(reported);
+
+    if (!progress || progress.key !== key) {
+      progress = { key, position: reported, at: sampledAt, playing };
+    } else {
+      const elapsed = progress.playing ? Math.max(0, (sampledAt - progress.at) / 1000) : 0;
+      let position = clampPosition(progress.position + elapsed);
+      // Treat 0 as "no position report" while playing: several players expose a
+      // duration but keep Position at 0, and snapping back would freeze the bar.
+      const reportUsable = rawPosition > 0.01;
+      if (reportUsable) {
+        const delta = reported - position;
+        if (Math.abs(delta) > 2.5) position = reported;
+        else if (Math.abs(delta) > 0.35) position = clampPosition(position + delta * 0.45);
+      }
+      if (playing !== progress.playing && reportUsable) position = reported;
+      progress = { key, position, at: sampledAt, playing };
+    }
+
+    if (pendingSeek) {
+      progress = { key, position: clampPosition(pendingSeek.position), at: sampledAt, playing };
+    }
+
+    media.position = progress.position;
+    media.sampledAt = sampledAt;
+    return media;
+  }
+
+  /** Hold a requested seek position while the player catches up. */
+  function markSeek(key: string, position: number, until: number = Date.now() + 2600): void {
+    pendingSeek = { key, position, until };
+  }
+
+  function reset(): void {
+    progress = null;
+    pendingSeek = null;
+    positionEvidence = null;
+  }
+
+  return { enrich, markSeek, reset };
+}