@hy-bricks/devtools - npm Package Compare versions

Comparing version 0.4.0 to 0.4.1

CHANGELOG.md

+# @hy-bricks/devtools
+
+## [0.4.1] - 2026-05-27
+
+文档补完 — 0.4.0 的发版说明现在 npm 包页面可见。代码无变更。
+从 0.4.0 升上来可跳过。
+
+---
+
+## [0.4.0] - 2026-05-27 · 组件 mounted 里立即可订阅
+
+### ✨ 新特性
+
+组件作者可在 `mounted` 里**直接调** `__HYPERCARD__.runtime.on(this.hcInstanceId, ...)` 立即生效,不再需要 nextTick / microtask 等一拍。
+
+每个组件实例可读 3 个 SDK 注入 prop:
+
+| Prop | 含义 |
+|---|---|
+| `this.hcInstanceId` | 实例 ID |
+| `this.hcCanvasId` | 所属画布 ID |
+| `this.hcComponentId` | 组件源 ID |
+
+```js
+// 组件源码 component.js
+export default {
+  mounted() {
+    console.log('我是谁', this.hcInstanceId, this.hcCanvasId)
+
+    // ✅ 立即订阅,不再要等
+    __HYPERCARD__.runtime.on(this.hcInstanceId, 'click', (payload) => {
+      // ...
+    })
+
+    // ✅ 立即拿到 handle
+    const handle = __HYPERCARD__.canvases
+      .get(this.hcCanvasId)
+      ?.getInstance(this.hcInstanceId)
+  },
+}
+```
+
+### ⚠ BREAKING — host 升级前 audit
+
+`onInstanceLifecycle('instance:ready')` / `handle.on('instance:ready')` 回调被调时,**子组件 DOM 还没渲染**,`vm.$el` 是 `null`。
+
+**修法**(回调内访问 DOM 的话):
+
+```js
+// ❌ 不能直接访问 $el
+onInstanceLifecycle('instance:ready', ({ instance }) => {
+  instance.$el.querySelector(...)  // null,报错
+})
+
+// ✅ 等下一帧 DOM 渲染完
+onInstanceLifecycle('instance:ready', ({ instance }) => {
+  nextTick(() => {
+    instance.$el.querySelector(...)
+  })
+})
+```
+
+### 升级 checklist
+
+```bash
+grep -rn "instance:ready\|onInstanceLifecycle\|getInstanceReady" src/
+```
+
+每处看回调内是否访问 `vm.$el` / DOM。
+- 没访问 → `npm install @hy-bricks/{core,canvas,editor,devtools}@^0.4.0` 透明升
+- 访问了 → 改 `nextTick`
+
+### 命名保留
+
+组件作者**不要**用这 3 个名字声明你自己的 prop(同名会被 SDK 注入覆盖):
+`hcInstanceId` / `hcCanvasId` / `hcComponentId`。
+
+之前的保留 prop `hcCustomValues` 不变。
+
+---
+
+## 0.3.0
+
+### Minor Changes
+
+- 0.3.0 渲染核心 · mount-ready 信号 + cache 精确读 API
+
+  **主题**:`RenderScheduler` 渐进 mount 下,SDK 第一次给出"组件挂好"信号(per-canvas 隔离的 event + Promise + cache 精确读 API)。host 替掉 `setTimeout(300)` / `mountConcurrency:50` / `replayFromCache` 全表遍历兜底。
+
+  **新 API**:
+  - `@hy-bricks/core`:`onInstanceLifecycle("instance:ready" | "instance:unmounted", cb)` — 模块级 lifecycle emitter,跨 canvas 共享,payload `{ canvasId, instanceId }`
+  - `@hy-bricks/canvas · CanvasHandle`:
+    - `handle.on("instance:ready" | "instance:unmounted", cb)` — per-canvas 自动过滤,payload 只透 `instanceId`
+    - `handle.getInstanceReady(instanceId): Promise<void>` — 已挂立即 resolved / 未挂等 emit / `handle.dispose()` 时 reject `HandleDisposedError`
+    - `handle.getInstanceRuntime(instanceId)` — 返**运行时 vm handle**(`ComponentInstanceHandle`),给 host 调 `setDataInput / call / emit` 用;跟 `getInstance(id)` 返 PageInstance snapshot 区分
+    - `handle.getCachedBySourceId(sourceId, params?)` — cache 精确读快照,plain object(不返 reactive)
+    - `HandleDisposedError` 具名 error class(host 可 `instanceof` 判)
+    - `handle.dispose()` 终态 guard:dispose 后所有入口 no-op / reject / null,防 listener 泄漏 + pending 永挂
+  - `@hy-bricks/canvas · HyperCardPageRendererExpose.data.getCachedBySourceId(sourceId, params?)` 同款
+
+  **边界**(摸底备忘 §1):SDK 只补"信号 + 暴露 API",**不**替 host 自动 push / replay / 重拉 — 数据治理仍归 host。D5.4 §R6 "cache 保留 + 不自动 replay,host 手动 invalidate" 合约**不变**。
+
+  **host 升级(不强制)**:
+  - 0.2.0 → 0.3.0 **不破坏现有代码**;不用 ready 信号当 0.3.0 没加
+  - 用了就简化:`handle.on("instance:ready", id => { const c = handle.getCachedBySourceId(src); if (c?.status === "success") handle.getInstanceRuntime(id)?.setDataInput?.(key, c.value) })`
+  - workaround(`replayFromCache` / `mountConcurrency:50` / 首屏 reload)**可保留**,SDK 不强制删
+
+  详见 `docs/v1/frontend-sdk/20260523-1648-claude-渲染核心-挂载就绪信号-实施稿-rev1.md`。

package.json

 {
   "name": "@hy-bricks/devtools",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "HyperCard 诊断 SDK — 运行时 hit-test / drag / render 探针 + 浮窗 UI(DEV 自动启 + prod opt-in)",
@@ -37,3 +37,4 @@ "keywords": [
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
@@ -45,4 +46,4 @@ "publishConfig": {
     "vue": "^3.5.0",
-    "@hy-bricks/canvas": "^0.4.0",
-    "@hy-bricks/core": "^0.4.0"
+    "@hy-bricks/canvas": "^0.4.1",
+    "@hy-bricks/core": "^0.4.1"
   },
@@ -49,0 +50,0 @@ "dependencies": {

README.md

@@ -9,2 +9,4 @@ # @hy-bricks/devtools
 
+> ✨ **0.4.0** ── 跟随 `@hy-bricks/core` 0.4.0 升级。本包 UI / API 不变,仅底层 `instance:ready` 触发时机变化会影响 trace 时序记录。详 [CHANGELOG](./CHANGELOG.md)。
+
 ---
@@ -11,0 +13,0 @@

No alert changes

Improved metrics

Total package byte prevSize

245780

1.85%

Number of package files

33

3.13%

Number of lines in readme file

92

2.22%

No dependency changes