# pathkit-ts

TypeScript 1:1 移植版 [pathkit](https://github.com/google/skia/tree/main/modules/pathkit)（Skia Path API）——纯 TS 实现，无 WASM、无原生依赖，可在 Node / 浏览器任意环境直接运行。

[src/index.ts](src/index.ts) 作为库入口，导出完整的 Skia 路径 API：路径构建、描边、测量、路径布尔运算、Dash/圆角特效及全部基础几何类型。

## 特性

- **1:1 移植**：逐行对照 Skia C++ 源码（`SkPath`、`SkStroke`、`SkPathMeasure`、pathops 引擎等）移植，行为与 Skia 一致
- **Tree-Shaking**：`sideEffects: false` + 按模块编译，打包时自动剔除未用代码
- **零依赖**：纯 TypeScript，无 WASM / 无原生绑定，`node --test` 即可跑 88 个回归测试
- **双入口**：单文件 bundle（ES / UMD）+ 逐模块 ESM 产物（支持子路径导入）
- **类型完备**：随包发布完整 `.d.ts` 声明

## 安装

```bash
npm install pathkit-ts
```

## 快速上手

### ESM 子路径导入（推荐，模块级 Tree-Shaking）

只打包用到的模块及其依赖，体积最小：

```ts
import { SkPath } from "pathkit-ts/core/SkPath";
import { SkRect } from "pathkit-ts/core/SkRect";
import { SkPoint } from "pathkit-ts/core/SkPoint";
import { SkStroke } from "pathkit-ts/core/SkStroke";
import { SkPaint } from "pathkit-ts/core/SkPaint";

// 构建路径
const path = new SkPath();
path.moveTo(0, 0);
path.lineTo(100, 0);
path.lineTo(100, 100);
path.close();

path.contains(50, 50);                     // true
path.getBounds();                          // {fLeft:0, fTop:0, fRight:100, fBottom:100}

// 描边（Skia stroker 输出闭合轮廓）
const stroker = new SkStroke();
stroker.setWidth(4);
stroker.setCap(SkPaint.kRound_Cap);
stroker.setJoin(SkPaint.kRound_Join);
const stroked = new SkPath();
stroker.strokePath(path, stroked);
```

### 根入口（单文件 bundle）

```ts
import { SkPath, SkRect, SkPathOp, Op } from "pathkit-ts";

const a = new SkPath();
a.addRect(SkRect.MakeLTRB(0, 0, 60, 60));
const b = new SkPath();
b.addRect(SkRect.MakeLTRB(40, 40, 100, 100));

const union = new SkPath();
Op(a, b, SkPathOp.kUnion_SkPathOp, union); // true
```

### UMD（`<script>` 全局或 CommonJS）

```html
<script src="./node_modules/pathkit-ts/dist/pathkit-ts.umd.cjs"></script>
<script>
  const p = new pathkit.SkPath();
  p.addRect({ fLeft: 0, fTop: 0, fRight: 100, fBottom: 100 });
  p.contains(50, 50); // true
</script>
```

```js
// CommonJS
const { SkPath } = require("pathkit-ts");
```

## 构建

```bash
npm run build          # 完整构建：单文件 bundle（ES+UMD）+ 逐模块 ESM + 类型声明
npm run build:lib      # 仅单文件 bundle：dist/pathkit-ts.js（ES）+ dist/pathkit-ts.umd.cjs（UMD）
npm run build:es       # 仅逐模块 ESM：dist/es/**（src 目录结构逐一编译）
npm run build:types    # 仅类型声明：dist/types/**
npm run dev            # 启动示例 dev server（Vite）
npm run build:examples # 构建静态示例（dist-examples/）
npm test               # 运行 88 个回归测试（node --test）
```

### 产物结构

```
dist/
├── pathkit-ts.js        # ES bundle（根入口 "import"）
├── pathkit-ts.umd.cjs   # UMD bundle（根入口 "require" / 浏览器全局 pathkit）
├── es/                  # 逐模块 ESM（支持子路径导入 + 模块级 Tree-Shaking）
│   ├── index.js
│   ├── core/  effects/  pathops/  private/  utils/
└── types/               # 与 es/ 对应的 .d.ts 声明
```

`package.json` 的 `exports` 已配置子路径映射：

```ts
import { SkPath } from "pathkit-ts/core/SkPath";          // → dist/es/core/SkPath.js
import { Op } from "pathkit-ts/pathops/SkPathOpsOp";      // → dist/es/pathops/SkPathOpsOp.js
import { SkDashPathEffect } from "pathkit-ts/effects/SkDashPathEffect";
```

## API 总览

| 分类 | 导出 |
| --- | --- |
| 路径 | `SkPath`（moveTo/lineTo/quadTo/conicTo/cubicTo/arcTo、addRect/addOval/addCircle/addRoundRect/addPoly、contains/getBounds/setFillType…）、`SkPathBuilder`（链式 API、offset、detach/snapshot） |
| 描边 | `SkStroke`（setWidth/setCap/setJoin/setMiterLimit、strokePath）、`SkStrokeRec`、`SkPaint`（cap/join 常量） |
| 测量 | `SkPathMeasure`（getLength/getPosTan）、`SkContourMeasure` |
| 特效 | `SkDashPathEffect.Make(intervals, count, phase)`、`SkCornerPathEffect.Make(radius)`、`SkPathEffect` |
| 路径运算 | `SkOpBuilder`（add/resolve）、`Op(one, two, op, result)`、`Simplify`、`AsWinding` |
| 几何 | `SkRect`、`SkRRect`、`SkPoint`、`SkPoint3`、`SkMatrix` |
| 枚举/常量 | `SkPathFillType`（kWinding/kEvenOdd）、`SkPathDirection`（kCW/kCCW）、`SkPathOp`（kUnion/kIntersect/kDifference/kXOR/kReverseDifference）、`SkPathVerb`、`SkPathSegmentMask`、`kMove_Verb` 等 |

## 示例

`examples/` 目录下有可直接运行的 Vite 演示：

| 示例 | 说明 |
| --- | --- |
| [path](examples/path/index.html) | SkPath 底层 verb、addRect/addOval、contains、迭代 |
| [path-builder](examples/path-builder/index.html) | 链式 SkPathBuilder、offset、detach |
| [path-stroke](examples/path-stroke/index.html) | 描边宽度、cap、join、miter limit |
| [path-dash](examples/path-dash/index.html) | 虚线间隔、phase、cap/join |
| [pathops](examples/pathops/index.html) | Union / Intersect / Difference / XOR |
| [path2d-cmp](examples/path2d-cmp/index.html) | 与原生 canvas `Path2D` 逐项对比，lil-gui 调参 |

## 移植保真度

- `SkPath.contains()` 与高精度扁平化绕数计算对照验证
- 虚线渲染与原生 Chrome canvas 逐像素对比（144 组配置全部一致）
- 描边、conic 弧线在 `path2d-cmp` 示例中与原生 `Path2D` 并排目视对比
- 88 个回归测试覆盖 path / builder / stroke / ops 全部模块

## 致谢

Google [Skia](https://skia.org/) 的 [pathkit](https://github.com/google/skia/tree/main/modules/pathkit) 项目——本库是它的 TypeScript 移植。
