Document component compatibility checks and automatic recovery

docs/en/guide/package.md

@@ -8,6 +8,16 @@ Include `manifest.json` and the local HTML referenced by entry, defaulting to `i
 
 window declares initial/minimum dimensions, initial layer and surface. Opaque is the default. Transparent work must explicitly handle native input mode and recovery; CSS cannot implement native click-through. Authors control size through the manifest and `window.setSize`; layouts do not override author size.
 
+## Declare runtime compatibility
+
+Component `version` identifies the work release. SDK release versions identify development references; neither replaces runtime compatibility checks. `hostApiMajor` identifies the interface and behavior generation. Published contracts remain compatible within a generation; cross-generation support requires an explicitly implemented and verified host. The current supported generation is 1.
+
+Declare mandatory host features in the manifest, for example `"requiredFeatures": ["saves.load", "saves.commit"]`. The default is an empty array. Identifiers match handshake features exactly: at most 256 unique entries, each containing 1–128 ASCII letters, digits, dots, underscores or hyphens. Require only features without which the component cannot run; probe optional features after ready and provide fallbacks. Supporting an interface does not grant permission. Handle denied capabilities independently.
+
+Missing mandatory features or an unsupported API generation cause package checks and installation to return PROTOCOL_UNSUPPORTED. Failed updates preserve the active version. If an installed component becomes incompatible with the host, execution stops while personal data and enabled intent are preserved. Compatibility recovery automatically restores enabled components; components explicitly disabled during the block remain disabled. Incompatible layout dependencies prevent applying or restoring the layout. Bundling an older SDK cannot bypass the checks: the host provides the SDK.
+
+See [runtime compatibility](../reference/contracts/component.md#runtime-compatibility) for the contract.
+
 ## Frontend tooling and types
 
 Build locally resolvable assets and copy the manifest into the final directory. Bind that runnable output directory on the Development page. A development server URL is not a component package.

docs/en/guide/sources.md

@@ -1,6 +1,6 @@
 # References
 
-The baseline is Widget Workshop SDK 0.1.1, `hostApiMajor`=1 and `protocolVersion`=1. The host SDK and owning contract/module files remain the authority; `host-snapshot.json` identifies synchronized inputs.
+The baseline is Widget Workshop SDK 0.1.2, `hostApiMajor`=1 and `protocolVersion`=1. The host SDK and owning contract/module files remain the authority; `host-snapshot.json` identifies synchronized inputs.
 
 ## Formats and compatibility
 

docs/en/reference/contracts/component.md

@@ -1,10 +1,24 @@
 # Component package contract
 
-The package `schemaVersion` and `hostApiMajor` are 1; the current SDK is 0.1.1, with independent [versioning rules](../modules/development.md#author-sdk-versioning). Deliver a directory containing `manifest.json`, its local HTML entry and local static resources. Users do not run author scripts. entry defaults to `index.html`; preview defaults to `preview.png` with a placeholder when implicit and absent. Explicit previews must exist and be PNG.
+The package `schemaVersion` and `hostApiMajor` are 1; the current SDK is 0.1.2, with independent [versioning rules](../modules/development.md#author-sdk-versioning). Deliver a directory containing `manifest.json`, its local HTML entry and local static resources. Users do not run author scripts. entry defaults to `index.html`; preview defaults to `preview.png` with a placeholder when implicit and absent. Explicit previews must exist and be PNG.
+
+## Runtime compatibility
+
+Component `version` orders work updates, SDK versions identify development and diagnostic releases, `schemaVersion` identifies manifest structure, and `hostApiMajor` identifies the interface and behavior generation. SDK releases need not match exactly. Published contracts stay compatible within a generation; cross-generation support covers only explicitly implemented and verified generations. Currently only manifest schema 1 and API generation 1 are supported for installation and execution.
+
+Optional `requiredFeatures` defaults to an empty array. It contains at most 256 unique, case-sensitive identifiers, each 1–128 ASCII letters, digits, dots, underscores or hyphens, matching the host handshake feature catalog. Unknown well-formed identifiers are missing mandatory features; malformed or duplicate entries are invalid manifests. Require only essential functionality. Probe optional features and degrade gracefully. Denied capabilities do not make a component version incompatible and do not prevent enabling it. Breaking changes to existing feature semantics require a new API generation; an SDK version increment alone is insufficient.
+
+For example, `"hostApiMajor": 1, "requiredFeatures": ["saves.load", "saves.commit"]` requires that generation and both features. Older hosts may reject this added manifest field; forward readability is not promised.
+
+Package checking, import, Workshop downloads and development reloads reject incompatible inputs with PROTOCOL_UNSUPPORTED and the required generation or missing features. First-install failure creates no installation; Workshop subscriptions and the failure reason remain. Failed updates preserve the active version, data and grants. Activation, layout apply/restore and final transaction commit recheck compatibility.
+
+An installed manifest with readable, valid structure is retained even if it cannot run. The host preserves installation, configuration, saves, KV, grants, bindings and enabled intent, displays the reason and creates no runtime for it. Other compatible components can recover normally. Users may disable or remove a blocked component, but cannot newly enable it. Compatibility is derived from the current host rather than persisted as another switch. Restart or an installation update reevaluates it; enabled components resume automatically when compatible, while explicitly disabled components remain disabled and disconnected displays wait for reconnection. Unknown schemas and corrupt data follow the format rules rather than being guessed or silently cleared.
+
+Any incompatible layout dependency blocks applying or restoring the whole layout and leaves the current layout intact. Rollback does not restore earlier saves, KV or permissions; authors own compatibility of their business data.
 
 ## Manifest fields
 
-Required identity fields include kind: widget, a UUID `widgetId`, three-part numeric version, nonempty name/author and matching `hostApiMajor`. Optional description/tags/i18n/entry/preview/window/capabilities/configuration follow the current schema. Unknown top-level fields, capabilities and field types are rejected. Capabilities are unique names; the array may be empty. configuration is an array with unique keys.
+Required identity fields include kind: widget, a UUID `widgetId`, three-part numeric version, nonempty name/author and matching `hostApiMajor`. Optional description/tags/i18n/entry/preview/window/capabilities/configuration/requiredFeatures follow the current schema. Unknown top-level fields, capabilities and field types are rejected. Capabilities are unique names; the array may be empty. configuration is an array with unique keys.
 
 `allowMultipleInstances` defaults false: one enabled intent across displays, including hidden/disconnected states. When true there is still at most one instance per installation per display. Installation identity is distinct from the author's `widgetId`, and cross-source duplicate additions are rejected.
 

docs/en/reference/contracts/layout.md

@@ -15,3 +15,5 @@ Display IDs are stable internal identities, not connection order or display numb
 ## Source and related declarations
 
 Exact method signatures and complete machine budgets are shared in [SDK declarations](../types.md).
+
+Runtime-incompatible installed dependencies are listed separately from missing dependencies and block applying or restoring the whole layout, preserving the current layout. Saved display layouts retain structurally valid incompatible references and enabled intent; apply/restore require the reference API generation to match the installed version and be supported by the host. See [runtime compatibility](component.md#runtime-compatibility).

docs/en/reference/modules/development.md

@@ -8,10 +8,12 @@ Read the [local development lessons](../../guide/lessons.md), [recipes](../../re
 
 ## Author SDK versioning
 
-The author SDK is not locked. Its current version is `0.1.1`, independently using `major.minor.patch`. `sdkVersion` in the host protocol is the current version source. Keep JavaScript, declarations, machine protocol, host distribution, examples and both guide editions synchronized when the SDK changes.
+The author SDK is not locked. Its current version is `0.1.2`, independently using `major.minor.patch`. `sdkVersion` in the host protocol is the current version source. Keep JavaScript, declarations, machine protocol, host distribution, examples and both guide editions synchronized when the SDK changes.
 
 During `0.x`, increment patch for routine additions and fixes, including limited protocol adjustments such as content tags. Increment minor and reset patch only when the user explicitly decides to enter a new SDK feature stage. Document affected methods, types, events and required author changes for any break. Starting at `1.0.0`, increment major for incompatible changes, minor for compatible additions and patch for fixes; reset all fields to the right. Use the highest-impact change once per SDK delivery. Host UI, internal refactoring, packaging and prose-only changes do not automatically change the SDK version. Different distributed SDK content must not reuse a version; comment/format-only changes are excluded.
 
 `hostApiMajor/apiMajor`, bridge `protocolVersion` and each data format version describe separate contract generations. Update only the generation whose contract changes; do not copy SDK or application version numbers into them. Optional additions with unchanged defaults retain their schema; breaking changes increment the affected format. Supported migration inputs and lower bounds must be explicitly documented and validated. The current canonical formats use v1; historical variants are not accepted merely because they share that number. SDK changes still follow the SDK versioning rules and explain author impact. Component/layout manifest versions remain their own three-part versions. See [format compatibility](../../guide/sources.md#formats-and-compatibility).
 
 The application separately uses four fields (`major.minor.patch.revision`). Development uploads retain the previous default application's version. Only after an explicit decision to update Steam default is the release version incremented once, based on all changes since the previous default, followed by validation, develop upload and default promotion. This does not automatically increment the SDK.
+
+Component requirements and enabled-intent recovery follow [runtime compatibility](../contracts/component.md#runtime-compatibility).

docs/guide/package.md

@@ -8,6 +8,16 @@
 
 window 声明初始/最小尺寸、初始层级以及 surface。默认不透明；透明作品必须明确 inputMode，并处理真实输入区域与恢复方式。页面 CSS 无法代替原生穿透。大小由作者声明或 window.setSize 请求，布局不覆盖作者尺寸。
 
+## 声明运行兼容性
+
+组件 `version` 是作品版本，SDK 发行版本用于开发参考；两者都不替代运行兼容检查。`hostApiMajor` 表示接口和行为代际，同代际维持兼容，跨代际只支持宿主明确实现的范围。当前可运行代际为1。
+
+在 manifest 中用 `"requiredFeatures": ["saves.load", "saves.commit"]` 声明不可缺少的宿主功能。缺省为空数组；标识精确匹配握手 features，最多256项，每项1–128个ASCII字母、数字、点、下划线或连字符，不可重复。只有无法降级的功能才列入必需项；可选接口继续在 ready 后通过 features 探测。权限被拒绝仍应有明确降级或错误处理，不能把支持接口当作已授权。
+
+缺少必需功能或接口代际不受支持时，包检查和安装返回 PROTOCOL_UNSUPPORTED。更新失败保留旧版；已安装组件遇到宿主不兼容时暂停运行并保留个人数据及启用意图，恢复兼容后自动恢复，期间主动停用者不会自动启用。布局中有不兼容依赖时不能应用或恢复。SDK 由宿主提供，无法通过随包附带旧 SDK 绕过检查。
+
+完整规则见[运行兼容性](../reference/contracts/component.md#运行兼容性)。
+
 ## 使用构建工具
 
 无论使用哪个前端工具，都要让入口与资源在最终目录内使用可解析的本地路径，把 manifest 一起输出。在宿主开发页绑定最终可运行目录；开发服务器 URL 不是组件包，也不由宿主运行。

docs/guide/sources.md

@@ -1,6 +1,6 @@
 # 参考资料
 
-本站以当前 Widget Workshop 的 SDK 0.1.1、hostApiMajor=1、protocolVersion=1 为基线。宿主源码中的 sdk 和所属协议/模块是唯一事实来源；host-snapshot.json 给出同步文件的哈希。
+本站以当前 Widget Workshop 的 SDK 0.1.2、hostApiMajor=1、protocolVersion=1 为基线。宿主源码中的 sdk 和所属协议/模块是唯一事实来源；host-snapshot.json 给出同步文件的哈希。
 
 ## 格式与兼容
 

docs/public/sdk/protocol.en.json

@@ -1,7 +1,7 @@
 {
   "protocolVersion": 1,
   "apiMajor": 1,
-  "sdkVersion": "0.1.1",
+  "sdkVersion": "0.1.2",
   "features": [
     "i18n",
     "config.get",

docs/public/sdk/protocol.json

@@ -1,7 +1,7 @@
 {
   "protocolVersion": 1,
   "apiMajor": 1,
-  "sdkVersion": "0.1.1",
+  "sdkVersion": "0.1.2",
   "features": [
     "i18n",
     "config.get",

docs/public/sdk/widget-host.d.ts

@@ -1,3 +1,4 @@
+/** WidgetWorkshop SDK 0.1.2; manifest requiredFeatures declares mandatory host features independently of SDK releases. */
 /** 组件清单中的标准标签；小写英文标识以 protocol.json.contentTags 为准，未知清单值不展示或上传。 */
 type WidgetTag = 'information' | 'productivity' | 'system' | 'files' | 'media' | 'decoration' | 'entertainment' | 'education' | 'lifestyle' | 'development';
 type JsonValue = null | boolean | number | string | JsonValue[] | {[key: string]: JsonValue};

docs/public/sdk/widget-host.en.d.ts

@@ -1,3 +1,4 @@
+/** WidgetWorkshop SDK 0.1.2; manifest requiredFeatures declares mandatory host features independently of SDK releases. */
 /** Standard manifest tags use the lowercase English identifiers in protocol.json.contentTags; unknown values are omitted from display and upload. */
 type WidgetTag = 'information' | 'productivity' | 'system' | 'files' | 'media' | 'decoration' | 'entertainment' | 'education' | 'lifestyle' | 'development';
 type JsonValue = null | boolean | number | string | JsonValue[] | {[key: string]: JsonValue};

docs/reference/contracts/component.md

@@ -2,7 +2,21 @@
 
 # 组件包协议
 
-包格式为schemaVersion=1、hostApiMajor=1，当前作者SDK为0.1.1，更新规则见[作者 SDK 版本管理](../modules/development.md#作者-sdk-版本管理)。公开协议和内部管理状态均以 v1 为基线，兼容与迁移遵循格式版本规则（宿主文档：`../development.md#格式版本兼容与迁移`）；存档正文格式由作者自行定义。能力声明及可拒绝授权见[宿主接口](host-api.md)。
+包格式为schemaVersion=1、hostApiMajor=1，当前作者SDK为0.1.2，更新规则见[作者 SDK 版本管理](../modules/development.md#作者-sdk-版本管理)。公开协议和内部管理状态均以 v1 为基线，兼容与迁移遵循格式版本规则（宿主文档：`../development.md#格式版本兼容与迁移`）；存档正文格式由作者自行定义。能力声明及可拒绝授权见[宿主接口](host-api.md)。
+
+## 运行兼容性
+
+组件 `version` 只用于作品更新排序；SDK 发行版本只用于开发与诊断，不要求组件与宿主 SDK 精确匹配。`schemaVersion` 标识清单结构，`hostApiMajor` 标识接口及行为兼容代际，分别管理。同代际保持已发布契约兼容；跨代际仅支持明确实现并验证的范围。当前清单结构只支持 schemaVersion=1，运行接口代际只支持 hostApiMajor=1，不根据应用版本猜测支持范围。
+
+清单可声明 `requiredFeatures` 字符串数组，缺省为空；最多256项，每项1–128个ASCII字母、数字、点、下划线或连字符，不允许重复。值精确匹配宿主握手 `features` 目录。只声明没有就无法运行的接口或特性；可选功能通过 `features` 探测并降级。未知的合法标识视为缺少必需功能，拒绝运行；类型、重复或格式错误属于无效清单。功能支持不等于授权，Capability 拒绝不构成版本不兼容，也不阻止启用。新增接口时为其登记稳定特性标识；改变既有接口或特性含义的破坏性变更必须提升接口代际，不能只修改 SDK 版本。
+
+例如 `"hostApiMajor": 1, "requiredFeatures": ["saves.load", "saves.commit"]` 表示依赖该代际和两项必需功能。作者工具与安装共用校验；旧宿主不认识新增清单字段时会拒绝，不承诺旧宿主读取新清单。
+
+Services 区分结构校验与运行兼容性。新导入、工坊下载、开发重载及候选版本先验证结构与当前支持；不兼容报 PROTOCOL_UNSUPPORTED，列出所需接口代际或缺少的功能。首次安装失败不创建安装；工坊保留订阅及失败原因。更新失败保留已有激活版本、数据和授权，不自动降级，不把下载成功当作安装成功。候选激活、布局应用/恢复及最终提交重新检查兼容性。
+
+已安装且结构可读取的组件即使运行不兼容，仍保留安装、配置、存档、KV、授权、绑定和启用意图；管理界面显示原因，不创建运行窗口或执行脚本，不影响其他兼容组件恢复。不兼容组件仍可停用或移除；不能新启用。宿主重启或安装更新后重新计算兼容性，恢复兼容时按保留的启用意图自动恢复，期间主动停用者保持停用，断屏者等待回接。兼容状态是当前宿主的派生结果，不持久化为新的启用开关。未知清单结构及损坏数据仍按格式版本规则保留原文件并报错，不能假装已理解未知结构。
+
+布局中的任一依赖不兼容时禁止整屏应用或恢复，预览列出组件及原因，保持原布局。包回退不回退用户存档、KV或权限，当前数据与旧组件业务格式的兼容性由作者负责。
 
 ## 内容目录