From 796153c96043aea32b7d4d3bdbe38b0965aac95b Mon Sep 17 00:00:00 2001 From: huangkai Date: Mon, 16 Nov 2026 13:09:17 +0800 Subject: [PATCH] build(npm): prepare CRYChart for public npm distribution --- .gitattributes | 4 ++ CONTEXT.md | 11 ++++++ README.md | 26 ++++++++----- README.zh-CN.md | 26 ++++++++----- .../adr/0001-publish-scoped-public-package.md | 5 +++ docs/delivery.md | 37 +++++++++++++------ docs/npm-usage.md | 31 ++++++++++++++++ docs/reference-examples.json | 2 +- docs/releases/1.0.1.md | 33 +++++++++++++++++ ...77\347\224\250\346\211\213\345\206\214.md" | 34 ++++++++--------- package-lock.json | 8 ++-- package.json | 25 +++++++++---- scripts/build.mjs | 2 +- scripts/check-package.mjs | 25 +++++++++++++ src/index.ts | 2 +- 15 files changed, 210 insertions(+), 61 deletions(-) create mode 100644 .gitattributes create mode 100644 CONTEXT.md create mode 100644 docs/adr/0001-publish-scoped-public-package.md create mode 100644 docs/npm-usage.md create mode 100644 docs/releases/1.0.1.md create mode 100644 scripts/check-package.mjs diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..40f1ece --- /dev/null +++ b/.gitattributes @@ -0,0 +1,4 @@ +# Preserve bytes verified by the example provenance manifests. +examples/data/brain-drummyfish.obj -text +examples/data/synthetic-air-quality.json -text +examples/data/stereo-spectrum-demo.json -text diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..3ca9ceb --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,11 @@ +# CRYChart 术语 + +本术语表区分图表库、库发行版和消费该库的应用。 + +## 术语 + +**CRYChart**:CRYSOUND 为 OpenTest 数据可视化场景提供的前端图表渲染库。 +_Avoid_:OpenTest 宿主、业务插件 + +**CRYChart 官方发行版**:以 `@crysound/crychart` 标识、由 CRYSOUND 维护的版本化库发行内容,采用 CRYChart Community License 1.0。其版本与 OpenTest 产品版本分别维护。 +_Avoid_:OpenTest 产品版本、OpenTest 消费者修订包 diff --git a/README.md b/README.md index 1cf5695..f8ba037 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,15 @@ CRYChart is a **frontend rendering library built by CRYSOUND for OpenTest**, wri Designed for OpenTest's data visualization needs, CRYChart provides streaming data rendering, interactive axes, cursors, and 2D and 3D charts. It uses WebGL2 for rendering, with a Canvas fallback. -The package name is `crychart`. The current version is **1.0.0**. +The first public npm release is `@crysound/crychart@1.0.1`. This source tree targets `1.0.2`, which includes the high precision waveform viewport fix merged after the `1.0.1` release build. + +## Install in an application + +```powershell +pnpm add --save-exact @crysound/crychart@1.0.1 --registry=https://registry.npmjs.org/ +``` + +Commit the application's lockfile and use `pnpm install --frozen-lockfile` for repeatable installs. See the [npm usage guide](docs/npm-usage.md) for package entry points and migration from the old `crychart` name. ## Install and build @@ -23,8 +31,8 @@ Open the local examples at . Chart containers must have ## Usage ```ts -import { cryChart, ColorRGBA, SolidFill, SolidLine } from 'crychart' -import type { CRYChart, CRYChartOptions } from 'crychart' +import { cryChart, ColorRGBA, SolidFill, SolidLine } from '@crysound/crychart' +import type { CRYChart, CRYChartOptions } from '@crysound/crychart' const options: CRYChartOptions = {} const context: CRYChart = cryChart(options) @@ -41,7 +49,7 @@ line.appendSamples({ y: new Float32Array([1, 2, 3]) }, { start: 0, step: 0.001 } context.dispose() ``` -The package provides ES modules, CommonJS, a browser script, and TypeScript declarations. The browser script exposes the `CRYChart` global. Themes are available through `crychart/themes`. +The package provides ES modules, CommonJS, a browser script, and TypeScript declarations. The browser script exposes the `CRYChart` global. Themes are available through `@crysound/crychart/themes`. ## Validation @@ -64,11 +72,11 @@ The free license imposes no limits on the number of channels, data series, curve ## Documentation -- [User guide](docs/使用手册.md) -- [Performance notes](docs/性能说明.md) -- [High-precision historical waveforms and Scope latency retest](docs/performance-scope-high-precision-20261109.md) -- [Architecture](docs/architecture.md) -- [Product specification](SPEC.md) +- [npm usage guide](docs/npm-usage.md) +- [User guide](https://github.com/crysound/CRYChart/blob/main/docs/使用手册.md) +- [Performance notes](https://github.com/crysound/CRYChart/blob/main/docs/性能说明.md) +- [Architecture](https://github.com/crysound/CRYChart/blob/main/docs/architecture.md) +- [Product specification](https://github.com/crysound/CRYChart/blob/main/SPEC.md) Some documentation is currently available only in Chinese. diff --git a/README.zh-CN.md b/README.zh-CN.md index 3119e26..90cde39 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -6,7 +6,15 @@ CRYChart 是 **CRYSOUND 为 OpenTest 定制的前端渲染库**,基于 TypeScr CRYChart 面向 OpenTest 的数据可视化场景,提供流式数据绘制、交互坐标轴、游标、二维和三维图表。绘图使用 WebGL2,并提供 Canvas 回退。 -包名为 `crychart`,当前版本为 **1.0.0**。 +首个 npm 公开版本为 `@crysound/crychart@1.0.1`。当前源码准备发布 `1.0.2`,包含 `1.0.1` 发行包构建后合入的高精度波形视口修复。 + +## 在应用中安装 + +```powershell +pnpm add --save-exact @crysound/crychart@1.0.1 --registry=https://registry.npmjs.org/ +``` + +提交应用的锁文件,后续执行 `pnpm install --frozen-lockfile`。包入口和旧 `crychart` 包名的迁移方式见 [npm 使用说明](docs/npm-usage.md)。 ## 安装与构建 @@ -21,8 +29,8 @@ npm run dev ## 使用 ```ts -import { cryChart, ColorRGBA, SolidFill, SolidLine } from 'crychart' -import type { CRYChart, CRYChartOptions } from 'crychart' +import { cryChart, ColorRGBA, SolidFill, SolidLine } from '@crysound/crychart' +import type { CRYChart, CRYChartOptions } from '@crysound/crychart' const options: CRYChartOptions = {} const context: CRYChart = cryChart(options) @@ -39,7 +47,7 @@ line.appendSamples({ y: new Float32Array([1, 2, 3]) }, { start: 0, step: 0.001 } context.dispose() ``` -包提供 ES 模块、CommonJS、浏览器脚本和 TypeScript 类型声明。浏览器脚本的全局对象为 `CRYChart`。主题入口为 `crychart/themes`。 +包提供 ES 模块、CommonJS、浏览器脚本和 TypeScript 类型声明。浏览器脚本的全局对象为 `CRYChart`。主题入口为 `@crysound/crychart/themes`。 ## 验证 @@ -62,10 +70,10 @@ CRYChart 采用 [CRYChart 社区许可协议 1.0](LICENSE.zh-CN.md),并提供 ## 文档 -- [使用手册](docs/使用手册.md) -- [性能说明](docs/性能说明.md) -- [高精度历史波形与 Scope 延迟复测](docs/performance-scope-high-precision-20261109.md) -- [架构说明](docs/architecture.md) -- [产品规格](SPEC.md) +- [npm 使用说明](docs/npm-usage.md) +- [使用手册](https://github.com/crysound/CRYChart/blob/main/docs/使用手册.md) +- [性能说明](https://github.com/crysound/CRYChart/blob/main/docs/性能说明.md) +- [架构说明](https://github.com/crysound/CRYChart/blob/main/docs/architecture.md) +- [产品规格](https://github.com/crysound/CRYChart/blob/main/SPEC.md) 示例中的合成数据仅用于演示和测试。继续使用的外部数据、模型和素材保留各自的来源及授权说明。 diff --git a/docs/adr/0001-publish-scoped-public-package.md b/docs/adr/0001-publish-scoped-public-package.md new file mode 100644 index 0000000..126a113 --- /dev/null +++ b/docs/adr/0001-publish-scoped-public-package.md @@ -0,0 +1,5 @@ +# 使用组织作用域发布公开 npm 包 + +2026-11-12 确定以 `@crysound/crychart` 在 npmjs.com 公开分发 CRYChart,首个稳定发行版本为 `1.0.1`,基于已合入 OpenTest 修复的当前 main。组织作用域明确发行归属,替代原有无作用域包名;宿主通过 pnpm 消费精确版本并保留锁文件。 + +保留 CRYChart Community License 1.0 及商业使用条件。公开包只包含运行库、类型声明、中英文许可证、README 和选定的使用文档,历史验证报告及修复记录保留在源码仓库;公开 npm 分发不表示改变许可条件。 diff --git a/docs/delivery.md b/docs/delivery.md index 4759267..0aedde3 100644 --- a/docs/delivery.md +++ b/docs/delivery.md @@ -1,26 +1,39 @@ -# CRYChart 源码与离线包 +# 构建和发布 CRYChart -源码目录为 `D:/workspace/CRYChart`,包版本为 `1.0.0`。当前分支为 `version/v1.0`。构建内容与指纹以对应交付清单为准。 +CRYChart 以公开包 `@crysound/crychart` 分发。首个公开版本 `1.0.1` 的内容与校验值见[发行验收记录](releases/1.0.1.md)。公开包包含 ESM、CommonJS、浏览器脚本、主题模块及完整 TypeScript 声明,保留 CRYChart Community License 1.0。 -## 构建与启动 +## 准备发行包 + +在源码仓库根目录使用已锁定的依赖: ```powershell -cd D:/workspace/CRYChart npm ci npm run typecheck npm test -npm run build -npm run dev +npm run test:opentest-contract +New-Item -ItemType Directory -Force .cache/npm-release +npm pack --pack-destination .cache/npm-release +npm run test:browser +npm run test:gallery ``` -在 Chrome 中访问 `http://127.0.0.1:4178/`。基础示例位于 `/examples/index.html`,完整场景目录位于 `/examples/official/index.html`。端口已占用时,启动前设置 `$env:PORT = '4180'`。 +`prepack` 构建库、示例及类型,并检查运行入口与版本一致性。检查实际归档中的文件,确认 `dist/types/index.d.ts` 和 `dist/types/themes.d.ts` 存在,再从归档安装到独立消费工程,验证 ESM、CommonJS 以及严格 NodeNext、Bundler 类型检查。 + +npm 包仅包含运行库、类型、中英文许可证、README 和 `docs/npm-usage.md`。完整使用手册、历史性能数据、功能报告、OpenTest 合同和修复记录保留在仓库。历史包位于 `version/v1.0/`,其旧版本号与验收结果不代表新发行版。 + +## 公开发布 -包提供 ES 模块、CommonJS、浏览器普通脚本和 TypeScript 类型声明。入口工厂为 `cryChart`,上下文类型为 `CRYChart`,选项类型为 `CRYChartOptions`。 +使用具备 `crysound` 组织发布权限的账号在本机登录。以下示例使用当前源码版本 `1.0.2`。先验收该版本的归档,再发布: -## 验证范围 +```powershell +npm login --registry=https://registry.npmjs.org/ +npm whoami --registry=https://registry.npmjs.org/ +npm publish .cache/npm-release/crysound-crychart-1.0.2.tgz --access public --tag latest --registry=https://registry.npmjs.org/ +npm view @crysound/crychart@1.0.2 version dist.integrity --registry=https://registry.npmjs.org/ +``` -单元测试检查数据、几何、事件和生命周期。浏览器测试使用真实可见 Chrome,检查指定图形与交互。OpenTest 消费合同通过 `npm run test:opentest-contract` 单独检查。该命令不能证明整个应用完成替包或部署。 +按 npm 提示完成本次发布所需的网页认证。发布成功后,对比 registry 的完整性摘要与已验收归档,再从 registry 安装验证。包名与版本一经发布不能复用,内容修正使用新的版本号。 -本地场景目录包含 167 个条目。历史本库检查与当前源码验收分别记录;目录数量不代表当前构建的通过数。详见 [功能清单](functional-verification.json) 和 [HTML 场景表](CRYChart-functional-report.html)。 +若发布返回账号因近期安全敏感操作被临时暂停,先确认是否使用过恢复码登录。[npm 对恢复码登录实施 72 小时只读保护](https://docs.npmjs.com/recovering-your-2fa-enabled-account/),期间登录可以成功,但不能发布、创建访问令牌或调整组织权限。保护期自动结束,重新登录不会提前解除。旧网页认证链接失效时,不重复使用旧链接;恢复发布时重新发起命令并完成其新认证会话。 -离线归档位于 `version/v1.0/`。使用前核对清单中的文件哈希。性能自测的构建、负载和限制见 [性能说明](性能说明.md)。OpenTest 在本次清理中保持只读。 +宿主接入使用 pnpm 精确版本和锁文件,见 [npm 使用说明](npm-usage.md)。源码仓库继续使用现有 npm 锁文件维护构建工具,不改变应用使用 pnpm 安装本库的方式。 diff --git a/docs/npm-usage.md b/docs/npm-usage.md new file mode 100644 index 0000000..f3ff76c --- /dev/null +++ b/docs/npm-usage.md @@ -0,0 +1,31 @@ +# 安装和使用 CRYChart + +在应用目录安装固定版本: + +```powershell +pnpm add --save-exact @crysound/crychart@1.0.1 --registry=https://registry.npmjs.org/ +``` + +ES 模块和 TypeScript 使用相同入口: + +```ts +import { cryChart } from '@crysound/crychart' +import type { CRYChartOptions } from '@crysound/crychart' + +const options: CRYChartOptions = {} +const context = cryChart(options) +const chart = context.ChartXY({ container: document.getElementById('chart')! }) +const line = chart.addLineSeries({ schema: { x: { auto: true }, y: {} } }) +line.appendSamples({ y: new Float32Array([1, 2, 3]) }, { start: 0, step: 1 }) + +// 在页面或组件卸载时调用。 +context.dispose() +``` + +图表容器需要明确的宽度和高度。CommonJS 使用 `require('@crysound/crychart')`。ES 模块主题入口为 `@crysound/crychart/themes`;CommonJS 从主入口取得主题。浏览器普通脚本为 `dist/crychart.global.js`,全局对象仍为 `CRYChart`。 + +从旧 `crychart` 包迁移时,将主入口和主题入口改为上述作用域包名。图表工厂、类型和浏览器全局名称保持不变。提交应用的 `package.json` 和 `pnpm-lock.yaml`,后续安装执行 `pnpm install --frozen-lockfile`。 + +运行包不包含源码、示例工程或历史验收报告。完整说明见[源码仓库使用手册](https://github.com/crysound/CRYChart/blob/main/docs/使用手册.md)。 + +CRYChart 采用 [CRYChart Community License 1.0](../LICENSE.md),并提供[中文版](../LICENSE.zh-CN.md)。商业分发、OEM、设备配套交付及付费托管遵循协议第 7 条。 diff --git a/docs/reference-examples.json b/docs/reference-examples.json index a3c9294..b4358ac 100644 --- a/docs/reference-examples.json +++ b/docs/reference-examples.json @@ -2,7 +2,7 @@ "schemaVersion": 2, "identity": { "name": "CRYChart", - "packageVersion": "1.0.1-opentest.31", + "packageVersion": "1.0.2", "entry": "examples/official/index.html" }, "count": 167, diff --git a/docs/releases/1.0.1.md b/docs/releases/1.0.1.md new file mode 100644 index 0000000..e207b9d --- /dev/null +++ b/docs/releases/1.0.1.md @@ -0,0 +1,33 @@ +# @crysound/crychart 1.0.1 发行验收 + +发行包于 2026-11-12 完成验收,2026-11-16 11:20(北京时间)公开发布到 npm。`latest` 指向 `1.0.1`。从 registry 下载的归档与下列 SHA-256、SRI 和类型声明数量一致。[npm 发行页](https://www.npmjs.com/package/@crysound/crychart/v/1.0.1) + +源码基线为 main 的 `c2ecea01621b0f09f8971fac53097ce0132dae39`,包含 PR #4 的 OpenTest 修复。本次调整包名、发行版本、包内容与发布检查,不改变图表 API。四个运行入口与宿主原 `1.0.1-opentest.30` 包在统一版本字符串、移除 source map 注释后逐字节相同。 + +## 发行内容 + +- 包名与版本:`@crysound/crychart@1.0.1`,公开访问,`latest` 标签。 +- 许可:CRYChart Community License 1.0,保留商业使用条件。 +- 包内共 82 个文件,其中 72 个 `.d.ts`;包含 ESM、CommonJS、浏览器脚本和主题模块。 +- 主入口类型:`dist/types/index.d.ts`;主题类型:`dist/types/themes.d.ts`。 +- 仅包含选定使用文档,历史报告、源码、示例数据及 source map 均未进入 npm 包。 +- 归档:`crysound-crychart-1.0.1.tgz`。 +- SHA-256:`8646a0bb2c1c5aaa9b2662b2164730d3af4b07eff5575a87e7399dab31d411bc`。 +- SRI:`sha512-DVrresNxQW/I+he03LduSNDw125OW61vX+0vvsPtUxhYpACy9CxQmmdZDMrcJ0XWvPH6xp3u5+9t+MpTDZfE0w==`。 + +## 已执行检查 + +- `npm run typecheck` 通过。 +- `npm test`:1221 通过,2 跳过,0 失败。 +- `npm run test:opentest-contract`:31 通过。 +- `npm pack` 的构建及运行入口检查通过,实际归档文件白名单检查通过。 +- 从实际归档安装后的 ESM、CommonJS、主题入口导入通过。 +- TypeScript 5.9.3 严格 NodeNext 和 Bundler 消费检查通过,`skipLibCheck: false`、`types: []`;同时检查 CommonJS 消费类型。 +- `npm run test:browser`:15 项通过,0 页面错误。 +- `npm run test:gallery`:41 个绘制示例、13 项交互通过。 + +本机 Windows、Node.js 24.10.0、esbuild 0.25.12。上述检查不代表宿主真实登录、硬件采集、长时间运行或安装包验收。发布后还需核对 registry 的 SRI,并从 registry 安装验证。 + +本次首次测试发现三个示例数据文件被 `core.autocrlf=true` 转成 CRLF,导致与既有来源摘要不一致。确认 Git 原始字节与原摘要一致后恢复原字节,并用 `.gitattributes` 保持这些文件的字节;未修改摘要或移除检查。 + +OpenTest 的安装和构建方法见宿主仓库的 `docs/crychart-integration.md`。 diff --git "a/docs/\344\275\277\347\224\250\346\211\213\345\206\214.md" "b/docs/\344\275\277\347\224\250\346\211\213\345\206\214.md" index e658740..47759f4 100644 --- "a/docs/\344\275\277\347\224\250\346\211\213\345\206\214.md" +++ "b/docs/\344\275\277\347\224\250\346\211\213\345\206\214.md" @@ -2,7 +2,7 @@ 2026-11-09:OpenTest 的轴右键、悬停高亮和自定义十字游标修复,见[接口说明与验收记录](ui-parity-fixes-20261109.md)。下文较早的 OpenTest 暂停状态保留为历史说明。 -本手册对应 `D:\workspace\CRYChart` 中 `crychart@1.0.0` 的当前源码,工作分支为 `version/v1.0`。当前功能结果和构建指纹见 [功能验收清单](functional-verification.json),逐例说明见 [完整 HTML 报告](CRYChart-functional-report.html)。 +本手册对应 `@crysound/crychart@1.0.1`。功能验证及历史记录保留在源码仓库,不能直接作为本次发行的验收结论。 本手册对应当前 CRYChart 源码。离线包与源码归档位于 [version/v1.0](../version/v1.0/README.md)。使用源码修订时重新构建,构建指纹以对应清单为准。 @@ -34,27 +34,27 @@ npm run dev ## 在应用中引用 -在应用目录安装本地包: +在应用目录安装固定版本: ```powershell -npm install "D:\workspace\CRYChart" +pnpm add --save-exact @crysound/crychart@1.0.1 --registry=https://registry.npmjs.org/ ``` -源码目录应先完成构建。完整交付目录包含源码、示例、测试、脚本和选定证据。npm 安装包是运行包,包含发行文件、类型声明和文档。安装包不包含源码工具与证据目录。构建及示例启动命令应在完整交付目录执行,文档中的相对 codex_artifact 链接也以该目录为准。 +从 npm 安装时无需在应用中编译图表库。完整源码仓库包含示例、测试、脚本和验证记录。npm 运行包只包含发行文件、类型声明、许可证和选定使用文档。构建及示例启动命令应在完整交付目录执行,文档中的相对 codex_artifact 链接也以该目录为准。 包提供以下入口: | 使用环境 | 入口 | | --- | --- | -| ES 模块 | `import { cryChart } from 'crychart'` | -| CommonJS | `const { cryChart } = require('crychart')` | +| ES 模块 | `import { cryChart } from '@crysound/crychart'` | +| CommonJS | `const { cryChart } = require('@crysound/crychart')` | | 浏览器普通脚本 | `dist/crychart.global.js`,全局对象 `CRYChart` | | 类型声明 | `dist/types/index.d.ts` | -| 主题子路径(仅 ES 模块) | `import { makeCustomTheme, Themes } from 'crychart/themes'` | +| 主题子路径(仅 ES 模块) | `import { makeCustomTheme, Themes } from '@crysound/crychart/themes'` | -CommonJS 使用方可从主入口获取主题:`const { makeCustomTheme, Themes } = require('crychart')`;不要对 `crychart/themes` 使用 require。 +CommonJS 使用方可从主入口获取主题:`const { makeCustomTheme, Themes } = require('@crysound/crychart')`;不要对 `@crysound/crychart/themes` 使用 require。 -当前包名不表示已经发布到 npm。使用 `cryChart` 创建 CRYChart 上下文。旧工厂和类型名称已移除;公开上下文类型为 `CRYChart`,选项类型为 `CRYChartOptions`。 +公开包的安装和版本信息以 npmjs.com 上的实际发布记录为准。使用 `cryChart` 创建 CRYChart 上下文。旧工厂和类型名称已移除;公开上下文类型为 `CRYChart`,选项类型为 `CRYChartOptions`。 ## 创建第一个图表 @@ -133,7 +133,7 @@ chart.getDefaultAxisX().setInterval({ start: 90, end: 100 }) 多个系列可共享 `DataSetXY`。销毁系列不会销毁外部数据集。 ```ts -import { DataSetXY } from 'crychart' +import { DataSetXY } from '@crysound/crychart' const data = new DataSetXY({ schema: { @@ -184,7 +184,7 @@ console.log(data.getStorageStats()) ## 坐标轴和交互 ```ts -import { AutoCursorModes } from 'crychart' +import { AutoCursorModes } from '@crysound/crychart' chart.getDefaultAxisX().setInterval({ start: 0, end: 10 }) chart.getDefaultAxisY().setInterval({ start: -2, end: 2 }) chart.setAutoCursorMode(AutoCursorModes.disabled) @@ -274,7 +274,7 @@ chart.getCursor().setVisible(false) 通过 CRYChart 格式化接口配置显示精度。`toFixed(3)` 表示固定 3 位小数;`toPrecision(6)` 表示 6 位有效数字;`toExponential(3)` 表示科学计数法的小数部分保留 3 位。这些函数只生成显示文本,不修改数据集中的数值。 ```ts -import { AxisTickStrategies } from 'crychart' +import { AxisTickStrategies } from '@crysound/crychart' const axisY = chart.getDefaultAxisY() axisY.setTickStrategy(AxisTickStrategies.Numeric, ticks => @@ -363,7 +363,7 @@ Polar与已覆盖的XY、3D、几何系列支持 `series.setHighlight(true)` 和 ```tsx import { useEffect, useRef } from 'react' -import { cryChart } from 'crychart' +import { cryChart } from '@crysound/crychart' export function SignalChart() { const host = useRef(null) @@ -388,7 +388,7 @@ export function SignalChart() { ```vue