@yunlefun-home/air-conditioner-core 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,6 +1,30 @@
 //#region src/types.d.ts
-type AcMode = 'cold' | 'hot';
-interface AcState {
+export type AcMode = 'cold' | 'hot';
+/**
+ * Sound mode: `normal` plays everything, `sleep` lowers the volume,
+ * `mute` silences the air conditioner.
+ */
+export type AcSoundMode = 'normal' | 'sleep' | 'mute';
+/**
+ * Fan speed (风速). `auto` lets the unit decide: strong at first, quieter
+ * once the room settles, with the occasional surge. The fixed speeds hold
+ * the airflow and fan sound steady.
+ */
+export type AcFanSpeed = 'auto' | 'low' | 'medium' | 'high';
+/**
+ * Temperature range a device supports. Real devices (e.g. Home Assistant
+ * climate entities) report their own range and step.
+ */
+export interface AcLimits {
+  min: number;
+  max: number;
+  step: number;
+}
+/**
+ * Visual tone of the unit: idle when off, otherwise follows the mode.
+ */
+export type AcTone = 'idle' | 'cool' | 'heat';
+export interface AcState {
   /**
    * Whether the air conditioner is powered on.
    */
@@ -10,75 +34,226 @@ interface AcState {
    */
   mode: AcMode;
   /**
-   * Target temperature in Celsius.
+   * Target temperature in Celsius, for the current mode.
    */
   temperature: number;
+  /**
+   * Last target temperature of each mode, like a real remote: switching
+   * from 制冷 20 °C to 制热 and back restores 20 °C. `normalizeAcState`
+   * always fills it in, with the current mode holding `temperature`; states
+   * saved before this field existed start with both modes at their saved
+   * temperature. Optional so hand-written states keep type-checking.
+   */
+  temperatures?: Record<AcMode, number>;
+  /**
+   * Sound mode. States saved before this field existed fall back to `normal`.
+   */
+  sound: AcSoundMode;
+  /**
+   * Whether the airflow sweeps left and right. States saved before this
+   * field existed fall back to `false`.
+   */
+  swing: boolean;
+  /**
+   * Fan speed. `normalizeAcState` fills in `auto` for states saved before
+   * this field existed; optional so hand-written states keep type-checking.
+   */
+  fan?: AcFanSpeed;
 }
-type AcAction = {
-  type: 'increment' | 'decrement' | 'toggleStatus';
+export type AcAction = {
+  type: 'increment' | 'decrement' | 'toggleStatus' | 'cycleSound' | 'toggleSwing' | 'cycleFan';
 } | {
   type: 'status';
   status: AcState['status'];
-} | {
+} |
+/**
+ * 切换模式。`powerOn` 为 true 时关机状态下顺便开机（遥控器的模式键就是这样）；
+ * Home Assistant 等外部同步不传，只改模式。
+ */
+{
   type: 'mode';
   mode: AcState['mode'];
+  powerOn?: boolean;
+} | {
+  type: 'sound';
+  sound: AcState['sound'];
+} | {
+  type: 'swing';
+  swing: AcState['swing'];
+} | {
+  type: 'fan';
+  fan: AcFanSpeed;
 } | {
   type: 'update';
   payload: Partial<AcState>;
 };
-type AcNotificationSeverity = 'success' | 'error' | 'info';
-interface AcNotification {
+export type AcNotificationSeverity = 'success' | 'error' | 'info';
+/**
+ * What a notification is about, which decides how views present it:
+ *
+ * - `tip`：节能建议，以「出风口吹出的小纸条」显示
+ * - `limit`：温度到了上下限，遥控器小屏抖一下，不弹提示
+ * - `setting`：风速、声音、扫风等设置变化，小屏已经显示，只给读屏播报
+ */
+export type AcNotificationKind = 'tip' | 'limit' | 'setting';
+export interface AcNotification {
   message: string;
   severity: AcNotificationSeverity;
+  /** Absent on notifications from before kinds existed; treat as `tip`. */
+  kind?: AcNotificationKind;
+  /** A second, quieter line, e.g. why a tip matters. */
+  detail?: string;
 }
-interface AcChangeEvent {
+export interface AcChangeEvent {
   action: AcAction;
   previousState: AcState;
   state: AcState;
   notification?: AcNotification;
 }
-type AcStoreListener = (event: AcChangeEvent) => void;
-interface AcStorage {
+export type AcStoreListener = (event: AcChangeEvent) => void;
+export interface AcStorage {
   getItem: (key: string) => string | null;
   setItem: (key: string, value: string) => void;
   removeItem?: (key: string) => void;
 }
-interface CreateAirConditionerStoreOptions {
+export interface CreateAirConditionerStoreOptions {
   initialState?: Partial<AcState>;
+  /**
+   * Device temperature limits. Defaults to 16–31 °C with a step of 1.
+   */
+  limits?: AcLimits;
   storage?: AcStorage | null;
   storageKey?: string;
   onNotify?: (notification: AcNotification, event: AcChangeEvent) => void;
 }
-interface AirConditionerStore {
+export interface AirConditionerStore {
   getState: () => AcState;
   dispatch: (action: AcAction) => AcChangeEvent;
   subscribe: (listener: AcStoreListener) => () => void;
 }
-interface AcAudioElement {
+/**
+ * The subset of `HTMLAudioElement` the audio controller uses. The optional
+ * members let it pause, loop and set volume when they exist.
+ */
+export interface AcAudioElement {
   currentTime: number;
   load: () => void;
   play: () => Promise<unknown> | unknown;
+  pause?: () => void;
+  volume?: number;
+  muted?: boolean;
+  loop?: boolean;
+  /** Used to fetch the file for Web Audio playback. */
+  src?: string;
+  currentSrc?: string;
 }
-interface AcAudioElements {
+export interface AcAudioElements {
   start: AcAudioElement | null;
   work: AcAudioElement | null;
   beep?: AcAudioElement | null;
 }
-interface AcAudioController {
+export interface AcAudioController {
   beep: () => void;
   toggleStatusAudio: (previousStatus: boolean) => void;
+  /**
+   * Change the volume of everything, including sounds already playing.
+   */
+  setSoundMode: (mode: AcSoundMode) => void;
+  /**
+   * Follow the fan speed: `auto` keeps the settle / surge cycle, fixed
+   * speeds hold the fan sound at a steady level.
+   */
+  setFanSpeed: (fan: AcFanSpeed) => void;
+  /**
+   * A soft synthesized drop of condensation (#21). Only in the `normal`
+   * sound mode and only through Web Audio; otherwise silent.
+   */
+  drip: () => void;
   dispose: () => void;
 }
+export interface CreateAcAudioControllerOptions {
+  /**
+   * Initial sound mode.
+   * @default 'normal'
+   */
+  soundMode?: AcSoundMode;
+  /**
+   * Initial fan speed.
+   * @default 'auto'
+   */
+  fanSpeed?: AcFanSpeed;
+  /**
+   * Play through the Web Audio API for a gapless loop and smooth fades.
+   * Falls back to the `<audio>` elements when the API is missing or the
+   * files cannot be fetched (for example across origins without CORS).
+   * @default true
+   */
+  webAudio?: boolean;
+  /**
+   * Create the `AudioContext`. Defaults to `new AudioContext()`.
+   */
+  createAudioContext?: () => AudioContext;
+  /**
+   * Fetch an audio file. Defaults to `fetch(url)`.
+   */
+  loadAudioData?: (url: string) => Promise<ArrayBuffer>;
+  /**
+   * Random source for the fan's quiet / busy cycle. Defaults to `Math.random`.
+   */
+  random?: () => number;
+}
 //#endregion
 //#region src/audio.d.ts
-declare function createAcAudioController(elements: AcAudioElements): AcAudioController;
+/**
+ * 空调音效：按键「嘀」声、开机启动声与持续的风声。
+ *
+ * 默认通过 Web Audio API 播放：风声无缝循环，开关机淡入淡出，运行一段时间后
+ * 风声变小、并不定时随压缩机发力起伏。环境不支持或音频无法获取时退回
+ * `<audio>` 元素。
+ *
+ * 需在用户交互（点击遥控器）里首次调用，浏览器才允许发声。
+ *
+ * @param elements 三个音频元素；Web Audio 会从它们的 `src` 获取音频
+ * @param options 声音模式与可替换的环境依赖
+ */
+export declare function createAcAudioController(elements: AcAudioElements, options?: CreateAcAudioControllerOptions): AcAudioController;
+//#endregion
+//#region src/condensation.d.ts
+type CondensationState = Pick<AcState, 'status' | 'mode' | 'temperature'> & {
+  fan?: AcFanSpeed;
+};
+/** 高于这个设定温度不滴水：冷凝水不该常见，只在开得很冷时偶尔出现 */
+export declare const acDripMaxTemperature = 22;
+/** 最冷（16 °C）与 {@link acDripMaxTemperature} 时，两滴水之间的间隔（ms） */
+export declare const acDripIntervalRange: readonly [9000, 18000];
+/**
+ * 出风口雾气的浓度（#70），0–1：只在制冷开机时出现，设定温度越低、风越大越浓。
+ *
+ * 视图把它写进 CSS 变量 `--acw-mist`，3D 等其他渲染器也可以按它控制粒子数量。
+ */
+export declare function getAcMist(state: CondensationState): number;
+/**
+ * 冷凝水滴落的间隔（#21，ms）：只在制冷开机、设定温度不高于 {@link acDripMaxTemperature} 时滴水，
+ * 越冷越频繁，高风再快一些；不滴水时返回 `undefined`。
+ *
+ * 视图把它写进 CSS 变量 `--acw-drip-cycle`，水珠在出风口边缘慢慢聚起再落下，开机后要等一整个间隔才滴第一滴。
+ */
+export declare function getAcDripInterval(state: CondensationState): number | undefined;
+/**
+ * 视图要写到空调根元素上的雾气 / 滴水样式变量与属性。
+ */
+export declare function getAcCondensationStyle(state: CondensationState): {
+  mist: number;
+  dripCycle?: string;
+  drip: 'on' | 'off';
+};
 //#endregion
 //#region src/constants.d.ts
-declare const acStorageKey = "ac:state";
+export declare const acStorageKey = "ac:state";
 /**
  * 各模式对应的显示图标（供各框架视图层复用）。
  */
-declare const acModeIcons: Record<AcMode, string>;
+export declare const acModeIcons: Record<AcMode, string>;
 /**
  * 默认音频资源文件名（不含扩展名）。
  *
@@ -86,20 +261,77 @@ declare const acModeIcons: Record<AcMode, string>;
  * - `start` 空调启动声
  * - `work` 持续工作（出风）声
  */
-declare const acAudioFileNames: {
+export declare const acAudioFileNames: {
   readonly beep: "di";
   readonly start: "ac-work";
   readonly work: "air-extractor-fan";
 };
-declare const minTemperature = 16;
-declare const maxTemperature = 31;
-declare const recommendedColdTemperature = 26;
-declare const recommendedHotTemperature = 20;
-declare const defaultAcState: AcState;
-declare const soundTimings: {
+export declare const minTemperature = 16;
+export declare const maxTemperature = 31;
+export declare const defaultAcLimits: AcLimits;
+export declare const recommendedColdTemperature = 26;
+export declare const recommendedHotTemperature = 20;
+export declare const defaultAcState: AcState;
+/**
+ * 遥控器「声音」键依次切换的顺序。
+ */
+export declare const acSoundModes: readonly AcSoundMode[];
+/**
+ * 各模式的中文名称（遥控器小屏与按键提示共用）。
+ */
+export declare const acModeLabels: Record<AcMode, string>;
+export declare const acSoundModeLabels: Record<AcSoundMode, string>;
+/**
+ * 各声音模式的总音量（0–1）。
+ */
+export declare const acSoundVolumes: Record<AcSoundMode, number>;
+/**
+ * 遥控器「风速」键依次切换的顺序。
+ */
+export declare const acFanSpeeds: readonly AcFanSpeed[];
+export declare const acFanSpeedLabels: Record<AcFanSpeed, string>;
+/**
+ * 小屏上点亮的风速格数（1–3）。自动风速由空调自己决定，显示为 0 并另加「自动」标记。
+ */
+export declare const acFanBars: Record<AcFanSpeed, number>;
+/**
+ * 固定风速下风声的相对音量（0–1）；自动风速沿用开机后的「达标 / 发力」循环。
+ */
+export declare const acFanSoundLevels: Record<Exclude<AcFanSpeed, 'auto'>, number>;
+export declare function isAcFanSpeed(value: unknown): value is AcFanSpeed;
+/**
+ * 风速键的下一档：自动 → 低 → 中 → 高 → 自动。
+ */
+export declare function nextAcFanSpeed(fan: AcFanSpeed | undefined): AcFanSpeed;
+export declare function isAcSoundMode(value: unknown): value is AcSoundMode;
+/**
+ * 声音键的下一个模式：标准 → 睡眠 → 静音 → 标准。
+ */
+export declare function nextAcSoundMode(mode: AcSoundMode | undefined): AcSoundMode;
+/**
+ * 音效时序。时长单位为毫秒，`*Level` 是风声相对音量（0–1）。
+ */
+export declare const soundTimings: {
+  /** 开机后多久接上持续的风声（启动声约 9 秒） */
   readonly startDelayMs: 8000;
-  readonly noiseStartTime: 2;
-  readonly noiseDuration: 56;
+  /** 风声循环首尾的交叉淡化时长 */
+  readonly loopCrossfadeMs: 1500;
+  /** 关机时声音淡出时长 */
+  readonly stopFadeMs: 600;
+  /** 开机运行多久后室温达标、风声降下来 */
+  readonly settleAfterMs: 90000;
+  /** 风声降下来的渐变时长 */
+  readonly settleRampMs: 20000;
+  /** 达标后的安静风声 */
+  readonly settleLevel: 0.5;
+  /** 室温回升、压缩机重新发力时的风声 */
+  readonly surgeLevel: 0.85;
+  /** 两次发力之间安静运行的时长范围 */
+  readonly quietDurationMs: readonly [180000, 360000];
+  /** 每次发力持续的时长范围 */
+  readonly surgeDurationMs: readonly [60000, 120000];
+  /** 发力 / 回落的渐变时长 */
+  readonly surgeRampMs: 10000;
 };
 /**
  * 根据基础路径解析出三个音频文件的完整 URL。
@@ -109,26 +341,464 @@ declare const soundTimings: {
  * @param baseUrl 音频目录，如 `/assets/audio`
  * @param ext 文件扩展名，默认 `m4a`
  */
-declare function resolveAcAudioAssets(baseUrl?: string, ext?: string): {
+export declare function resolveAcAudioAssets(baseUrl?: string, ext?: string): {
   beep: string;
   start: string;
   work: string;
 };
 //#endregion
+//#region src/layout.d.ts
+/**
+ * 机身的设计尺寸（px），约 3:1，接近真实壁挂机（如 800–900mm × 280–300mm）的比例。
+ * 窄容器下按比例整体缩放，保持「长款」外观不被压扁。
+ *
+ * - `compact`：Vue / React 组件库 / Web Component 使用的 360 × 128 机身
+ * - `wide`：React 主站使用的 600 × 200 机身
+ */
+export declare const acShellSize: {
+  readonly compact: {
+    readonly width: 360;
+    readonly height: 128;
+  };
+  readonly wide: {
+    readonly width: 600;
+    readonly height: 200;
+  };
+};
+/**
+ * 根据可用宽度计算机身缩放比例：只缩小、不放大。
+ */
+export declare function getAcScale(availableWidth: number, designWidth: number): number;
+/**
+ * 监听容器宽度变化并回调缩放比例。
+ *
+ * 不支持 `ResizeObserver` 的环境（如 SSR）直接返回空的清理函数，保持 1 倍显示。
+ *
+ * @param target 被测量宽度的容器（不要传被缩放的元素本身）
+ * @param designWidth 机身的设计宽度
+ * @param onScale 比例变化时的回调
+ * @returns 停止监听的清理函数
+ */
+export declare function observeAcScale(target: Element, designWidth: number, onScale: (scale: number) => void): () => void;
+/** 指针跟随倾斜的最大角度（deg） */
+export declare const acMaxTilt = 4;
+/**
+ * 指针在元素上移动时回调轻微的 3D 倾斜角度（`rotateX` / `rotateY`，单位 deg），离开时回到 0。
+ *
+ * 仅在有悬停能力的精细指针（鼠标 / 触控板）上启用；`prefers-reduced-motion: reduce`、
+ * 触屏或 SSR 下直接返回空的清理函数。
+ *
+ * @returns 停止监听的清理函数
+ */
+export declare function observeAcTilt(target: HTMLElement, onTilt: (rotateX: number, rotateY: number) => void, maxTilt?: number): () => void;
+//#endregion
+//#region src/model.d.ts
+/**
+ * 3D 模型的两种形态：挂机与柜机。
+ *
+ * 模型由 `apps/macos/Model/build_cute_ac.py` 在 Blender 里生成：原生应用读 USDZ，网页读同一个场景导出的 GLB。
+ * 这里的约定与 Swift 共享包里的 `ACModel` 一一对应，改动时两边一起改（有测试检查）。
+ */
+export type AcForm = 'wall' | 'tower';
+export declare const acForms: readonly AcForm[];
+export declare const acFormLabels: Record<AcForm, string>;
+/** 网页用的模型文件名（站点的 `public/models/` 下） */
+export declare const acModelFiles: Record<AcForm, string>;
+/** 渲染器要控制的命名节点，两种形态相同 */
+export declare const acModelParts: {
+  /** 导风板：挂机是一整块，柜机是一组百叶（子节点） */
+  readonly louver: "Louver";
+  /** 0.25 × 0.1、UV 为 0–1 的平面，贴温度画面 */
+  readonly display: "Display";
+  /** 指示灯 */
+  readonly led: "Led";
+};
+/**
+ * 开机时导风板怎么动：都绕本地 X 轴转；`node` 是导风板整体转，`children` 是每片百叶各自转。
+ */
+export interface AcLouverMotion {
+  pivot: 'node' | 'children';
+  /** 开机时的角度（度），关机为 0 */
+  openAngle: number;
+}
+export declare const acLouverMotion: Record<AcForm, AcLouverMotion>;
+/**
+ * 出风的起点（相对导风板的世界坐标，Y 轴朝上、+Z 朝向观看者）、出风口的宽度和出风方向：
+ * 挂机向下吹，柜机从百叶侧面吹出。
+ */
+export interface AcAirflowAnchor {
+  offset: readonly [number, number, number];
+  extent: number;
+  direction: 'down' | 'side';
+}
+export declare const acAirflowAnchors: Record<AcForm, AcAirflowAnchor>;
+/** 指示灯与显示窗的颜色：开机时是模式色，关机是灰色（与 `ACPalette` 一致） */
+export declare const acModelColors: {
+  readonly cold: "#5aa9ff";
+  readonly hot: "#ff9f5a";
+  readonly off: "#8e97aa";
+};
+export declare function getAcLedColor(state: Pick<AcState, 'status' | 'mode'>): string;
+export declare function isAcForm(value: unknown): value is AcForm;
+//#endregion
+//#region src/motion.d.ts
+/**
+ * 动效 token：各框架视图层共用的时长与缓动曲线。
+ *
+ * 样式里统一通过 CSS 变量（`--acw-motion-*`）引用，
+ * 需要在 JS 里计时的地方（如 React 过渡组件）直接读取 `acMotion`。
+ */
+export declare const acMotion: {
+  readonly duration: {
+    /** 按下反馈 */
+    readonly instant: 90;
+    /** 悬停、指示灯、图标 */
+    readonly fast: 160;
+    /** 显示屏、数字切换、提示 */
+    readonly base: 240;
+    /** 导风板、出风淡入淡出 */
+    readonly slow: 420;
+    /** 出风气流单次循环 */
+    readonly flow: 1800;
+    /** 扫风：左右摆动一个来回 */
+    readonly swing: 5200;
+  };
+  readonly easing: {
+    /** 常规状态切换 */
+    readonly standard: "cubic-bezier(0.2, 0, 0, 1)";
+    /** 进入：快起慢停 */
+    readonly enter: "cubic-bezier(0, 0, 0, 1)";
+    /** 退出：慢起快走 */
+    readonly exit: "cubic-bezier(0.3, 0, 1, 1)";
+    /** 轻微回弹（按钮松开、图标弹出） */
+    readonly spring: "cubic-bezier(0.34, 1.56, 0.64, 1)";
+  };
+};
+export type AcMotionDuration = keyof typeof acMotion.duration;
+export type AcMotionEasing = keyof typeof acMotion.easing;
+/**
+ * `prefers-reduced-motion: reduce` 时使用的时长：
+ * 保留短促的淡入淡出（不涉及位移），去掉较长的过渡；循环动画由各样式表自行关闭。
+ */
+export declare const acReducedMotionDuration: Record<AcMotionDuration, number>;
+export declare const acReducedMotionQuery = "(prefers-reduced-motion: reduce)";
+/**
+ * 当前环境是否要求减少动效（SSR / 无 matchMedia 时返回 `false`）。
+ */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * 生成动效 CSS 变量声明（含 reduced-motion 覆盖），供 Shadow DOM 注入或样式表同步使用。
+ *
+ * @param selector 变量挂载的选择器，如 `:root`、`:host`
+ */
+export declare function renderAcMotionCssVars(selector?: string): string;
+//#endregion
+//#region src/press.d.ts
+/** 长按连续调节的节奏（ms） */
+export interface AcPressRepeatOptions {
+  /** 按住多久后开始连续触发 @default 500 */
+  delay?: number;
+  /** 连续触发的初始间隔 @default 200 */
+  interval?: number;
+  /** 加速后的最短间隔 @default 100 */
+  minInterval?: number;
+  /**
+   * 读取当前值（例如温度）。连续触发时值不再变化，说明到了上下限，就停下来，
+   * 不会在边界上一直「嘀」。
+   */
+  value?: () => unknown;
+}
+/**
+ * 让按键支持长按连续触发，和真的遥控器一样：按下立即触发一次，按住一会儿后连续触发并逐渐加速，
+ * 松开、移出或取消时停止。键盘的 Enter / 空格仍走 `click`，每按一次触发一次。
+ *
+ * @param element 按键
+ * @param fire 每次触发时调用
+ * @param options 节奏与停止条件
+ * @returns 解除绑定的清理函数
+ */
+export declare function bindAcPressRepeat(element: HTMLElement, fire: () => void, options?: AcPressRepeatOptions): () => void;
+//#endregion
 //#region src/reducer.d.ts
-declare function normalizeAcState(state: Partial<AcState> | undefined): AcState;
-declare function clampTemperature(temperature: number): number;
-declare function acReducer(state: AcState, action: AcAction): AcState;
-declare function getRecommendedTemperatureMessage(mode: AcState['mode'], temperature: number): string;
-declare function getAcActionNotification(previousState: AcState, nextState: AcState, action: AcAction): AcNotification | undefined;
+/**
+ * Merge a partial state over the defaults and clamp its temperature.
+ *
+ * @param state - Partial or stored state
+ * @param limits - Device limits; omit to keep the default 16–31 °C range
+ */
+export declare function normalizeAcState(state: Partial<AcState> | undefined, limits?: AcLimits): AcState;
+/**
+ * Clamp a temperature into range. When `limits` are given the value also
+ * snaps to the device step, measured from `limits.min`.
+ *
+ * @param temperature - Requested temperature in Celsius
+ * @param limits - Device limits; omit to clamp to 16–31 °C without snapping
+ */
+export declare function clampTemperature(temperature: number, limits?: AcLimits): number;
+/**
+ * Apply an action to the state.
+ *
+ * @param state - Current state
+ * @param action - Action to apply
+ * @param limits - Device limits; increments use `limits.step`
+ */
+export declare function acReducer(state: AcState, action: AcAction, limits?: AcLimits): AcState;
+/**
+ * 节能建议的短文案（显示在小纸条上）与补充说明。
+ */
+export declare function getEnergyTip(mode: AcState['mode'], temperature: number): {
+  message: string;
+  detail: string;
+};
+/**
+ * 视图如何呈现一条提示：
+ *
+ * - `note`：节能建议，以小纸条显示
+ * - `shake`：温度到了上下限，遥控器小屏抖一下
+ * - `announce`：设置变化，小屏已经显示，只给读屏播报
+ * - `skip`：同一模式、同一温度的建议已经提示过，不再重复
+ */
+export type AcNotificationPresentation = 'note' | 'shake' | 'announce' | 'skip';
+/**
+ * 创建一个提示「呈现器」：每个视图实例一个，记住提示过的节能建议，避免重复打扰。
+ */
+export declare function createAcNotificationPresenter(): (notification: AcNotification, state: Pick<AcState, 'mode' | 'temperature'>) => AcNotificationPresentation;
+export declare function getRecommendedTemperatureMessage(mode: AcState['mode'], temperature: number): string;
+export declare function getSoundModeMessage(sound: AcState['sound']): string;
+export declare function getFanSpeedMessage(fan: AcFanSpeed): string;
+export declare function getSwingMessage(swing: AcState['swing']): string;
+/**
+ * Visual tone for a state: `idle` when off, otherwise `cool` or `heat`.
+ *
+ * @param state - Current state
+ */
+export declare function acTone(state: Pick<AcState, 'status' | 'mode'>): AcTone;
+export declare function getAcActionNotification(previousState: AcState, nextState: AcState, action: AcAction, limits?: AcLimits): AcNotification | undefined;
 //#endregion
 //#region src/storage.d.ts
-declare function readAcState(storage: AcStorage | null | undefined, storageKey: string): AcState;
-declare function writeAcState(storage: AcStorage | null | undefined, storageKey: string, state: AcState): void;
-declare function createMemoryStorage(initialValue?: Record<string, string>): AcStorage;
-declare function getBrowserStorage(): AcStorage | null;
+export declare function readAcState(storage: AcStorage | null | undefined, storageKey: string): AcState;
+export declare function writeAcState(storage: AcStorage | null | undefined, storageKey: string, state: AcState): void;
+export declare function createMemoryStorage(initialValue?: Record<string, string>): AcStorage;
+export declare function getBrowserStorage(): AcStorage | null;
 //#endregion
 //#region src/store.d.ts
-declare function createAirConditionerStore(options?: CreateAirConditionerStoreOptions): AirConditionerStore;
+export declare function createAirConditionerStore(options?: CreateAirConditionerStoreOptions): AirConditionerStore;
+//#endregion
+//#region src/thermal/types.d.ts
+/**
+ * Heat levels shared by the browser Compute Pressure API and macOS
+ * `ProcessInfo.ThermalState`, so web and native hosts speak the same language.
+ */
+export type HeatLevel = 'nominal' | 'fair' | 'serious' | 'critical';
+export interface HeatReading {
+  level: HeatLevel;
+  /** Real temperature, only when the source can measure one */
+  celsius?: number;
+  /** Identifier of the source that produced the reading */
+  source: string;
+  /** Epoch milliseconds */
+  at: number;
+}
+/**
+ * Something that reports how hot a computer is.
+ */
+export interface HeatSource {
+  id: string;
+  /** Whether the current environment can provide readings */
+  isSupported: () => boolean;
+  /**
+   * Start delivering readings.
+   *
+   * @returns A function that stops the source
+   */
+  start: (listener: (reading: HeatReading) => void) => () => void;
+}
+/**
+ * What the virtual air conditioner should do for a heat level.
+ */
+export interface CoolingPlan {
+  status: true;
+  mode: 'cold';
+  temperature: number;
+  /** 0–1, drives airflow intensity */
+  airflow: number;
+}
+/**
+ * A native host's reading of the computer it runs on, seen as the room the
+ * air conditioner cools. Same JSON as `RoomReading` in the Swift CuteACCore
+ * package; Yun Home passes it to plugins granted `sensor:thermal`.
+ */
+export interface RoomReading {
+  /** CPU/SoC temperature, rounded; absent when no sensor is readable */
+  celsius?: number;
+  thermalState: HeatLevel;
+  /** Fastest fan, rounded to 100 RPM; absent on fanless computers */
+  fanRPM?: number;
+  /** Airflow strength 1–3, from fan load or the heat level */
+  windLevel: number;
+}
+//#endregion
+//#region src/thermal/levels.d.ts
+export declare const heatLevels: readonly HeatLevel[];
+/** Default Celsius thresholds for fair, serious and critical. */
+export declare const defaultHeatThresholds: readonly [number, number, number];
+/**
+ * @param level - A heat level
+ * @returns Its rank from 0 (nominal) to 3 (critical)
+ */
+export declare function heatLevelRank(level: HeatLevel): number;
+export declare function isHeatLevel(value: unknown): value is HeatLevel;
+/**
+ * Convert a temperature to a heat level. With a previous level, the value
+ * must fall `hysteresis` degrees below a threshold before dropping a level,
+ * which keeps readings near a threshold from flickering.
+ *
+ * @param celsius - Measured temperature
+ * @param thresholds - Lower bounds for fair, serious and critical
+ * @param previous - Level from the previous reading
+ * @param hysteresis - Degrees required below a threshold to step down
+ */
+export declare function celsiusToHeatLevel(celsius: number, thresholds?: readonly [number, number, number], previous?: HeatLevel, hysteresis?: number): HeatLevel;
+/**
+ * Create a filter that raises the level immediately but only lowers it after
+ * lower readings persist for `dwellMs`, measured with `reading.at`.
+ *
+ * @param options - Governor options
+ * @param options.dwellMs - Time a lower level must persist; defaults to 30 seconds
+ * @returns A function that maps each reading to the settled level
+ */
+export declare function createHeatGovernor(options?: {
+  dwellMs?: number;
+}): (reading: HeatReading) => HeatLevel;
+//#endregion
+//#region src/thermal/plan.d.ts
+/**
+ * Decide how the virtual air conditioner should respond to a heat level.
+ *
+ * @param level - Settled heat level
+ * @param limits - Device limits used to clamp the target temperature
+ * @returns A cooling plan, or `null` at `nominal` so the user keeps control
+ */
+export declare function planCooling(level: HeatLevel, limits?: AcLimits): CoolingPlan | null;
+//#endregion
+//#region src/thermal/pressure.d.ts
+export interface ComputePressureSourceOptions {
+  /** Requested sample interval; browsers may deliver less often */
+  sampleIntervalMs?: number;
+  /** Called when observing fails, e.g. blocked by permissions policy */
+  onError?: (error: unknown) => void;
+}
+/**
+ * Heat source backed by the browser Compute Pressure API. It reports CPU
+ * load levels, not temperatures; browsers expose no CPU temperature.
+ *
+ * Supported in Chromium-based browsers on secure origins. The API is only
+ * touched when the source is started.
+ *
+ * @param options - Sampling and error handling options
+ */
+export declare function createComputePressureSource(options?: ComputePressureSourceOptions): HeatSource;
+//#endregion
+//#region src/icons.d.ts
+/**
+ * 遥控器按钮与提示图标（24 × 24 viewBox 的 SVG path），全部来自 Material Design
+ * Icons，和站点通过 UnoCSS presetIcons 使用的 i-mdi-* 是同一套。
+ */
+export declare const acIconPaths: {
+  /** mdi:snowflake */
+  readonly cold: "m20.79 13.95l-2.33.62l-2-1.13v-2.88l2-1.13l2.33.62l.52-1.93l-1.77-.47l.46-1.77l-1.93-.52l-.62 2.33l-2 1.13L13 7.38V5.12l1.71-1.71L13.29 2L12 3.29L10.71 2L9.29 3.41L11 5.12v2.26L8.5 8.82l-2-1.13l-.58-2.33L4 5.88l.47 1.77l-1.77.47l.52 1.93l2.33-.62l2 1.13v2.89l-2 1.13l-2.33-.62l-.52 1.93l1.77.47L4 18.12l1.93.52l.62-2.33l2-1.13L11 16.62v2.26l-1.71 1.71L10.71 22L12 20.71L13.29 22l1.41-1.41l-1.7-1.71v-2.26l2.5-1.45l2 1.13l.62 2.33l1.88-.51l-.47-1.77l1.77-.47zM9.5 10.56L12 9.11l2.5 1.45v2.88L12 14.89l-2.5-1.45z";
+  /** mdi:white-balance-sunny */
+  readonly hot: "m3.55 19.09l1.41 1.41l1.8-1.79l-1.42-1.42M12 6c-3.31 0-6 2.69-6 6s2.69 6 6 6s6-2.69 6-6c0-3.32-2.69-6-6-6m8 7h3v-2h-3m-2.76 7.71l1.8 1.79l1.41-1.41l-1.79-1.8M20.45 5l-1.41-1.4l-1.8 1.79l1.42 1.42M13 1h-2v3h2M6.76 5.39L4.96 3.6L3.55 5l1.79 1.81zM1 13h3v-2H1m12 9h-2v3h2";
+  /** mdi:power */
+  readonly power: "m16.56 5.44l-1.45 1.45A5.97 5.97 0 0 1 18 12a6 6 0 0 1-6 6a6 6 0 0 1-6-6c0-2.17 1.16-4.06 2.88-5.12L7.44 5.44A7.96 7.96 0 0 0 4 12a8 8 0 0 0 8 8a8 8 0 0 0 8-8c0-2.72-1.36-5.12-3.44-6.56M13 3h-2v10h2";
+  /** mdi:plus */
+  readonly plus: "M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6z";
+  /** mdi:minus */
+  readonly minus: "M19 13H5v-2h14z";
+  /** mdi:menu-up */
+  readonly increase: "m7 15l5-5l5 5z";
+  /** mdi:menu-down */
+  readonly decrease: "m7 10l5 5l5-5z";
+  /** mdi:fan */
+  readonly fan: "M12 11a1 1 0 0 0-1 1a1 1 0 0 0 1 1a1 1 0 0 0 1-1a1 1 0 0 0-1-1m.5-9c4.5 0 4.61 3.57 2.25 4.75c-.99.49-1.43 1.54-1.62 2.47c.48.2.9.51 1.22.91c3.7-2 7.68-1.21 7.68 2.37c0 4.5-3.57 4.6-4.75 2.23c-.5-.99-1.56-1.43-2.49-1.62c-.2.48-.51.89-.91 1.23c1.99 3.69 1.2 7.66-2.38 7.66c-4.5 0-4.59-3.58-2.23-4.76c.98-.49 1.42-1.53 1.62-2.45c-.49-.2-.92-.52-1.24-.92C5.96 15.85 2 15.07 2 11.5C2 7 5.56 6.89 6.74 9.26c.5.99 1.55 1.42 2.48 1.61c.19-.48.51-.9.92-1.22C8.15 5.96 8.94 2 12.5 2";
+  /** mdi:arrow-oscillating */
+  readonly swing: "M6 14h3l-4 4l-4-4h3c0-2.7 1.7-7.4 7-7.9v2c-3.4.5-5 3.8-5 5.9m14 0c0-2.7-1.7-7.4-7-7.9v2c3.4.6 5 3.8 5 5.9h-3l4 4l4-4z";
+  /** mdi:volume-high */
+  readonly soundNormal: "M14 3.23v2.06c2.89.86 5 3.54 5 6.71s-2.11 5.84-5 6.7v2.07c4-.91 7-4.49 7-8.77s-3-7.86-7-8.77M16.5 12c0-1.77-1-3.29-2.5-4.03V16c1.5-.71 2.5-2.24 2.5-4M3 9v6h4l5 5V4L7 9z";
+  /** mdi:weather-night */
+  readonly soundSleep: "m17.75 4.09l-2.53 1.94l.91 3.06l-2.63-1.81l-2.63 1.81l.91-3.06l-2.53-1.94L12.44 4l1.06-3l1.06 3zm3.5 6.91l-1.64 1.25l.59 1.98l-1.7-1.17l-1.7 1.17l.59-1.98L15.75 11l2.06-.05L18.5 9l.69 1.95zm-2.28 4.95c.83-.08 1.72 1.1 1.19 1.85c-.32.45-.66.87-1.08 1.27C15.17 23 8.84 23 4.94 19.07c-3.91-3.9-3.91-10.24 0-14.14c.4-.4.82-.76 1.27-1.08c.75-.53 1.93.36 1.85 1.19c-.27 2.86.69 5.83 2.89 8.02a9.96 9.96 0 0 0 8.02 2.89m-1.64 2.02a12.08 12.08 0 0 1-7.8-3.47c-2.17-2.19-3.33-5-3.49-7.82c-2.81 3.14-2.7 7.96.31 10.98c3.02 3.01 7.84 3.12 10.98.31";
+  /** mdi:volume-off */
+  readonly soundMute: "M12 4L9.91 6.09L12 8.18M4.27 3L3 4.27L7.73 9H3v6h4l5 5v-6.73l4.25 4.26c-.67.51-1.42.93-2.25 1.17v2.07c1.38-.32 2.63-.95 3.68-1.81L19.73 21L21 19.73l-9-9M19 12c0 .94-.2 1.82-.54 2.64l1.51 1.51A8.9 8.9 0 0 0 21 12c0-4.28-3-7.86-7-8.77v2.06c2.89.86 5 3.54 5 6.71m-2.5 0c0-1.77-1-3.29-2.5-4.03v2.21l2.45 2.45c.05-.2.05-.42.05-.63";
+  /** mdi:leaf */
+  readonly leaf: "M17 8C8 10 5.9 16.17 3.82 21.34l1.89.66l.95-2.3c.48.17.98.3 1.34.3C19 20 22 3 22 3c-1 2-8 2.25-13 3.25S2 11.5 2 13.5s1.75 3.75 1.75 3.75C7 8 17 8 17 8";
+};
+//#endregion
+//#region src/ui.d.ts
+export type AcIconName = keyof typeof acIconPaths;
+/**
+ * 声音键在各声音模式下显示的图标。
+ */
+export declare const acSoundIcons: Record<AcSoundMode, AcIconName>;
+/**
+ * 遥控器按键发出的指令：`RemoteControl` 的 `command` 事件 / `onCommand` 参数。
+ * 模式键发出目标模式（`cold` / `hot`）。
+ */
+export type AcRemoteCommand = 'power' | AcMode | 'increase' | 'decrease' | 'swing' | 'sound' | 'fan';
+/**
+ * 遥控器小屏的读屏文字与各按键的悬停提示，保证各框架文案一致。
+ */
+export declare function getAcRemoteText(state: AcState): {
+  display: string;
+  power: string;
+  mode: Record<AcMode, string>;
+  fan: string;
+  swing: string;
+  sound: string;
+};
+/**
+ * 一行「黑点 / 白点」文字占位，模拟能效标签上的细密文字。
+ */
+export interface AcDotRow {
+  num: number;
+  /** 点的直径（px） */
+  size: number;
+  /** 水平外边距（px） */
+  mx: number;
+  /** 垂直外边距（px） */
+  my: number;
+  color: string;
+}
+/**
+ * 能效标签的点阵与等级条布局：蓝白背景的「中国能效标识」，带能效信息码
+ * （二维码），样式依据《房间空气调节器能源效率标识实施规则》（CEL 010—2019）。
+ *
+ * 等级按现行 GB 21455-2019 分 5 级，1 级最高。GB 21455 的修订版征求意见稿
+ * （2026 年 5 月）拟改为 3 级、以全年动态能源消耗效率（DAPF）分级；正式发布并
+ * 实施后，再更新 `grades`、`standard` 与 `levels`。
+ *
+ * - `top`：标识名称（白点），右侧是能效信息码
+ * - 等级区：首行是 1 级绿色条和指示箭头，`levels` 是 2–5 级
+ * - `detail`：生产者、型号、APF 等参数（黑点）
+ * - `footer`：依据的国家标准编号（白点）
+ */
+export declare const acEnergyLabel: {
+  /** 标签所示的能效等级：云空调是 1 级 */
+  grade: number;
+  /** 等级总数 */
+  grades: number;
+  /** 依据的能源效率强制性国家标准 */
+  standard: string;
+  top: AcDotRow[];
+  detail: AcDotRow[];
+  footer: AcDotRow;
+  levels: {
+    background: string;
+    width: string;
+  }[];
+};
+/**
+ * 能效标签的读屏文字。
+ */
+export declare function getAcEnergyLabelText(): string;
 //#endregion
-export { AcAction, AcAudioController, AcAudioElement, AcAudioElements, AcChangeEvent, AcMode, AcNotification, AcNotificationSeverity, AcState, AcStorage, AcStoreListener, AirConditionerStore, CreateAirConditionerStoreOptions, acAudioFileNames, acModeIcons, acReducer, acStorageKey, clampTemperature, createAcAudioController, createAirConditionerStore, createMemoryStorage, defaultAcState, getAcActionNotification, getBrowserStorage, getRecommendedTemperatureMessage, maxTemperature, minTemperature, normalizeAcState, readAcState, recommendedColdTemperature, recommendedHotTemperature, resolveAcAudioAssets, soundTimings, writeAcState };
+export {};