kei-lisp-plugin-graphics 3.0.1 → 4.0.0

package/dist/index.d.ts

@@ -5,8 +5,15 @@ import { Cons, InterpretedSymbol, KeiLispPlugin, LispValue, PluginContext } from
  * @class
  * @classdesc Canvas2D drawing plugin for the kei-lisp interpreter. Implements
  *            the `KeiLispPlugin` contract (`name` / `has` / `apply`) and
- *            exposes 75 `g…` Lisp functions (plus two deprecated aliases)
- *            that proxy to a 2D rendering context.
+ *            exposes 75 `g…` Lisp functions that proxy to a 2D rendering
+ *            context. Failures (wrong arity,
+ *            type mismatch, closed canvas, canvas-level errors) signal an
+ *            `EvalError` that Lisp callers can intercept with
+ *            `(handler-case … (eval-error (e) …))`. Two exceptions still go
+ *            to `process.stderr` as diagnostics: asynchronous work (image
+ *            loading, OffscreenCanvas file writes), which fails after the
+ *            call has returned, and `selectColor`'s best-effort color
+ *            parsing, which falls back to black instead of failing.
  * @author Keisuke Ikeda
  */
 declare class GraphicsPlugin implements KeiLispPlugin {
@@ -40,37 +47,29 @@ declare class GraphicsPlugin implements KeiLispPlugin {
    * @param aSymbol - the call symbol
    * @param arguments_ - the evaluated argument list
    * @param _context - the interpreter context (unused by this plugin)
-   * @return the method's result, or `Cons.nil` if dispatch fails
+   * @return the method's result
    */
   apply(aSymbol: InterpretedSymbol, arguments_: Cons, _context: PluginContext): LispValue;
-  /**
-   * Checks whether the canvas exposes a usable 2D context, and narrows
-   * `this.ctx` to non-null for the caller when it returns true.
-   * @return type predicate — true when context is non-null
-   */
-  checkSupport(): this is GraphicsPlugin & {
-    ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
-  };
   gAlpha(arguments_: Cons): LispValue;
   gArc(arguments_: Cons): LispValue;
   gArcTo(arguments_: Cons): LispValue;
   gBezCurveTo(arguments_: Cons): LispValue;
   gClear(arguments_: Cons): LispValue;
-  gClose(): LispValue;
+  gClose(arguments_?: Cons): LispValue;
   gColor(arguments_: Cons): LispValue;
-  gFill(): LispValue;
+  gFill(arguments_?: Cons): LispValue;
   gFillColor(arguments_: Cons): LispValue;
   gFillRect(arguments_: Cons): LispValue;
   gFillText(arguments_: Cons): LispValue;
   gFillTri(arguments_: Cons): LispValue;
-  gFinishPath(): LispValue;
+  gFinishPath(arguments_?: Cons): LispValue;
   gImage(arguments_: Cons): LispValue;
   gLineTo(arguments_: Cons): LispValue;
   gLineCap(arguments_: Cons): LispValue;
   gLineJoin(arguments_: Cons): LispValue;
   gLineWidth(arguments_: Cons): LispValue;
   gMoveTo(arguments_: Cons): LispValue;
-  gOpen(): LispValue;
+  gOpen(arguments_?: Cons): LispValue;
   gPattern(arguments_: Cons): LispValue;
   gQuadCurveTo(arguments_: Cons): LispValue;
   gSaveJpeg(arguments_: Cons): LispValue;
@@ -82,7 +81,7 @@ declare class GraphicsPlugin implements KeiLispPlugin {
    * @param arguments_ - the evaluated argument list (empty, or one path string)
    * @param mimeType - the image MIME type to encode
    * @param label - the format name used in diagnostics ("jpeg" / "png")
-   * @return `t` on success, `Cons.nil` otherwise
+   * @return `t` on success
    */
   saveCanvas(arguments_: Cons, mimeType: string, label: string): LispValue;
   gScale(arguments_: Cons): LispValue;
@@ -91,8 +90,8 @@ declare class GraphicsPlugin implements KeiLispPlugin {
   gShadowOffsetX(arguments_: Cons): LispValue;
   gShadowOffsetY(arguments_: Cons): LispValue;
   gSleep(arguments_: Cons): LispValue;
-  gStartPath(): LispValue;
-  gStroke(): LispValue;
+  gStartPath(arguments_?: Cons): LispValue;
+  gStroke(arguments_?: Cons): LispValue;
   gStrokeColor(arguments_: Cons): LispValue;
   gStrokeRect(arguments_: Cons): LispValue;
   gStrokeText(arguments_: Cons): LispValue;
@@ -110,26 +109,26 @@ declare class GraphicsPlugin implements KeiLispPlugin {
    * state explicitly. Replaces the legacy per-method `context.save()` calls, which
    * pushed state on every draw with no matching `restore()` and grew the stack
    * unbounded.
-   * @return `t` on success, `Cons.nil` otherwise
+   * @return `t` on success
    */
-  gSave(): LispValue;
+  gSave(arguments_?: Cons): LispValue;
   /**
    * Pops the most recently saved drawing state off the context's state stack.
    * Pairs with `gSave`. Popping an empty stack is a no-op per the Canvas spec.
-   * @return `t` on success, `Cons.nil` otherwise
+   * @return `t` on success
    */
-  gRestore(): LispValue;
+  gRestore(arguments_?: Cons): LispValue;
   gEllipse(arguments_: Cons): LispValue;
   gRoundRect(arguments_: Cons): LispValue;
   gLineDash(arguments_: Cons): LispValue;
   gLineDashOffset(arguments_: Cons): LispValue;
   gMiterLimit(arguments_: Cons): LispValue;
-  gClip(): LispValue;
+  gClip(arguments_?: Cons): LispValue;
   gIsPointInPath(arguments_: Cons): LispValue;
   gIsPointInStroke(arguments_: Cons): LispValue;
   gTransform(arguments_: Cons): LispValue;
   gSetTransform(arguments_: Cons): LispValue;
-  gResetTransform(): LispValue;
+  gResetTransform(arguments_?: Cons): LispValue;
   gComposite(arguments_: Cons): LispValue;
   gFilter(arguments_: Cons): LispValue;
   gImageSmoothing(arguments_: Cons): LispValue;
@@ -141,9 +140,9 @@ declare class GraphicsPlugin implements KeiLispPlugin {
   gFontVariant(arguments_: Cons): LispValue;
   gTextRendering(arguments_: Cons): LispValue;
   gClearRect(arguments_: Cons): LispValue;
-  gReset(): LispValue;
-  gWidth(): LispValue;
-  gHeight(): LispValue;
+  gReset(arguments_?: Cons): LispValue;
+  gWidth(arguments_?: Cons): LispValue;
+  gHeight(arguments_?: Cons): LispValue;
   gPixel(arguments_: Cons): LispValue;
   gSetPixel(arguments_: Cons): LispValue;
   gLinearGradient(arguments_: Cons): LispValue;
@@ -152,7 +151,8 @@ declare class GraphicsPlugin implements KeiLispPlugin {
   /**
    * Parses a color spec from the head of the argument Cons. Accepts
    * (1 string), (3 numbers — rgb), or (4 numbers — rgba); falls back to
-   * `'black'` on anything else (legacy behavior).
+   * `'black'` on anything else (legacy behavior — a best-effort color parse
+   * that prints a diagnostic instead of signaling an error).
    * @param arguments_ - the argument Cons to parse
    * @return CSS color string
    */