@easytwin/devkit 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -5,7 +5,7 @@ declare const CONFIG_FILE_NAME = "easytwin.config.json";
  */
 declare const DEFAULT_BASE_URL = "http://saas-twin.k8s.dtstack.cn/";
 /** 官方测试环境域名。 */
-declare const TEST_BASE_URL = "http://saas-twin-test.k8s.dtstack.cn/";
+declare const TEST_BASE_URL = "http://172.16.125.3:10100/";
 /**
  * 官方 OSS(twin runtime baseOSSUrl)。系统资产由此拼出:
  * `{ossUrl}/easytwin/system/libs/webp-wasm.wasm`、
@@ -30,6 +30,20 @@ interface EasyTwinConfig {
     baseUrl?: string;
     /** twin runtime 资产根(baseOSSUrl);缺省官方 OSS,可覆盖为 CDN/自建存储。 */
     ossUrl?: string;
+    /**
+     * 关联场景摘要,由 scene list / 场景树刷新写入(D17)。
+     * 不含场景 JSON 本体;下次 list 全量覆盖。
+     */
+    scenes?: ConfigScene[];
+}
+/** 写入 easytwin.config.json 的关联场景摘要(对应 listScenes 的可序列化子集)。 */
+interface ConfigScene {
+    /** Scene Key,与 `easytwin scene pull <id>` 对应。 */
+    id: string;
+    name: string;
+    linkedSceneId?: string;
+    snapshotUrl?: string;
+    defaultLoading?: boolean;
 }
 /** 解析 + 环境变量覆盖后的最终配置。 */
 interface ResolvedConfig {
@@ -38,7 +52,7 @@ interface ResolvedConfig {
     baseUrl: string;
     /** twin runtime baseOSSUrl(系统库 draco/basis/webp、custom script 与相对路径资产);缺省官方 OSS。 */
     ossUrl: string;
-    /** 本地测试模式:appId/appSecret 均为 "test" 时启用,scene/upload 走本地 mock 不发请求。 */
+    /** 本地测试模式:appId/appSecret 均为 "test" 时启用,scene/upload/pull 走本地 mock 不发请求。 */
     mock: boolean;
     source: "file" | "env";
 }
@@ -67,19 +81,25 @@ interface InitResult {
 }
 /** init 的 lib 实现:生成配置文件 + 追加 gitignore(与插件配置向导共用同一实现)。 */
 declare function initConfig(input: EasyTwinConfig, cwd: string): Promise<InitResult>;
+/** 把场景摘要写入配置 `scenes`(全量覆盖该数组,保留其余字段)。 */
+declare function writeConfigScenes(cwd: string, scenes: ConfigScene[]): Promise<void>;
 
 /**
- * TODO(swagger): 认证头名称、endpoint 路径、请求/响应结构一律以内部 swagger 为准。
- * 以下常量为占位约定;swagger 到位后在 client.ts / scene.ts / upload.ts 集中修订,不扩散到其它文件。
+ * 认证与路径以内部 swagger 为准(标签:SDK 应用场景 / 分享相关 / SDK 应用代码)。
+ * 全仓唯一认证头注入点:`x-app-id` = App ID,`x-app-secret` = App Secret(D20)。
+ * share 代码与场景列表接口无路径参数(D21 / D22);上传不请求仍走 OP 网关的 workspace-config(D24)。
  */
-declare const AUTH_HEADER = "Authorization";
-declare const BEARER_PREFIX = "Bearer";
-/** TODO(swagger): 应用标识头名待定(上传目标空间由 App ID 决定)。 */
-declare const APP_ID_HEADER = "X-Easytwin-App-Id";
+declare const APP_ID_HEADER = "x-app-id";
+declare const AUTH_HEADER = "x-app-secret";
 declare const ENDPOINTS: {
-    readonly scenes: "/api/scenes";
-    readonly scene: (id: string) => string;
-    readonly upload: "/api/upload";
+    /** POST 已关联场景列表(分享路径,空 body)。 */
+    readonly linkedScenes: () => string;
+    /** POST 拉取工作区全部代码文件(分享路径,空 body)。 */
+    readonly workspaceCodePull: () => string;
+    /** POST 一次推送 create/update/delete(分享路径)。 */
+    readonly workspaceCodePush: () => string;
+    /** GET 工作区文件约束(仍带 applicationId,走 OP 网关;上传不调用,拉取失败则降级)。 */
+    readonly workspaceConfig: (applicationId: string) => string;
 };
 declare class EasyTwinApiError extends Error {
     readonly status: number;
@@ -87,16 +107,19 @@ declare class EasyTwinApiError extends Error {
     constructor(status: number, message: string, body?: unknown);
 }
 interface RequestOptions {
-    method?: "GET" | "POST" | "PUT" | "DELETE";
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
     headers?: Record<string, string>;
     body?: string | null;
     signal?: AbortSignal;
 }
 declare class EasyTwinClient {
     readonly baseUrl: string;
-    /** 本地测试模式:true 时 scene/upload 走本地 mock,不发网络请求(见 config.ts)。 */
+    /** twin runtime / 场景快照资产根(baseOSSUrl)。 */
+    readonly ossUrl: string;
+    /** 接入凭证 App ID;写入 `x-app-id`,workspace-config 路径仍可用。 */
+    readonly appId: string;
+    /** 本地测试模式:true 时 scene/upload/pull 走本地 mock,不发网络请求(见 config.ts)。 */
     readonly mock: boolean;
-    private readonly appId;
     private readonly appSecret;
     constructor(config: ResolvedConfig);
     /** 全仓唯一认证头注入点。 */
@@ -115,21 +138,49 @@ declare class EasyTwinClient {
     private handleStatus;
 }
 
+/** swagger `SdkApplicationLinkedSceneVo`。 */
+interface LinkedScene {
+    /** 关联记录 ID。 */
+    id: string;
+    /** SDK 业务标识 Scene Key(list/pull 的主键)。 */
+    sceneKey: string;
+    name: string;
+    defaultLoading: boolean;
+    sourceSceneId: string;
+    sourceProjectId: string;
+    sourceSceneName: string;
+    sourceProjectName: string;
+    sourceLost: boolean;
+    /** 场景快照 JSON 的 OSS 相对路径(或绝对 URL)。 */
+    snapshotUrl: string;
+    snapshotUpdatedAt: string;
+}
 interface SceneSummary {
+    /** Scene Key,与 `easytwin scene pull <id>` 对应。 */
     id: string;
     name: string;
+    linkedSceneId?: string;
+    snapshotUrl?: string;
+    defaultLoading?: boolean;
 }
 interface SceneDetail {
     id: string;
     name: string;
     /**
-     * 服务端返回的场景 JSON 原始内容。
+     * 场景快照 JSON 原始内容。
      * 结构以 easytwin-runtime 的 SceneJson 为准(见 skills/easytwin-scene)。
      */
     payload: unknown;
 }
+/** 从信封/Runtime VO/数组中取出场景列表。 */
+declare function extractSceneArray(data: unknown): unknown[];
+/** 把 swagger 关联场景 / Runtime scenes 规范为 LinkedScene[]。 */
+declare function normalizeLinkedScenes(data: unknown): LinkedScene[];
 declare function normalizeSceneList(data: unknown): SceneSummary[];
-declare function normalizeSceneDetail(data: unknown): SceneDetail;
+/** 把 list 结果收成配置里的 scenes 摘要(省略空可选字段)。 */
+declare function toConfigScenes(scenes: SceneSummary[]): ConfigScene[];
+/** 拼接场景快照地址:绝对 URL 原样使用,否则挂到 ossUrl 下。 */
+declare function resolveSnapshotUrl(ossUrl: string, snapshotUrl: string): string;
 /** devkit 包内本地测试场景文件名(4.4 本地测试模式)。 */
 declare const EXAMPLE_SCENE_FILE = "scene.example.json";
 /** 本地测试模式下场景列表展示的名字(示例文件本身不含场景级 name)。 */
@@ -147,6 +198,7 @@ declare function deriveExampleSceneId(payload: unknown): string;
 declare function exampleSceneSummary(exampleFile?: string): Promise<SceneSummary>;
 declare function listScenes(client: EasyTwinClient, options?: {
     exampleFile?: string;
+    cwd?: string;
 }): Promise<SceneSummary[]>;
 declare function pullScene(client: EasyTwinClient, id: string, options?: {
     exampleFile?: string;
@@ -177,19 +229,69 @@ interface UploadProgress {
 }
 interface UploadOptions {
     onProgress?: (progress: UploadProgress) => void;
-    /** 自定义忽略规则,默认只跳过 .git。 */
+    /** 额外忽略规则;默认已跳过插件产物与相关文件(D23)。 */
     ignore?: (relPath: string) => boolean;
 }
+interface CollectedFile {
+    relPath: string;
+    absPath: string;
+    size: number;
+}
 interface UploadResult {
     fileCount: number;
     byteCount: number;
+    created: number;
+    updated: number;
+    deleted: number;
+    unchanged: number;
     /** 本地测试模式(dry-run)时置 true:未真正上传。 */
     mock?: boolean;
 }
-interface CollectedFile {
-    relPath: string;
-    absPath: string;
-    size: number;
+interface UploadCreate {
+    file: CollectedFile;
+    content: string;
+}
+interface UploadUpdate {
+    file: CollectedFile;
+    id: string;
+    content: string;
+}
+interface UploadDelete {
+    id: string;
+    filePath: string;
+}
+/** 对照远端文件,本地区分新增 / 更新 / 删除(D21,一次 push)。 */
+interface WorkspaceUploadPlan {
+    creates: UploadCreate[];
+    updates: UploadUpdate[];
+    deletes: UploadDelete[];
+    unchanged: CollectedFile[];
+}
+/** 上传/拉取共同跳过:插件产物、agent 目录、构建产物与凭据。 */
+declare const WORKSPACE_IGNORED_DIRS: Set<string>;
+declare const WORKSPACE_IGNORED_FILES: Set<string>;
+/** 与 push 服务端一致的工作区代码扩展名(D25)。 */
+declare const WORKSPACE_CODE_EXTENSIONS: readonly [".ts", ".tsx", ".js", ".json"];
+/** 工作区本地预览测试文件:不参与 pull/upload(D27)。 */
+declare function isWorkspaceSpecFile(relPath: string): boolean;
+/**
+ * 插件产物、凭据、构建目录与场景快照。
+ * 不含 `*.spec.ts`(预览测试扫描需要读这些文件)。
+ */
+declare function isIgnoredWorkspacePath(relPath: string): boolean;
+/** 跳过插件产物/凭据/场景快照,以及本地预览测试文件 `*.spec.ts`(D23 / D26 / D27)。 */
+declare function defaultWorkspaceIgnore(relPath: string): boolean;
+/** swagger `SdkApplicationWorkspaceCodeConfigVo`。 */
+interface WorkspaceCodeConfig {
+    allowedFileExtensions: string[];
+    maxCodeFiles: number;
+    maxCodeDirectoryDepth: number;
+}
+/** swagger `SdkApplicationWorkspaceCodeFileVo`。 */
+interface WorkspaceCodeFile {
+    id: string;
+    filePath: string;
+    content: string;
 }
 /** 递归收集目录下全部文件(默认跳过 .git),按相对路径升序排列,保证顺序稳定。 */
 declare function collectFiles(dir: string, ignore?: (relPath: string) => boolean): Promise<CollectedFile[]>;
@@ -197,13 +299,151 @@ declare function buildMultipartBody(boundary: string, fields: Record<string, str
     name: string;
     content: Buffer;
 }): Buffer;
-/** 全量覆盖上传目录:逐文件 multipart 上传,带进度回调(供插件进度条)。本地测试模式(mock)时退化为 dry-run。 */
+declare function normalizePath(relPath: string): string;
+declare function normalizeWorkspaceConfig(data: unknown): WorkspaceCodeConfig;
+declare function normalizeWorkspaceFiles(data: unknown): WorkspaceCodeFile[];
+/** 是否为可同步的工作区代码文件(`.ts` / `.tsx` / `.js` / `.json`)。 */
+declare function isWorkspaceCodeFile(relPath: string): boolean;
+/** 目录深度:根文件为 0,`src/a.ts` 为 1,`src/utils/a.ts` 为 2。 */
+declare function directoryDepth(relPath: string): number;
+declare function assertUploadable(files: CollectedFile[], config: WorkspaceCodeConfig): void;
+/**
+ * 对照远端工作区文件,把本地文件分成新增 / 更新 / 删除 / 未变。
+ * 不做本地清单:每次上传以本次 GET 的远端列表为准。
+ */
+declare function planWorkspaceUpload(local: {
+    file: CollectedFile;
+    content: string;
+}[], remote: WorkspaceCodeFile[]): WorkspaceUploadPlan;
+declare function formatUploadResult(result: UploadResult): string;
+/** swagger `PushSdkApplicationWorkspaceCodeDto`:字段均可选,有变更才带上。 */
+declare function buildWorkspacePushBody(plan: WorkspaceUploadPlan): Record<string, unknown> | null;
+/**
+ * 全量对齐上传目录:对照远端工作区,本地 diff 后一次 push(create/update/delete)。
+ * 不请求仍走 OP 网关的 workspace-config(D24);只收集 `.ts`/`.tsx`/`.js`/`.json`(D25)。本地测试模式(mock)时退化为 dry-run。
+ */
 declare function uploadDirectory(client: EasyTwinClient, dir: string, options?: UploadOptions): Promise<UploadResult>;
 
+declare const DEFAULT_ENTRY_PATH = "src/main.ts";
+/** 与 easytwin-render 可上传子集示例对齐的默认 TwinApp 子类入口。 */
+declare const DEFAULT_MAIN_TS = "import { TwinApp, type TwinAppContext } from \"@easytwin/apps\";\n\nexport default class App extends TwinApp {\n  async init(ctx: TwinAppContext) {\n    // engine / container \u5DF2\u6709;scene / camera \u4E3A null\n    void ctx;\n  }\n\n  async onSceneLoaded(ctx: TwinAppContext) {\n    // \u573A\u666F\u5B57\u6BB5\u6709\u503C;\u5728\u6B64\u52A0\u7269\u4F53 / \u7ED1\u4E8B\u4EF6,\u5E76\u7528 ctx.sceneCleanup \u5BF9\u79F0\u62C6\u9664\n    void ctx;\n  }\n\n  onUpdate(ctx: TwinAppContext, delta: number, elapsed: number) {\n    void ctx;\n    void delta;\n    void elapsed;\n  }\n\n  onDispose(ctx: TwinAppContext) {\n    void ctx;\n  }\n}\n";
+type WorkspaceChangeKind = "identical" | "remote-only" | "local-only" | "modified" | "seed";
+interface WorkspaceFileChange {
+    path: string;
+    kind: WorkspaceChangeKind;
+    localContent?: string;
+    remoteContent?: string;
+}
+interface WorkspacePullPlan {
+    remoteEmpty: boolean;
+    seededDefaults: boolean;
+    mock?: boolean;
+    skippedRemotePaths: string[];
+    changes: WorkspaceFileChange[];
+}
+interface WorkspacePullOptions {
+    /** 用远端内容覆盖内容冲突的本地文件;仅本地文件仍不删除。 */
+    force?: boolean;
+    /** 只算计划,不写盘。 */
+    dryRun?: boolean;
+    ignore?: (relPath: string) => boolean;
+}
+interface WorkspacePullResult {
+    plan: WorkspacePullPlan;
+    written: string[];
+    skippedConflicts: string[];
+    dryRun?: boolean;
+    mock?: boolean;
+}
+declare function defaultPullIgnore(relPath: string): boolean;
+/** 拒绝逃逸、空路径与凭据文件,避免远端路径写到工作区外。 */
+declare function isSafeRelPath(relPath: string): boolean;
+/**
+ * 对照远端工作区代码与本地目录,算出 diff 计划。
+ * mock 或远端无有效文件时,本地缺省入口视为 seed。
+ */
+declare function planWorkspacePull(client: EasyTwinClient, dir: string, options?: Pick<WorkspacePullOptions, "ignore">): Promise<WorkspacePullPlan>;
+interface WorkspacePullApplyResult {
+    written: string[];
+    skippedConflicts: string[];
+}
+/** 按计划写盘:seed 与 remote-only 始终写入;modified 仅 force 时覆盖;不删 local-only。 */
+declare function applyWorkspacePull(dir: string, plan: WorkspacePullPlan, options?: {
+    force?: boolean;
+}): Promise<WorkspacePullApplyResult>;
+declare function pullWorkspace(client: EasyTwinClient, dir: string, options?: WorkspacePullOptions): Promise<WorkspacePullResult>;
+declare function formatWorkspacePullPlan(plan: WorkspacePullPlan): string;
+declare function formatWorkspacePullResult(result: WorkspacePullResult): string;
+declare function workspacePullHasConflicts(plan: WorkspacePullPlan): boolean;
+declare function workspacePullPendingWrites(plan: WorkspacePullPlan, force?: boolean): string[];
+
+/** 用户代码固定入口(相对工作区根)。 */
+declare const USER_ENTRY = "src/main.ts";
+/** CLI 缺省输出路径(相对工作区根)。 */
+declare const DEFAULT_BUNDLE_OUT = "dist/main.js";
+/** 白名单允许的裸模块。 */
+declare const RUNTIME_MODULE = "@easytwin/runtime";
+declare const APPS_MODULE = "@easytwin/apps";
+declare class BundleError extends Error {
+    constructor(message: string);
+}
+interface BundleUserCodeOptions {
+    cwd: string;
+    /** 缺省不落盘,只返回产物字符串(插件内存编译);CLI 传入绝对/相对路径。 */
+    outFile?: string;
+}
+interface BundleWorkspaceModuleOptions extends BundleUserCodeOptions {
+    /** 相对 cwd 的入口文件(posix 或当前平台分隔符均可)。 */
+    entry: string;
+    /** 入口缺失时的报错文案;缺省按路径拼一条。 */
+    missingEntryMessage?: string;
+}
+interface BundleResult {
+    code: string;
+    warnings: string[];
+}
+/** 打包工作区任意入口。产物标准 ESM + inline sourcemap;仅允许 @easytwin/runtime 与 @easytwin/apps。 */
+declare function bundleWorkspaceModule(options: BundleWorkspaceModuleOptions): Promise<BundleResult>;
+/** 打包工作区 src/main.ts。产物标准 ESM + inline sourcemap;仅允许 @easytwin/runtime 与 @easytwin/apps。 */
+declare function bundleUserCode(options: BundleUserCodeOptions): Promise<BundleResult>;
+/** 若工作区尚未同步 runtime 类型,返回提示文案;已同步则返回 undefined。 */
+declare function typesMissingHint(cwd: string): Promise<string | undefined>;
+interface SourceMapJson {
+    sources?: string[];
+    mappings?: string;
+}
+declare function extractInlineSourceMap(code: string): SourceMapJson | undefined;
+/**
+ * 把 bundled JS 的 stack(blob: 行号)映射回 TS 源码行号。
+ * 映射失败时原样返回。
+ */
+declare function remapErrorStack(stack: string, bundledCode: string): string;
+
+interface WorkspaceTestCase {
+    /** `${file}:${name}`,文件内唯一。 */
+    id: string;
+    /** 相对工作区根的 posix 路径。 */
+    file: string;
+    name: string;
+    /** 除 ctx 外还有参数时,预览显示输入框。 */
+    hasInput: boolean;
+    /** 第二个参数名,作输入框占位。 */
+    inputName?: string;
+}
+/** 从 spec 源码解析命名导出的函数(跳过 default / type / class / 再导出)。 */
+declare function parseExportedTestFunctions(source: string): Omit<WorkspaceTestCase, "id" | "file">[];
+declare function workspaceTestId(file: string, name: string): string;
+/** 扫描工作区 `*.spec.ts` 的命名导出函数。跳过插件产物目录,不跳过 spec 本身。 */
+declare function listWorkspaceTests(cwd: string): Promise<WorkspaceTestCase[]>;
+declare function bundleWorkspaceTestFile(options: {
+    cwd: string;
+    file: string;
+}): Promise<BundleResult>;
+
 type SyncTarget = "cursor" | "claude" | "codex" | "qoder";
 type SyncTargetArg = SyncTarget | "all";
-/** 六件套清单(5.1),顺序即输出顺序。 */
-declare const SKILL_NAMES: readonly ["easytwin-render", "easytwin-core", "easytwin-develop", "easytwin-bootstrap", "easytwin-scene", "easytwin-upload"];
+/** 七件套清单(5.1),顺序即输出顺序。 */
+declare const SKILL_NAMES: readonly ["easytwin-render", "easytwin-core", "easytwin-develop", "easytwin-bootstrap", "easytwin-scene", "easytwin-upload", "easytwin-test"];
 type SyncAction = "created" | "updated" | "unchanged";
 interface SyncEntrySummary {
     name: string;
@@ -229,7 +469,9 @@ declare const META_FILE_NAME = ".easytwin-meta.json";
 /** 用户项目内 runtime 类型落地目录(posix)。 */
 declare const EASYTWIN_TYPES_DIR = ".easytwin/types";
 declare const MINIMAL_TSCONFIG: string;
-declare const TSCONFIG_PATHS_HINT = "\u5DF2\u6709 tsconfig.json,\u672A\u6539\u52A8\u3002\u8BF7\u5728 compilerOptions \u4E2D\u52A0\u5165:\n  \"skipLibCheck\": true,\n  \"paths\": {\n    \"@easytwin/runtime\": [\".easytwin/types\"]\n  }";
+declare const TSCONFIG_PATHS_HINT = "\u5DF2\u6709 tsconfig.json,\u672A\u6539\u52A8\u3002\u8BF7\u5728 compilerOptions \u4E2D\u52A0\u5165:\n  \"skipLibCheck\": true,\n  \"paths\": {\n    \"@easytwin/runtime\": [\".easytwin/types\"],\n    \"@easytwin/apps\": [\".easytwin/types/apps\"]\n  }";
+declare const APPS_TYPES_FILE = "apps.d.ts";
+declare const APPS_DTS = "import type { RuntimeEngine, RuntimeScene, SceneManager } from \"@easytwin/runtime\";\n\nexport type TwinAppContext = {\n    app: {\n        id: string;\n        mode: \"preview\" | \"publish\";\n    };\n    engine: RuntimeEngine;\n    container: HTMLElement;\n    runtimeScene: RuntimeScene | null;\n    scene: RuntimeScene[\"sceneObject\"] | null;\n    camera: RuntimeScene[\"camera\"][\"main\"] | null;\n    sceneManager: {\n        currentSceneId: string;\n        runtime: SceneManager | null;\n        loadScene(sceneId: string): Promise<void>;\n    };\n    logger: {\n        log(...args: unknown[]): void;\n        info(...args: unknown[]): void;\n        warn(...args: unknown[]): void;\n        error(...args: unknown[]): void;\n    };\n    assets: {\n        text(path: string): Promise<string>;\n        json<T = unknown>(path: string): Promise<T>;\n    };\n    cleanup(fn: () => void | Promise<void>): void;\n    sceneCleanup(fn: () => void | Promise<void>): void;\n};\n\nexport declare abstract class TwinApp {\n    init?(ctx: TwinAppContext): void | Promise<void>;\n    onUpdate?(ctx: TwinAppContext, delta: number, elapsed: number): void;\n    onBeforeSceneUnload?(ctx: TwinAppContext): void | Promise<void>;\n    onSceneLoaded?(ctx: TwinAppContext): void | Promise<void>;\n    onDispose?(ctx: TwinAppContext): void | Promise<void>;\n    onError?(ctx: TwinAppContext, error: unknown): boolean | void;\n}\n\nexport declare function defineApp<T>(app: T): T;\n";
 declare function buildRuntimeTypesContent(sourceDts: string): string;
 declare function normalizeTargets(target?: SyncTargetArg | SyncTarget[]): SyncTarget[];
 /** skills 源目录默认解析:CLI 下为 devkit 包内 skills/。插件 bundle 到 CJS 后 import.meta.url 为空,
@@ -261,37 +503,181 @@ interface SkillsStatus {
 /** 供插件"缺失/过期时提示一次"使用:检测各目标当前同步状态。 */
 declare function detectSkillsStatus(cwd: string, sourceDir?: string): Promise<SkillsStatus>;
 
-/** 用户代码固定入口(相对工作区根)。 */
-declare const USER_ENTRY = "src/main.ts";
-/** CLI 缺省输出路径(相对工作区根)。 */
-declare const DEFAULT_BUNDLE_OUT = "dist/main.js";
-/** 白名单唯一允许的裸模块。 */
-declare const RUNTIME_MODULE = "@easytwin/runtime";
-declare class BundleError extends Error {
-    constructor(message: string);
-}
-interface BundleUserCodeOptions {
-    cwd: string;
-    /** 缺省不落盘,只返回产物字符串(插件内存编译);CLI 传入绝对/相对路径。 */
-    outFile?: string;
-}
-interface BundleResult {
-    code: string;
-    warnings: string[];
+/** 在线 TwinApp 编译 stub 露出的 `@easytwin/runtime` 导出名。本地整包 external,超出此集合只 warning。 */
+declare const PORTABLE_RUNTIME_EXPORTS: readonly ["THREE", "RuntimeEngine", "SceneManager", "LoadSceneMode", "convertObjToComponentJson"];
+type PortableRuntimeExport = (typeof PORTABLE_RUNTIME_EXPORTS)[number];
+type TwinAppEngine = {
+    container: HTMLElement;
+    time: {
+        deltaTime: number;
+        elapsedTime: number;
+    };
+    mainScene?: TwinAppRuntimeScene | null;
+    getManager(ctor: unknown): TwinAppSceneManager | null;
+    destroy(): void;
+};
+type TwinAppRuntimeScene = {
+    sceneObject?: {
+        add(object: unknown): void;
+        remove(object: unknown): void;
+    } | null;
+    camera?: {
+        main?: unknown;
+    } | null;
+};
+type TwinAppSceneManager = {
+    loadScene(...args: unknown[]): Promise<unknown>;
+};
+type TwinAppContext = {
+    app: {
+        id: string;
+        mode: "preview" | "publish";
+    };
+    engine: TwinAppEngine;
+    container: HTMLElement;
+    runtimeScene: TwinAppRuntimeScene | null;
+    scene: TwinAppRuntimeScene["sceneObject"] | null;
+    camera: unknown | null;
+    sceneManager: {
+        currentSceneId: string;
+        runtime: TwinAppSceneManager | null;
+        loadScene(sceneId: string): Promise<void>;
+    };
+    logger: {
+        log(...args: unknown[]): void;
+        info(...args: unknown[]): void;
+        warn(...args: unknown[]): void;
+        error(...args: unknown[]): void;
+    };
+    assets: {
+        text(path: string): Promise<string>;
+        json<T = unknown>(path: string): Promise<T>;
+    };
+    cleanup(fn: () => void | Promise<void>): void;
+    sceneCleanup(fn: () => void | Promise<void>): void;
+};
+declare abstract class TwinApp {
+    init?(ctx: TwinAppContext): void | Promise<void>;
+    onUpdate?(ctx: TwinAppContext, delta: number, elapsed: number): void;
+    onBeforeSceneUnload?(ctx: TwinAppContext): void | Promise<void>;
+    onSceneLoaded?(ctx: TwinAppContext): void | Promise<void>;
+    onDispose?(ctx: TwinAppContext): void | Promise<void>;
+    onError?(ctx: TwinAppContext, error: unknown): boolean | void;
 }
-/** 打包工作区 src/main.ts。产物标准 ESM + inline sourcemap;仅允许依赖 @easytwin/runtime。 */
-declare function bundleUserCode(options: BundleUserCodeOptions): Promise<BundleResult>;
-/** 若工作区尚未同步 runtime 类型,返回提示文案;已同步则返回 undefined。 */
-declare function typesMissingHint(cwd: string): Promise<string | undefined>;
-interface SourceMapJson {
-    sources?: string[];
-    mappings?: string;
+declare function defineApp<T>(app: T): T;
+/** 把用户模块 default 导出收成 TwinApp 实例。函数式 `main` 不认。 */
+declare function createAppInstance(appExport: unknown): TwinApp;
+declare function portableRuntimeWarning(names: Iterable<string>): string | undefined;
+
+/**
+ * 把 ctx.assets 的相对路径落到工作区磁盘。规范化后必须仍在 cwd 内。
+ */
+declare function resolveWorkspaceAssetPath(cwd: string, relPath: string): string;
+
+declare const LOCAL_LOAD_SCENE_ERROR = "\u672C\u5730\u9884\u89C8\u5355\u573A\u666F,\u4E0D\u80FD\u8C03\u7528 sceneManager.loadScene";
+declare const MISSING_TICK_ERROR = "\u5F53\u524D runtime \u4E0D\u652F\u6301\u5F15\u64CE\u65F6\u949F(\u7F3A\u5C11 registerEngineTickListener)\u3002\u65E0\u6CD5\u8FD0\u884C onUpdate\u3002";
+type TwinAppTickListener = (engine: TwinAppEngine) => void;
+type TwinAppRuntimeModule = {
+    RuntimeEngine: {
+        create(config: Record<string, unknown>): Promise<TwinAppEngine>;
+    };
+    SceneManager: unknown;
+    LoadSceneMode: {
+        Single: unknown;
+    };
+    RuntimeSceneMode: {
+        Publish: unknown;
+    };
+    registerEngineTickListener?: (engine: TwinAppEngine, listener: TwinAppTickListener) => void;
+    unregisterEngineTickListener?: (engine: TwinAppEngine, listener: TwinAppTickListener) => void;
+};
+type TwinAppPreviewHostOptions = {
+    runtime: TwinAppRuntimeModule;
+    containerId: string;
+    ossUrl: string;
+    appId: string;
+    sceneId: string;
+    sceneJson: unknown;
+    customComponentDeps: Record<string, unknown>;
+    loadScene(engine: TwinAppEngine, sceneJson: unknown): Promise<void>;
+    readAsset(path: string): Promise<string>;
+    importUserModule?(code: string): Promise<{
+        default: unknown;
+    }>;
+    log?: (line: string) => void;
+};
+declare class TwinAppPreviewHost {
+    private readonly options;
+    private app;
+    private engine;
+    private disposed;
+    /** 用户应用已经成功 onSceneLoaded。 */
+    private scenePresented;
+    private tickAttached;
+    private sceneLoadTask;
+    private ctx;
+    private cleanups;
+    private sceneCleanups;
+    private warnedAsyncUpdate;
+    private userBlobUrl;
+    private currentSceneId;
+    private readonly onEngineTick;
+    constructor(options: TwinAppPreviewHostOptions);
+    getEngine(): TwinAppEngine | null;
+    /** 给 spec 调用:场景字段取当前引擎主场景(不要求已 Run TwinApp)。 */
+    getTestContext(): TwinAppContext;
+    invokeTest(fn: (ctx: TwinAppContext, input?: string) => unknown, input?: string): Promise<unknown>;
+    boot(): Promise<void>;
+    run(code: string): Promise<void>;
+    dispose(): Promise<void>;
+    private assertTickApi;
+    private importUser;
+    private loadCurrentScene;
+    private handleTick;
+    private handleUpdateError;
+    private failRun;
+    private attachTick;
+    private detachTick;
+    private teardownApp;
+    private unloadUserScene;
+    private runHooks;
+    private getContext;
 }
-declare function extractInlineSourceMap(code: string): SourceMapJson | undefined;
+
+type PreviewHostKind = "vscode" | "http";
 /**
- * 把 bundled JS 的 stack(blob: 行号)映射回 TS 源码行号。
- * 映射失败时原样返回。
+ * 纯函数:构造场景预览页 HTML(插件 webview 与 CLI localhost HTTP 共用,D28)。
+ * 单栏三维场景页:module script 动态 import twin runtime,
+ * 用场景数据经 convertObjToComponentJson + RuntimeEngine.create + loadScene 真实渲染。
+ * baseOSSUrl 必须是 ossUrl(缺省官方 OSS),不是 API baseUrl。
+ * host=vscode 且页面为 HTTPS 时,HTTP 资源经扩展宿主代理,规避 mixed content。
+ * host=http(CLI preview)时直连 API 与 OSS,走同源 `/api/*` 做 bundle/tests/assets。
+ * 底部 Run 走 TwinAppPreviewHost(D14):import map 注入 @easytwin/runtime 与 @easytwin/apps。
+ * 工作区 *.spec.ts 命名导出在 Run 栏上方列出(D27)。
  */
-declare function remapErrorStack(stack: string, bundledCode: string): string;
+declare function escapeHtml(text: string): string;
+/**
+ * 把 JSON 文本安全嵌入 `<script type="application/json">`。
+ * script 元素的内容是 raw text,HTML 实体不会解码,因此不能使用 escapeHtml;
+ * 只需把 `<`/`>` 与 U+2028/U+2029 转成 JSON 字面转义。
+ */
+declare function escapeJsonForScript(json: string): string;
+/** 纯状态页:预览加载中 / 加载失败时的兜底内容,避免空白 webview。 */
+declare function buildStatusHtml(message: string): string;
+declare function buildPreviewHtml(options: {
+    baseUrl: string;
+    ossUrl: string;
+    sceneJson: string;
+    mock?: boolean;
+    runtimeUri: string;
+    appsUri?: string;
+    hostUri?: string;
+    appId?: string;
+    /** vscode=webview postMessage+混合内容代理;http=CLI 同源 /api/*。缺省 vscode。 */
+    host?: PreviewHostKind;
+    /** VSCode webview.cspSource;缺省回退 runtimeUri 的 origin(单测用)。 */
+    cspSource?: string;
+    tests?: WorkspaceTestCase[];
+}): string;
 
-export { APP_ID_HEADER, AUTH_HEADER, BEARER_PREFIX, BundleError, type BundleResult, type BundleUserCodeOptions, CODEX_MARKER_BEGIN, CODEX_MARKER_END, CONFIG_FILE_NAME, type CollectedFile, ConfigError, DEFAULT_BASE_URL, DEFAULT_BUNDLE_OUT, DEFAULT_OSS_URL, EASYTWIN_TYPES_DIR, ENDPOINTS, EXAMPLE_SCENE_FILE, EasyTwinApiError, EasyTwinClient, type EasyTwinConfig, type EasyTwinEnv, GITIGNORE_ENTRY, GITIGNORE_FILE_NAME, type GitignoreResult, type InitResult, META_FILE_NAME, MINIMAL_TSCONFIG, MOCK_APP_ID, MOCK_APP_SECRET, MOCK_SCENE_NAME, RUNTIME_MODULE, type RequestOptions, type ResolvedConfig, SKILL_NAMES, type SceneDetail, type SceneSummary, type SceneTreeNode, type SkillsStatus, type SkillsTargetStatus, type SyncAction, type SyncEntrySummary, type SyncOptions, type SyncSkillsResult, type SyncSummary, type SyncTarget, type SyncTargetArg, TEST_BASE_URL, TSCONFIG_PATHS_HINT, type TypesSyncSummary, USER_ENTRY, type UploadOptions, type UploadProgress, type UploadResult, appendGitignore, buildMultipartBody, buildRuntimeTypesContent, bundleUserCode, collectFiles, configFilePath, deriveExampleSceneId, detectSkillsStatus, exampleSceneSummary, extractInlineSourceMap, initConfig, isMockCredentials, listScenes, loadConfig, loadExampleScene, normalizeSceneDetail, normalizeSceneList, normalizeTargets, parseConfig, parseSceneStructure, pullScene, readConfigFile, readDevkitVersion, remapErrorStack, resolveConfig, resolveExampleScenePath, resolveRuntimeTypesSourceFile, resolveSkillsSourceDir, saveSceneJson, syncSkills, typesMissingHint, uploadDirectory, validateConfigShape, writeConfigFile };
+export { APPS_DTS, APPS_MODULE, APPS_TYPES_FILE, APP_ID_HEADER, AUTH_HEADER, BundleError, type BundleResult, type BundleUserCodeOptions, type BundleWorkspaceModuleOptions, CODEX_MARKER_BEGIN, CODEX_MARKER_END, CONFIG_FILE_NAME, type CollectedFile, ConfigError, type ConfigScene, DEFAULT_BASE_URL, DEFAULT_BUNDLE_OUT, DEFAULT_ENTRY_PATH, DEFAULT_MAIN_TS, DEFAULT_OSS_URL, EASYTWIN_TYPES_DIR, ENDPOINTS, EXAMPLE_SCENE_FILE, EasyTwinApiError, EasyTwinClient, type EasyTwinConfig, type EasyTwinEnv, GITIGNORE_ENTRY, GITIGNORE_FILE_NAME, type GitignoreResult, type InitResult, LOCAL_LOAD_SCENE_ERROR, type LinkedScene, META_FILE_NAME, MINIMAL_TSCONFIG, MISSING_TICK_ERROR, MOCK_APP_ID, MOCK_APP_SECRET, MOCK_SCENE_NAME, PORTABLE_RUNTIME_EXPORTS, type PortableRuntimeExport, type PreviewHostKind, RUNTIME_MODULE, type RequestOptions, type ResolvedConfig, SKILL_NAMES, type SceneDetail, type SceneSummary, type SceneTreeNode, type SkillsStatus, type SkillsTargetStatus, type SyncAction, type SyncEntrySummary, type SyncOptions, type SyncSkillsResult, type SyncSummary, type SyncTarget, type SyncTargetArg, TEST_BASE_URL, TSCONFIG_PATHS_HINT, TwinApp, type TwinAppContext, type TwinAppEngine, TwinAppPreviewHost, type TwinAppPreviewHostOptions, type TwinAppRuntimeModule, type TwinAppRuntimeScene, type TwinAppSceneManager, type TwinAppTickListener, type TypesSyncSummary, USER_ENTRY, type UploadCreate, type UploadDelete, type UploadOptions, type UploadProgress, type UploadResult, type UploadUpdate, WORKSPACE_CODE_EXTENSIONS, WORKSPACE_IGNORED_DIRS, WORKSPACE_IGNORED_FILES, type WorkspaceChangeKind, type WorkspaceCodeConfig, type WorkspaceCodeFile, type WorkspaceFileChange, type WorkspacePullApplyResult, type WorkspacePullOptions, type WorkspacePullPlan, type WorkspacePullResult, type WorkspaceTestCase, type WorkspaceUploadPlan, appendGitignore, applyWorkspacePull, assertUploadable, buildMultipartBody, buildPreviewHtml, buildRuntimeTypesContent, buildStatusHtml, buildWorkspacePushBody, bundleUserCode, bundleWorkspaceModule, bundleWorkspaceTestFile, collectFiles, configFilePath, createAppInstance, defaultPullIgnore, defaultWorkspaceIgnore, defineApp, deriveExampleSceneId, detectSkillsStatus, directoryDepth, escapeHtml, escapeJsonForScript, exampleSceneSummary, extractInlineSourceMap, extractSceneArray, formatUploadResult, formatWorkspacePullPlan, formatWorkspacePullResult, initConfig, isIgnoredWorkspacePath, isMockCredentials, isSafeRelPath, isWorkspaceCodeFile, isWorkspaceSpecFile, listScenes, listWorkspaceTests, loadConfig, loadExampleScene, normalizeLinkedScenes, normalizePath, normalizeSceneList, normalizeTargets, normalizeWorkspaceConfig, normalizeWorkspaceFiles, parseConfig, parseExportedTestFunctions, parseSceneStructure, planWorkspacePull, planWorkspaceUpload, portableRuntimeWarning, pullScene, pullWorkspace, readConfigFile, readDevkitVersion, remapErrorStack, resolveConfig, resolveExampleScenePath, resolveRuntimeTypesSourceFile, resolveSkillsSourceDir, resolveSnapshotUrl, resolveWorkspaceAssetPath, saveSceneJson, syncSkills, toConfigScenes, typesMissingHint, uploadDirectory, validateConfigShape, workspacePullHasConflicts, workspacePullPendingWrites, workspaceTestId, writeConfigFile, writeConfigScenes };