@anionex/dsh-eye-care 0.1.0

package/src/client/controller.ts

@@ -0,0 +1,435 @@
+/** Eye-care state owner: durable settings synchronization plus theme lifecycle. */
+
+import type { ClientConnectionRpc } from '@deepseek-ai/dsh-client-connection/client'
+import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ThemeRuntime, ThemeSnapshot } from '@deepseek-ai/dsh-client-ui-theme/client'
+import {
+  DEFAULT_EYE_CARE_SETTINGS,
+  decodeEyeCareSnapshot,
+  EYE_CARE_RPC_CHANNEL,
+  EYE_CARE_RPC_READ,
+  EYE_CARE_RPC_SAVE,
+  type EyeCareIntensity,
+  type EyeCareMode,
+  type EyeCareSettings,
+  type EyeCareSettingsSnapshot,
+} from '../shared.ts'
+import {
+  EYE_CARE_THEMES,
+  eyeCareThemeId,
+  isEyeCareThemeId,
+} from './themes.ts'
+
+/** State consumed by the General-settings row. */
+export interface EyeCareState {
+  /** Current eye-care selection. */
+  settings: EyeCareSettings
+  /** Persistence lifecycle. */
+  status: 'loading' | 'ready' | 'saving' | 'unavailable' | 'error'
+  /** Whether the Host settings document can be written. */
+  writable: boolean
+  /** Host namespace revision for the next write. */
+  revision: number | undefined
+  /** User-facing read or write failure, when one stands. */
+  error: string | null
+}
+
+/** Inputs isolated for deterministic controller tests. */
+export interface EyeCareControllerOptions {
+  /** DSH theme registry. */
+  theme: Pick<ThemeRuntime, 'getTheme' | 'setTheme' | 'register'>
+  /** Snapshot change subscription. */
+  subscribeTheme(listener: (snapshot: ThemeSnapshot) => void): () => void
+  /** Loopback-only Connection RPC; absent remote browsers stay process-local. */
+  rpc?: ClientConnectionRpc
+  /** System dark-mode sensor. */
+  media?: MediaQueryList
+  /** Monotonic wall-clock source used only by the one-shot startup adoption fence. */
+  now?: () => number
+}
+
+const INITIAL_STATE: EyeCareState = {
+  settings: { ...DEFAULT_EYE_CARE_SETTINGS },
+  status: 'loading',
+  writable: false,
+  revision: undefined,
+  error: null,
+}
+
+/** Maximum delay accepted for ui-theme's already-started Host adoption. */
+const STARTUP_BASE_THEME_GRACE_MS = 1000
+
+function sameSettings(left: EyeCareSettings, right: EyeCareSettings): boolean {
+  return left.mode === right.mode && left.intensity === right.intensity
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/** Stateful controller shared by theme listeners and the Settings row. */
+export class EyeCareController {
+  /** Reactive row source. */
+  readonly store: SnapshotStore<EyeCareState> = createSnapshotStore(INITIAL_STATE)
+
+  private readonly theme: EyeCareControllerOptions['theme']
+  private readonly rpc: ClientConnectionRpc | undefined
+  private readonly media: MediaQueryList | undefined
+  private readonly now: () => number
+  private readonly unregisterThemes: Array<() => void> = []
+  private unsubscribeTheme: (() => void) | undefined
+  private unsubscribeMedia: (() => void) | undefined
+  private tail: Promise<void> = Promise.resolve()
+  private disposeTask: Promise<void> | undefined
+  private pendingSettings: EyeCareSettings | undefined
+  private disposed = false
+  private applyingTheme = 0
+  private restoreTheme = 'system'
+  private hasRestoreTheme = false
+  private acceptedRemoteSnapshot = false
+  private startupBaseTheme: 'light' | 'dark' | 'system' | undefined
+  private startupBaseThemeDeadline = 0
+
+  /**
+   * Register the concrete themes and lifecycle listeners.
+   * @param options - theme, transport, and system-scheme collaborators.
+   */
+  constructor(options: EyeCareControllerOptions) {
+    this.theme = options.theme
+    this.rpc = options.rpc
+    this.now = options.now ?? Date.now
+    this.media = options.media ?? (typeof matchMedia === 'function' ? matchMedia('(prefers-color-scheme: dark)') : undefined)
+    const currentTheme = this.theme.getTheme().preference
+    if (!isEyeCareThemeId(currentTheme)) {
+      this.restoreTheme = currentTheme
+      this.hasRestoreTheme = true
+    }
+    try {
+      for (const definition of EYE_CARE_THEMES) {
+        this.unregisterThemes.push(this.theme.register(definition))
+      }
+      this.unsubscribeTheme = options.subscribeTheme(snapshot => { this.onThemeChanged(snapshot) })
+      if (this.media !== undefined) {
+        const media = this.media
+        const listener = (): void => {
+          if (!this.disposed && this.store.getSnapshot().settings.mode === 'auto') this.applyCurrentTheme()
+        }
+        media.addEventListener('change', listener)
+        this.unsubscribeMedia = () => { media.removeEventListener('change', listener) }
+      }
+    } catch (error) {
+      for (const unregister of this.unregisterThemes.splice(0).reverse()) unregister()
+      throw error
+    }
+  }
+
+  /**
+   * Load durable settings without blocking plugin activation.
+   * @returns settlement after this read reaches the serialized transport queue.
+   */
+  load(): Promise<void> {
+    if (this.rpc === undefined) {
+      this.setUnavailable()
+      return Promise.resolve()
+    }
+    if (this.store.getSnapshot().revision === undefined) {
+      this.store.update(state => {
+        state.status = 'loading'
+        state.error = null
+      })
+    }
+    return this.enqueue(async () => { await this.readRemote() })
+  }
+
+  /**
+   * Select a mode and persist the latest selection when Host settings are writable.
+   * @param mode - next operating mode.
+   * @returns settlement after the serialized persistence attempt.
+   */
+  setMode(mode: EyeCareMode): Promise<void> {
+    return this.select({ ...this.store.getSnapshot().settings, mode })
+  }
+
+  /**
+   * Select a warmth and persist the latest selection when Host settings are writable.
+   * @param intensity - next warmth level.
+   * @returns settlement after the serialized persistence attempt.
+   */
+  setIntensity(intensity: EyeCareIntensity): Promise<void> {
+    return this.select({ ...this.store.getSnapshot().settings, intensity })
+  }
+
+  /** Queue a refresh after a Host settings invalidation. */
+  refresh(): void {
+    void this.load()
+  }
+
+  /**
+   * Reach transport quiescence, restore the user's live non-eye-care theme, and unregister all resources.
+   * @returns settlement after cleanup completes.
+   */
+  dispose(): Promise<void> {
+    return this.disposeTask ??= this.disposeOnce()
+  }
+
+  private async disposeOnce(): Promise<void> {
+    this.disposed = true
+    this.pendingSettings = undefined
+
+    const failures: unknown[] = []
+    for (const unsubscribe of [this.unsubscribeMedia, this.unsubscribeTheme]) {
+      if (unsubscribe === undefined) continue
+      try { unsubscribe() } catch (error) { failures.push(error) }
+    }
+    this.unsubscribeMedia = undefined
+    this.unsubscribeTheme = undefined
+
+    await this.tail
+
+    const current = this.theme.getTheme()
+    if (isEyeCareThemeId(current.preference)) {
+      try {
+        this.setTheme(this.resolveRestoreTheme())
+      } catch (error) {
+        failures.push(error)
+        try { this.setTheme('system') } catch (fallbackError) { failures.push(fallbackError) }
+      }
+    }
+    for (const unregister of this.unregisterThemes.splice(0).reverse()) {
+      try { unregister() } catch (error) { failures.push(error) }
+    }
+    if (failures.length > 0) throw new AggregateError(failures, 'eye-care cleanup failed')
+  }
+
+  private enqueue(operation: () => Promise<void>): Promise<void> {
+    if (this.disposed) return Promise.resolve()
+    const task = this.tail.then(async () => {
+      if (!this.disposed) await operation()
+    })
+    this.tail = task.catch(() => {})
+    return task
+  }
+
+  private select(settings: EyeCareSettings): Promise<void> {
+    if (this.disposed) return Promise.resolve()
+    const previous = this.store.getSnapshot().settings
+    if (previous.mode === 'off' && settings.mode !== 'off') this.captureRestoreTheme()
+    this.store.update(state => {
+      state.settings = settings
+      state.error = null
+      if (state.status === 'error') state.status = state.revision === undefined ? 'unavailable' : 'ready'
+    })
+    this.applyCurrentTheme()
+    return this.persist(settings)
+  }
+
+  private persist(settings: EyeCareSettings): Promise<void> {
+    const state = this.store.getSnapshot()
+    if (this.rpc === undefined) {
+      this.setUnavailable(state.error)
+      return Promise.resolve()
+    }
+    if (state.revision !== undefined && !state.writable) {
+      this.setUnavailable(state.error)
+      return Promise.resolve()
+    }
+    this.pendingSettings = { ...settings }
+    return this.enqueue(async () => { await this.flushPending() })
+  }
+
+  private async flushPending(): Promise<void> {
+    while (!this.disposed && this.pendingSettings !== undefined) {
+      const desired = this.pendingSettings
+      this.pendingSettings = undefined
+
+      let state = this.store.getSnapshot()
+      if (state.revision === undefined) {
+        if (this.pendingSettings === undefined) this.pendingSettings = desired
+        if (!await this.readRemote()) return
+        continue
+      }
+      if (!state.writable || state.revision === undefined) {
+        this.setUnavailable(state.error)
+        return
+      }
+
+      this.store.update(next => {
+        next.status = 'saving'
+        next.error = null
+      })
+      let response: Awaited<ReturnType<ClientConnectionRpc['call']>>
+      try {
+        const rpc = this.rpc
+        if (rpc === undefined) return
+        response = await rpc.call(EYE_CARE_RPC_CHANNEL, EYE_CARE_RPC_SAVE, {
+          expectedRevision: state.revision,
+          value: desired,
+        })
+      } catch (error) {
+        if (!this.disposed) this.setUnavailable(messageOf(error))
+        return
+      }
+      if (this.disposed) return
+      if (!response.ok) {
+        if (response.error.code === 'settings-conflict') {
+          const latest = this.pendingSettings ?? desired
+          this.pendingSettings = latest
+          if (!await this.readRemote()) return
+          if (this.disposed) return
+          continue
+        }
+        this.setUnavailable(response.error.message)
+        return
+      }
+      const snapshot = decodeEyeCareSnapshot(response.value)
+      if (snapshot === undefined) {
+        this.store.update(next => {
+          next.status = 'error'
+          next.error = 'eye-care Settings returned an invalid save response'
+        })
+        return
+      }
+      const preserveSettings = this.pendingSettings !== undefined
+        || !sameSettings(this.store.getSnapshot().settings, desired)
+      this.accept(snapshot, preserveSettings)
+    }
+  }
+
+  private async readRemote(): Promise<boolean> {
+    let response: Awaited<ReturnType<ClientConnectionRpc['call']>>
+    try {
+      const rpc = this.rpc
+      if (rpc === undefined) return false
+      response = await rpc.call(EYE_CARE_RPC_CHANNEL, EYE_CARE_RPC_READ, {})
+    } catch (error) {
+      if (!this.disposed) this.setUnavailable(messageOf(error), true)
+      return false
+    }
+    if (this.disposed) return false
+    if (!response.ok) {
+      this.setUnavailable(response.error.message, true)
+      return false
+    }
+    const snapshot = decodeEyeCareSnapshot(response.value)
+    if (snapshot === undefined) {
+      this.store.update(state => {
+        state.status = 'error'
+        state.error = 'eye-care Settings returned an invalid read response'
+      })
+      return false
+    }
+    this.accept(snapshot, this.pendingSettings !== undefined)
+    return true
+  }
+
+  private accept(snapshot: EyeCareSettingsSnapshot, preserveSettings: boolean): void {
+    const previous = this.store.getSnapshot().settings
+    const next = preserveSettings ? previous : snapshot.settings.value
+    const firstRemote = !this.acceptedRemoteSnapshot
+    this.acceptedRemoteSnapshot = true
+
+    if (next.mode === 'off') {
+      this.startupBaseTheme = undefined
+      this.startupBaseThemeDeadline = 0
+      if (!this.hasRestoreTheme && snapshot.baseThemePreference !== undefined) {
+        this.restoreTheme = snapshot.baseThemePreference
+        this.hasRestoreTheme = true
+      }
+    } else if (firstRemote) {
+      const base = snapshot.baseThemePreference
+      if (base === undefined) {
+        if (!this.hasRestoreTheme) this.captureRestoreTheme()
+      } else {
+        this.restoreTheme = base
+        this.hasRestoreTheme = true
+        if (this.theme.getTheme().preference !== base) {
+          this.startupBaseTheme = base
+          this.startupBaseThemeDeadline = this.now() + STARTUP_BASE_THEME_GRACE_MS
+        }
+      }
+    } else if (!preserveSettings && previous.mode === 'off') {
+      this.captureRestoreTheme(snapshot.baseThemePreference)
+    }
+
+    this.store.set({
+      settings: next,
+      status: snapshot.writable ? 'ready' : 'unavailable',
+      writable: snapshot.writable,
+      revision: snapshot.settings.revision,
+      error: null,
+    })
+    this.applyCurrentTheme()
+  }
+
+  private setUnavailable(error: string | null = null, clearRevision = false): void {
+    this.store.update(state => {
+      state.status = 'unavailable'
+      state.writable = false
+      if (clearRevision) state.revision = undefined
+      state.error = error
+    })
+  }
+
+  private captureRestoreTheme(fallback?: 'light' | 'dark' | 'system'): void {
+    const preference = this.theme.getTheme().preference
+    const candidate = isEyeCareThemeId(preference) ? fallback ?? 'system' : preference
+    this.restoreTheme = candidate
+    this.hasRestoreTheme = true
+  }
+
+  private resolveRestoreTheme(): string {
+    if (!this.hasRestoreTheme || this.restoreTheme === 'system') return 'system'
+    return this.theme.getTheme().themes.some(theme => theme.id === this.restoreTheme)
+      ? this.restoreTheme
+      : 'system'
+  }
+
+  private applyCurrentTheme(): void {
+    const { mode, intensity } = this.store.getSnapshot().settings
+    const current = this.theme.getTheme().preference
+    if (mode === 'off') {
+      if (isEyeCareThemeId(current)) this.setTheme(this.resolveRestoreTheme())
+      this.hasRestoreTheme = false
+      return
+    }
+    if (!this.hasRestoreTheme) this.captureRestoreTheme()
+    const scheme = mode === 'auto' ? (this.media?.matches === true ? 'dark' : 'light') : mode
+    this.setTheme(eyeCareThemeId(scheme, intensity))
+  }
+
+  private setTheme(id: string): void {
+    if (this.theme.getTheme().preference === id) return
+    this.applyingTheme += 1
+    try {
+      this.theme.setTheme(id)
+    } finally {
+      this.applyingTheme -= 1
+    }
+  }
+
+  private onThemeChanged(snapshot: ThemeSnapshot): void {
+    if (this.disposed || this.applyingTheme > 0 || isEyeCareThemeId(snapshot.preference)) return
+    if (this.startupBaseTheme !== undefined) {
+      const expected = this.startupBaseTheme
+      const withinStartupWindow = this.now() <= this.startupBaseThemeDeadline
+      this.startupBaseTheme = undefined
+      this.startupBaseThemeDeadline = 0
+      if (withinStartupWindow && snapshot.preference === expected) {
+        this.restoreTheme = expected
+        this.hasRestoreTheme = true
+        this.applyCurrentTheme()
+        return
+      }
+    }
+    const state = this.store.getSnapshot()
+    if (state.settings.mode === 'off') return
+    this.restoreTheme = snapshot.preference
+    this.hasRestoreTheme = true
+    const settings = { ...state.settings, mode: 'off' as const }
+    this.store.update(next => {
+      next.settings = settings
+      next.error = null
+    })
+    void this.persist(settings)
+  }
+}

package/src/client/css-modules.d.ts

@@ -0,0 +1,5 @@
+/** CSS Module class maps emitted by the browser bundle. */
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}

