kei-lisp-plugin-graphics 3.0.0 → 4.0.0

package/README.md

@@ -21,8 +21,11 @@ interpreter. Register it on a `LispInterpreter` and call drawing primitives
 
 ![Shapes and text drawn from Lisp source with kei-lisp-plugin-graphics](./docs/assets/basic-drawing.png)
 
-_The canvas above is painted entirely from Lisp source — try it in the
-[**live demo**](https://ike-keichan.github.io/kei-lisp-plugin-graphics/)._
+_The canvas above is painted entirely from Lisp source. You can see this
+program rendered in the
+[**example page**](https://ike-keichan.github.io/kei-lisp-plugin-graphics/).
+To write and run kei-lisp yourself, use
+[**kei-lisp-web**](https://ike-keichan.github.io/kei-lisp-web/)._
 
 ## Features
 
@@ -34,11 +37,18 @@ _The canvas above is painted entirely from Lisp source — try it in the
 ## Installation
 
 ```sh
+# npm
+npm install kei-lisp-plugin-graphics kei-lisp
+
+# yarn
+yarn add kei-lisp-plugin-graphics kei-lisp
+
+# pnpm
 pnpm add kei-lisp-plugin-graphics kei-lisp
-# or: npm install kei-lisp-plugin-graphics kei-lisp
 ```
 
 `kei-lisp` is a **peer dependency**; install both into your project. Requires
+**kei-lisp >= 3.0.1** (for kei-lisp 2.x use kei-lisp-plugin-graphics 3.x) and
 **Node.js >= 24** for the build toolchain (the plugin itself targets any
 environment that exposes a `CanvasRenderingContext2D`).
 
@@ -60,7 +70,7 @@ interpreter.evalString(`
   (gstroke-color "black")
   (gline-width 2)
   (gstroke-rect 10 10 120 80)
-  (gclose)
+  (gclose) ; note: gclose clears the canvas — omit it to keep the drawing visible
 `);
 ```
 
@@ -69,11 +79,9 @@ interpreter.evalString(`
 ## API
 
 ```ts
-import type { KeiLispPlugin } from 'kei-lisp';
-
 export function createGraphicsPlugin(options: {
   canvas: HTMLCanvasElement | OffscreenCanvas;
-}): KeiLispPlugin;
+}): GraphicsPlugin;
 ```
 
 The returned plugin implements the [`KeiLispPlugin`](https://github.com/ike-keichan/kei-lisp/blob/main/docs/plugins.md)
@@ -94,25 +102,47 @@ canvas's 2D rendering context.
 | State          | `gsave`, `grestore`                                                                                                                                                                                                                                                 |
 | Image / export | `gimage`, `gsave-png`, `gsave-jpeg`, `gclear-rect`, `gpixel`, `gset-pixel`                                                                                                                                                                                          |
 
-Each function returns `t` on success. See [`docs/graphics.md`](./docs/graphics.md)
-for argument signatures and side effects.
+Each function returns `t` on success; failures signal an evaluation error
+that Lisp code can intercept with `(handler-case … (eval-error (e) …))`.
+See [`docs/graphics.md`](./docs/graphics.md) for argument signatures and
+side effects.
+
+## Bundled Lisp patterns
+
+The package ships loadable `.lisp` pattern files under `lisp/` — a grid
+helper (`ggrid`), color-palette helpers (`gpalette` / `gpalette-color`),
+and a frame-loop helper (`ganimate`):
+
+```lisp
+(load "node_modules/kei-lisp-plugin-graphics/lisp/grid.lisp")
+(gopen)
+(ggrid 40)
+```
+
+`load` reads from the filesystem (Node.js); browser hosts can fetch the
+file's text and evaluate it instead. See
+[`docs/patterns.md`](./docs/patterns.md) for the full list.
 
 ## Environment support
 
-| Capability                            | Browser (`HTMLCanvasElement`)                            | `OffscreenCanvas` (worker) | Node.js (e.g. `@napi-rs/canvas`) |
-| ------------------------------------- | -------------------------------------------------------- | -------------------------- | -------------------------------- |
-| Drawing primitives (`g…`)             | ✅                                                       | ✅                         | ✅                               |
-| `gimage` / `gpattern` (image loading) | ✅                                                       | ⚠️ needs a global `Image`  | ❌ returns `nil`                 |
-| `gsave-png` / `gsave-jpeg` (download) | ✅                                                       | ❌ returns `nil`           | ❌ returns `nil`                 |
-| `gsave-png` / `gsave-jpeg` (`path`)   | ❌ returns `nil`                                         | ⚠️ async `convertToBlob`   | ✅                               |
-| Diagnostics                           | `console.error` (or host-provided `process.stderr` shim) | same                       | `process.stderr`                 |
+| Capability                            | Browser (`HTMLCanvasElement`)                            | `OffscreenCanvas` (worker)                        | Node.js (e.g. `@napi-rs/canvas`) |
+| ------------------------------------- | -------------------------------------------------------- | ------------------------------------------------- | -------------------------------- |
+| Drawing primitives (`g…`)             | ✅                                                       | ✅                                                | ✅                               |
+| `gimage` / `gpattern` (image loading) | ✅                                                       | ⚠️ needs a global `Image`                         | ❌ signals an error              |
+| `gsave-png` / `gsave-jpeg` (download) | ✅                                                       | ❌ signals an error                               | ❌ signals an error              |
+| `gsave-png` / `gsave-jpeg` (`path`)   | ❌ signals an error                                      | ⚠️ needs Node's `process` (async `convertToBlob`) | ✅                               |
+| Diagnostics                           | `console.error` (or host-provided `process.stderr` shim) | same                                              | `process.stderr`                 |
 
 ## Reference
 
-- [Live demo](https://ike-keichan.github.io/kei-lisp-plugin-graphics/) — the examples, served from GitHub Pages
+In-depth documentation of each area:
+
+- [Example page](https://ike-keichan.github.io/kei-lisp-plugin-graphics/) — the examples rendered on GitHub Pages
+- [kei-lisp-web](https://ike-keichan.github.io/kei-lisp-web/) — interactive kei-lisp playground
 - [API docs (TypeDoc)](https://ike-keichan.github.io/kei-lisp-plugin-graphics/api/) — generated API documentation
 - [API Reference](./docs/api.md) — TypeScript / JavaScript API
 - [Graphics Reference](./docs/graphics.md) — every `g…` Lisp function
+- [Bundled Lisp Patterns](./docs/patterns.md) — the loadable `.lisp` helpers shipped under `lisp/`
 - [Non-goals](./docs/non-goals.md) — what this project deliberately does not do
 - [kei-lisp Plugin Guide](https://github.com/ike-keichan/kei-lisp/blob/main/docs/plugins.md) — how plugins integrate with the interpreter
 
@@ -127,13 +157,16 @@ pnpm install
 Requires [pnpm](https://pnpm.io/) and Node.js 24+
 (see [`.node-version`](./.node-version) for the exact version).
 
-| Command           | Description                                |
-| ----------------- | ------------------------------------------ |
-| `pnpm build`      | Build for distribution (CJS + ESM + types) |
-| `pnpm test`       | Run tests                                  |
-| `pnpm test:watch` | Run tests in watch mode                    |
-| `pnpm check`      | Run all checks (format, lint, spell, ...)  |
-| `pnpm fix`        | Auto-fix format and lint issues            |
+| Command              | Description                               |
+| -------------------- | ----------------------------------------- |
+| `pnpm build`         | Build for distribution                    |
+| `pnpm test`          | Run tests                                 |
+| `pnpm test:coverage` | Run tests with coverage thresholds        |
+| `pnpm test:watch`    | Run tests in watch mode                   |
+| `pnpm e2e`           | Browser E2E (Playwright + Chromium)       |
+| `pnpm screenshot`    | Regenerate the README screenshot          |
+| `pnpm check`         | Run all checks (format, lint, spell, ...) |
+| `pnpm fix`           | Auto-fix format and lint issues           |
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for the branch policy and PR flow.