Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -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
11 changes: 11 additions & 0 deletions CONTEXT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# CRYChart 术语

本术语表区分图表库、库发行版和消费该库的应用。

## 术语

**CRYChart**:CRYSOUND 为 OpenTest 数据可视化场景提供的前端图表渲染库。
_Avoid_:OpenTest 宿主、业务插件

**CRYChart 官方发行版**:以 `@crysound/crychart` 标识、由 CRYSOUND 维护的版本化库发行内容,采用 CRYChart Community License 1.0。其版本与 OpenTest 产品版本分别维护。
_Avoid_:OpenTest 产品版本、OpenTest 消费者修订包
26 changes: 17 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -23,8 +31,8 @@ Open the local examples at <http://127.0.0.1:4178/>. 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)
Expand All @@ -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

Expand All @@ -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.

Expand Down
26 changes: 17 additions & 9 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)。

## 安装与构建

Expand All @@ -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)
Expand All @@ -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`。

## 验证

Expand All @@ -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)

示例中的合成数据仅用于演示和测试。继续使用的外部数据、模型和素材保留各自的来源及授权说明。
5 changes: 5 additions & 0 deletions docs/adr/0001-publish-scoped-public-package.md
Original file line number Diff line number Diff line change
@@ -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 分发不表示改变许可条件。
37 changes: 25 additions & 12 deletions docs/delivery.md
Original file line number Diff line number Diff line change
@@ -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 安装本库的方式。
31 changes: 31 additions & 0 deletions docs/npm-usage.md
Original file line number Diff line number Diff line change
@@ -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 条。
2 changes: 1 addition & 1 deletion docs/reference-examples.json
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
33 changes: 33 additions & 0 deletions docs/releases/1.0.1.md
Original file line number Diff line number Diff line change
@@ -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`。
Loading
Loading