Skip to content
Back to search

pts

A library for visualization and creative-coding

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/williamngan/pts with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/williamngan/pts'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/williamngan--pts/badge.svg)](/listings/williamngan--pts)

HTML

<a href="/listings/williamngan--pts"><img src="/api/listings/williamngan--pts/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 226 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: pts
  3. description: Use the Pts library (pts on npm) to build canvas/SVG visualizations, generative art, and interactive sketches in TypeScript or JavaScript.
  4. ---
  5. # Using Pts
  6. Pts is a TypeScript/JavaScript library for visualization and creative
  7. coding. Mental model: **Space** is the paper (a canvas or SVG), **Form** is the pencil (the drawing API), and **Pt/Group** are
  8. the ideas (points/vectors/matrices every operation consumes and produces).
  9. ## Setup
  10. ```js
  11. import { CanvasSpace, Pt, Group, Line, Circle, Num } from "pts"; // ESM (also has CJS entry)
  12. ```
  13. Browser script (no bundler — prefer this in sandboxed pages):
  14. ```html
  15. <div id="pt"></div>
  16. <script src="https://unpkg.com/pts/dist/pts.min.js"></script>
  17. <script>
  18. // quickStart puts all Pts classes plus `space` and `form` on globalThis,
  19. // and returns a run() helper. If #pt is an <svg> (or has one as a direct
  20. // child), it renders SVG; otherwise canvas — same sketch code either way.
  21. var run = Pts.quickStart("#pt", "#fe3");
  22. run((time, ftime) => {
  23. var pts = Create.distributeRandom(space.innerBound, 50);
  24. form.fillOnly("#123").points(pts, 2, "circle");
  25. form.strokeOnly("#f03", 2).line([space.center, space.pointer]);
  26. });
  27. </script>
  28. ```
  29. `run(animate, start?, action?, resize?)` wires the callbacks, binds
  30. mouse/touch, and starts playing.
  31. ## Minimal sketch
  32. ```js
  33. const space = new CanvasSpace("#container").setup({
  34. bgcolor: "#fff",
  35. retina: true,
  36. resize: true,
  37. });
  38. const form = space.getForm();
  39. space.add((time, ftime) => {
  40. // this runs every frame: compute Pts, then draw them with form
  41. const pts = Create.distributeRandom(space.innerBound, 100);
  42. form.fillOnly("#123").points(pts, 3, "circle");
  43. });
  44. space.bindMouse().bindTouch().play();
  45. ```
  46. A player can also be an object: `space.add({ start, animate, action, resize })`.
  47. `animate(time, ftime, space)` draws each frame; `action(type, px, py, evt)`
  48. receives pointer/touch/keyboard events; `space.pointer` always has the
  49. current pointer position. Call `space.dispose()` when unmounting (safe in
  50. React StrictMode; listeners and frames are fully cleaned up).
  51. ## Packages
  52. Core data and math:
  53. - `Pt`, `Group`, `Bound` — a Pt subclasses Float32Array; a Group
  54. subclasses Array<Pt>; Bound is a Group with size/center accessors.
  55. - `Num`, `Geom`, `Shaping`, `Range` — numbers, angles, easing curves,
  56. and mapping a dataset's domain onto a drawing area.
  57. - `Line`, `Rectangle`, `Circle`, `Triangle`, `Polygon`, `Curve` —
  58. geometry as static functions that take Groups: intersections,
  59. hit-tests, subdivisions, convex hulls, and curves (Catmull-Rom,
  60. cardinal, B-spline, bezier) from control points, `cardinalToBezier` /
  61. `bsplineToBezier` to draw them as native paths with `form.bezier`, and
  62. `bezierToCardinal` / `bezierToBspline` back.
  63. - `Path` — polygon boolean operations:
  64. `unite`, `intersect`, `exclude`, `minusFront`, `minusBack` return the
  65. rings of one polygon with holes (draw with `form.compound(rings)`);
  66. `divide` and `crop` return one such polygon per face. Shapes are listed
  67. back to front; a result can be passed back as one shape.
  68. - `Vec`, `Mat` — the lower-level vector/matrix helpers behind Pt ops.
  69. Generators and media:
  70. - `Create` — point generators: `distributeRandom`, `gridPts`/`gridCells`,
  71. `radialPts`, plus `noisePts` for Perlin noise fields
  72. (each Pt gets a `noise2D()` you can step per frame).
  73. - `Create.sampling(bound, radius)` — evenly spaced random points (blue
  74. noise), never closer than `radius`. For a set that grows over frames, use
  75. `new PoissonDisk().setup(bound, radius)` with `.sample(n)` or `.step()`.
  76. - `Create.delaunay(group)` — Delaunay triangulation: call `.delaunay()`
  77. for triangles, `.voronoi()` for the dual Voronoi cells, `.mesh()` for
  78. the neighbor structure. Good for organic cell patterns from any point
  79. set.
  80. - `Color` — color as a Pt subclass, in rgb/hsl/hsb/lab/lch/luv/xyz/
  81. oklab/oklch modes with conversions between them (`toMode("oklch")`)
  82. and hex/css output. Oklab/Oklch give perceptually-even gradients.
  83. - `Physics` — a small verlet engine: `World` holds `Particle`s (points
  84. with mass/impulse) and `Body`s (particles linked by constraints into
  85. soft shapes), with gravity, friction, and particle/body collisions.
  86. Call `world.update(ftime)` each frame and draw the results yourself.
  87. - `Sound` — audio in three ways: `Sound.load(url)` for files,
  88. `Sound.generate(type, freq)` for oscillators, `Sound.input()` for the
  89. microphone (Promise). Attach `analyze(size)` and read
  90. `freqDomainTo(area)` / `timeDomainTo(area)` as Groups — mapping sound
  91. to drawable points is one line.
  92. - `Tempo` — beat-based animation instead of milliseconds:
  93. `new Tempo(120)`, `space.add(tempo)`, then `tempo.every(4).start(fn)`
  94. fires on the beat and `.progress(fn)` gives a 0→1 `t` within each
  95. period. Keeps animation in musical time.
  96. - `Img` — image loading and pixel access: `Img.load(url)` (Promise),
  97. `Img.blank(size)`, read `pixel(pt)`, `crop(bound)`, resize, and use an
  98. image as a canvas fill pattern. Editable Imgs are backed by their own
  99. canvas.
  100. - `Typography` — text fitting helpers (`textWidthEstimator`,
  101. `fontSizeToBox`) used with `form.textBox` / `paragraphBox` for
  102. truncation and alignment inside shapes.
  103. - `UI`, `UIButton`, `UIDragger` — hit-tested interactive elements
  104. (rectangle/circle/polygon/line/polyline, or custom via
  105. `UI.registerShape`); register with `space.track(ui)`.
  106. References: full API at https://ptsjs.org/docs.md (single markdown
  107. file, agent-friendly); guides + demo catalog at https://ptsjs.org/guide.md;
  108. source at https://github.com/williamngan/pts. The repo's `demo/` folder
  109. has 80 runnable single-file examples, each named after the API it
  110. demonstrates (eg, `circle.intersectCircle2D.js`, `create.delaunay.js`,
  111. `sound.freqDomain.js`) — read one before writing a sketch in an
  112. unfamiliar area.
  113. ## Conventions that matter
  114. - **Mutating vs `$`-prefixed**: `p.add(q)` mutates and returns `this`;
  115. `p.$add(q)` returns a new Pt. Same for `$subtract`, `$multiply`, etc.
  116. Geometry statics (`Line.*`, `Circle.*`) return new objects.
  117. - **Everything accepts loose point data** (`PtLike` = Pt | Float32Array |
  118. number[]; iterables of these for groups): `form.point([50, 50], 10)` works.
  119. - **Pt is Float32**: ~7 significant digits. Don't expect double precision;
  120. compare with `p.equals(q, threshold)` or `Num.equals`.
  121. - **`new Pt(3)` is a length-3 zero Pt** (TypedArray semantics), not the
  122. value 3. Use `new Pt([3])` for a 1-D value.
  123. - **Chaining is idiomatic**: `form.strokeOnly("#f03", 2).line(ln)`;
  124. `space.bindMouse().bindTouch().play()`.
  125. - **"No result" is expressed as `undefined`, not an error.** Functions
  126. that compute something that may not exist return the value when it
  127. exists and `undefined` when it doesn't — so check before using the
  128. result. Examples: `Line.intersectLine2D(a, b)` returns the
  129. intersection Pt, or `undefined` when the segments don't cross;
  130. `Triangle.circumcircle` returns `undefined` for collinear points;
  131. `Line.slope` for a vertical line; `Bound.z` on a 2-D bound.
  132. `const hit = Line.intersectLine2D(a, b); if (hit) form.point(hit);`
  133. - `Pt.angleBetween` returns a normalized signed angle in [−π, π).
  134. - `Group.segments`/`lines`/`split` return real `Group`s; iterate or index
  135. them like arrays.
  136. ## Reproducibility
  137. `Num.seed("any string")` makes `Num.random()` (and everything built on
  138. it: `randomRange`, `randomPt`, `Create.distributeRandom`, noise seeding)
  139. deterministic. Sequences are stable across versions (pinned by tests).
  140. Seeds are hashed by _effective_ key — surrounding whitespace and control
  141. characters are stripped. Perlin noise follows the same rule:
  142. `Create.noisePts` takes no seed parameter — it seeds itself from
  143. `Num.random()`, so call `Num.seed(...)` beforehand for a deterministic
  144. field. Individual `Noise` points can also be reseeded with
  145. `noise.seed(n)`.
  146. ## Rendering targets
  147. - `CanvasSpace` is the default. `setup({ retina: true, resize: true })`
  148. for crisp, responsive output; `offscreen: true` for a second buffer.
  149. - `SVGSpace` mirrors the full `CanvasForm` drawing API and reconciles
  150. DOM elements per frame — use it for DOM output (`HTMLSpace` is
  151. deprecated). To build a custom renderer, implement the documented
  152. context contract (`SVGContext2D` is the reference).
  153. - Text: `form.textBox`, `form.paragraphBox`, `form.alignText` with
  154. `Typography` helpers for fitting.
  155. ## Interaction
  156. For simple cases, read `space.pointer` in `animate`. For hit-tested
  157. elements use UI:
  158. ```js
  159. const btn = new UIButton([[20, 20], [120, 60]], UIShape.rectangle);
  160. btn.onClick((target, pt, type, evt) => { ... });
  161. space.track(btn); // forwards this space's events to it; untrack to remove
  162. ```
  163. (The `UI.fromRectangle`/`fromCircle`/`fromPolygon` factories also work
  164. but are typed as returning `UI`, so in TypeScript prefer the constructor
  165. for subclasses.) Handler `evt` may be mouse, touch, pointer, or
  166. keyboard. `on()` supports `{ once, signal }`. Custom shapes:
  167. `UI.registerShape(name, testFn)`. For rhythm-driven animation, create
  168. `new Tempo(120)` (bpm), `space.add(tempo)`, then
  169. `tempo.every(2).start(fn)` / `.progress(fn)`.
  170. ## Working on this repository
  171. - Plan-first workflow: significant changes get a plan in `plans/*.md`
  172. (review one for the house style: verified findings → pinned tests →
  173. fixes → benchmark A/B → results).
  174. - Check chain: `pnpm typecheck && pnpm lint && pnpm test && pnpm build`,
  175. then `pnpm check:artifacts` (byte-exact size ceilings on dist —
  176. regenerate budgets when dist legitimately changes), `pnpm check:docs`
  177. (docs must be regenerated via `pnpm run docs` after signature/doc
  178. edits), `pnpm format:check`.
  179. - Benchmarks: `node --expose-gc scripts/bench.mjs --against HEAD --suite <name>`
  180. is the authoritative perf gate; cross-session `--compare` drifts ±8%.
  181. - TypeScript is strict; keep fixes type-level unless behavior change is
  182. intended and pinned. Do not add `verbatimModuleSyntax` to tsconfig
  183. (tsdown reads it and the bundle changes — see comment there).
  184. - Tests: vitest projects `node`, `browser` (Playwright Chromium),
  185. `visual` (PNG baselines; update with `pnpm test:visual:update`).
  186. Type-level pins live in `src/test/Types.test-d.ts`.
  187. # Ecosystem
  188. - `react-pts-canvas` (separate repository) wraps a Pts space in a React
  189. component; it is published on npm and documented at react.ptsjs.org.
  190. - `pts-render` is the Pts CLI, published on npm and documented at
  191. cli.ptsjs.org; it renders sketches from the terminal without a browser.
  192. The Ecosystem guide (`guide/md/_8000_Ecosystem.md`) is the source of truth
  193. for both.
