@djvlc/contracts-types 1.7.0 → 1.7.2

package/dist/index.d.mts

@@ -790,6 +790,116 @@ interface Expression {
         returnType?: string;
     };
 }
+/**
+ * 表达式求值上下文
+ *
+ * @description
+ * 表达式引擎在求值时可访问的上下文对象。
+ * 所有动态表达式（state/binding/context/template/computed）都从此上下文获取数据。
+ *
+ * 使用场景：
+ * - Runtime 表达式求值
+ * - 编辑器表达式预览
+ * - 表达式校验与调试
+ *
+ * @example
+ * ```typescript
+ * const ctx: ExpressionContext = {
+ *   state: { count: 0, userInfo: { name: 'Alice' } },
+ *   binding: { userList: [{ id: 1, name: 'Bob' }] },
+ *   context: { item: { id: 1, name: 'Bob' }, index: 0 },
+ * };
+ *
+ * // 求值 { type: 'state', value: 'userInfo.name' } => 'Alice'
+ * // 求值 { type: 'context', value: 'item.name' } => 'Bob'
+ * ```
+ */
+interface ExpressionContext {
+    /**
+     * 页面状态
+     *
+     * @description
+     * 对应 PageState.fields 的运行时值。
+     * 表达式通过 { type: 'state', value: 'fieldName.path' } 访问。
+     */
+    state: Record<string, unknown>;
+    /**
+     * 数据绑定结果
+     *
+     * @description
+     * 对应 DataBinding 查询的返回数据，按 bindingId 组织。
+     * 表达式通过 { type: 'binding', value: 'bindingId.path' } 访问。
+     */
+    binding: Record<string, unknown>;
+    /**
+     * 局部上下文
+     *
+     * @description
+     * 包含循环变量、事件参数等临时作用域数据。
+     * 表达式通过 { type: 'context', value: 'item.path' } 访问。
+     */
+    context: ExpressionLocalContext;
+    /**
+     * 组件属性（可选）
+     *
+     * @description
+     * 当前组件的 props 值，供组件内部表达式访问。
+     * 通常在组件内部求值时提供。
+     */
+    props?: Record<string, unknown>;
+    /**
+     * 当前事件（可选）
+     *
+     * @description
+     * 事件处理器执行时的事件对象。
+     * 仅在事件处理链中可用。
+     */
+    event?: ExpressionEventContext;
+}
+/**
+ * 局部上下文（循环变量、事件参数等）
+ */
+interface ExpressionLocalContext {
+    /**
+     * 循环项（loop.itemName 指定的变量名）
+     *
+     * @description
+     * 在 loop 渲染中，当前迭代的数据项。
+     */
+    item?: unknown;
+    /**
+     * 循环索引（loop.indexName 指定的变量名）
+     *
+     * @description
+     * 在 loop 渲染中，当前迭代的索引。
+     */
+    index?: number;
+    /**
+     * 动态扩展字段
+     *
+     * @description
+     * 支持自定义局部变量，如嵌套循环的多个 item/index。
+     */
+    [key: string]: unknown;
+}
+/**
+ * 事件上下文
+ */
+interface ExpressionEventContext {
+    /** 事件类型 */
+    type: string;
+    /** 事件目标（组件实例 ID） */
+    target?: string;
+    /** 事件载荷（组件抛出的数据） */
+    payload?: unknown;
+    /** 原生事件（如 MouseEvent 的部分安全属性） */
+    nativeEvent?: {
+        clientX?: number;
+        clientY?: number;
+        key?: string;
+        keyCode?: number;
+    };
+}
 /**
  * 任意值或表达式
  *
@@ -805,6 +915,21 @@ type AnyValueOrExpression = Expression | string | number | boolean | null | AnyV
  * @deprecated 使用 AnyValueOrExpression 代替
  */
 type PropValue = AnyValueOrExpression;
