kei-lisp-plugin-graphics 3.0.1 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +31 -13
  2. package/dist/index.cjs +303 -640
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +28 -28
  5. package/dist/index.d.ts +28 -28
  6. package/dist/index.js +304 -641
  7. package/dist/index.js.map +1 -1
  8. package/lisp/animation.lisp +17 -0
  9. package/lisp/grid.lisp +26 -0
  10. package/lisp/palette.lisp +28 -0
  11. package/package.json +11 -10
package/README.md CHANGED
@@ -48,6 +48,7 @@ pnpm add kei-lisp-plugin-graphics kei-lisp
48
48
  ```
49
49
 
50
50
  `kei-lisp` is a **peer dependency**; install both into your project. Requires
51
+ **kei-lisp >= 3.0.1** (for kei-lisp 2.x use kei-lisp-plugin-graphics 3.x) and
51
52
  **Node.js >= 24** for the build toolchain (the plugin itself targets any
52
53
  environment that exposes a `CanvasRenderingContext2D`).
53
54
 
@@ -69,7 +70,7 @@ interpreter.evalString(`
69
70
  (gstroke-color "black")
70
71
  (gline-width 2)
71
72
  (gstroke-rect 10 10 120 80)
72
- (gclose)
73
+ (gclose) ; note: gclose clears the canvas — omit it to keep the drawing visible
73
74
  `);
74
75
  ```
75
76
 
@@ -78,11 +79,9 @@ interpreter.evalString(`
78
79
  ## API
79
80
 
80
81
  ```ts
81
- import type { KeiLispPlugin } from 'kei-lisp';
82
-
83
82
  export function createGraphicsPlugin(options: {
84
83
  canvas: HTMLCanvasElement | OffscreenCanvas;
85
- }): KeiLispPlugin;
84
+ }): GraphicsPlugin;
86
85
  ```
87
86
 
88
87
  The returned plugin implements the [`KeiLispPlugin`](https://github.com/ike-keichan/kei-lisp/blob/main/docs/plugins.md)
@@ -103,18 +102,36 @@ canvas's 2D rendering context.
103
102
  | State | `gsave`, `grestore` |
104
103
  | Image / export | `gimage`, `gsave-png`, `gsave-jpeg`, `gclear-rect`, `gpixel`, `gset-pixel` |
105
104
 
106
- Each function returns `t` on success. See [`docs/graphics.md`](./docs/graphics.md)
107
- for argument signatures and side effects.
105
+ Each function returns `t` on success; failures signal an evaluation error
106
+ that Lisp code can intercept with `(handler-case … (eval-error (e) …))`.
107
+ See [`docs/graphics.md`](./docs/graphics.md) for argument signatures and
108
+ side effects.
109
+
110
+ ## Bundled Lisp patterns
111
+
112
+ The package ships loadable `.lisp` pattern files under `lisp/` — a grid
113
+ helper (`ggrid`), color-palette helpers (`gpalette` / `gpalette-color`),
114
+ and a frame-loop helper (`ganimate`):
115
+
116
+ ```lisp
117
+ (load "node_modules/kei-lisp-plugin-graphics/lisp/grid.lisp")
118
+ (gopen)
119
+ (ggrid 40)
120
+ ```
121
+
122
+ `load` reads from the filesystem (Node.js); browser hosts can fetch the
123
+ file's text and evaluate it instead. See
124
+ [`docs/patterns.md`](./docs/patterns.md) for the full list.
108
125
 
109
126
  ## Environment support
110
127
 
111
- | Capability | Browser (`HTMLCanvasElement`) | `OffscreenCanvas` (worker) | Node.js (e.g. `@napi-rs/canvas`) |
112
- | ------------------------------------- | -------------------------------------------------------- | -------------------------- | -------------------------------- |
113
- | Drawing primitives (`g…`) | ✅ | ✅ | ✅ |
114
- | `gimage` / `gpattern` (image loading) | ✅ | ⚠️ needs a global `Image` | ❌ returns `nil` |
115
- | `gsave-png` / `gsave-jpeg` (download) | ✅ | ❌ returns `nil` | ❌ returns `nil` |
116
- | `gsave-png` / `gsave-jpeg` (`path`) | ❌ returns `nil` | ⚠️ async `convertToBlob` | ✅ |
117
- | Diagnostics | `console.error` (or host-provided `process.stderr` shim) | same | `process.stderr` |
128
+ | Capability | Browser (`HTMLCanvasElement`) | `OffscreenCanvas` (worker) | Node.js (e.g. `@napi-rs/canvas`) |
129
+ | ------------------------------------- | -------------------------------------------------------- | ------------------------------------------------- | -------------------------------- |
130
+ | Drawing primitives (`g…`) | ✅ | ✅ | ✅ |
131
+ | `gimage` / `gpattern` (image loading) | ✅ | ⚠️ needs a global `Image` | ❌ signals an error |
132
+ | `gsave-png` / `gsave-jpeg` (download) | ✅ | ❌ signals an error | ❌ signals an error |
133
+ | `gsave-png` / `gsave-jpeg` (`path`) | ❌ signals an error | ⚠️ needs Node's `process` (async `convertToBlob`) | ✅ |
134
+ | Diagnostics | `console.error` (or host-provided `process.stderr` shim) | same | `process.stderr` |
118
135
 
119
136
  ## Reference
120
137
 
@@ -125,6 +142,7 @@ In-depth documentation of each area:
125
142
  - [API docs (TypeDoc)](https://ike-keichan.github.io/kei-lisp-plugin-graphics/api/) — generated API documentation
126
143
  - [API Reference](./docs/api.md) — TypeScript / JavaScript API
127
144
  - [Graphics Reference](./docs/graphics.md) — every `g…` Lisp function
145
+ - [Bundled Lisp Patterns](./docs/patterns.md) — the loadable `.lisp` helpers shipped under `lisp/`
128
146
  - [Non-goals](./docs/non-goals.md) — what this project deliberately does not do
129
147
  - [kei-lisp Plugin Guide](https://github.com/ike-keichan/kei-lisp/blob/main/docs/plugins.md) — how plugins integrate with the interpreter
130
148