README.md · README · 92 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Pts
  2. ![Pts examples](https://raw.githubusercontent.com/williamngan/pts/master/assets/pts-gif-10.gif)
  3. Pts is a TypeScript and JavaScript library for visualization and creative coding.
  4. **Get started at [ptsjs.org](https://ptsjs.org).** Please try it, [file issues](https://github.com/williamngan/pts/issues), and send feedback to [@williamngan](https://twitter.com/williamngan).
  5. ## Usage
  6. ### Browser script
  7. Download `pts.js` or `pts.min.js` from the [dist directory](https://github.com/williamngan/pts/tree/master/dist), or use a CDN such as [cdnjs](https://cdnjs.com/libraries/pts), [jsDelivr](https://cdn.jsdelivr.net/npm/pts/dist/pts.min.js), or [unpkg](https://unpkg.com/pts/dist/pts.min.js).
  8. ```html
  9. <script src="path/to/pts.min.js"></script>
  10. ```
  11. The classic script exposes the library as `globalThis.Pts`.
  12. ### Package
  13. Install the package:
  14. ```bash
  15. npm install pts
  16. ```
  17. Pts is ESM-first and also provides a CommonJS compatibility entry.
  18. ```js
  19. import { CanvasSpace, Group, Line, Pt } from "pts";
  20. ```
  21. ```js
  22. const { CanvasSpace, Group, Line, Pt } = require("pts");
  23. ```
  24. Starter projects and integrations:
  25. - [pts-starter-kit](https://github.com/williamngan/pts-starter-kit)
  26. - [pts-react-example](https://github.com/williamngan/pts-react-example)
  27. - [react-pts-canvas](https://www.npmjs.com/package/react-pts-canvas)
  28. Read the [guides](https://ptsjs.org/guide/Get-started-0100.html) and explore the [demos](https://ptsjs.org/demo/?name=circle.intersectCircle2D).
  29. ## Development
  30. The maintained build environment is Node 24.18 or newer in the Node 24 line. The published library is also exercised on current Node 20 and 22 releases.
  31. ```bash
  32. pnpm install --frozen-lockfile
  33. pnpm exec playwright install chromium
  34. pnpm check
  35. ```
  36. Useful individual commands include:
  37. ```bash
  38. pnpm build
  39. pnpm typecheck
  40. pnpm test
  41. pnpm test:browser
  42. pnpm test:integrations
  43. pnpm check:package
  44. pnpm format
  45. pnpm format:watch
  46. ```
  47. `pnpm check` validates formatting, linting, types, unit tests, deterministic documentation, documentation and bundle behavior in a real browser, reproducible artifacts, the packed package, ESM and CommonJS resolution, declarations, and tree-shaking. Its packed-package integration suite also builds and runs the maintained React, Vue, `skia-canvas`, and single-file vanilla fixtures in [`test/integrations`](./test/integrations).
  48. Prettier defines the repository's formatting rules. Run `pnpm format` once or keep `pnpm format:watch` running to reformat maintained source files as they change. The recommended VS Code extension and workspace settings also enable Prettier on save, while `pnpm check` rejects unformatted changes in CI.
  49. ### Generate documentation
  50. The documentation generator uses TypeDoc's Node API to rebuild the custom static documentation JSON from explicit source entry points. It also generates [`docs.md`](./docs.md), [`guide.md`](./guide.md), and [`llms.txt`](./llms.txt) for agents and other clients that cannot navigate the documentation SPA:
  51. ```bash
  52. pnpm run docs
  53. ```
  54. Generated documentation is checked in. `pnpm check:docs` regenerates it in memory, reports stale or extra files, and exercises navigation, search, anchors, and responsive layouts in Chromium.
  55. ## Contributing
  56. Issues and small pull requests are welcome. For larger changes, please start a discussion with [@williamngan](https://twitter.com/williamngan).
  57. ## License
  58. Apache License 2.0. See [LICENSE](./LICENSE).
  59. Copyright © 2017-present William Ngan and contributors.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.