diff --git a/docs/en/guide/package.md b/docs/en/guide/package.md index 86590ae..2b65ce8 100644 --- a/docs/en/guide/package.md +++ b/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. diff --git a/docs/en/guide/sources.md b/docs/en/guide/sources.md index 584ba82..fec4139 100644 --- a/docs/en/guide/sources.md +++ b/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 diff --git a/docs/en/reference/contracts/component.md b/docs/en/reference/contracts/component.md index 7070af8..e9c4779 100644 --- a/docs/en/reference/contracts/component.md +++ b/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. diff --git a/docs/en/reference/contracts/layout.md b/docs/en/reference/contracts/layout.md index 9232bce..da878b6 100644 --- a/docs/en/reference/contracts/layout.md +++ b/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). diff --git a/docs/en/reference/modules/development.md b/docs/en/reference/modules/development.md index 48bd3f3..5a2f5ff 100644 --- a/docs/en/reference/modules/development.md +++ b/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). diff --git a/docs/guide/package.md b/docs/guide/package.md index be3c117..6c7378f 100644 --- a/docs/guide/package.md +++ b/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 不是组件包,也不由宿主运行。 diff --git a/docs/guide/sources.md b/docs/guide/sources.md index f411cb3..7d69ca8 100644 --- a/docs/guide/sources.md +++ b/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 给出同步文件的哈希。 ## 格式与兼容 diff --git a/docs/public/sdk/protocol.en.json b/docs/public/sdk/protocol.en.json index 581b9df..f1912ee 100644 --- a/docs/public/sdk/protocol.en.json +++ b/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", diff --git a/docs/public/sdk/protocol.json b/docs/public/sdk/protocol.json index 8e72583..376d830 100644 --- a/docs/public/sdk/protocol.json +++ b/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", diff --git a/docs/public/sdk/widget-host.d.ts b/docs/public/sdk/widget-host.d.ts index b8a5a76..6cb043e 100644 --- a/docs/public/sdk/widget-host.d.ts +++ b/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}; diff --git a/docs/public/sdk/widget-host.en.d.ts b/docs/public/sdk/widget-host.en.d.ts index 9c46de6..3525db3 100644 --- a/docs/public/sdk/widget-host.en.d.ts +++ b/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}; diff --git a/docs/reference/contracts/component.md b/docs/reference/contracts/component.md index 4a7866d..29c7854 100644 --- a/docs/reference/contracts/component.md +++ b/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或权限,当前数据与旧组件业务格式的兼容性由作者负责。 ## 内容目录 diff --git a/docs/reference/contracts/layout.md b/docs/reference/contracts/layout.md index 16e5d3f..2ce3aa5 100644 --- a/docs/reference/contracts/layout.md +++ b/docs/reference/contracts/layout.md @@ -42,7 +42,7 @@ 组件引用形式为 `{widgetId:"...",hostApiMajor:1}`,不保存 source、appId 或 publishedFileId。依赖仅按 UUID 匹配已安装组件,与本地、开发或工坊来源无关;同 UUID 多个安装时拒绝歧义,不任意选择。宿主API版本必须为1,不支持的引用禁止应用。工坊发布保留相同引用,不要求组件来自工坊,也不提供引用重绑定。 -schemaVersion、kind、layoutId、version、name、sourceResolution、sourceWorkArea、items 必填;sourceResolution 为保存时完整显示区域的物理像素正整数宽高(不是工作区或 DIP),每项 componentName 为非空名称快照。组件不可重复身份仅由 component.widgetId 确定,名称不参与匹配。其余规则:version 格式与组件包一致。items 可为空,表示清空目标屏当前布局;同一组件 UUID 最多一次。enabled/visible 必须为布尔值,layer 必须为 top/bottom。sourceWorkArea 宽高必须为正;bounds 为有限 DIP 数值,宽高为正。未知字段、重复 JSON 键、重复组件引用和不支持的协议均拒绝导入。 +schemaVersion、kind、layoutId、version、name、sourceResolution、sourceWorkArea、items 必填;sourceResolution 为保存时完整显示区域的物理像素正整数宽高(不是工作区或 DIP),每项 componentName 为非空名称快照。组件不可重复身份仅由 component.widgetId 确定,名称不参与匹配。其余规则:version 格式与组件包一致。items 可为空,表示清空目标屏当前布局;同一组件 UUID 最多一次。enabled/visible 必须为布尔值,layer 必须为 top/bottom。sourceWorkArea 宽高必须为正;bounds 为有限 DIP 数值,宽高为正。未知字段、重复 JSON 键、重复组件引用和不支持的协议均拒绝导入。已保存的当前屏布局允许读取结构有效但运行代际不兼容的安装引用,以保留启用意图;应用/恢复仍检查引用代际与激活版本一致且为宿主所支持。 zOrder 为 0 到 2147483647 的整数,同一 layer 内不得重复,越大越靠前;不同层可重复,top 始终位于 bottom 之上。隐藏条目同样保留顺序。预览与实际应用使用同一排列。 @@ -54,7 +54,7 @@ zOrder 为 0 到 2147483647 的整数,同一 layer 内不得重复,越大越 ## 应用与恢复 -1. 选择目标显示器,确认已连接且物理像素宽高与 sourceResolution 一致,否则禁止应用或覆盖。解析布局并校验引用;逐项检查是否存在已完整安装、兼容、未待清理的本地激活版本。列出缺失项,任一缺失即禁用应用按钮,不自动订阅或下载。 +1. 选择目标显示器,确认已连接且物理像素宽高与 sourceResolution 一致,否则禁止应用或覆盖。解析布局并校验引用;逐项检查是否存在已完整安装、兼容、未待清理的本地激活版本。列出缺失项及[运行不兼容](component.md#运行兼容性)的组件和原因,任一依赖不可用即禁用应用按钮,不自动订阅或下载。 2. 在数据层计算适配与配置变化,显示新增、替换、停用及默认值回落。预览不运行新组件、不修改状态,也不检查用户是否授予 Capability。 3. 用户确认后取得目标屏布局操作锁,重新检查显示器、依赖、版本和配置模式,保存原状态快照,再准备候选状态与窗口。新窗口准备期间不启动作者脚本;失败保留原状态。 4. 原子提交候选状态;目标屏中未列出的条目移除,其既有配置不在当前布局中保留,列出的组件按布局的 enabled/visible/layer/zOrder 排布。不复制到其他屏,不改变安装级授权。 diff --git a/docs/reference/modules/development.md b/docs/reference/modules/development.md index e714aa9..9ce9d26 100644 --- a/docs/reference/modules/development.md +++ b/docs/reference/modules/development.md @@ -4,7 +4,7 @@ ## 作者 SDK -sdk/是JS、TypeScript声明及机器可读协议的唯一维护来源,当前版本0.1.1。宿主将widget-host.js编译为自身资源,在包主文档创建时、业务脚本执行前提供window.widgetHost,等待注册完成后才导航;重载和版本切换同样自动提供。组件包不携带widget-host.js、widget-host.d.ts或protocol.json,不添加SDK脚本标签。类型声明供编辑器和构建工具从宿主随附sdk目录引用,不进入发布包;protocol.json由宿主和开发工具使用。SDK变化同步宿主、开发工具及许可证。Worker没有直接宿主桥接。组件可通过 `widgetHost.context.language` 和 `language.changed` 无权限读取并跟随宿主实际语言,定义见[宿主语言](../contracts/host-api.md#宿主语言)。强调色、文字缩放及组件原生菜单见[宿主接口](../contracts/host-api.md#强调色与文字缩放),均无需Capability;菜单按实例文档注册,重载后由作者重新设置。协议版本及兼容范围遵循格式版本规则(宿主文档:`../development.md#格式版本兼容与迁移`)。 +sdk/是JS、TypeScript声明及机器可读协议的唯一维护来源,当前版本0.1.2。宿主将widget-host.js编译为自身资源,在包主文档创建时、业务脚本执行前提供window.widgetHost,等待注册完成后才导航;重载和版本切换同样自动提供。组件包不携带widget-host.js、widget-host.d.ts或protocol.json,不添加SDK脚本标签。类型声明供编辑器和构建工具从宿主随附sdk目录引用,不进入发布包;protocol.json由宿主和开发工具使用。SDK变化同步宿主、开发工具及许可证。Worker没有直接宿主桥接。组件可通过 `widgetHost.context.language` 和 `language.changed` 无权限读取并跟随宿主实际语言,定义见[宿主语言](../contracts/host-api.md#宿主语言)。强调色、文字缩放及组件原生菜单见[宿主接口](../contracts/host-api.md#强调色与文字缩放),均无需Capability;菜单按实例文档注册,重载后由作者重新设置。协议版本及兼容范围遵循格式版本规则(宿主文档:`../development.md#格式版本兼容与迁移`)。 ready提供context/features/limits;事件先更新context,on返回解除函数,离开取消调用并释放订阅。compatibility分开报告宿主支持、浏览器API存在、实际探测和未实测设备,不能从存在性推定可用性。Capability可拒绝,安装获准后直接调用;外链不逐次确认,实际系统选择/覆盖和本人账号同意保留。 @@ -12,7 +12,7 @@ TypeScript使用ES2020、DOM、strict及noEmit,不启用skipLibCheck。HTTP头 ## 作者 SDK 版本管理 -作者 SDK 不锁定,当前为 `0.1.1`,采用独立的 `major.minor.patch` 三段版本。`sdk/protocol.json` 的 `sdkVersion` 是当前版本来源,`widget-host.js` 标头、类型声明、宿主分发及作者指南必须同步;SDK 版本不是宿主最低版本或权限授予依据。 +作者 SDK 不锁定,当前为 `0.1.2`,采用独立的 `major.minor.patch` 三段版本。`sdk/protocol.json` 的 `sdkVersion` 是当前版本来源,`widget-host.js` 标头、类型声明、宿主分发及作者指南必须同步;SDK 版本不是宿主最低版本或权限授予依据。组件的接口代际、必需特性及不兼容处理统一见[运行兼容性](../contracts/component.md#运行兼容性)。 | 阶段/变更 | 递增规则 | | --- | --- | diff --git a/docs/reference/modules/workshop.md b/docs/reference/modules/workshop.md index 20f1c0b..1bd40cb 100644 --- a/docs/reference/modules/workshop.md +++ b/docs/reference/modules/workshop.md @@ -16,6 +16,8 @@ Steam 适配器负责 SDK 初始化、回调泵和退出,与组件恢复独立 ## 浏览与订阅 +详情抽屉提供收藏/取消收藏、赞/踩、分享和查看作者作品。收藏与投票属于当前 Steam 账号,不改变订阅、安装或授权;进入抽屉读取真实状态,修改以异步成功结果为准,同一条目同类操作串行,失败保留已确认状态并提供重试。状态读取失败不能显示为未收藏或未投票;账号会话变化清空状态并拒绝迟到结果。收藏读取最多200页、10000项且总时限120秒,未完整读取且未找到条目时保持未知。投票只支持赞或踩及二者切换,不提供撤回投票。分享复制固定 Steam 作品链接;查看作者作品打开该作者在本应用的 Steam 工坊作品列表,作者身份无效时不可用。 + 工坊页分组件、布局,支持统一名称/条目ID搜索、标准标签多选、排序、分页和卡片/抽屉详情;只查询本应用的AppID。类型标签`Widget`、`Layout`与内容标签分开:内容标签不选表示全部,多选匹配任一所选标签,且必须满足内容类型;只接受标准目录的英文身份,不识别未知标签。名称查询通过Steam的独立必需标签组实现上述条件,精确条目ID结果由Services执行同样筛选;不在分页后的结果上伪造完整标签搜索。最近更新排序使用Steam的最后更新时间倒序,最新发布仍按发布时间。详情包括作者 Steam 昵称、说明、预览、来源、版本、所需能力以及订阅/安装状态。SteamID仅用于所有权与账号关联,不显示为作者名称;昵称尚未取得时显示作者占位,获取后同时刷新卡片和抽屉,拒绝过期账号会话的昵称回调。姓名请求只取昵称,适配器最多跟踪256个作者并在五分钟后失效,不请求头像。订阅后自动下载和检查更新,抽屉不提供“下载或检查更新”按钮。呈现和交互见管理界面(宿主文档:`ui.md`)。 两类内容均使用Community类型,保留`Widget`、`Layout`标签,组件附加标签直接取当前源码manifest中识别的tags,发布表单只显示本地化结果,不另行编辑;未知值不上传,附加标签不能改变分类。内部内容类型与开发者元数据的kind仍为`widget`、`layout`;Services在提交查询与发布时统一转换为上述Steam标签,后台可见标签使用相同大小写。开发者元数据描述kind、作品UUID、version及组件hostApiMajor/capabilities,仅为未校验的展示摘要,不授予权限;安装以下载目录的实际协议校验为准。预览按需从Steam图片服务读取,响应最多1MiB,规范化为最长边512像素的PNG,缓存最多128份;页面不执行描述HTML或远端脚本。 diff --git a/host-snapshot.json b/host-snapshot.json index 54db488..dd818e6 100644 --- a/host-snapshot.json +++ b/host-snapshot.json @@ -1,5 +1,5 @@ { - "sdkVersion": "0.1.1", + "sdkVersion": "0.1.2", "files": [ { "source": "docs/CONTEXT.md", @@ -22,8 +22,8 @@ { "source": "docs/contracts/component.md", "destination": "docs/reference/contracts/component.md", - "sourceSha256": "5786d997e769e30f6979249a32e4655e442367a978fa4d9e21e4cc4da7ab4e42", - "sha256": "a9f68e6be9afb8475f7c1ee400b0fe99d1cd8d220e5640c7ab16317c1ff79b96" + "sourceSha256": "6e0983cb87cadce8106fab768a5e5ccb13cde9b865d4c986cd048bc17f7fc7bd", + "sha256": "82387add17a69cf38c6f55c547f4f6a3e3422cf01f0993e66d2e592bf0a00f9e" }, { "source": "docs/contracts/configuration.md", @@ -46,8 +46,8 @@ { "source": "docs/contracts/layout.md", "destination": "docs/reference/contracts/layout.md", - "sourceSha256": "1dcd45cdcb4f8d27a765df1112dbb57d43bcff02e7a5261d20f0dc242d5c4885", - "sha256": "ee3cb54619be5998e44d4e27c2657f8bc53475d7640e72b7105a32cd04cf8345" + "sourceSha256": "de3c5b88af8cac2938f2cc2ad49e6013e223112f2764ec3d393f9c7b6cb3adc0", + "sha256": "f83013f72233b4230a13b50293c74a041f93bfcbb4cf4b7631c6c9bb7b28487f" }, { "source": "docs/contracts/reminders.md", @@ -76,8 +76,8 @@ { "source": "docs/modules/development.md", "destination": "docs/reference/modules/development.md", - "sourceSha256": "285bbf836ee1625754ed4fe6da8f37a1cddc49172b0b987826679bb0f14dae32", - "sha256": "3c46baf62c44dba452d94a6ee0428f917e51d5b069f3ef5f8d14a0a266ad4923" + "sourceSha256": "d462a23796d987b014188a66be743a2cd1b03083b16460a3e0c6f967b05ba56e", + "sha256": "5e3c91193c2a7eb485a1d4be4c8c43d218f7aa6bf09469032c40dd2e13710e03" }, { "source": "docs/modules/edge-garden.md", @@ -118,8 +118,8 @@ { "source": "docs/modules/workshop.md", "destination": "docs/reference/modules/workshop.md", - "sourceSha256": "f537936546357006d2d3267a1ee7ff6a10ef1c9095177980ffe083e75fb3243b", - "sha256": "eb272a936026bf959d843568bf0065d47942315256d826ccd2f959b6212c1eba" + "sourceSha256": "cd4f4fe2a07085b443a1f6785da5c5814eb3956546680815e803d28118553305", + "sha256": "2ced55578ceeebbe3d6220bf1dfca98734058ccaa77a52bedadda214cde21199" }, { "source": "examples/edge-garden/audio.js", @@ -328,26 +328,26 @@ { "source": "sdk/protocol.json", "destination": "docs/public/sdk/protocol.json", - "sourceSha256": "00477afa9e1374fe7c1f0fc98e516813c3292e916edf44aa6707fcdc57dbfa9b", - "sha256": "ce3a12727b47b616e06c9b0ca29c981e12fcab1ab3281c1921fa136d21433eec" + "sourceSha256": "e41764220e9abed5147a35f643069a687a1b85e89abef14993ea904543f1876b", + "sha256": "16769fc027da0c3ed44faa308c6a0a3f594137935d41d32cd6d79d530f68f98d" }, { "source": "sdk/protocol.json", "destination": "docs/public/sdk/protocol.en.json", - "sourceSha256": "00477afa9e1374fe7c1f0fc98e516813c3292e916edf44aa6707fcdc57dbfa9b", - "sha256": "298a5c0146108e721ad0350801cf332f0e58093c305359473e5670ea1b5d72e0" + "sourceSha256": "e41764220e9abed5147a35f643069a687a1b85e89abef14993ea904543f1876b", + "sha256": "3c7b9739b22cf4756fa74623075401fa1efb63f60080ba0d0d0cbd4de7b7477c" }, { "source": "sdk/widget-host.d.ts", "destination": "docs/public/sdk/widget-host.d.ts", - "sourceSha256": "411de44f4d2f80d39cd2703ad6fe482f304362820c87e2b87e82b4f59ade6c65", - "sha256": "e1c0111544e6f59da09790d1789623c718fd962232674ff1cb3321b6b3fb67a6" + "sourceSha256": "055c41d21f29b6933655abe05aca3265687a8e50173320138d0705f79661c45e", + "sha256": "6afc561021a16f3a899b975328d30cede822d92a17c6b49b3006fec24f85c747" }, { "source": "sdk/widget-host.d.ts", "destination": "docs/public/sdk/widget-host.en.d.ts", - "sourceSha256": "411de44f4d2f80d39cd2703ad6fe482f304362820c87e2b87e82b4f59ade6c65", - "sha256": "b32a7e4dd807f3e719ac8c6c994293c08084c13998c25688c1837cfdd0c0e153" + "sourceSha256": "055c41d21f29b6933655abe05aca3265687a8e50173320138d0705f79661c45e", + "sha256": "ff6ec6a81e6dab70dee0c277c66cfb65f72e2a64f8ad84e681a546c641a8380a" } ] } diff --git a/skills/widget-workshop-dev/SKILL.md b/skills/widget-workshop-dev/SKILL.md index 9896df9..d522324 100644 --- a/skills/widget-workshop-dev/SKILL.md +++ b/skills/widget-workshop-dev/SKILL.md @@ -13,7 +13,7 @@ The plugin root is two directories above this file. Resolve all paths from that 2. Identify the author-visible result, data ownership, required failure states and runtime verification. Resolve material ambiguity with one focused question while progressing on independent work. 3. Generate a new widgetId for a new work. Keep an existing identity when updating it. The host rejects cross-source duplicate widgetIds; same-monitor duplicates are never supported. 4. Use a complete schemaVersion=1, kind=widget, hostApiMajor=1 manifest. Configuration is a field array. Default to an opaque surface and no capabilities. Read the actual declaration before selecting any capability. -5. Wait for widgetHost.ready before calls. The host injects the SDK; do not bundle widget-host.js, widget-host.d.ts or protocol.json, and do not add an SDK script tag. Worker code has no direct bridge. +5. Declare essential host features with manifest requiredFeatures (see the package guide); probe optional features and handle denied capabilities independently. SDK release versions are not runtime compatibility ranges. Wait for widgetHost.ready before calls. The host injects the SDK; do not bundle widget-host.js, widget-host.d.ts or protocol.json, and do not add an SDK script tag. Worker code has no direct bridge. 6. Register pagehide cleanup before asynchronous initialization. Track document validity, cancel calls, timers and streams, unsubscribe events, and prevent late success or failure from updating old DOM. Bound input, work queues, request count and retries. 7. Deliver the runnable static package. Run relevant static checks and the actual host's read-only package checker when available. Tell the user exactly which runtime paths were tested; do not substitute browser rendering for desktop verification.