+/**
+ * 创建空的表达式上下文
+ *
+ * @description
+ * 用于初始化表达式求值环境，所有字段都有合理的默认值。
+ */
+declare function createExpressionContext(partial?: Partial<ExpressionContext>): ExpressionContext;
+/**
+ * 创建带循环变量的局部上下文
+ *
+ * @param item - 当前循环项
+ * @param index - 当前循环索引
+ * @param extras - 额外的局部变量（如嵌套循环）
+ */
+declare function createLoopContext(item: unknown, index: number, extras?: Record<string, unknown>): ExpressionLocalContext;
 /**
  * 创建字面量表达式
  * @deprecated V2 版本移除 literal 表达式类型，静态值请直接使用原始类型
@@ -1704,14 +1829,487 @@ interface PageDraft {
     updatedAt: ISODateTime;
 }
 
+/**
+ * 页面快照类型（CDN 产物核心结构）
+ *
+ * @description
+ * PageSnapshotJson 是发布后生成的运行时渲染闭包，包含：
+ * - 页面渲染数据
+ * - 组件锁定清单
+ * - Definition 版本摘要
+ * - 运维配置引用
+ * - 元数据
+ *
+ * 设计原则：一次 resolve 返回渲染所需的一切闭包，减少运行时请求次数。
+ */
+
+/**
+ * 页面快照 JSON 结构
+ *
+ * @description
+ * 对应 CDN 产物：`/pages/{pageId}/{pageVersionId}/snapshot.json`
+ * Runtime 加载此文件即可完成页面渲染。
+ */
+interface PageSnapshotJson {
+    /**
+     * 页面渲染数据
+     */
+    page: PageSnapshotPage;
+    /**
+     * 组件锁定清单
+     */
+    manifest: PageSnapshotManifest;
+    /**
+     * 绑定的 Definition 版本摘要（审计/回放用）
+     */
+    definitionsDigest: DefinitionsDigest;
+    /**
+     * 运维配置（内联或引用）
+     */
+    ops: OpsConfig;
+    /**
+     * 元数据
+     */
+    meta: PageSnapshotMeta;
+}
+/**
+ * 页面渲染数据
+ */
+interface PageSnapshotPage {
+    /** Schema 版本 */
+    schemaVersion: string;
+    /** 页面 ID */
+    pageId: string;
+    /** 页面版本 */
+    pageVersion: SemVer;
+    /** 页面标题 */
+    title: string;
+    /** 初始状态 */
+    initialState: Record<string, JsonValue>;
+    /** 数据绑定配置 */
+    bindings: DataBinding[];
+    /** 组件树根节点 */
+    root: ComponentNode;
+    /** 页面配置（画布类型、背景等） */
+    config: {
+        canvasType: 'h5' | 'tablet' | 'pc' | 'responsive';
+        canvasSize?: {
+            width: number;
+            height: number;
+        };
+        background?: {
+            type: 'color' | 'image' | 'gradient';
+            value: string;
+        };
+        cssVariables?: Record<string, string>;
+    };
+    /** SEO 配置 */
+    seo?: {
+        title?: string;
+        description?: string;
+        keywords?: string[];
+    };
+}
+/**
+ * 组件锁定清单（Snapshot 内嵌版本）
+ */
+interface PageSnapshotManifest {
+    /** 组件列表 */
+    components: SnapshotComponentEntry[];
+    /** Runtime 版本要求 */
+    runtime: {
+        /** 推荐版本 */
+        version: SemVer;
+        /** 最低版本 */
+        minVersion: SemVer;
+    };
+}
+/**
+ * Snapshot 中的组件条目
+ */
+interface SnapshotComponentEntry {
+    /** 组件名称 */
+    name: string;
+    /** 组件版本 */
+    version: SemVer;
+    /** SRI 完整性哈希 */
+    integrity: SHAIntegrity;
+    /** CDN 资源基础 URL */
+    assetsUrl: string;
+    /** 入口点 */
+    entrypoints: {
+        /** JS 入口（相对于 assetsUrl） */
+        js: string;
+        /** CSS 入口（可选） */
+        css?: string;
+        /** 分包列表（可选） */
+        chunks?: string[];
+    };
+    /** 是否预加载 */
+    preload?: boolean;
+    /** 加载优先级 */
+    priority?: 'critical' | 'high' | 'normal' | 'low';
+}
+/**
+ * Definition 版本摘要
+ *
+ * @description
+ * 记录页面绑定的 ActionDefinition 和 DataQueryDefinition 版本。
+ * 用于审计、回放、版本追溯。
+ */
+interface DefinitionsDigest {
+    /** 绑定的 Action Definition 版本 */
+    actions: DefinitionVersionDigest[];
+    /** 绑定的 Data Query Definition 版本 */
+    queries: DefinitionVersionDigest[];
+}
+/**
+ * 单个 Definition 版本摘要
+ */
+interface DefinitionVersionDigest {
+    /** Definition ID */
+    id: UniqueId;
+    /** Definition 名称 */
+    name: string;
+    /** 版本 ID */
+    versionId: UniqueId;
+    /** 内容哈希（用于完整性校验） */
+    hash: string;
+}
+/**
+ * 运维配置
+ *
+ * @description
+ * 包含 kill-switch、blocked 组件列表、功能开关等运维控制配置。
+ * 由 User API resolve 时下发，Runtime 据此做运行时控制。
+ */
+interface OpsConfig {
+    /** 配置版本 ID（用于缓存失效） */
+    configVersionId?: string;
+    /** Kill-Switch 列表（被紧急关闭的功能/动作） */
+    killSwitch: KillSwitchItem[];
+    /** 被阻断的组件列表 */
+    blockedComponents: BlockedComponentItem[];
+    /** 功能开关 */
+    flags: Record<string, boolean>;
+    /** 限流配置（可选） */
+    rateLimit?: {
+        /** 全局 QPS 限制 */
+        globalQps?: number;
+        /** 按动作类型的 QPS 限制 */
+        actionQps?: Record<string, number>;
+    };
+    /** 配置过期时间（用于缓存） */
+    expiresAt?: ISODateTime;
+}
+/**
+ * Kill-Switch 条目
+ */
+interface KillSwitchItem {
+    /** 目标类型 */
+    targetType: 'action' | 'component' | 'feature' | 'page' | 'query';
+    /** 目标 ID（actionType / componentName / featureKey / pageId / queryId） */
+    targetId: string;
+    /** 是否启用（true = 被关闭） */
+    enabled: boolean;
+    /** 关闭原因 */
+    reason?: string;
+    /** 关闭时间 */
+    enabledAt?: ISODateTime;
+    /** 关闭操作者 */
+    enabledBy?: string;
+    /** 用户提示消息 */
+    userMessage?: string;
+}
+/**
+ * 被阻断的组件条目
+ */
+interface BlockedComponentItem {
+    /** 组件名称 */
+    name: string;
+    /** 组件版本（可选，不指定则阻断所有版本） */
+    version?: SemVer;
+    /** 阻断原因 */
+    reason: string;
+    /** 阻断时间 */
+    blockedAt: ISODateTime;
+    /** 阻断操作者 */
+    blockedBy: string;
+    /** 降级版本（可选） */
+    fallbackVersion?: SemVer;
+    /** 是否紧急阻断 */
+    urgent: boolean;
+}
+/**
+ * 页面快照元数据
+ *
+ * @description
+ * 对应 CDN 产物：`/pages/{pageId}/{pageVersionId}/meta.json`
+ * 用于审计、回放、排查。
+ */
+interface PageSnapshotMeta {
+    /** 页面 ID */
+    pageId: UniqueId;
+    /** 页面版本 ID */
+    pageVersionId: UniqueId;
+    /** 发布 ID（用于追踪发布操作） */
+    publishId: UniqueId;
+    /** Schema 版本 */
+    schemaVersion: string;
+    /** 创建时间 */
+    createdAt: ISODateTime;
+    /** 创建者 */
+    createdBy: string;
+    /** 内容哈希 */
+    contentHash: string;
+    /** 绑定摘要 */
+    bindings: {
+        /** 组件版本列表（格式：name@version） */
+        componentVersions: string[];
+        /** Definition 版本列表 */
+        definitionVersions: string[];
+    };
+    /** Runtime 版本 */
+    runtimeVersion: SemVer;
+    /** 环境 */
+    env?: 'preview' | 'staging' | 'prod';
+}
+/**
+ * Bootstrap 配置
+ *
+ * @description
+ * 极小的启动参数，用于静态 HTML 场景。
+ * 对应 CDN 产物：`/pages/{pageId}/{pageVersionId}/bootstrap.json`
+ *
+ * 使用场景：
+ * - 静态 HTML 页面（不经过服务端渲染）
+ * - 嵌入式页面（iframe）
+ * - 离线缓存场景
+ */
+interface BootstrapConfig {
+    /** 页面 ID */
+    pageId: UniqueId;
+    /** 页面版本 ID */
+    pageVersionId: UniqueId;
+    /** Runtime 版本 */
+    runtimeVersion: SemVer;
+    /** Runtime 入口 URL */
+    runtimeEntryUrl: string;
+    /** 页面 JSON URL（snapshot.json） */
+    snapshotUrl: string;
+    /** Manifest URL */
+    manifestUrl: string;
+    /** CDN 基础 URL */
+    cdnBaseUrl: string;
+    /** API 基础 URL */
+    apiBaseUrl: string;
+    /** 环境 */
+    env: 'preview' | 'staging' | 'prod';
+    /** 预连接 URL 列表（性能优化） */
+    preconnectUrls?: string[];
+    /** 预加载资源列表 */
+    preloadAssets?: string[];
+}
+/**
+ * 预览 Token
+ *
+ * @description
+ * Editor 生成预览链接时使用的令牌。
+ * 存储在 Redis，短 TTL（通常 1-4 小时）。
+ *
+ * 使用流程：
+ * 1. Editor 调用 Admin API 生成预览 Token
+ * 2. 预览链接：`https://{domain}/preview/{token}`
+ * 3. Runtime 调用 User API 验证 Token 并获取草稿内容
+ */
+interface PreviewToken {
+    /** Token 值 */
+    token: string;
+    /** 页面 ID */
+    pageId: UniqueId;
+    /** 页面版本 ID（如果预览已发布版本） */
+    pageVersionId?: UniqueId;
+    /** 草稿 ID（如果预览草稿） */
+    draftId?: UniqueId;
+    /** 预览类型 */
+    type: 'draft' | 'version';
+    /** 过期时间 */
+    expiresAt: ISODateTime;
+    /** 创建时间 */
+    createdAt: ISODateTime;
+    /** 创建者 */
+    createdBy: string;
+    /** 允许的访问者（可选，用于限制预览范围） */
+    allowedViewers?: string[];
+    /** 是否允许编辑（预览时是否可以修改草稿） */
+    allowEdit?: boolean;
+}
+/**
+ * 预览 Token 创建请求
+ */
+interface CreatePreviewTokenRequest {
+    /** 页面 ID */
+    pageId: UniqueId;
+    /** 预览类型 */
+    type: 'draft' | 'version';
+    /** 页面版本 ID（type 为 version 时必填） */
+    pageVersionId?: UniqueId;
+    /** 过期时间（秒），默认 3600 */
+    ttlSeconds?: number;
+    /** 允许的访问者 */
+    allowedViewers?: string[];
+}
+/**
+ * 预览 Token 验证响应
+ */
+interface PreviewTokenValidationResult {
+    /** 是否有效 */
+    valid: boolean;
+    /** Token 信息（有效时返回） */
+    token?: PreviewToken;
+    /** 错误原因（无效时返回） */
+    error?: 'expired' | 'not_found' | 'invalid_viewer' | 'revoked';
+}
+/**
+ * 页面完整性校验 JSON
+ *
+ * @description
+ * 对应 CDN 产物：`/pages/{pageId}/{pageVersionId}/integrity.json`
+ * 用于防篡改校验。
+ */
+interface PageIntegrityJson {
+    /** 文件完整性哈希 */
+    files: {
+        /** snapshot.json 的哈希 */
+        'snapshot.json': SHAIntegrity;
+        /** manifest.json 的哈希 */
+        'manifest.json': SHAIntegrity;
+        /** meta.json 的哈希（可选） */
+        'meta.json'?: SHAIntegrity;
+    };
+    /** 聚合哈希（所有文件的综合哈希） */
+    aggregateHash: SHAIntegrity;
+    /** 签名（可选，用于更高安全级别） */
+    signature?: {
+        /** 签名算法 */
+        algorithm: 'ed25519' | 'rsa-sha256';
+        /** 签名值（Base64） */
+        value: string;
+        /** 公钥 ID（用于查找对应的公钥） */
+        keyId: string;
+    };
+    /** 生成时间 */
+    generatedAt: ISODateTime;
+    /** 生成者 */
+    generatedBy: string;
+}
+/**
+ * 页面资源列表 JSON
+ *
+ * @description
+ * 对应 CDN 产物：`/pages/{pageId}/{pageVersionId}/assets.json`
+ * 用于预热、排障。
+ */
+interface PageAssetsJson {
+    /** 页面 ID */
+    pageId: UniqueId;
+    /** 页面版本 ID */
+    pageVersionId: UniqueId;
+    /** Runtime 资源 */
+    runtime: {
+        /** Runtime 版本 */
+        version: SemVer;
+        /** JS 入口 */
+        js: string;
+        /** CSS 入口 */
+        css?: string;
+    };
+    /** 组件资源 */
+    components: {
+        /** 组件名称 */
+        name: string;
+        /** 组件版本 */
+        version: SemVer;
+        /** JS 入口 */
+        js: string;
+        /** CSS 入口 */
+        css?: string;
+        /** 分包列表 */
+        chunks?: string[];
+    }[];
+    /** 所有资源 URL 列表（用于预热） */
+    allUrls: string[];
+    /** 生成时间 */
+    generatedAt: ISODateTime;
+}
+
 /**
  * 页面解析响应类型
  */
 
 /**
- * 页面解析响应（Runtime 使用）
+ * 页面解析响应（User API → Runtime）
+ *
+ * @description
+ * 对应 User API：`GET /page/resolve`
+ * Runtime 首先调用此接口获取要加载的版本信息。
  */
 interface PageResolveResponse {
+    /** 页面 ID */
+    pageId: UniqueId;
+    /** 解析后的页面版本 ID */
+    resolvedVersionId: UniqueId;
+    /** CDN 基础 URL */
+    cdnBase: string;
+    /** Snapshot URL */
+    snapshotUrl: string;
+    /** Manifest URL */
+    manifestUrl: string;
+    /** 运维配置 */
+    ops: OpsConfig;
+    /** ETag（用于缓存） */
+    etag: string;
+    /** 缓存 TTL（秒） */
+    cacheTtlSeconds: number;
+    /** 灰度匹配信息（可选，用于调试） */
+    rolloutMatch?: {
+        /** 匹配的策略 ID */
+        strategyId?: string;
+        /** 匹配的策略名称 */
+        strategyName?: string;
+        /** 是否使用默认版本 */
+        isDefault: boolean;
+    };
+}
+/**
+ * 页面解析请求参数
+ */
+interface PageResolveRequest {
+    /** 页面 ID */
+    pageId: UniqueId;
+    /** 环境 */
+    env?: 'preview' | 'staging' | 'prod';
+    /** 用户 ID（用于灰度） */
+    uid?: string;
+    /** 设备 ID（用于灰度） */
+    deviceId?: string;
+    /** 渠道（用于灰度） */
+    channel?: string;
+    /** 是否包含完整 Snapshot（CDN 失败保底） */
+    includeSnapshot?: boolean;
+}
+/**
+ * 页面解析响应（包含 Snapshot 的保底版本）
+ */
+interface PageResolveWithSnapshotResponse extends PageResolveResponse {
+    /** 完整的页面快照（CDN 失败时使用） */
+    snapshot: PageSnapshotJson;
+}
+/**
+ * 页面解析响应（旧版本）
+ * @deprecated 使用 PageResolveResponse 代替
+ */
+interface LegacyPageResolveResponse {
     /** 页面版本 ID */
     pageVersionId: UniqueId;
     /** 页面 Schema */
@@ -1724,7 +2322,8 @@ interface PageResolveResponse {
     preloadedData?: Record<string, JsonValue>;
 }
 /**
- * 运行时配置
+ * 运行时配置（旧版本）
+ * @deprecated 使用 OpsConfig 代替
  */
 interface RuntimeConfig {
     /** 推荐的运行时版本 */
@@ -4252,4 +4851,4 @@ declare const ACTION_SPEC_VERSION = "2.0.0";
  */
 declare const DATA_QUERY_SPEC_VERSION = "2.0.0";
 
-export { type ABTestRolloutConfig, ACTION_SPEC_VERSION, ALLOWED_FUNCTION_NAMES, ALL_BUILTIN_FUNCTIONS, ARRAY_FUNCTIONS, type ActionClientContext, type ActionDefinition, type ActionDefinitionVersion, type ActionExecuteRequest, type ActionExecuteResponse, type ActionExecutor, type ActionPolicy, type ActionRef, type ActionResult, type ActionSheetItem, type ActionSheetOptions, type ActionSheetResult, type ActionSpec, ActionType, type Activity, type ActivityPrecondition, type ActivityRule, type ActivityStatus, type ActivityType, type AggregationDataSourceConfig, type AggregationQueryItem, type AnyValueOrExpression, type ApiErrorDetail, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type AppContext, AuditAction, type AuditConfig, type AuditLogEntry, type BackgroundConfig, type BaseActivityRule, type BlacklistRolloutConfig, type BlockedComponentInfo, type BrowserCompat, type BuiltinActionType, COMPONENT_META_SCHEMA_VERSION, CURRENT_ACTION_SPEC_VERSION, CURRENT_COMPONENT_META_VERSION, CURRENT_DATA_QUERY_SPEC_VERSION, CURRENT_SCHEMA_VERSION, type CacheConfig, type CacheLevel, type CanaryHealthCheck, type CanaryRolloutConfig, type CanaryStage, type CanvasType, type CapabilityDeclaration, type CapabilityName, type ChangeLog, type ChangeLogItem, type ClaimActivityRule, type ClaimPrize, type ClaimRecord, type ClaimState, type ClipboardApi, type CompatInfo, type Component, type ComponentCategory, type ComponentContext, type ComponentDependency, type ComponentIntegrity, type ComponentMeta, type ComponentNode, type ComponentQueryParams, type ComponentRegisterRequest, type ComponentStatus, type ComponentStatusChangeRequest, type ComponentVersion, type ConfirmOptions, type ConsecutiveReward, type CreateManifestRequest, type CumulativeReward, DATA_QUERY_SPEC_VERSION, DATE_FUNCTIONS, DEFAULT_EXPRESSION_VALIDATION_CONFIG, type DataBinding, type DataBindingErrorConfig, type DataLoadStrategy, type DataQueryDefinition, type DataQueryDefinitionVersion, type DataQueryRequest, type DataQueryResponse, type DataQuerySpec, type DataSourceConfig, type DataSourceType, type DatabaseDataSourceConfig, type DialogOptions, type DialogResult, type DjvlcError, type EditorComponent, type Environment, ErrorCategory, ErrorCode, ErrorCodeToHttpStatus, type ErrorMapping, ErrorMessages, type EventDeclaration, type EventHandler, type ExecutorContext, type ExecutorResult, type Expression, type ExpressionFunctionCategory, type ExpressionFunctionDefinition, type ExpressionType, type ExpressionValidationConfig, type ExpressionValidationError, type ExpressionValidationResult, type ExpressionValidationWarning, FORMAT_FUNCTIONS, type FallbackCondition, type FallbackConfig, type FeatureCondition, type FeatureRolloutConfig, type FieldPermission, type FieldPolicy, type FieldTransform, type FileIntegrity, type FunctionParamDefinition, type GraphQLDataSourceConfig, type HostApi, type HttpDataSourceConfig, type HttpRetryConfig, type I18nDetectionStrategy, type ISODateTime, type IdempotencyKeyStrategy, type IdempotencyRule, type IntegrityHash, type InternalDataSourceConfig, type InventoryConfig, type JsonObject, type JsonValue, LOGIC_FUNCTIONS, type LayoutConfig, type LayoutValues, type LoopConfig, type LotteryActivityRule, type LotteryCost, type LotteryPrize, type LotteryState, type Manifest, type ManifestEntry, type ManifestItem, type ManifestValidationError, type ManifestValidationResult, type ManifestValidationWarning, type MaskingConfig, type MaskingRule, type MaskingType, type MethodCategory, type MethodDeclaration, type MethodParam, NUMBER_FUNCTIONS, type NavigateOptions, type NodeStyleConfig, type OperatorInfo, type OrderByItem, PAGE_SCHEMA_VERSION, PROTOCOL_VERSION, type PageConfig, type PageDraft, type PageI18nConfig, type PageLifecycle, type PageManifest, type PageMeta, type PageResolveResponse, type PageSEO, type PageSchema, type PageState, PageStatus, type PageStatusType, type PageVersion, type PaginatedResponse, type PaginationMeta, type PaginationParams, type ParamPermission, type ParticipationLimit, type PercentageRolloutConfig, type PityConfig, type Precondition, type PreconditionType, type PreviewImageOptions, type ProbabilityConfig, type PropDefinition, type PropFormat, type PropGroup, type PropType, type PropValue, type PropsSchema, type PublishCdnConfig, PublishChannel, type PublishConfig, type PublishEnvironment, type PublishNotificationConfig, type PublishRecord, type PublishRolloutConfig, PublishStatus, type QueryPermissions, type RateLimitDimension, type RateLimitItem, type RateLimitRule, type RequestContext, type ResolvedManifest, type ResponsiveBreakpoints, type RetryPolicy, type RiskControlConfig, type RolloutConfig, type RolloutMatchRequest, type RolloutMatchResult, type RolloutStrategy, type RolloutStrategyConfig, type RolloutStrategyType, type RuntimeConfig, type RuntimeContext, type RuntimeSpec, type SHAIntegrity, STRING_FUNCTIONS, type ScanCodeResult, type SchemaVersion, type SemVer, type ShareOptions, type ShareResult, type SigninActivityRule, type SigninRecord, type SigninRewardRecord, type SigninState, type SlotCategory, type SlotDeclaration, type StateFieldDefinition, type StorageApi, type StorageOptions, type StyleConfig, type StyleIsolation, type TimeWindowRolloutConfig, type ToastOptions, type TrackEvent, type URLString, UTILITY_FUNCTIONS, type UniqueId, type UpsertRolloutRequest, type UserActivityState, type UserContext, VERSION, type ValidationRule, type VersionDiff, type VersionInfo, VersionStatus, type VersionStatusType, type WhitelistRolloutConfig, bindingRef, createDjvlcError, isDjvlcError, literal, queryRef, stateRef, template };
+export { type ABTestRolloutConfig, ACTION_SPEC_VERSION, ALLOWED_FUNCTION_NAMES, ALL_BUILTIN_FUNCTIONS, ARRAY_FUNCTIONS, type ActionClientContext, type ActionDefinition, type ActionDefinitionVersion, type ActionExecuteRequest, type ActionExecuteResponse, type ActionExecutor, type ActionPolicy, type ActionRef, type ActionResult, type ActionSheetItem, type ActionSheetOptions, type ActionSheetResult, type ActionSpec, ActionType, type Activity, type ActivityPrecondition, type ActivityRule, type ActivityStatus, type ActivityType, type AggregationDataSourceConfig, type AggregationQueryItem, type AnyValueOrExpression, type ApiErrorDetail, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type AppContext, AuditAction, type AuditConfig, type AuditLogEntry, type BackgroundConfig, type BaseActivityRule, type BlacklistRolloutConfig, type BlockedComponentInfo, type BlockedComponentItem, type BootstrapConfig, type BrowserCompat, type BuiltinActionType, COMPONENT_META_SCHEMA_VERSION, CURRENT_ACTION_SPEC_VERSION, CURRENT_COMPONENT_META_VERSION, CURRENT_DATA_QUERY_SPEC_VERSION, CURRENT_SCHEMA_VERSION, type CacheConfig, type CacheLevel, type CanaryHealthCheck, type CanaryRolloutConfig, type CanaryStage, type CanvasType, type CapabilityDeclaration, type CapabilityName, type ChangeLog, type ChangeLogItem, type ClaimActivityRule, type ClaimPrize, type ClaimRecord, type ClaimState, type ClipboardApi, type CompatInfo, type Component, type ComponentCategory, type ComponentContext, type ComponentDependency, type ComponentIntegrity, type ComponentMeta, type ComponentNode, type ComponentQueryParams, type ComponentRegisterRequest, type ComponentStatus, type ComponentStatusChangeRequest, type ComponentVersion, type ConfirmOptions, type ConsecutiveReward, type CreateManifestRequest, type CreatePreviewTokenRequest, type CumulativeReward, DATA_QUERY_SPEC_VERSION, DATE_FUNCTIONS, DEFAULT_EXPRESSION_VALIDATION_CONFIG, type DataBinding, type DataBindingErrorConfig, type DataLoadStrategy, type DataQueryDefinition, type DataQueryDefinitionVersion, type DataQueryRequest, type DataQueryResponse, type DataQuerySpec, type DataSourceConfig, type DataSourceType, type DatabaseDataSourceConfig, type DefinitionVersionDigest, type DefinitionsDigest, type DialogOptions, type DialogResult, type DjvlcError, type EditorComponent, type Environment, ErrorCategory, ErrorCode, ErrorCodeToHttpStatus, type ErrorMapping, ErrorMessages, type EventDeclaration, type EventHandler, type ExecutorContext, type ExecutorResult, type Expression, type ExpressionContext, type ExpressionEventContext, type ExpressionFunctionCategory, type ExpressionFunctionDefinition, type ExpressionLocalContext, type ExpressionType, type ExpressionValidationConfig, type ExpressionValidationError, type ExpressionValidationResult, type ExpressionValidationWarning, FORMAT_FUNCTIONS, type FallbackCondition, type FallbackConfig, type FeatureCondition, type FeatureRolloutConfig, type FieldPermission, type FieldPolicy, type FieldTransform, type FileIntegrity, type FunctionParamDefinition, type GraphQLDataSourceConfig, type HostApi, type HttpDataSourceConfig, type HttpRetryConfig, type I18nDetectionStrategy, type ISODateTime, type IdempotencyKeyStrategy, type IdempotencyRule, type IntegrityHash, type InternalDataSourceConfig, type InventoryConfig, type JsonObject, type JsonValue, type KillSwitchItem, LOGIC_FUNCTIONS, type LayoutConfig, type LayoutValues, type LegacyPageResolveResponse, type LoopConfig, type LotteryActivityRule, type LotteryCost, type LotteryPrize, type LotteryState, type Manifest, type ManifestEntry, type ManifestItem, type ManifestValidationError, type ManifestValidationResult, type ManifestValidationWarning, type MaskingConfig, type MaskingRule, type MaskingType, type MethodCategory, type MethodDeclaration, type MethodParam, NUMBER_FUNCTIONS, type NavigateOptions, type NodeStyleConfig, type OperatorInfo, type OpsConfig, type OrderByItem, PAGE_SCHEMA_VERSION, PROTOCOL_VERSION, type PageAssetsJson, type PageConfig, type PageDraft, type PageI18nConfig, type PageIntegrityJson, type PageLifecycle, type PageManifest, type PageMeta, type PageResolveRequest, type PageResolveResponse, type PageResolveWithSnapshotResponse, type PageSEO, type PageSchema, type PageSnapshotJson, type PageSnapshotManifest, type PageSnapshotMeta, type PageSnapshotPage, type PageState, PageStatus, type PageStatusType, type PageVersion, type PaginatedResponse, type PaginationMeta, type PaginationParams, type ParamPermission, type ParticipationLimit, type PercentageRolloutConfig, type PityConfig, type Precondition, type PreconditionType, type PreviewImageOptions, type PreviewToken, type PreviewTokenValidationResult, type ProbabilityConfig, type PropDefinition, type PropFormat, type PropGroup, type PropType, type PropValue, type PropsSchema, type PublishCdnConfig, PublishChannel, type PublishConfig, type PublishEnvironment, type PublishNotificationConfig, type PublishRecord, type PublishRolloutConfig, PublishStatus, type QueryPermissions, type RateLimitDimension, type RateLimitItem, type RateLimitRule, type RequestContext, type ResolvedManifest, type ResponsiveBreakpoints, type RetryPolicy, type RiskControlConfig, type RolloutConfig, type RolloutMatchRequest, type RolloutMatchResult, type RolloutStrategy, type RolloutStrategyConfig, type RolloutStrategyType, type RuntimeConfig, type RuntimeContext, type RuntimeSpec, type SHAIntegrity, STRING_FUNCTIONS, type ScanCodeResult, type SchemaVersion, type SemVer, type ShareOptions, type ShareResult, type SigninActivityRule, type SigninRecord, type SigninRewardRecord, type SigninState, type SlotCategory, type SlotDeclaration, type SnapshotComponentEntry, type StateFieldDefinition, type StorageApi, type StorageOptions, type StyleConfig, type StyleIsolation, type TimeWindowRolloutConfig, type ToastOptions, type TrackEvent, type URLString, UTILITY_FUNCTIONS, type UniqueId, type UpsertRolloutRequest, type UserActivityState, type UserContext, VERSION, type ValidationRule, type VersionDiff, type VersionInfo, VersionStatus, type VersionStatusType, type WhitelistRolloutConfig, bindingRef, createDjvlcError, createExpressionContext, createLoopContext, isDjvlcError, literal, queryRef, stateRef, template };

package/dist/index.d.ts

@@ -790,6 +790,116 @@ interface Expression {
         returnType?: string;
     };
 }
+/**
+ * 表达式求值上下文
+ *
+ * @description
+ * 表达式引擎在求值时可访问的上下文对象。
+ * 所有动态表达式（state/binding/context/template/computed）都从此上下文获取数据。
+ *
+ * 使用场景：
+ * - Runtime 表达式求值
+ * - 编辑器表达式预览
+ * - 表达式校验与调试
+ *
+ * @example
+ * ```typescript
+ * const ctx: ExpressionContext = {
+ *   state: { count: 0, userInfo: { name: 'Alice' } },
+ *   binding: { userList: [{ id: 1, name: 'Bob' }] },
+ *   context: { item: { id: 1, name: 'Bob' }, index: 0 },
+ * };
+ *
+ * // 求值 { type: 'state', value: 'userInfo.name' } => 'Alice'
+ * // 求值 { type: 'context', value: 'item.name' } => 'Bob'
+ * ```
+ */
+interface ExpressionContext {
+    /**
+     * 页面状态
+     *
+     * @description
+     * 对应 PageState.fields 的运行时值。
+     * 表达式通过 { type: 'state', value: 'fieldName.path' } 访问。
+     */
+    state: Record<string, unknown>;
+    /**
+     * 数据绑定结果
+     *
+     * @description
+     * 对应 DataBinding 查询的返回数据，按 bindingId 组织。
+     * 表达式通过 { type: 'binding', value: 'bindingId.path' } 访问。
+     */
+    binding: Record<string, unknown>;
+    /**
+     * 局部上下文
+     *
+     * @description
+     * 包含循环变量、事件参数等临时作用域数据。
+     * 表达式通过 { type: 'context', value: 'item.path' } 访问。
+     */
+    context: ExpressionLocalContext;
+    /**
+     * 组件属性（可选）
+     *
+     * @description
+     * 当前组件的 props 值，供组件内部表达式访问。
+     * 通常在组件内部求值时提供。
+     */
+    props?: Record<string, unknown>;
+    /**
+     * 当前事件（可选）
+     *
+     * @description
+     * 事件处理器执行时的事件对象。
+     * 仅在事件处理链中可用。
+     */
+    event?: ExpressionEventContext;
+}
+/**
+ * 局部上下文（循环变量、事件参数等）
+ */
+interface ExpressionLocalContext {
+    /**
+     * 循环项（loop.itemName 指定的变量名）
+     *
+     * @description
+     * 在 loop 渲染中，当前迭代的数据项。
+     */
+    item?: unknown;
+    /**
+     * 循环索引（loop.indexName 指定的变量名）
+     *
+     * @description
+     * 在 loop 渲染中，当前迭代的索引。
+     */
+    index?: number;
+    /**
+     * 动态扩展字段
+     *
+     * @description
+     * 支持自定义局部变量，如嵌套循环的多个 item/index。
+     */
+    [key: string]: unknown;
+}
+/**
+ * 事件上下文
+ */
+interface ExpressionEventContext {
+    /** 事件类型 */
+    type: string;
+    /** 事件目标（组件实例 ID） */
+    target?: string;
+    /** 事件载荷（组件抛出的数据） */
+    payload?: unknown;
+    /** 原生事件（如 MouseEvent 的部分安全属性） */
+    nativeEvent?: {
+        clientX?: number;
+        clientY?: number;
+        key?: string;
+        keyCode?: number;
+    };
+}
 /**
  * 任意值或表达式
  *
@@ -805,6 +915,21 @@ type AnyValueOrExpression = Expression | string | number | boolean | null | AnyV
  * @deprecated 使用 AnyValueOrExpression 代替
  */
 type PropValue = AnyValueOrExpression;
+/**
+ * 创建空的表达式上下文
+ *
+ * @description
+ * 用于初始化表达式求值环境，所有字段都有合理的默认值。
+ */
+declare function createExpressionContext(partial?: Partial<ExpressionContext>): ExpressionContext;
+/**
+ * 创建带循环变量的局部上下文
+ *
+ * @param item - 当前循环项
+ * @param index - 当前循环索引
+ * @param extras - 额外的局部变量（如嵌套循环）
+ */
+declare function createLoopContext(item: unknown, index: number, extras?: Record<string, unknown>): ExpressionLocalContext;
 /**
  * 创建字面量表达式
  * @deprecated V2 版本移除 literal 表达式类型，静态值请直接使用原始类型
@@ -1704,14 +1829,487 @@ interface PageDraft {
     updatedAt: ISODateTime;
 }
 
+/**
+ * 页面快照类型（CDN 产物核心结构）
+ *
+ * @description
+ * PageSnapshotJson 是发布后生成的运行时渲染闭包，包含：
+ * - 页面渲染数据
+ * - 组件锁定清单
+ * - Definition 版本摘要
+ * - 运维配置引用
+ * - 元数据
+ *
+ * 设计原则：一次 resolve 返回渲染所需的一切闭包，减少运行时请求次数。
+ */
+
+/**
+ * 页面快照 JSON 结构
+ *
+ * @description
+ * 对应 CDN 产物：`/pages/{pageId}/{pageVersionId}/snapshot.json`
+ * Runtime 加载此文件即可完成页面渲染。
+ */
+interface PageSnapshotJson {
+    /**
+     * 页面渲染数据
+     */
+    page: PageSnapshotPage;
+    /**
+     * 组件锁定清单
+     */
+    manifest: PageSnapshotManifest;
+    /**
+     * 绑定的 Definition 版本摘要（审计/回放用）
+     */
+    definitionsDigest: DefinitionsDigest;
+    /**
+     * 运维配置（内联或引用）
+     */
+    ops: OpsConfig;
+    /**
+     * 元数据
+     */
+    meta: PageSnapshotMeta;
+}
+/**
+ * 页面渲染数据
+ */
+interface PageSnapshotPage {
+    /** Schema 版本 */
+    schemaVersion: string;
+    /** 页面 ID */
+    pageId: string;
+    /** 页面版本 */
+    pageVersion: SemVer;
+    /** 页面标题 */
+    title: string;
+    /** 初始状态 */
+    initialState: Record<string, JsonValue>;
+    /** 数据绑定配置 */
+    bindings: DataBinding[];
+    /** 组件树根节点 */
+    root: ComponentNode;
+    /** 页面配置（画布类型、背景等） */
+    config: {
+        canvasType: 'h5' | 'tablet' | 'pc' | 'responsive';
+        canvasSize?: {
+            width: number;
+            height: number;
+        };
+        background?: {
+            type: 'color' | 'image' | 'gradient';
+            value: string;
+        };
+        cssVariables?: Record<string, string>;
+    };
+    /** SEO 配置 */
+    seo?: {
+        title?: string;
+        description?: string;
+        keywords?: string[];
+    };
+}
+/**
+ * 组件锁定清单（Snapshot 内嵌版本）
+ */
+interface PageSnapshotManifest {
+    /** 组件列表 */
+    components: SnapshotComponentEntry[];
+    /** Runtime 版本要求 */
+    runtime: {
+        /** 推荐版本 */
+        version: SemVer;
+        /** 最低版本 */
+        minVersion: SemVer;
+    };
+}
+/**
+ * Snapshot 中的组件条目
+ */
+interface SnapshotComponentEntry {
+    /** 组件名称 */
+    name: string;
+    /** 组件版本 */
+    version: SemVer;
+    /** SRI 完整性哈希 */
+    integrity: SHAIntegrity;
+    /** CDN 资源基础 URL */
+    assetsUrl: string;
+    /** 入口点 */
+    entrypoints: {
+        /** JS 入口（相对于 assetsUrl） */
+        js: string;
+        /** CSS 入口（可选） */
+        css?: string;
+        /** 分包列表（可选） */
+        chunks?: string[];
+    };
+    /** 是否预加载 */
+    preload?: boolean;
+    /** 加载优先级 */
+    priority?: 'critical' | 'high' | 'normal' | 'low';
+}
+/**
+ * Definition 版本摘要
+ *
+ * @description
+ * 记录页面绑定的 ActionDefinition 和 DataQueryDefinition 版本。
+ * 用于审计、回放、版本追溯。
+ */
+interface DefinitionsDigest {
+    /** 绑定的 Action Definition 版本 */
+    actions: DefinitionVersionDigest[];
+    /** 绑定的 Data Query Definition 版本 */
+    queries: DefinitionVersionDigest[];
+}
+/**
+ * 单个 Definition 版本摘要
+ */
+interface DefinitionVersionDigest {
+    /** Definition ID */
+    id: UniqueId;
+    /** Definition 名称 */
+    name: string;
+    /** 版本 ID */
+    versionId: UniqueId;
+    /** 内容哈希（用于完整性校验） */
+    hash: string;
+}
+/**
+ * 运维配置
+ *
+ * @description
+ * 包含 kill-switch、blocked 组件列表、功能开关等运维控制配置。
+ * 由 User API resolve 时下发，Runtime 据此做运行时控制。
+ */
+interface OpsConfig {
+    /** 配置版本 ID（用于缓存失效） */
+    configVersionId?: string;
+    /** Kill-Switch 列表（被紧急关闭的功能/动作） */
+    killSwitch: KillSwitchItem[];
+    /** 被阻断的组件列表 */
+    blockedComponents: BlockedComponentItem[];
+    /** 功能开关 */
+    flags: Record<string, boolean>;
+    /** 限流配置（可选） */
+    rateLimit?: {
+        /** 全局 QPS 限制 */
+        globalQps?: number;
+        /** 按动作类型的 QPS 限制 */
+        actionQps?: Record<string, number>;
+    };
+    /** 配置过期时间（用于缓存） */
+    expiresAt?: ISODateTime;
+}
+/**
+ * Kill-Switch 条目
+ */
+interface KillSwitchItem {
+    /** 目标类型 */
+    targetType: 'action' | 'component' | 'feature' | 'page' | 'query';
+    /** 目标 ID（actionType / componentName / featureKey / pageId / queryId） */
+    targetId: string;
+    /** 是否启用（true = 被关闭） */
+    enabled: boolean;
+    /** 关闭原因 */
+    reason?: string;
+    /** 关闭时间 */
+    enabledAt?: ISODateTime;
+    /** 关闭操作者 */
+    enabledBy?: string;
+    /** 用户提示消息 */
+    userMessage?: string;
+}
+/**
+ * 被阻断的组件条目
+ */
+interface BlockedComponentItem {
+    /** 组件名称 */
+    name: string;
+    /** 组件版本（可选，不指定则阻断所有版本） */
+    version?: SemVer;
+    /** 阻断原因 */
+    reason: string;
+    /** 阻断时间 */
+    blockedAt: ISODateTime;
+    /** 阻断操作者 */
+    blockedBy: string;
+    /** 降级版本（可选） */
+    fallbackVersion?: SemVer;
+    /** 是否紧急阻断 */
+    urgent: boolean;
+}
+/**
+ * 页面快照元数据
+ *
+ * @description
+ * 对应 CDN 产物：`/pages/{pageId}/{pageVersionId}/meta.json`
+ * 用于审计、回放、排查。
+ */
+interface PageSnapshotMeta {
+    /** 页面 ID */
+    pageId: UniqueId;
+    /** 页面版本 ID */
+    pageVersionId: UniqueId;
+    /** 发布 ID（用于追踪发布操作） */
+    publishId: UniqueId;
+    /** Schema 版本 */
+    schemaVersion: string;
+    /** 创建时间 */
+    createdAt: ISODateTime;
+    /** 创建者 */
+    createdBy: string;
+    /** 内容哈希 */
+    contentHash: string;
+    /** 绑定摘要 */
+    bindings: {
+        /** 组件版本列表（格式：name@version） */
+        componentVersions: string[];
+        /** Definition 版本列表 */
+        definitionVersions: string[];
+    };
+    /** Runtime 版本 */
+    runtimeVersion: SemVer;
+    /** 环境 */
+    env?: 'preview' | 'staging' | 'prod';
+}
+/**
+ * Bootstrap 配置
+ *
+ * @description
+ * 极小的启动参数，用于静态 HTML 场景。
+ * 对应 CDN 产物：`/pages/{pageId}/{pageVersionId}/bootstrap.json`
+ *
+ * 使用场景：
+ * - 静态 HTML 页面（不经过服务端渲染）
+ * - 嵌入式页面（iframe）
+ * - 离线缓存场景
+ */
+interface BootstrapConfig {
+    /** 页面 ID */
+    pageId: UniqueId;
+    /** 页面版本 ID */
+    pageVersionId: UniqueId;
+    /** Runtime 版本 */
+    runtimeVersion: SemVer;
+    /** Runtime 入口 URL */
+    runtimeEntryUrl: string;
+    /** 页面 JSON URL（snapshot.json） */
+    snapshotUrl: string;
+    /** Manifest URL */
+    manifestUrl: string;
+    /** CDN 基础 URL */
+    cdnBaseUrl: string;
+    /** API 基础 URL */
+    apiBaseUrl: string;
+    /** 环境 */
+    env: 'preview' | 'staging' | 'prod';
+    /** 预连接 URL 列表（性能优化） */
+    preconnectUrls?: string[];
+    /** 预加载资源列表 */
+    preloadAssets?: string[];
+}
+/**
+ * 预览 Token
+ *
+ * @description
+ * Editor 生成预览链接时使用的令牌。
+ * 存储在 Redis，短 TTL（通常 1-4 小时）。
+ *
+ * 使用流程：
+ * 1. Editor 调用 Admin API 生成预览 Token
+ * 2. 预览链接：`https://{domain}/preview/{token}`
+ * 3. Runtime 调用 User API 验证 Token 并获取草稿内容
+ */
+interface PreviewToken {
+    /** Token 值 */
+    token: string;
+    /** 页面 ID */
+    pageId: UniqueId;
+    /** 页面版本 ID（如果预览已发布版本） */
+    pageVersionId?: UniqueId;
+    /** 草稿 ID（如果预览草稿） */
+    draftId?: UniqueId;
+    /** 预览类型 */
+    type: 'draft' | 'version';
+    /** 过期时间 */
+    expiresAt: ISODateTime;
+    /** 创建时间 */
+    createdAt: ISODateTime;
+    /** 创建者 */
+    createdBy: string;
+    /** 允许的访问者（可选，用于限制预览范围） */
+    allowedViewers?: string[];
+    /** 是否允许编辑（预览时是否可以修改草稿） */
+    allowEdit?: boolean;
+}
+/**
+ * 预览 Token 创建请求
+ */
+interface CreatePreviewTokenRequest {
+    /** 页面 ID */
+    pageId: UniqueId;
+    /** 预览类型 */
+    type: 'draft' | 'version';
+    /** 页面版本 ID（type 为 version 时必填） */
+    pageVersionId?: UniqueId;
+    /** 过期时间（秒），默认 3600 */
+    ttlSeconds?: number;
+    /** 允许的访问者 */
+    allowedViewers?: string[];
+}
+/**
+ * 预览 Token 验证响应
+ */
+interface PreviewTokenValidationResult {
+    /** 是否有效 */
+    valid: boolean;
+    /** Token 信息（有效时返回） */
+    token?: PreviewToken;
+    /** 错误原因（无效时返回） */
+    error?: 'expired' | 'not_found' | 'invalid_viewer' | 'revoked';
+}
+/**
+ * 页面完整性校验 JSON
+ *
+ * @description
+ * 对应 CDN 产物：`/pages/{pageId}/{pageVersionId}/integrity.json`
+ * 用于防篡改校验。
+ */
+interface PageIntegrityJson {
+    /** 文件完整性哈希 */
+    files: {
+        /** snapshot.json 的哈希 */
+        'snapshot.json': SHAIntegrity;
+        /** manifest.json 的哈希 */
+        'manifest.json': SHAIntegrity;
+        /** meta.json 的哈希（可选） */
+        'meta.json'?: SHAIntegrity;
+    };
+    /** 聚合哈希（所有文件的综合哈希） */
+    aggregateHash: SHAIntegrity;
+    /** 签名（可选，用于更高安全级别） */
+    signature?: {
+        /** 签名算法 */
+        algorithm: 'ed25519' | 'rsa-sha256';
+        /** 签名值（Base64） */
+        value: string;
+        /** 公钥 ID（用于查找对应的公钥） */
+        keyId: string;
+    };
+    /** 生成时间 */
+    generatedAt: ISODateTime;
+    /** 生成者 */
+    generatedBy: string;
+}
+/**
+ * 页面资源列表 JSON
+ *
+ * @description
+ * 对应 CDN 产物：`/pages/{pageId}/{pageVersionId}/assets.json`
+ * 用于预热、排障。
+ */
+interface PageAssetsJson {
+    /** 页面 ID */
+    pageId: UniqueId;
+    /** 页面版本 ID */
+    pageVersionId: UniqueId;
+    /** Runtime 资源 */
+    runtime: {
+        /** Runtime 版本 */
+        version: SemVer;
+        /** JS 入口 */
+        js: string;
+        /** CSS 入口 */
+        css?: string;
+    };
+    /** 组件资源 */
+    components: {
+        /** 组件名称 */
+        name: string;
+        /** 组件版本 */
+        version: SemVer;
+        /** JS 入口 */
+        js: string;
+        /** CSS 入口 */
+        css?: string;
+        /** 分包列表 */
+        chunks?: string[];
+    }[];
+    /** 所有资源 URL 列表（用于预热） */
+    allUrls: string[];
+    /** 生成时间 */
+    generatedAt: ISODateTime;
+}
+
 /**
  * 页面解析响应类型
  */
 
 /**
- * 页面解析响应（Runtime 使用）
+ * 页面解析响应（User API → Runtime）
+ *
+ * @description
+ * 对应 User API：`GET /page/resolve`
+ * Runtime 首先调用此接口获取要加载的版本信息。
  */
 interface PageResolveResponse {
+    /** 页面 ID */
+    pageId: UniqueId;
+    /** 解析后的页面版本 ID */
+    resolvedVersionId: UniqueId;
+    /** CDN 基础 URL */
+    cdnBase: string;
+    /** Snapshot URL */
+    snapshotUrl: string;
+    /** Manifest URL */
+    manifestUrl: string;
+    /** 运维配置 */
+    ops: OpsConfig;
+    /** ETag（用于缓存） */
+    etag: string;
+    /** 缓存 TTL（秒） */
+    cacheTtlSeconds: number;
+    /** 灰度匹配信息（可选，用于调试） */
+    rolloutMatch?: {
+        /** 匹配的策略 ID */
+        strategyId?: string;
+        /** 匹配的策略名称 */
+        strategyName?: string;
+        /** 是否使用默认版本 */
+        isDefault: boolean;
+    };
+}
+/**
+ * 页面解析请求参数
+ */
+interface PageResolveRequest {
+    /** 页面 ID */
+    pageId: UniqueId;
+    /** 环境 */
+    env?: 'preview' | 'staging' | 'prod';
+    /** 用户 ID（用于灰度） */
+    uid?: string;
+    /** 设备 ID（用于灰度） */
+    deviceId?: string;
+    /** 渠道（用于灰度） */
+    channel?: string;
+    /** 是否包含完整 Snapshot（CDN 失败保底） */
+    includeSnapshot?: boolean;
+}
+/**
+ * 页面解析响应（包含 Snapshot 的保底版本）
+ */
+interface PageResolveWithSnapshotResponse extends PageResolveResponse {
+    /** 完整的页面快照（CDN 失败时使用） */
+    snapshot: PageSnapshotJson;
+}
+/**
+ * 页面解析响应（旧版本）
+ * @deprecated 使用 PageResolveResponse 代替
+ */
+interface LegacyPageResolveResponse {
     /** 页面版本 ID */
     pageVersionId: UniqueId;
     /** 页面 Schema */
@@ -1724,7 +2322,8 @@ interface PageResolveResponse {
     preloadedData?: Record<string, JsonValue>;
 }
 /**
- * 运行时配置
+ * 运行时配置（旧版本）
+ * @deprecated 使用 OpsConfig 代替
  */
 interface RuntimeConfig {
     /** 推荐的运行时版本 */
@@ -4252,4 +4851,4 @@ declare const ACTION_SPEC_VERSION = "2.0.0";
  */
 declare const DATA_QUERY_SPEC_VERSION = "2.0.0";
 
-export { type ABTestRolloutConfig, ACTION_SPEC_VERSION, ALLOWED_FUNCTION_NAMES, ALL_BUILTIN_FUNCTIONS, ARRAY_FUNCTIONS, type ActionClientContext, type ActionDefinition, type ActionDefinitionVersion, type ActionExecuteRequest, type ActionExecuteResponse, type ActionExecutor, type ActionPolicy, type ActionRef, type ActionResult, type ActionSheetItem, type ActionSheetOptions, type ActionSheetResult, type ActionSpec, ActionType, type Activity, type ActivityPrecondition, type ActivityRule, type ActivityStatus, type ActivityType, type AggregationDataSourceConfig, type AggregationQueryItem, type AnyValueOrExpression, type ApiErrorDetail, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type AppContext, AuditAction, type AuditConfig, type AuditLogEntry, type BackgroundConfig, type BaseActivityRule, type BlacklistRolloutConfig, type BlockedComponentInfo, type BrowserCompat, type BuiltinActionType, COMPONENT_META_SCHEMA_VERSION, CURRENT_ACTION_SPEC_VERSION, CURRENT_COMPONENT_META_VERSION, CURRENT_DATA_QUERY_SPEC_VERSION, CURRENT_SCHEMA_VERSION, type CacheConfig, type CacheLevel, type CanaryHealthCheck, type CanaryRolloutConfig, type CanaryStage, type CanvasType, type CapabilityDeclaration, type CapabilityName, type ChangeLog, type ChangeLogItem, type ClaimActivityRule, type ClaimPrize, type ClaimRecord, type ClaimState, type ClipboardApi, type CompatInfo, type Component, type ComponentCategory, type ComponentContext, type ComponentDependency, type ComponentIntegrity, type ComponentMeta, type ComponentNode, type ComponentQueryParams, type ComponentRegisterRequest, type ComponentStatus, type ComponentStatusChangeRequest, type ComponentVersion, type ConfirmOptions, type ConsecutiveReward, type CreateManifestRequest, type CumulativeReward, DATA_QUERY_SPEC_VERSION, DATE_FUNCTIONS, DEFAULT_EXPRESSION_VALIDATION_CONFIG, type DataBinding, type DataBindingErrorConfig, type DataLoadStrategy, type DataQueryDefinition, type DataQueryDefinitionVersion, type DataQueryRequest, type DataQueryResponse, type DataQuerySpec, type DataSourceConfig, type DataSourceType, type DatabaseDataSourceConfig, type DialogOptions, type DialogResult, type DjvlcError, type EditorComponent, type Environment, ErrorCategory, ErrorCode, ErrorCodeToHttpStatus, type ErrorMapping, ErrorMessages, type EventDeclaration, type EventHandler, type ExecutorContext, type ExecutorResult, type Expression, type ExpressionFunctionCategory, type ExpressionFunctionDefinition, type ExpressionType, type ExpressionValidationConfig, type ExpressionValidationError, type ExpressionValidationResult, type ExpressionValidationWarning, FORMAT_FUNCTIONS, type FallbackCondition, type FallbackConfig, type FeatureCondition, type FeatureRolloutConfig, type FieldPermission, type FieldPolicy, type FieldTransform, type FileIntegrity, type FunctionParamDefinition, type GraphQLDataSourceConfig, type HostApi, type HttpDataSourceConfig, type HttpRetryConfig, type I18nDetectionStrategy, type ISODateTime, type IdempotencyKeyStrategy, type IdempotencyRule, type IntegrityHash, type InternalDataSourceConfig, type InventoryConfig, type JsonObject, type JsonValue, LOGIC_FUNCTIONS, type LayoutConfig, type LayoutValues, type LoopConfig, type LotteryActivityRule, type LotteryCost, type LotteryPrize, type LotteryState, type Manifest, type ManifestEntry, type ManifestItem, type ManifestValidationError, type ManifestValidationResult, type ManifestValidationWarning, type MaskingConfig, type MaskingRule, type MaskingType, type MethodCategory, type MethodDeclaration, type MethodParam, NUMBER_FUNCTIONS, type NavigateOptions, type NodeStyleConfig, type OperatorInfo, type OrderByItem, PAGE_SCHEMA_VERSION, PROTOCOL_VERSION, type PageConfig, type PageDraft, type PageI18nConfig, type PageLifecycle, type PageManifest, type PageMeta, type PageResolveResponse, type PageSEO, type PageSchema, type PageState, PageStatus, type PageStatusType, type PageVersion, type PaginatedResponse, type PaginationMeta, type PaginationParams, type ParamPermission, type ParticipationLimit, type PercentageRolloutConfig, type PityConfig, type Precondition, type PreconditionType, type PreviewImageOptions, type ProbabilityConfig, type PropDefinition, type PropFormat, type PropGroup, type PropType, type PropValue, type PropsSchema, type PublishCdnConfig, PublishChannel, type PublishConfig, type PublishEnvironment, type PublishNotificationConfig, type PublishRecord, type PublishRolloutConfig, PublishStatus, type QueryPermissions, type RateLimitDimension, type RateLimitItem, type RateLimitRule, type RequestContext, type ResolvedManifest, type ResponsiveBreakpoints, type RetryPolicy, type RiskControlConfig, type RolloutConfig, type RolloutMatchRequest, type RolloutMatchResult, type RolloutStrategy, type RolloutStrategyConfig, type RolloutStrategyType, type RuntimeConfig, type RuntimeContext, type RuntimeSpec, type SHAIntegrity, STRING_FUNCTIONS, type ScanCodeResult, type SchemaVersion, type SemVer, type ShareOptions, type ShareResult, type SigninActivityRule, type SigninRecord, type SigninRewardRecord, type SigninState, type SlotCategory, type SlotDeclaration, type StateFieldDefinition, type StorageApi, type StorageOptions, type StyleConfig, type StyleIsolation, type TimeWindowRolloutConfig, type ToastOptions, type TrackEvent, type URLString, UTILITY_FUNCTIONS, type UniqueId, type UpsertRolloutRequest, type UserActivityState, type UserContext, VERSION, type ValidationRule, type VersionDiff, type VersionInfo, VersionStatus, type VersionStatusType, type WhitelistRolloutConfig, bindingRef, createDjvlcError, isDjvlcError, literal, queryRef, stateRef, template };
+export { type ABTestRolloutConfig, ACTION_SPEC_VERSION, ALLOWED_FUNCTION_NAMES, ALL_BUILTIN_FUNCTIONS, ARRAY_FUNCTIONS, type ActionClientContext, type ActionDefinition, type ActionDefinitionVersion, type ActionExecuteRequest, type ActionExecuteResponse, type ActionExecutor, type ActionPolicy, type ActionRef, type ActionResult, type ActionSheetItem, type ActionSheetOptions, type ActionSheetResult, type ActionSpec, ActionType, type Activity, type ActivityPrecondition, type ActivityRule, type ActivityStatus, type ActivityType, type AggregationDataSourceConfig, type AggregationQueryItem, type AnyValueOrExpression, type ApiErrorDetail, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type AppContext, AuditAction, type AuditConfig, type AuditLogEntry, type BackgroundConfig, type BaseActivityRule, type BlacklistRolloutConfig, type BlockedComponentInfo, type BlockedComponentItem, type BootstrapConfig, type BrowserCompat, type BuiltinActionType, COMPONENT_META_SCHEMA_VERSION, CURRENT_ACTION_SPEC_VERSION, CURRENT_COMPONENT_META_VERSION, CURRENT_DATA_QUERY_SPEC_VERSION, CURRENT_SCHEMA_VERSION, type CacheConfig, type CacheLevel, type CanaryHealthCheck, type CanaryRolloutConfig, type CanaryStage, type CanvasType, type CapabilityDeclaration, type CapabilityName, type ChangeLog, type ChangeLogItem, type ClaimActivityRule, type ClaimPrize, type ClaimRecord, type ClaimState, type ClipboardApi, type CompatInfo, type Component, type ComponentCategory, type ComponentContext, type ComponentDependency, type ComponentIntegrity, type ComponentMeta, type ComponentNode, type ComponentQueryParams, type ComponentRegisterRequest, type ComponentStatus, type ComponentStatusChangeRequest, type ComponentVersion, type ConfirmOptions, type ConsecutiveReward, type CreateManifestRequest, type CreatePreviewTokenRequest, type CumulativeReward, DATA_QUERY_SPEC_VERSION, DATE_FUNCTIONS, DEFAULT_EXPRESSION_VALIDATION_CONFIG, type DataBinding, type DataBindingErrorConfig, type DataLoadStrategy, type DataQueryDefinition, type DataQueryDefinitionVersion, type DataQueryRequest, type DataQueryResponse, type DataQuerySpec, type DataSourceConfig, type DataSourceType, type DatabaseDataSourceConfig, type DefinitionVersionDigest, type DefinitionsDigest, type DialogOptions, type DialogResult, type DjvlcError, type EditorComponent, type Environment, ErrorCategory, ErrorCode, ErrorCodeToHttpStatus, type ErrorMapping, ErrorMessages, type EventDeclaration, type EventHandler, type ExecutorContext, type ExecutorResult, type Expression, type ExpressionContext, type ExpressionEventContext, type ExpressionFunctionCategory, type ExpressionFunctionDefinition, type ExpressionLocalContext, type ExpressionType, type ExpressionValidationConfig, type ExpressionValidationError, type ExpressionValidationResult, type ExpressionValidationWarning, FORMAT_FUNCTIONS, type FallbackCondition, type FallbackConfig, type FeatureCondition, type FeatureRolloutConfig, type FieldPermission, type FieldPolicy, type FieldTransform, type FileIntegrity, type FunctionParamDefinition, type GraphQLDataSourceConfig, type HostApi, type HttpDataSourceConfig, type HttpRetryConfig, type I18nDetectionStrategy, type ISODateTime, type IdempotencyKeyStrategy, type IdempotencyRule, type IntegrityHash, type InternalDataSourceConfig, type InventoryConfig, type JsonObject, type JsonValue, type KillSwitchItem, LOGIC_FUNCTIONS, type LayoutConfig, type LayoutValues, type LegacyPageResolveResponse, type LoopConfig, type LotteryActivityRule, type LotteryCost, type LotteryPrize, type LotteryState, type Manifest, type ManifestEntry, type ManifestItem, type ManifestValidationError, type ManifestValidationResult, type ManifestValidationWarning, type MaskingConfig, type MaskingRule, type MaskingType, type MethodCategory, type MethodDeclaration, type MethodParam, NUMBER_FUNCTIONS, type NavigateOptions, type NodeStyleConfig, type OperatorInfo, type OpsConfig, type OrderByItem, PAGE_SCHEMA_VERSION, PROTOCOL_VERSION, type PageAssetsJson, type PageConfig, type PageDraft, type PageI18nConfig, type PageIntegrityJson, type PageLifecycle, type PageManifest, type PageMeta, type PageResolveRequest, type PageResolveResponse, type PageResolveWithSnapshotResponse, type PageSEO, type PageSchema, type PageSnapshotJson, type PageSnapshotManifest, type PageSnapshotMeta, type PageSnapshotPage, type PageState, PageStatus, type PageStatusType, type PageVersion, type PaginatedResponse, type PaginationMeta, type PaginationParams, type ParamPermission, type ParticipationLimit, type PercentageRolloutConfig, type PityConfig, type Precondition, type PreconditionType, type PreviewImageOptions, type PreviewToken, type PreviewTokenValidationResult, type ProbabilityConfig, type PropDefinition, type PropFormat, type PropGroup, type PropType, type PropValue, type PropsSchema, type PublishCdnConfig, PublishChannel, type PublishConfig, type PublishEnvironment, type PublishNotificationConfig, type PublishRecord, type PublishRolloutConfig, PublishStatus, type QueryPermissions, type RateLimitDimension, type RateLimitItem, type RateLimitRule, type RequestContext, type ResolvedManifest, type ResponsiveBreakpoints, type RetryPolicy, type RiskControlConfig, type RolloutConfig, type RolloutMatchRequest, type RolloutMatchResult, type RolloutStrategy, type RolloutStrategyConfig, type RolloutStrategyType, type RuntimeConfig, type RuntimeContext, type RuntimeSpec, type SHAIntegrity, STRING_FUNCTIONS, type ScanCodeResult, type SchemaVersion, type SemVer, type ShareOptions, type ShareResult, type SigninActivityRule, type SigninRecord, type SigninRewardRecord, type SigninState, type SlotCategory, type SlotDeclaration, type SnapshotComponentEntry, type StateFieldDefinition, type StorageApi, type StorageOptions, type StyleConfig, type StyleIsolation, type TimeWindowRolloutConfig, type ToastOptions, type TrackEvent, type URLString, UTILITY_FUNCTIONS, type UniqueId, type UpsertRolloutRequest, type UserActivityState, type UserContext, VERSION, type ValidationRule, type VersionDiff, type VersionInfo, VersionStatus, type VersionStatusType, type WhitelistRolloutConfig, bindingRef, createDjvlcError, createExpressionContext, createLoopContext, isDjvlcError, literal, queryRef, stateRef, template };

package/dist/index.js

@@ -1002,6 +1002,21 @@ var DEFAULT_EXPRESSION_VALIDATION_CONFIG = {
 };
 
 // src/page/expression.ts
+function createExpressionContext(partial) {
+  return {
+    state: {},
+    binding: {},
+    context: {},
+    ...partial
+  };
+}
+function createLoopContext(item, index, extras) {
+  return {
+    item,
+    index,
+    ...extras
+  };
+}
 function literal(value) {
   return value;
 }
@@ -1105,6 +1120,8 @@ exports.VERSION = VERSION;
 exports.VersionStatus = VersionStatus;
 exports.bindingRef = bindingRef;
 exports.createDjvlcError = createDjvlcError;
+exports.createExpressionContext = createExpressionContext;
+exports.createLoopContext = createLoopContext;
 exports.isDjvlcError = isDjvlcError;
 exports.literal = literal;
 exports.queryRef = queryRef;

package/dist/index.mjs

@@ -1000,6 +1000,21 @@ var DEFAULT_EXPRESSION_VALIDATION_CONFIG = {
 };
 
 // src/page/expression.ts
+function createExpressionContext(partial) {
+  return {
+    state: {},
+    binding: {},
+    context: {},
+    ...partial
+  };
+}
+function createLoopContext(item, index, extras) {
+  return {
+    item,
+    index,
+    ...extras
+  };
+}
 function literal(value) {
   return value;
 }
@@ -1071,4 +1086,4 @@ var COMPONENT_META_SCHEMA_VERSION = "2.0.0";
 var ACTION_SPEC_VERSION = "2.0.0";
 var DATA_QUERY_SPEC_VERSION = "2.0.0";
 
-export { ACTION_SPEC_VERSION, ALLOWED_FUNCTION_NAMES, ALL_BUILTIN_FUNCTIONS, ARRAY_FUNCTIONS, ActionType, AuditAction, COMPONENT_META_SCHEMA_VERSION, CURRENT_ACTION_SPEC_VERSION, CURRENT_COMPONENT_META_VERSION, CURRENT_DATA_QUERY_SPEC_VERSION, CURRENT_SCHEMA_VERSION, DATA_QUERY_SPEC_VERSION, DATE_FUNCTIONS, DEFAULT_EXPRESSION_VALIDATION_CONFIG, ErrorCategory, ErrorCode, ErrorCodeToHttpStatus, ErrorMessages, FORMAT_FUNCTIONS, LOGIC_FUNCTIONS, NUMBER_FUNCTIONS, PAGE_SCHEMA_VERSION, PROTOCOL_VERSION, PageStatus, PublishChannel, PublishStatus, STRING_FUNCTIONS, UTILITY_FUNCTIONS, VERSION, VersionStatus, bindingRef, createDjvlcError, isDjvlcError, literal, queryRef, stateRef, template };
+export { ACTION_SPEC_VERSION, ALLOWED_FUNCTION_NAMES, ALL_BUILTIN_FUNCTIONS, ARRAY_FUNCTIONS, ActionType, AuditAction, COMPONENT_META_SCHEMA_VERSION, CURRENT_ACTION_SPEC_VERSION, CURRENT_COMPONENT_META_VERSION, CURRENT_DATA_QUERY_SPEC_VERSION, CURRENT_SCHEMA_VERSION, DATA_QUERY_SPEC_VERSION, DATE_FUNCTIONS, DEFAULT_EXPRESSION_VALIDATION_CONFIG, ErrorCategory, ErrorCode, ErrorCodeToHttpStatus, ErrorMessages, FORMAT_FUNCTIONS, LOGIC_FUNCTIONS, NUMBER_FUNCTIONS, PAGE_SCHEMA_VERSION, PROTOCOL_VERSION, PageStatus, PublishChannel, PublishStatus, STRING_FUNCTIONS, UTILITY_FUNCTIONS, VERSION, VersionStatus, bindingRef, createDjvlcError, createExpressionContext, createLoopContext, isDjvlcError, literal, queryRef, stateRef, template };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djvlc/contracts-types",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "DJV Low-code Platform - TypeScript 类型定义包",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",