package/src/client/index.tsx

@@ -0,0 +1,72 @@
+/** DSH Web browser half for the eye-care profile bundle. */
+
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ThemeRuntime, ThemeSnapshot } from '@deepseek-ai/dsh-client-ui-theme/client'
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+import type {} from '@deepseek-ai/dsh-api-remotes/client'
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import type {} from '@deepseek-ai/dsh-client-ui-theme/client'
+import { EyeCareRow, type EyeCareRowInjected } from './EyeCareRow.tsx'
+import { EyeCareController } from './controller.ts'
+import { en, zh, type EyeCareKey } from './locales.ts'
+
+/** Required browser services. */
+export const inject = ['slots', 'locale', 'theme', 'connection', 'remote']
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** Eye-care General row copy. */
+    'settings.eyeCare': EyeCareKey
+  }
+}
+
+/** Browser context with the theme service declaration merged by ui-theme. */
+type EyeCareClientContext = ClientContext & { theme: ThemeRuntime }
+
+/** Register settings copy, controller lifecycle, and General row. */
+export function apply(ctx: EyeCareClientContext): void {
+  const theme = ctx.get('theme') as ThemeRuntime
+  const connection = ctx.get('connection') as ConnectionHandle
+  const controller = new EyeCareController({
+    theme,
+    ...(connection.isLoopback ? { rpc: connection.rpc } : {}),
+    subscribeTheme: (listener: (snapshot: ThemeSnapshot) => void): (() => void) => ctx.on('theme/change', listener),
+  })
+  ctx.effect(() => ctx.locale.register('settings.eyeCare', { zh, en }), 'dsh-eye-care: dictionaries')
+  ctx.effect(() => {
+    const refresh = (namespace?: string): void => {
+      if (namespace !== undefined && namespace !== 'eye-care') return
+      controller.refresh()
+    }
+    const disposers = [
+      ctx.remote.$on('settings/document-updated', refresh),
+      ctx.on('connection/reset', () => {
+        if (connection.isLoopback) controller.refresh()
+      }),
+    ]
+    void controller.load()
+    return async () => {
+      for (const dispose of disposers) dispose()
+      await controller.dispose()
+    }
+  }, 'dsh-eye-care: controller lifecycle')
+
+  const injected = (): EyeCareRowInjected => ({
+    hooks: { eyeCare: controller.store },
+    setMode: mode => controller.setMode(mode),
+    setIntensity: intensity => controller.setIntensity(intensity),
+  })
+  ctx.slots.inject('settings.general.item', () => ctx.slots.register({
+    name: 'settings.general.item',
+    id: 'eye-care',
+    order: 15,
+    locale: 'settings.eyeCare',
+    inject: injected,
+  }, EyeCareRow))
+}
+
+export type { EyeCareRowInjected, EyeCareRowProps } from './EyeCareRow.tsx'
+export type { EyeCareState } from './controller.ts'
+export { EyeCareController } from './controller.ts'
+export { EYE_CARE_THEMES, eyeCareThemeId, isEyeCareThemeId } from './themes.ts'

