pts 0.12.9 → 1.0.0

package/README.md

@@ -1,80 +1,92 @@
-# Pts
-
-![image](./assets/pts-gif-10.gif)   
-
-Pts is a typescript/javascript library for visualization and creative-coding. 
-
-**Get started at [ptsjs.org](https://ptsjs.org)**.
-
-Please give it a try, [file issues](https://github.com/williamngan/pts/issues), and send feedbacks to [@williamngan](https://twitter.com/williamngan). Thank you!
-
----    
-
-### Usage
-
-**Option 1**   
-Get the latest `pts.js` or `pts.min.js` (in [dist](https://github.com/williamngan/pts/tree/master/dist) folder). Alternatively use a CDN service like [cdnjs](https://cdnjs.com/libraries/pts) or [jsdelivr](https://cdn.jsdelivr.net/gh/williamngan/pts/dist/pts.min.js) or [unpkg](https://unpkg.com/pts/dist/pts.min.js). Then add it to your html page like this:
-```html
-<script type="text/javascript" src="path/to/pts.js"></script>
-```
-Pts is pretty lightweight. Currently at ~100kb minified and 30kb gzipped.
-
-
-**Option 2:**   
-Install via `npm install pts`. Then you can choose to import some parts of Pts into your project as needed. 
-```js
-import {CanvasSpace, Pt, Group, Line} from 'pts';
-```
-
-To quickly get started, try download or clone these repos:
-- [pts-starter-kit](https://github.com/williamngan/pts-starter-kit): Get started with a sample app using npm and webpack
-- [pts-react-example](https://github.com/williamngan/pts-react-example): Try an example of using Pts with React.
-- [react-pts-canvas](https://www.npmjs.com/package/react-pts-canvas): Use it in your React project by extending react-pts-canvas component
-
-**Get Started**   
-Read the [guides](https://ptsjs.org/guide/get-started-0100) and take a look at the [demos](https://ptsjs.org/demo/?name=circle.intersectCircle2D) and their source code.    
-If you need help, please don't hesitate to [file an issue](https://github.com/williamngan/pts/issues).
-
----    
-
-### For development
-
-Pts is written in typescript. You can clone or fork this project and build it as follows:
-
-#### Build and test
-
-Clone this repo and install dependencies via `npm install`.
-
-```bash
-npm start
-npm run build
-npm test
-```
-
-#### Generate documentations
-Run this to generate Pts styled documentations. (Requires python 3.6)
-```bash
-npm run docs 
-```
-
-If you prefer to generate default typedocs, run this:
-```bash
-typedoc --readme none --out typedocs src --name Pts
-```
-
----
-
-### Contributing
-
-We appreciate your support and feedbacks!
-
-Please file issues if you find bugs and have feature requests. If you are able to send small PRs to improve Pts or fix bugs, that would be awesome too. 
-
-For larger PRs, please ping [@williamngan](https://twitter.com/williamngan) to discuss first.
-
----    
-
-### License
-Apache License 2.0. See LICENSE file for details.   
-Copyright © 2017-today by William Ngan and contributors.
-
+# Pts
+
+![Pts examples](https://raw.githubusercontent.com/williamngan/pts/master/assets/pts-gif-10.gif)
+
+Pts is a TypeScript and JavaScript library for visualization and creative coding.
+
+**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).
+
+## Usage
+
+### Browser script
+
+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).
+
+```html
+<script src="path/to/pts.min.js"></script>
+```
+
+The classic script exposes the library as `globalThis.Pts`.
+
+### Package
+
+Install the package:
+
+```bash
+npm install pts
+```
+
+Pts is ESM-first and also provides a CommonJS compatibility entry.
+
+```js
+import { CanvasSpace, Group, Line, Pt } from "pts";
+```
+
+```js
+const { CanvasSpace, Group, Line, Pt } = require("pts");
+```
+
+Starter projects and integrations:
+
+- [pts-starter-kit](https://github.com/williamngan/pts-starter-kit)
+- [pts-react-example](https://github.com/williamngan/pts-react-example)
+- [react-pts-canvas](https://www.npmjs.com/package/react-pts-canvas)
+
+Read the [guides](https://ptsjs.org/guide/Get-started-0100.html) and explore the [demos](https://ptsjs.org/demo/?name=circle.intersectCircle2D).
+
+## Development
+
+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.
+
+```bash
+pnpm install --frozen-lockfile
+pnpm exec playwright install chromium
+pnpm check
+```
+
+Useful individual commands include:
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm test:browser
+pnpm test:integrations
+pnpm check:package
+pnpm format
+pnpm format:watch
+```
+
+`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).
+
+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.
+
+### Generate documentation
+
+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:
+
+```bash
+pnpm run docs
+```
+
+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.
+
+## Contributing
+
+Issues and small pull requests are welcome. For larger changes, please start a discussion with [@williamngan](https://twitter.com/williamngan).
+
+## License
+
+Apache License 2.0. See [LICENSE](./LICENSE).
+
+Copyright © 2017-present William Ngan and contributors.