[break] Add PreviewService with standalone resource preview page.

.github/workflows/check-dts.yml

@@ -38,6 +38,17 @@ jobs:
           npx jest --roots packages/cocos-cli-types --testPathPattern dts-snapshot --no-cache -u
           npx jest packages/cocos-cli-types --roots="<rootDir>/packages/cocos-cli-types"
 
+      - name: Typecheck DTS declarations
+        shell: bash
+        run: |
+          errors=$(npx tsc -p packages/cocos-cli-types/tsconfig.typecheck.json --noEmit 2>&1 | grep "^packages/cocos-cli-types/" || true)
+          if [ -n "$errors" ]; then
+            echo "::error::DTS typecheck failed — type errors found in cocos-cli-types declarations:"
+            echo "$errors"
+            exit 1
+          fi
+          echo "DTS typecheck passed."
+
       - name: Check DTS API compatibility
         shell: bash
         env:

packages/cocos-cli-types/__tests__/__snapshots__/dts-snapshot.test.ts.snap

@@ -777,8 +777,7 @@ export { }
 exports[`DTS API compatibility builder.d.ts should match snapshot 1`] = `
 "import EventEmitter from 'events';
 import { EventEmitter as EventEmitter_2 } from 'stream';
-import { IAssetDeleteOptions } from './filesystem';
-import { IAssetWriteFileOptions } from './filesystem';
+import { IAssetDeleteOptions, IAssetWriteFileOptions } from '@cocos/asset-db/libs/filesystem';
 import type { PluginItem } from '@babel/core';
 import { SpriteFrame } from 'cc';
 export declare interface AcornNode {
@@ -1350,7 +1349,7 @@ export declare interface BundleRenderConfig {
     maxOptionList: Record<string, any[]>;
     minOptionList?: Record<string, any[]>;
 }
-export declare type CCEnvConstants = ConstantManager.CCEnvConstants;
+export declare type CCEnvConstants = StatsQuery.ConstantManager.CCEnvConstants;
 export declare type ChangeEvent = 'create' | 'update' | 'delete';
 export declare interface ChokidarOptions {
     	alwaysStat?: boolean;
@@ -1431,7 +1430,7 @@ export declare interface Config {
     optimizeDecorators: IOptimizeDecorators;
     treeShake?: ITreeShakeConfig;
 }
-declare namespace ConfigInterface {
+export declare namespace ConfigInterface {
     export {
         Config,
         IndexConfig,
@@ -4191,7 +4190,7 @@ export declare type ResolveImportMetaHook = (
 	prop: string | null,
 	options: { chunkId: string; format: InternalModuleFormat; moduleId: string }
 ) => string | null | void;
-declare namespace rollup {
+export declare namespace rollup {
     export {
         rollup_2 as rollup,
         watch,
@@ -4633,7 +4632,7 @@ export declare class StatsQuery {
     private _featureUnits;
     private _editorPublicModules;
 }
-declare namespace StatsQuery {
+export declare namespace StatsQuery {
     namespace ConstantManager {
         type PlatformType = 'WEB_EDITOR' | 'WEB_MOBILE' | 'WEB_DESKTOP' | 'WECHAT' | 'WECHAT_MINI_PROGRAM' | 'BYTEDANCE' | 'ALIPAY' | 'TAOBAO' | 'TAOBAO_MINIGAME' | 'OPPO' | 'VIVO' | 'HUAWEI' | 'HONOR' | 'COCOS_RUNTIME' | 'SUD' | 'SUDV2' | 'NATIVE_EDITOR' | 'ANDROID' | 'WINDOWS' | 'IOS' | 'MAC' | 'OHOS' | 'OPEN_HARMONY' | 'LINUX' | 'HTML5' | 'NATIVE' | 'NODEJS' | 'INVALID_PLATFORM';
         type IPlatformConfig = { [key in PlatformType]: boolean };
@@ -5445,6 +5444,8 @@ export declare interface IEditorService extends IServiceEvents {
 export declare interface IEngineService extends IServiceEvents {
     init(): Promise<void>;
     repaintInEditMode(): Promise<void>;
+    pause(): void;
+    resume(): void;
 }
 export declare interface IExecuteComponentMethodOptions {
     path: string;
@@ -5627,6 +5628,20 @@ export declare interface IPrefabStateInfo {
     isNested: boolean;
     assetUuid: string;
 }
+export declare interface IPreviewInstance {
+    onMouseDown(event: any): void;
+    onMouseMove(event: any): void;
+    onMouseUp(event: any): void;
+    onMouseWheel(event: any): void;
+    viewToggle(): void;
+    is2DView(): boolean;
+    resetCameraView(): void;
+    hide(): void;
+}
+export declare interface IPreviewService {
+    open(uuid: string): Promise<IPreviewInstance | null>;
+    generateThumbnail(uuid: string, assetType: string, width?: number, height?: number): Promise<any>;
+}
 export declare interface IProperty {
     value: { [key: string]: IPropertyValueType } | IPropertyValueType;
     default?: any; 
@@ -5759,8 +5774,8 @@ export declare interface ISceneViewService {
     saveConfig(): Promise<void>;
     setSceneLightOn(enable: boolean): void;
     querySceneLightOn(): boolean;
-    onSceneOpened(scene: any): void;
-    onSceneClosed(): void;
+    onEditorOpened(): void;
+    onEditorClosed(): void;
     onComponentAdded(comp: Component): void;
     onComponentRemoved(comp: Component): void;
 }
@@ -5826,6 +5841,7 @@ export declare interface IServiceManager {
     Camera: ICameraService;
     Gizmo: IGizmoService;
     SceneView: ISceneViewService;
+    Preview: IPreviewService;
     UI: IUIService;
 }
 export declare interface ISetPropertyOptions {
@@ -7450,6 +7466,8 @@ export declare interface IEngineProjectConfig extends Exclude<IEngineConfig, 'in
 export declare interface IEngineService extends IServiceEvents {
     init(): Promise<void>;
     repaintInEditMode(): Promise<void>;
+    pause(): void;
+    resume(): void;
 }
 export declare interface IExecuteComponentMethodOptions {
     path: string;
@@ -7720,6 +7738,20 @@ export declare interface IPrefabStateInfo {
     isNested: boolean;
     assetUuid: string;
 }
+export declare interface IPreviewInstance {
+    onMouseDown(event: any): void;
+    onMouseMove(event: any): void;
+    onMouseUp(event: any): void;
+    onMouseWheel(event: any): void;
+    viewToggle(): void;
+    is2DView(): boolean;
+    resetCameraView(): void;
+    hide(): void;
+}
+export declare interface IPreviewService {
+    open(uuid: string): Promise<IPreviewInstance | null>;
+    generateThumbnail(uuid: string, assetType: string, width?: number, height?: number): Promise<any>;
+}
 export declare interface IProject {
     get path(): string;
     get type(): '2d' | '3d';
@@ -7865,8 +7897,8 @@ export declare interface ISceneViewService {
     saveConfig(): Promise<void>;
     setSceneLightOn(enable: boolean): void;
     querySceneLightOn(): boolean;
-    onSceneOpened(scene: any): void;
-    onSceneClosed(): void;
+    onEditorOpened(): void;
+    onEditorClosed(): void;
     onComponentAdded(comp: Component): void;
     onComponentRemoved(comp: Component): void;
 }
@@ -7932,6 +7964,7 @@ export declare interface IServiceManager {
     Camera: ICameraService;
     Gizmo: IGizmoService;
     SceneView: ISceneViewService;
+    Preview: IPreviewService;
     UI: IUIService;
 }
 export declare interface ISetPropertyOptions {

packages/cocos-cli-types/__tests__/assets.test.ts

@@ -1,6 +1,55 @@
-import type { AssetHandlerType, AssetDBOptions, IAssetInfo, IAssetType } from '../assets';
+type AssetsModule = typeof import('../assets');
+import type { AssetHandlerType, AssetDBOptions, IAssetInfo, IAssetType, IAssetMeta, AssetUserDataMap, CreateAssetOptions, DeleteAssetOptions, QueryAssetsOption } from '../assets';
 
 describe('cocos-cli-types: assets', () => {
+    it('should be able to import api functions', () => {
+        let _init: AssetsModule['init'] | undefined = undefined;
+        let _createAsset: AssetsModule['createAsset'] | undefined = undefined;
+        let _createAssetByType: AssetsModule['createAssetByType'] | undefined = undefined;
+        let _deleteAsset: AssetsModule['deleteAsset'] | undefined = undefined;
+        let _importAsset: AssetsModule['importAsset'] | undefined = undefined;
+        let _queryAssetInfo: AssetsModule['queryAssetInfo'] | undefined = undefined;
+        let _queryAssetInfos: AssetsModule['queryAssetInfos'] | undefined = undefined;
+        let _queryAssetMeta: AssetsModule['queryAssetMeta'] | undefined = undefined;
+        let _saveAsset: AssetsModule['saveAsset'] | undefined = undefined;
+        let _moveAsset: AssetsModule['moveAsset'] | undefined = undefined;
+        let _renameAsset: AssetsModule['renameAsset'] | undefined = undefined;
+        let _refresh: AssetsModule['refresh'] | undefined = undefined;
+        let _reimportAsset: AssetsModule['reimportAsset'] | undefined = undefined;
+        let _queryUUID: AssetsModule['queryUUID'] | undefined = undefined;
+        let _queryPath: AssetsModule['queryPath'] | undefined = undefined;
+        let _queryUrl: AssetsModule['queryUrl'] | undefined = undefined;
+        let _generateThumbnail: AssetsModule['generateThumbnail'] | undefined = undefined;
+        let _onAssetAdded: AssetsModule['onAssetAdded'] | undefined = undefined;
+        let _onAssetChanged: AssetsModule['onAssetChanged'] | undefined = undefined;
+        let _onAssetRemoved: AssetsModule['onAssetRemoved'] | undefined = undefined;
+        let _onReady: AssetsModule['onReady'] | undefined = undefined;
+        let _onDBReady: AssetsModule['onDBReady'] | undefined = undefined;
+
+        expect(_init).toBeUndefined();
+        expect(_createAsset).toBeUndefined();
+        expect(_createAssetByType).toBeUndefined();
+        expect(_deleteAsset).toBeUndefined();
+        expect(_importAsset).toBeUndefined();
+        expect(_queryAssetInfo).toBeUndefined();
+        expect(_queryAssetInfos).toBeUndefined();
+        expect(_queryAssetMeta).toBeUndefined();
+        expect(_saveAsset).toBeUndefined();
+        expect(_moveAsset).toBeUndefined();
+        expect(_renameAsset).toBeUndefined();
+        expect(_refresh).toBeUndefined();
+        expect(_reimportAsset).toBeUndefined();
+        expect(_queryUUID).toBeUndefined();
+        expect(_queryPath).toBeUndefined();
+        expect(_queryUrl).toBeUndefined();
+        expect(_generateThumbnail).toBeUndefined();
+        expect(_onAssetAdded).toBeUndefined();
+        expect(_onAssetChanged).toBeUndefined();
+        expect(_onAssetRemoved).toBeUndefined();
+        expect(_onReady).toBeUndefined();
+        expect(_onDBReady).toBeUndefined();
+    });
+
     it('should be able to import AssetHandlerType', () => {
         let type: AssetHandlerType = 'database';
         expect(type).toBe('database');
@@ -10,21 +59,60 @@ describe('cocos-cli-types: assets', () => {
         let options: Partial<AssetDBOptions> = {
             name: 'test-db',
             target: 'path/to/target',
-            level: 3
+            level: 3,
         };
         expect(options.name).toBe('test-db');
     });
-
-    it('should be able to import IAssetInfo', () => {
+
+    it('IAssetInfo should have core properties', () => {
+        const keys: (keyof IAssetInfo)[] = [
+            'name', 'source', 'url', 'file', 'uuid',
+            'importer', 'imported', 'invalid', 'type',
+            'isDirectory', 'library',
+        ];
+        expect(keys.length).toBeGreaterThan(0);
+
         let info: Partial<IAssetInfo> = {
             name: 'test-asset',
             uuid: 'test-uuid',
+            type: 'cc.Texture2D',
         };
         expect(info.name).toBe('test-asset');
     });
-    
+
     it('should be able to import IAssetType', () => {
         let type: IAssetType = 'cc.Texture2D';
         expect(type).toBe('cc.Texture2D');
     });
+
+    it('IAssetMeta should have meta properties', () => {
+        const keys: (keyof IAssetMeta)[] = [
+            'ver', 'importer', 'imported', 'uuid', 'files', 'subMetas', 'userData',
+        ];
+        expect(keys.length).toBeGreaterThan(0);
+    });
+
+    it('CreateAssetOptions should have target', () => {
+        let options: CreateAssetOptions = {
+            target: 'db://assets/test.png',
+            uuid: 'test-uuid',
+        };
+        expect(options.target).toBe('db://assets/test.png');
+    });
+
+    it('AssetUserDataMap should support known asset types', () => {
+        type ImageUserData = AssetUserDataMap['image'];
+        let _data: Partial<ImageUserData> = { type: 'texture' };
+        expect(_data.type).toBe('texture');
+    });
+
+    it('DeleteAssetOptions should be importable', () => {
+        let options: DeleteAssetOptions = { useTrash: true };
+        expect(options.useTrash).toBe(true);
+    });
+
+    it('QueryAssetsOption should be importable', () => {
+        let _options: Partial<QueryAssetsOption> = {};
+        expect(_options).toBeDefined();
+    });
 });

packages/cocos-cli-types/__tests__/builder.test.ts

@@ -1,5 +1,5 @@
 type BuilderModule = typeof import('../builder');
-import type { IBuildTaskOption, IBuildResultData } from '../builder';
+import type { IBuildTaskOption, IBuildResultData, IBuildResult, IBuildCommonOptions, IBuilder, BuildConfiguration, StatsQuery } from '../builder';
 
 describe('cocos-cli-types: builder', () => {
     it('should be able to import build task api functions', () => {
@@ -8,12 +8,22 @@ describe('cocos-cli-types: builder', () => {
         let _make: BuilderModule['make'] | undefined = undefined;
         let _run: BuilderModule['run'] | undefined = undefined;
         let _queryBuildConfig: BuilderModule['queryBuildConfig'] | undefined = undefined;
+        let _init: BuilderModule['init'] | undefined = undefined;
+        let _createBuildTask: BuilderModule['createBuildTask'] | undefined = undefined;
+        let _getPreviewSettings: BuilderModule['getPreviewSettings'] | undefined = undefined;
+        let _getRegisteredPlatforms: BuilderModule['getRegisteredPlatforms'] | undefined = undefined;
+        let _executeBuildStageTask: BuilderModule['executeBuildStageTask'] | undefined = undefined;
 
         expect(_build).toBeUndefined();
         expect(_buildBundleOnly).toBeUndefined();
         expect(_make).toBeUndefined();
         expect(_run).toBeUndefined();
         expect(_queryBuildConfig).toBeUndefined();
+        expect(_init).toBeUndefined();
+        expect(_createBuildTask).toBeUndefined();
+        expect(_getPreviewSettings).toBeUndefined();
+        expect(_getRegisteredPlatforms).toBeUndefined();
+        expect(_executeBuildStageTask).toBeUndefined();
     });
 
     it('should be able to import IBuildTaskOption', () => {
@@ -22,11 +32,55 @@ describe('cocos-cli-types: builder', () => {
         };
         expect(options.buildPath).toBe('build');
     });
-    
+
     it('should be able to import IBuildResultData', () => {
-        // IBuildResultData is a branded string or a complex type depending on compilation output.
-        // We will just verify it can be declared as a type.
         let result: IBuildResultData | undefined = undefined;
         expect(result).toBeUndefined();
     });
+
+    it('IBuildCommonOptions should have key properties', () => {
+        const keys: (keyof IBuildCommonOptions)[] = [
+            'name', 'outputName', 'buildPath', 'platform',
+            'skipCompressTexture', 'packAutoAtlas', 'sourceMaps',
+            'debug', 'md5Cache', 'startScene', 'packages',
+        ];
+        expect(keys.length).toBeGreaterThan(0);
+    });
+
+    it('IBuildResult should have result methods', () => {
+        const keys: (keyof IBuildResult)[] = [
+            'dest', 'paths', 'containsAsset',
+            'getRawAssetPaths', 'getJsonPathInfo',
+            'getImportAssetPaths', 'getAssetPathInfo',
+        ];
+        expect(keys.length).toBeGreaterThan(0);
+    });
+
+    it('IBuilder should have builder properties', () => {
+        const keys: (keyof IBuilder)[] = [
+            'cache', 'result', 'options', 'bundleManager',
+            'hooksInfo', 'buildTemplate', 'id', 'utils',
+            'updateProcess', 'break',
+        ];
+        expect(keys.length).toBeGreaterThan(0);
+    });
+
+    it('BuildConfiguration should have config sections', () => {
+        const keys: (keyof BuildConfiguration)[] = [
+            'common', 'platforms', 'bundleConfig', 'textureCompressConfig',
+        ];
+        expect(keys.length).toBeGreaterThan(0);
+    });
+
+    it('StatsQuery should be importable as a class', () => {
+        let _query: StatsQuery | undefined = undefined;
+        expect(_query).toBeUndefined();
+    });
+
+    it('StatsQuery.ConstantManager namespace types should be accessible', () => {
+        let _platformType: StatsQuery.ConstantManager.PlatformType = 'WEB_MOBILE';
+        let _valueType: StatsQuery.ConstantManager.ValueType = true;
+        expect(_platformType).toBe('WEB_MOBILE');
+        expect(_valueType).toBe(true);
+    });
 });