package/src/client/locales.ts

@@ -0,0 +1,56 @@
+/** `settings.eyeCare` dictionaries. */
+
+/** Simplified Chinese dictionary. */
+export const zh = {
+  'title': '护眼模式',
+  'description': '降低页面的冷白光感，长时间阅读更柔和。',
+  'enabled.title': '护眼模式',
+  'enabled.off': '关闭',
+  'enabled.on': '开启',
+  'advanced.title': '显示方式与暖色强度',
+  'mode.title': '显示方式',
+  'mode.off': '关闭',
+  'mode.auto': '自动',
+  'mode.light': '日间',
+  'mode.dark': '夜间',
+  'intensity.title': '暖色强度',
+  'intensity.soft': '柔和',
+  'intensity.balanced': '均衡',
+  'intensity.warm': '温暖',
+  'status.off': '护眼模式已关闭',
+  'status.auto': '自动跟随系统明暗外观',
+  'status.light': '正在使用暖色日间主题',
+  'status.dark': '正在使用暖暗夜间主题',
+  'status.local': '仅当前浏览器有效',
+  'status.saving': '正在保存',
+  'status.error': '设置暂未保存',
+} satisfies Record<string, string>
+
+/** Dictionary key union. */
+export type EyeCareKey = keyof typeof zh
+
+/** English dictionary. */
+export const en = {
+  'title': 'Eye care',
+  'description': 'Use warm semantic themes to reduce cool-white glare during long reading sessions',
+  'enabled.title': 'Eye care',
+  'enabled.off': 'Off',
+  'enabled.on': 'On',
+  'advanced.title': 'Appearance and warmth',
+  'mode.title': 'Appearance',
+  'mode.off': 'Off',
+  'mode.auto': 'Auto',
+  'mode.light': 'Day',
+  'mode.dark': 'Night',
+  'intensity.title': 'Warmth',
+  'intensity.soft': 'Soft',
+  'intensity.balanced': 'Balanced',
+  'intensity.warm': 'Warm',
+  'status.off': 'Eye care is off',
+  'status.auto': 'Following the system light or dark appearance',
+  'status.light': 'Warm day theme is active',
+  'status.dark': 'Warm night theme is active',
+  'status.local': 'Current browser only',
+  'status.saving': 'Saving',
+  'status.error': 'Setting is not saved yet',
+} satisfies Record<EyeCareKey, string>