@ptengine/inline-core

English | 简体中文

Ptengine Inline 画布链路里多端共享的基础层：没有 UI、没有框架依赖，只有类型、协议常量和纯函数。

它由原 ptengine-frontend/packages/ 下的三个 workspace 包合并而来：

| 子路径 | 原包 | 内容 | 运行环境 | |---|---|---|---| | @ptengine/inline-core/protocol | @ptengine/inline-canvas-protocol | 产品页 ↔ 插件 service worker ↔ content script 的画布消息契约（命令 / 事件 / 载荷类型、CONTRACT_VERSION）+ 大 DOM 分片传输 | 无 DOM | | @ptengine/inline-core/change-format | @ptengine/inline-change-format | change list 明文形态类型，以及与现役数值形态的双向转译（toWireFormat / fromWireFormat） | 无 DOM（SDK / Node / SW 都能跑） | | @ptengine/inline-core/selector | @ptengine/inline-kernel | 生成 / 解析标准 CSS selector（v1，与线上 SDK 的查找语义对齐） | 需要 DOM |

没有根入口 @ptengine/inline-core，只能按子路径引用。这是刻意的：只需要 change-format 的 消费方（比如 SDK）不应该把依赖 DOM 的 selector 也带进来。

安装

pnpm add @ptengine/inline-core

使用

import { CONTRACT_VERSION, type CanvasFrameCommand } from '@ptengine/inline-core/protocol';
import { toWireFormat, fromWireFormat, type InlineChange } from '@ptengine/inline-core/change-format';
import { buildSelector, resolveSelector } from '@ptengine/inline-core/selector';

同时提供 ESM（.js）、CJS（.cjs）和类型声明。TypeScript 的 moduleResolution 用 bundler / node16 / nodenext 时走 exports；老的 node（node10）靠 typesVersions 兜底。

各子模块的硬约束（改代码前必读）

• change-format：零依赖、不引用 DOM。约束由 src/change-format/tsconfig.json（lib: ["ES2020"]、 types: []）在编译期强制。转译表是与 SDK 共同的规范，改一行都要同步 SDK，详见 src/change-format/README.md。
• protocol：同样不引用 DOM（src/protocol/tsconfig.json）。改动命令 / 事件时注意 CONTRACT_VERSION 与 MIN_SUPPORTED_CONTRACT_VERSION 的维护规则（见 src/protocol/index.ts 顶部注释）。
• selector：src/selector/tsconfig.json 的 lib 故意不含 DOM.Iterable，请用 Array.from(...) 而不是对 children / classList 展开。也不要与 ptengine-frontend 的 packages/utils/element.ts 里的 getSelector 合并 —— 两者是不同方言，原因见 src/selector/index.ts 顶部注释。

测试文件（*.spec.ts）被刻意排除在上面三份 tsconfig 之外：vitest 的类型会把 lib.dom 拉进来、 让约束失效。测试的类型检查走根目录的 tsconfig.spec.json。

开发

pnpm install
pnpm type-check   # 逐个跑三个子模块的 tsconfig + 测试 tsconfig
pnpm test         # vitest；selector 的测试用 jsdom
pnpm build        # tsup → dist/{protocol,change-format,selector}/index.{js,cjs,d.ts,d.cts}
pnpm test:build   # 产物断言：exports 能按包名解析、导出齐全、无 sourcemap、无 DOM 入口不碰 DOM、
                  # 装包方 TS 在 bundler / node16(CJS+ESM) / node10 下都能解析类型

⚠️ package.json 的 pnpm.overrides 把 nwsapi（jsdom 的 selector 引擎）钉在 2.2.24： 2.2.28 解析不了 CSS 十六进制转义（document.querySelectorAll('#\\31 x') 返回 0 个元素，真实浏览器返回 1 个）， 会让 selector 的「数字开头 id」测试假红。升级 jsdom / nwsapi 前先确认这个问题已修复。

版本号

一个包一个版本号，三个子模块一起发。由消费方要不要改代码决定：

| 位 | 什么情况下递增 | |---|---| | major | 删除 / 重命名导出、改变转译表或 selector 生成语义、不兼容地改动已有命令 / 事件（此时通常也要抬 MIN_SUPPORTED_CONTRACT_VERSION） | | minor | 向后兼容地新增：新命令 / 事件（CONTRACT_VERSION +1）、新 change 类型、新导出 | | patch | 修 bug、注释、类型标注修正，公开契约不变 |

⚠️ 包的 semver 和 CONTRACT_VERSION 是两回事：后者是产品页与插件之间的运行时握手版本， 由 src/protocol/index.ts 自己维护，不随包版本自动变化。

发布

由 GitLab CI 在 main 分支上手动触发，发布的版本号就是 package.json 里的 version：

1. 新拉分支，递增 package.json 的 version，更新 CHANGELOG.md，以 MR 合入 main
2. 打开 main 最新的流水线（Build → Pipelines），verify 通过后手动点 publish job
3. 发布后可以补一个 vX.Y.Z tag 标记对应提交（tag 只做标记，不会触发发布）

publish job 在版本已存在时直接失败并提示，误点不会重复发布。 认证走 npm Trusted Publishing（OIDC），CI 里不配 token；Trusted Publisher 的登记项见 .gitlab-ci.yml 头部注释。 首发 0.1.0 因为包还不存在、无法先登记，由维护者在本地手动 npm publish。

授权

UNLICENSED，Ptmind 内部使用。包发布在公共 npm registry 上，产物公开可见：不要在导出的 类型注释里写入机密信息。