@onekeyfe/hd-core 1.2.0-alpha.54 → 1.2.0-alpha.55

package/src/types/api/index.ts

@@ -1,6 +1,7 @@
 import type {
   deviceGetOnboardingStatus,
   deviceReboot,
+  deviceUploadNft,
   deviceUploadWallpaper,
   testProtocolV2Ping,
   uploadPortfolio,
@@ -18,6 +19,7 @@ import type { checkBootloaderRelease } from './checkBootloaderRelease';
 import type { checkAllFirmwareRelease } from './checkAllFirmwareRelease';
 import type { checkFirmwareTypeAvailable } from './checkFirmwareTypeAvailable';
 import type { searchDevices } from './searchDevices';
+import type { detectDeviceConnectProtocol } from './detectDeviceConnectProtocol';
 import type { getFeatures } from './getFeatures';
 import type { getDeviceState } from './getDeviceState';
 import type { getOnekeyFeatures } from './getOnekeyFeatures';
@@ -30,15 +32,7 @@ import type {
   firmwareUpdateV2,
   firmwareUpdateV3,
   firmwareUpdateV4,
-  getFirmwareUpdateHostBindingGeneration,
-  registerFirmwareUpdateHostBinding,
-  unregisterFirmwareUpdateHostBinding,
 } from './firmwareUpdate';
-import type { getFirmwareUpdateCapabilities } from './firmwareUpdateCapabilities';
-import type {
-  prepareFirmwareUpdatePlan,
-  validateFirmwareUpdatePreparedPlan,
-} from './firmwareUpdatePreparedPlan';
 import type { promptWebDeviceAccess } from './promptWebDeviceAccess';
 import type { deviceReset } from './deviceReset';
 import type { deviceRecovery } from './deviceRecovery';
@@ -152,6 +146,7 @@ import type { benfenSignMessage } from './benfenSignMessage';
 import type { neoGetAddress } from './neoGetAddress';
 import type { neoSignTransaction } from './neoSignTransaction';
 import type { ConnectSettings } from '../settings';
+import type { HardwareConnectProtocol } from '@onekeyfe/hd-shared';
 
 export * from './export';
 export type { DeviceStateScope, GetDeviceStateParams } from './getDeviceState';
@@ -176,6 +171,14 @@ export type CoreApi = {
   removeAllListeners: typeof removeAllListeners;
   dispose: () => void | Promise<void>;
   call: (params: any) => Promise<any>;
+  /**
+   * Bind a protocol that has already been verified for one transport endpoint.
+   * Every later SDK call for the same connectId uses it as a strict expectation.
+   */
+  setDeviceConnectProtocol: (
+    connectId: string,
+    connectProtocol: HardwareConnectProtocol | undefined
+  ) => void;
   uiResponse: typeof uiResponse;
   cancel: (connectId?: string) => void;
   updateSettings: typeof updateSettings;
@@ -203,6 +206,7 @@ export type CoreApi = {
    * Device function
    */
   searchDevices: typeof searchDevices;
+  detectDeviceConnectProtocol: typeof detectDeviceConnectProtocol;
   promptWebDeviceAccess: typeof promptWebDeviceAccess;
   getFeatures: typeof getFeatures;
   getDeviceState: typeof getDeviceState;
@@ -235,12 +239,6 @@ export type CoreApi = {
   firmwareUpdateV2: typeof firmwareUpdateV2;
   firmwareUpdateV3: typeof firmwareUpdateV3;
   firmwareUpdateV4: typeof firmwareUpdateV4;
-  registerFirmwareUpdateHostBinding: typeof registerFirmwareUpdateHostBinding;
-  unregisterFirmwareUpdateHostBinding: typeof unregisterFirmwareUpdateHostBinding;
-  getFirmwareUpdateHostBindingGeneration: typeof getFirmwareUpdateHostBindingGeneration;
-  getFirmwareUpdateCapabilities: typeof getFirmwareUpdateCapabilities;
-  prepareFirmwareUpdatePlan: typeof prepareFirmwareUpdatePlan;
-  validateFirmwareUpdatePreparedPlan: typeof validateFirmwareUpdatePreparedPlan;
   cipherKeyValue: typeof cipherKeyValue;
 
   /**
@@ -248,6 +246,7 @@ export type CoreApi = {
    */
   deviceReboot: typeof deviceReboot;
   deviceGetOnboardingStatus: typeof deviceGetOnboardingStatus;
+  deviceUploadNft: typeof deviceUploadNft;
   deviceUploadWallpaper: typeof deviceUploadWallpaper;
   uploadPortfolio: typeof uploadPortfolio;
 

package/src/types/api/protocolV2.ts

@@ -5,6 +5,10 @@ import type {
   DeviceUploadWallpaperParams,
   DeviceUploadWallpaperResponse,
 } from '../../api/protocol-v2/DeviceUploadWallpaper';
+import type {
+  DeviceUploadNftParams,
+  DeviceUploadNftResponse,
+} from '../../api/protocol-v2/DeviceUploadNft';
 
 // Re-export implementation parameter types as the single source of truth.
 export type { DeviceRebootParams, RebootTypeInput } from '../../api/protocol-v2/helpers';
@@ -12,6 +16,10 @@ export type {
   DeviceUploadWallpaperParams,
   DeviceUploadWallpaperResponse,
 } from '../../api/protocol-v2/DeviceUploadWallpaper';
+export type {
+  DeviceUploadNftParams,
+  DeviceUploadNftResponse,
+} from '../../api/protocol-v2/DeviceUploadNft';
 
 // ── Shared response shapes (Protocol V2 file system) ────────────────────
 
@@ -52,6 +60,11 @@ export declare function deviceUploadWallpaper(
   params: CommonParams & DeviceUploadWallpaperParams
 ): Response<DeviceUploadWallpaperResponse>;
 
+export declare function deviceUploadNft(
+  connectId: string,
+  params: CommonParams & DeviceUploadNftParams
+): Response<DeviceUploadNftResponse>;
+
 export declare function uploadPortfolio(
   connectId: string,
   params: {

package/src/types/device.ts

@@ -210,7 +210,9 @@ export type DeviceStateStatus = {
   recoveryMode: boolean | null;
   passphraseProtection: boolean | null;
   pinProtection: boolean | null;
+  /** `attach_to_pin_enabled`：是否至少存在一个 Attach PIN 绑定。 */
   attachToPinEnabled: boolean | null;
+  /** `unlocked_by_attach_to_pin`：本次解锁是否由 Attach PIN 完成。 */
   unlockedAttachPin: boolean | null;
 };
 
@@ -321,6 +323,7 @@ export type NormalizedFeatures = {
   sdProtection: boolean | null;
   wipeCodeProtection: boolean | null;
   passphraseAlwaysOnDevice: boolean | null;
+  /** `attach_to_pin_enabled`：是否至少存在一个 Attach PIN 绑定。 */
   attachToPinEnabled?: boolean | null;
   safetyChecks: Enum_SafetyCheckLevel | null;
   autoLockDelayMs: number | null;

package/src/types/params.ts

@@ -61,9 +61,15 @@ export interface CommonParams {
 
   /**
    * Strictly expected transport protocol. The SDK actively verifies this value and
-   * rejects a mismatch. If omitted, a cached protocol only influences probe order.
+   * rejects a mismatch. After a successful probe, the cached protocol is also strict.
    */
   connectProtocol?: HardwareConnectProtocol;
+
+  /**
+   * Ignore a previously bound protocol for this call and actively detect the
+   * protocol again. Intended for the first verified connection or explicit recovery.
+   */
+  forceProtocolDetection?: boolean;
 }
 
 export type Params<T> = CommonParams & T & { bundle?: undefined };

package/src/types/settings.ts

@@ -31,8 +31,6 @@ export type ConnectSettings = {
   timestamp: number;
   isFrame?: boolean;
   preRelease?: boolean;
-  firmwareManifestMode?: 'sdk-managed' | 'external-only';
-  preloadedConfig?: RemoteConfigResponse;
   fetchConfig?: boolean;
   extension?: string;
   configFetcher?: (url: string) => Promise<RemoteConfigResponse | null>;
@@ -60,18 +58,55 @@ export type IProtocolV2FirmwareComponent = {
   fingerprint?: string;
   /** OKPP payload hash, used to detect same-version package changes. */
   payloadHash?: string;
-  expectedSize?: number;
   version?: IVersionArray;
 };
 
+export type IProtocolV2ResourceType =
+  | 'images'
+  | 'animation'
+  | 'wallpaper'
+  | 'translations'
+  | 'roobert'
+  | 'noto';
+
+/** Pro2 RES package descriptor. Hashes identify content without a human-managed version. */
+export type IProtocolV2Resource = {
+  type: IProtocolV2ResourceType;
+  url: string;
+  /** Complete okpkg file size in bytes. */
+  size: number;
+  /** SHA-256 of the complete okpkg file. */
+  fileHash: string;
+  /** SHA3-512 header_hash from the signed okpkg header. */
+  headerHash: string;
+};
+
+/** Optional Pro2 startup-resource CRATE installed by the bootloader updater. */
+export type IProtocolV2BootResources = {
+  required: false;
+  target: 'CRATE';
+  url: string;
+  /** Complete CRATE file size in bytes. */
+  size: number;
+  /** SHA-256 of the complete CRATE file. */
+  fileHash: string;
+  /** SHA3-512 payload_hash from the signed CRATE header. */
+  payloadHash: string;
+  /** SHA3-512 header_hash from the signed CRATE header. */
+  headerHash: string;
+};
+
+export type IProtocolV2Resources = {
+  stable: IProtocolV2Resource[];
+  boot?: IProtocolV2BootResources;
+};
+
 /** Pro2 RESC bundle okpkg descriptor for incremental FileWrite synchronization. */
 export type IProtocolV2ResourceBundle = {
   /** Bundle name, such as images, animation, translations, or fonts_roobert. */
   name: string;
   /** Download URL. */
   url: string;
-  fingerprint?: string;
-  expectedSize?: number;
   /** Device target path, such as vol0:/bundles/images/images.okpkg. */
   devicePath: string;
   /** okpkg payload_version used to skip matching content after FileRead. */
@@ -93,16 +128,10 @@ export type IFirmwareReleaseInfo = {
   firmwareType?: EFirmwareType;
   /** Firmware UI resource */
   resource?: string;
-  resourceFingerprint?: string;
-  resourceExpectedSize?: number;
   /** Firmware full UI resource */
   fullResource?: string;
-  fullResourceFingerprint?: string;
-  fullResourceExpectedSize?: number;
   fullResourceRange?: string[];
   bootloaderResource?: string;
-  bootloaderFingerprint?: string;
-  bootloaderExpectedSize?: number;
   bootloaderVersion?: IVersionArray;
   displayBootloaderVersion?: IVersionArray;
   bootloaderRelatedFirmwareVersion?: IVersionArray;
@@ -115,7 +144,6 @@ export type IFirmwareReleaseInfo = {
     [k in ILocale]: string;
   };
   fingerprint: string;
-  expectedSize?: number;
   version: IVersionArray;
   changelog: {
     [k in ILocale]: string;
@@ -131,7 +159,6 @@ export type IBLEFirmwareReleaseInfo = {
   webUpdate: string;
   fingerprint: string;
   fingerprintWeb: string;
-  expectedSize?: number;
   version: IVersionArray;
   changelog: {
     [k in ILocale]: string;
@@ -149,6 +176,8 @@ export type DeviceTypeMap = {
     'firmware-v8'?: IFirmwareReleaseInfo[];
     'firmware-btc-v8'?: IFirmwareReleaseInfo[];
     ble: IBLEFirmwareReleaseInfo[];
+    /** Independent Pro2 resource release configuration. */
+    resources?: IProtocolV2Resources;
   };
 };
 

package/src/utils/deviceFeaturesCompat.ts

@@ -37,12 +37,6 @@ export const resolveDeviceSerialNo = (features?: DeviceFeaturesInput): string =>
   );
 };
 
-export const resolveDeviceBootloaderMode = (features?: DeviceFeaturesInput): boolean => {
-  if (!features) return false;
-  const compatible = asCompatibleFeatures(features);
-  return (compatible.bootloaderMode ?? compatible.bootloader_mode) === true;
-};
-
 export const resolveDeviceType = (features?: DeviceFeaturesInput): IDeviceType => {
   if (!features || typeof features !== 'object') {
     return EDeviceType.Unknown;

package/src/utils/deviceFeaturesUtils.ts

@@ -106,6 +106,8 @@ export const getPassphraseStateWithRefreshDeviceInfo = async (
     expectPassphraseState?: string;
     onlyMainPin?: boolean;
     initSession?: boolean;
+    deriveCardano?: boolean;
+    rejectAttachPinForMainWallet?: boolean;
   }
 ) => {
   if (device.isProtocolV2()) {
@@ -121,6 +123,8 @@ export const getPassphraseStateWithRefreshDeviceInfo = async (
       initSession: options?.initSession,
       expectedPassphraseState: options?.expectPassphraseState,
       onlyMainPin: options?.onlyMainPin,
+      deriveCardano: options?.deriveCardano,
+      rejectAttachPinForMainWallet: options?.rejectAttachPinForMainWallet,
     });
   }
 
@@ -185,6 +189,8 @@ export const getPassphraseState = async (
     expectPassphraseState?: string;
     onlyMainPin?: boolean;
     initSession?: boolean;
+    deriveCardano?: boolean;
+    rejectAttachPinForMainWallet?: boolean;
   }
 ): Promise<{
   passphraseState: string | undefined;
@@ -205,6 +211,8 @@ export const getPassphraseState = async (
       initSession: options?.initSession,
       expectedPassphraseState: options?.expectPassphraseState,
       onlyMainPin: options?.onlyMainPin,
+      deriveCardano: options?.deriveCardano,
+      rejectAttachPinForMainWallet: options?.rejectAttachPinForMainWallet,
     });
   }
 

package/src/utils/homescreen.ts

@@ -4,6 +4,12 @@ import { EDeviceType } from '@onekeyfe/hd-shared';
 import { getDeviceType } from './deviceInfoUtils';
 import { getDeviceFirmwareVersion } from './deviceVersionUtils';
 import { PRO2_WALLPAPER_HEIGHT, PRO2_WALLPAPER_WIDTH } from './pro2Wallpaper';
+import {
+  PRO2_NFT_IMAGE_HEIGHT,
+  PRO2_NFT_IMAGE_WIDTH,
+  PRO2_NFT_THUMBNAIL_HEIGHT,
+  PRO2_NFT_THUMBNAIL_WIDTH,
+} from './pro2Nft';
 
 import type { Features, IDeviceType } from '../types';
 
@@ -302,6 +308,31 @@ type SizeConfig = {
   radius?: number;
 };
 
+export const getNftSize = ({
+  deviceType,
+  thumbnail,
+}: {
+  deviceType: IDeviceType;
+  thumbnail?: boolean;
+}): SizeConfig | undefined => {
+  const sizes: Partial<Record<IDeviceType, { full: SizeConfig; thumbnail: SizeConfig }>> = {
+    touch: {
+      full: { width: 480, height: 800 },
+      thumbnail: { width: 238, height: 238 },
+    },
+    pro: {
+      full: { width: 480, height: 800 },
+      thumbnail: { width: 226, height: 226, radius: 40 },
+    },
+    pro2: {
+      full: { width: PRO2_NFT_IMAGE_WIDTH, height: PRO2_NFT_IMAGE_HEIGHT },
+      thumbnail: { width: PRO2_NFT_THUMBNAIL_WIDTH, height: PRO2_NFT_THUMBNAIL_HEIGHT },
+    },
+  };
+
+  return sizes[deviceType]?.[thumbnail ? 'thumbnail' : 'full'];
+};
+
 export const getHomeScreenSize = ({
   deviceType,
   homeScreenType,
@@ -312,12 +343,7 @@ export const getHomeScreenSize = ({
   thumbnail?: boolean;
 }) => {
   if (deviceType === EDeviceType.Pro2) {
-    return thumbnail
-      ? undefined
-      : {
-          width: PRO2_WALLPAPER_WIDTH,
-          height: PRO2_WALLPAPER_HEIGHT,
-        };
+    return thumbnail ? undefined : { width: PRO2_WALLPAPER_WIDTH, height: PRO2_WALLPAPER_HEIGHT };
   }
 
   const sizes: Partial<

package/src/utils/index.ts

@@ -54,7 +54,12 @@ export { getHDPath, getScriptType, getOutputScriptType } from '../api/helpers/pa
 
 export const isBleConnect = (env: string) => env === 'react-native' || env === 'lowlevel';
 
-export { getHomeScreenHex, getHomeScreenDefaultList, getHomeScreenSize } from './homescreen';
+export {
+  getHomeScreenHex,
+  getHomeScreenDefaultList,
+  getHomeScreenSize,
+  getNftSize,
+} from './homescreen';
 export { encodePro2Wallpaper, PRO2_WALLPAPER_HEIGHT, PRO2_WALLPAPER_WIDTH } from './pro2Wallpaper';
 export type { Pro2WallpaperColorFormat } from './pro2Wallpaper';
 

package/src/utils/pro2Nft.ts

@@ -0,0 +1,142 @@
+import { blake2s } from '@noble/hashes/blake2s';
+import { bytesToHex } from '@noble/hashes/utils';
+
+import { invalidParameter } from '../api/helpers/filesystemValidation';
+import { encodePro2Image } from './pro2Wallpaper';
+
+export const PRO2_NFT_IMAGE_WIDTH = 540;
+export const PRO2_NFT_IMAGE_HEIGHT = 540;
+export const PRO2_NFT_THUMBNAIL_WIDTH = 263;
+export const PRO2_NFT_THUMBNAIL_HEIGHT = 263;
+export const PRO2_NFT_DIRECTORY = 'vol1:/nft';
+export const PRO2_NFT_DEFAULT_CHUNK_SIZE = 2048;
+export const PRO2_NFT_DEFAULT_PACE_MS = 0;
+export const PRO2_NFT_DEFAULT_TIMEOUT_MS = 15_000;
+export const PRO2_NFT_MIN_CHUNK_SIZE = 64;
+export const PRO2_NFT_MAX_CHUNK_SIZE = 2048;
+export const PRO2_NFT_MAX_ITEMS = 10;
+
+export type Pro2NftImage = {
+  width: number;
+  height: number;
+  rgba: Uint8Array | ArrayBuffer;
+};
+
+export type Pro2NftBundle = {
+  basename: string;
+  image: Uint8Array;
+  thumbnail: Uint8Array;
+  metadata: Uint8Array;
+};
+
+const PRO2_NFT_BASENAME_PATTERN = /^nft-[0-9a-f]{8}-[1-9][0-9]*$/;
+
+type Pro2NftFileType = 'image' | 'thumbnail' | 'metadata';
+
+function parsePro2NftFile(listedPath: string):
+  | {
+      basename: string;
+      fileType: Pro2NftFileType;
+    }
+  | undefined {
+  const filename = listedPath.trim().split('/').at(-1);
+  if (!filename) return undefined;
+
+  let basename: string | undefined;
+  let fileType: Pro2NftFileType | undefined;
+  if (filename.endsWith('_m.bin')) {
+    basename = filename.slice(0, -'_m.bin'.length);
+    fileType = 'thumbnail';
+  } else if (filename.endsWith('.json')) {
+    basename = filename.slice(0, -'.json'.length);
+    fileType = 'metadata';
+  } else if (filename.endsWith('.bin')) {
+    basename = filename.slice(0, -'.bin'.length);
+    fileType = 'image';
+  }
+
+  return basename && fileType && PRO2_NFT_BASENAME_PATTERN.test(basename)
+    ? { basename, fileType }
+    : undefined;
+}
+
+export function getCompletePro2NftBasenames(childFiles?: string): Set<string> {
+  const filesByBasename = new Map<string, Set<Pro2NftFileType>>();
+
+  for (const listedPath of childFiles?.split('\n') ?? []) {
+    const file = parsePro2NftFile(listedPath);
+    if (file) {
+      const fileTypes = filesByBasename.get(file.basename) ?? new Set<Pro2NftFileType>();
+      fileTypes.add(file.fileType);
+      filesByBasename.set(file.basename, fileTypes);
+    }
+  }
+
+  return new Set(
+    [...filesByBasename.entries()]
+      .filter(([, fileTypes]) => fileTypes.size === 3)
+      .map(([basename]) => basename)
+  );
+}
+
+function utf8Length(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function assertImage(
+  name: string,
+  image: Pro2NftImage,
+  expectedWidth: number,
+  expectedHeight: number
+) {
+  if (image.width !== expectedWidth || image.height !== expectedHeight) {
+    throw invalidParameter(
+      `Pro2 NFT ${name} dimensions must be ${expectedWidth}x${expectedHeight}.`
+    );
+  }
+  if (!(image.rgba instanceof ArrayBuffer) && !ArrayBuffer.isView(image.rgba)) {
+    throw invalidParameter(`Parameter [${name}.rgba] must be an ArrayBuffer or Uint8Array.`);
+  }
+}
+
+export function buildPro2NftBundle(options: {
+  image: Pro2NftImage;
+  thumbnail: Pro2NftImage;
+  title: string;
+  subtitle: string;
+  timestampMs: number;
+}): Pro2NftBundle {
+  const { image, thumbnail, title, subtitle, timestampMs } = options;
+  assertImage('image', image, PRO2_NFT_IMAGE_WIDTH, PRO2_NFT_IMAGE_HEIGHT);
+  assertImage('thumbnail', thumbnail, PRO2_NFT_THUMBNAIL_WIDTH, PRO2_NFT_THUMBNAIL_HEIGHT);
+  const titleLength = typeof title === 'string' ? utf8Length(title) : 0;
+  const subtitleLength =
+    typeof subtitle === 'string' ? utf8Length(subtitle) : Number.POSITIVE_INFINITY;
+  if (titleLength < 1 || titleLength > 63) {
+    throw invalidParameter('Pro2 NFT title must contain 1 to 63 UTF-8 bytes.');
+  }
+  if (subtitleLength > 95) {
+    throw invalidParameter('Pro2 NFT subtitle must contain at most 95 UTF-8 bytes.');
+  }
+  if (!Number.isSafeInteger(timestampMs) || timestampMs <= 0) {
+    throw invalidParameter('Parameter [timestampMs] must be a positive safe integer.');
+  }
+
+  const encodedImage = encodePro2Image({ ...image, alphaMode: 'black-background' }).data;
+  const encodedThumbnail = encodePro2Image({
+    ...thumbnail,
+    alphaMode: 'black-background',
+  }).data;
+  const metadata = new TextEncoder().encode(JSON.stringify({ title, subtitle }));
+  if (metadata.byteLength === 0 || metadata.byteLength > 512) {
+    throw invalidParameter('Pro2 NFT metadata must contain 1 to 512 UTF-8 bytes.');
+  }
+
+  const hash8 = bytesToHex(blake2s(encodedImage)).slice(0, 8);
+  return {
+    basename: `nft-${hash8}-${timestampMs}`,
+    image: encodedImage,
+    thumbnail: encodedThumbnail,
+    metadata,
+  };
+}

package/src/utils/pro2Wallpaper.ts

@@ -8,6 +8,8 @@ export const PRO2_WALLPAPER_HEIGHT = 1024;
 
 export type Pro2WallpaperColorFormat = 'RGB565' | 'RGB565A8';
 
+export type Pro2ImageAlphaMode = 'preserve' | 'black-background';
+
 const COLOR_FORMAT_RGB565 = 0x12;
 const COLOR_FORMAT_RGB565A8 = 0x14;
 
@@ -36,10 +38,11 @@ function align(value: number, boundary: number): number {
   return Math.ceil(value / boundary) * boundary;
 }
 
-export function encodePro2Wallpaper(options: {
+export function encodePro2Image(options: {
   width: number;
   height: number;
   rgba: Uint8Array | ArrayBuffer;
+  alphaMode?: Pro2ImageAlphaMode;
 }): { data: Uint8Array; colorFormat: Pro2WallpaperColorFormat } {
   const { width, height } = options;
   if (!Number.isInteger(width) || width <= 0 || width > 0xffff) {
@@ -57,11 +60,14 @@ export function encodePro2Wallpaper(options: {
     );
   }
 
+  const alphaMode = options.alphaMode ?? 'preserve';
   let hasTransparency = false;
-  for (let index = 3; index < rgba.length; index += 4) {
-    if (rgba[index] !== 0xff) {
-      hasTransparency = true;
-      break;
+  if (alphaMode === 'preserve') {
+    for (let index = 3; index < rgba.length; index += 4) {
+      if (rgba[index] !== 0xff) {
+        hasTransparency = true;
+        break;
+      }
     }
   }
 
@@ -85,9 +91,22 @@ export function encodePro2Wallpaper(options: {
     for (let x = 0; x < width; x += 1) {
       const sourceOffset = (y * width + x) * 4;
       const thresholdIndex = ((y & 7) << 3) + (x & 7);
-      const red = Math.min(rgba[sourceOffset] + RED_THRESHOLD[thresholdIndex], 0xff) & 0xf8;
-      const green = Math.min(rgba[sourceOffset + 1] + GREEN_THRESHOLD[thresholdIndex], 0xff) & 0xfc;
-      const blue = Math.min(rgba[sourceOffset + 2] + BLUE_THRESHOLD[thresholdIndex], 0xff) & 0xf8;
+      const alpha = rgba[sourceOffset + 3];
+      const redChannel =
+        alphaMode === 'black-background'
+          ? Math.round((rgba[sourceOffset] * alpha) / 0xff)
+          : rgba[sourceOffset];
+      const greenChannel =
+        alphaMode === 'black-background'
+          ? Math.round((rgba[sourceOffset + 1] * alpha) / 0xff)
+          : rgba[sourceOffset + 1];
+      const blueChannel =
+        alphaMode === 'black-background'
+          ? Math.round((rgba[sourceOffset + 2] * alpha) / 0xff)
+          : rgba[sourceOffset + 2];
+      const red = Math.min(redChannel + RED_THRESHOLD[thresholdIndex], 0xff) & 0xf8;
+      const green = Math.min(greenChannel + GREEN_THRESHOLD[thresholdIndex], 0xff) & 0xfc;
+      const blue = Math.min(blueChannel + BLUE_THRESHOLD[thresholdIndex], 0xff) & 0xf8;
       const rgb565 = ((red >> 3) << 11) | ((green >> 2) << 5) | (blue >> 3);
       const rgbOffset = 12 + y * stride + x * 2;
       data[rgbOffset] = rgb565 & 0xff;
@@ -101,3 +120,11 @@ export function encodePro2Wallpaper(options: {
 
   return { data, colorFormat };
 }
+
+export function encodePro2Wallpaper(options: {
+  width: number;
+  height: number;
+  rgba: Uint8Array | ArrayBuffer;
+}): { data: Uint8Array; colorFormat: Pro2WallpaperColorFormat } {
+  return encodePro2Image(options);
+}

package/src/utils/uiProgressThrottle.ts

@@ -0,0 +1,63 @@
+import { UI_EVENT, UI_REQUEST } from '../events/ui-request';
+
+import type { CoreMessage } from '../events';
+
+const DEFAULT_UI_PROGRESS_INTERVAL_MS = 250;
+
+type UiProgressThrottleState = {
+  lastEmittedAt: number;
+  lastProgress?: number;
+};
+
+const normalizeProgress = (progress: unknown) => {
+  if (typeof progress !== 'number' || !Number.isFinite(progress)) {
+    return undefined;
+  }
+
+  return Math.max(0, Math.min(100, Math.floor(progress)));
+};
+
+export const createUiProgressMessageFilter = (
+  intervalMs = DEFAULT_UI_PROGRESS_INTERVAL_MS,
+  now = Date.now
+) => {
+  const stateByType = new Map<string, UiProgressThrottleState>();
+
+  return (message: CoreMessage) => {
+    if (
+      !('event' in message) ||
+      message.event !== UI_EVENT ||
+      (message.type !== UI_REQUEST.DEVICE_PROGRESS && message.type !== UI_REQUEST.FIRMWARE_PROGRESS)
+    ) {
+      return true;
+    }
+
+    const key =
+      message.type === UI_REQUEST.FIRMWARE_PROGRESS
+        ? `${message.type}:${message.payload.progressType}`
+        : message.type;
+    const progress = normalizeProgress(message.payload.progress);
+    const currentTime = now();
+    const state = stateByType.get(key);
+
+    if (!state) {
+      stateByType.set(key, { lastEmittedAt: currentTime, lastProgress: progress });
+      return true;
+    }
+
+    const isBoundary = progress === 0 || progress === 100;
+    if (isBoundary && progress === state.lastProgress) {
+      return false;
+    }
+
+    const startsNewPhase =
+      progress !== undefined && state.lastProgress !== undefined && progress < state.lastProgress;
+
+    if (!isBoundary && !startsNewPhase && currentTime - state.lastEmittedAt < intervalMs) {
+      return false;
+    }
+
+    stateByType.set(key, { lastEmittedAt: currentTime, lastProgress: progress });
+    return true;
+  };
+};