@gjsify/canvas2d-core 0.1.3

package/lib/esm/canvas-state.js

@@ -0,0 +1,39 @@
+import { BLACK } from "./color.js";
+function createDefaultState() {
+  return {
+    fillStyle: "#000000",
+    fillColor: { ...BLACK },
+    strokeStyle: "#000000",
+    strokeColor: { ...BLACK },
+    lineWidth: 1,
+    lineCap: "butt",
+    lineJoin: "miter",
+    miterLimit: 10,
+    lineDash: [],
+    lineDashOffset: 0,
+    globalAlpha: 1,
+    globalCompositeOperation: "source-over",
+    shadowColor: "rgba(0, 0, 0, 0)",
+    shadowBlur: 0,
+    shadowOffsetX: 0,
+    shadowOffsetY: 0,
+    font: "10px sans-serif",
+    textAlign: "start",
+    textBaseline: "alphabetic",
+    direction: "ltr",
+    imageSmoothingEnabled: true,
+    imageSmoothingQuality: "low"
+  };
+}
+function cloneState(state) {
+  return {
+    ...state,
+    fillColor: { ...state.fillColor },
+    strokeColor: { ...state.strokeColor },
+    lineDash: [...state.lineDash]
+  };
+}
+export {
+  cloneState,
+  createDefaultState
+};

package/lib/esm/color.js

@@ -0,0 +1,209 @@
+const NAMED_COLORS = {
+  aliceblue: "#f0f8ff",
+  antiquewhite: "#faebd7",
+  aqua: "#00ffff",
+  aquamarine: "#7fffd4",
+  azure: "#f0ffff",
+  beige: "#f5f5dc",
+  bisque: "#ffe4c4",
+  black: "#000000",
+  blanchedalmond: "#ffebcd",
+  blue: "#0000ff",
+  blueviolet: "#8a2be2",
+  brown: "#a52a2a",
+  burlywood: "#deb887",
+  cadetblue: "#5f9ea0",
+  chartreuse: "#7fff00",
+  chocolate: "#d2691e",
+  coral: "#ff7f50",
+  cornflowerblue: "#6495ed",
+  cornsilk: "#fff8dc",
+  crimson: "#dc143c",
+  cyan: "#00ffff",
+  darkblue: "#00008b",
+  darkcyan: "#008b8b",
+  darkgoldenrod: "#b8860b",
+  darkgray: "#a9a9a9",
+  darkgreen: "#006400",
+  darkgrey: "#a9a9a9",
+  darkkhaki: "#bdb76b",
+  darkmagenta: "#8b008b",
+  darkolivegreen: "#556b2f",
+  darkorange: "#ff8c00",
+  darkorchid: "#9932cc",
+  darkred: "#8b0000",
+  darksalmon: "#e9967a",
+  darkseagreen: "#8fbc8f",
+  darkslateblue: "#483d8b",
+  darkslategray: "#2f4f4f",
+  darkslategrey: "#2f4f4f",
+  darkturquoise: "#00ced1",
+  darkviolet: "#9400d3",
+  deeppink: "#ff1493",
+  deepskyblue: "#00bfff",
+  dimgray: "#696969",
+  dimgrey: "#696969",
+  dodgerblue: "#1e90ff",
+  firebrick: "#b22222",
+  floralwhite: "#fffaf0",
+  forestgreen: "#228b22",
+  fuchsia: "#ff00ff",
+  gainsboro: "#dcdcdc",
+  ghostwhite: "#f8f8ff",
+  gold: "#ffd700",
+  goldenrod: "#daa520",
+  gray: "#808080",
+  green: "#008000",
+  greenyellow: "#adff2f",
+  grey: "#808080",
+  honeydew: "#f0fff0",
+  hotpink: "#ff69b4",
+  indianred: "#cd5c5c",
+  indigo: "#4b0082",
+  ivory: "#fffff0",
+  khaki: "#f0e68c",
+  lavender: "#e6e6fa",
+  lavenderblush: "#fff0f5",
+  lawngreen: "#7cfc00",
+  lemonchiffon: "#fffacd",
+  lightblue: "#add8e6",
+  lightcoral: "#f08080",
+  lightcyan: "#e0ffff",
+  lightgoldenrodyellow: "#fafad2",
+  lightgray: "#d3d3d3",
+  lightgreen: "#90ee90",
+  lightgrey: "#d3d3d3",
+  lightpink: "#ffb6c1",
+  lightsalmon: "#ffa07a",
+  lightseagreen: "#20b2aa",
+  lightskyblue: "#87cefa",
+  lightslategray: "#778899",
+  lightslategrey: "#778899",
+  lightsteelblue: "#b0c4de",
+  lightyellow: "#ffffe0",
+  lime: "#00ff00",
+  limegreen: "#32cd32",
+  linen: "#faf0e6",
+  magenta: "#ff00ff",
+  maroon: "#800000",
+  mediumaquamarine: "#66cdaa",
+  mediumblue: "#0000cd",
+  mediumorchid: "#ba55d3",
+  mediumpurple: "#9370db",
+  mediumseagreen: "#3cb371",
+  mediumslateblue: "#7b68ee",
+  mediumspringgreen: "#00fa9a",
+  mediumturquoise: "#48d1cc",
+  mediumvioletred: "#c71585",
+  midnightblue: "#191970",
+  mintcream: "#f5fffa",
+  mistyrose: "#ffe4e1",
+  moccasin: "#ffe4b5",
+  navajowhite: "#ffdead",
+  navy: "#000080",
+  oldlace: "#fdf5e6",
+  olive: "#808000",
+  olivedrab: "#6b8e23",
+  orange: "#ffa500",
+  orangered: "#ff4500",
+  orchid: "#da70d6",
+  palegoldenrod: "#eee8aa",
+  palegreen: "#98fb98",
+  paleturquoise: "#afeeee",
+  palevioletred: "#db7093",
+  papayawhip: "#ffefd5",
+  peachpuff: "#ffdab9",
+  peru: "#cd853f",
+  pink: "#ffc0cb",
+  plum: "#dda0dd",
+  powderblue: "#b0e0e6",
+  purple: "#800080",
+  rebeccapurple: "#663399",
+  red: "#ff0000",
+  rosybrown: "#bc8f8f",
+  royalblue: "#4169e1",
+  saddlebrown: "#8b4513",
+  salmon: "#fa8072",
+  sandybrown: "#f4a460",
+  seagreen: "#2e8b57",
+  seashell: "#fff5ee",
+  sienna: "#a0522d",
+  silver: "#c0c0c0",
+  skyblue: "#87ceeb",
+  slateblue: "#6a5acd",
+  slategray: "#708090",
+  slategrey: "#708090",
+  snow: "#fffafa",
+  springgreen: "#00ff7f",
+  steelblue: "#4682b4",
+  tan: "#d2b48c",
+  teal: "#008080",
+  thistle: "#d8bfd8",
+  tomato: "#ff6347",
+  turquoise: "#40e0d0",
+  violet: "#ee82ee",
+  wheat: "#f5deb3",
+  white: "#ffffff",
+  whitesmoke: "#f5f5f5",
+  yellow: "#ffff00",
+  yellowgreen: "#9acd32",
+  transparent: "#00000000"
+};
+function parseColor(color) {
+  if (!color || typeof color !== "string") return null;
+  const trimmed = color.trim().toLowerCase();
+  const named = NAMED_COLORS[trimmed];
+  if (named) return parseHex(named);
+  if (trimmed.startsWith("#")) return parseHex(trimmed);
+  const rgbMatch = trimmed.match(
+    /^rgba?\(\s*(\d+(?:\.\d+)?%?)\s*[,\s]\s*(\d+(?:\.\d+)?%?)\s*[,\s]\s*(\d+(?:\.\d+)?%?)\s*(?:[,/]\s*(\d+(?:\.\d+)?%?))?\s*\)$/
+  );
+  if (rgbMatch) {
+    return {
+      r: parseComponent(rgbMatch[1], 255) / 255,
+      g: parseComponent(rgbMatch[2], 255) / 255,
+      b: parseComponent(rgbMatch[3], 255) / 255,
+      a: rgbMatch[4] !== void 0 ? parseComponent(rgbMatch[4], 1) : 1
+    };
+  }
+  return null;
+}
+function parseHex(hex) {
+  const h = hex.slice(1);
+  let r, g, b, a = 1;
+  if (h.length === 3) {
+    r = parseInt(h[0] + h[0], 16) / 255;
+    g = parseInt(h[1] + h[1], 16) / 255;
+    b = parseInt(h[2] + h[2], 16) / 255;
+  } else if (h.length === 4) {
+    r = parseInt(h[0] + h[0], 16) / 255;
+    g = parseInt(h[1] + h[1], 16) / 255;
+    b = parseInt(h[2] + h[2], 16) / 255;
+    a = parseInt(h[3] + h[3], 16) / 255;
+  } else if (h.length === 6) {
+    r = parseInt(h.slice(0, 2), 16) / 255;
+    g = parseInt(h.slice(2, 4), 16) / 255;
+    b = parseInt(h.slice(4, 6), 16) / 255;
+  } else if (h.length === 8) {
+    r = parseInt(h.slice(0, 2), 16) / 255;
+    g = parseInt(h.slice(2, 4), 16) / 255;
+    b = parseInt(h.slice(4, 6), 16) / 255;
+    a = parseInt(h.slice(6, 8), 16) / 255;
+  } else {
+    return null;
+  }
+  return { r, g, b, a };
+}
+function parseComponent(value, max) {
+  if (value.endsWith("%")) {
+    return parseFloat(value) / 100 * max;
+  }
+  return parseFloat(value);
+}
+const BLACK = { r: 0, g: 0, b: 0, a: 1 };
+const TRANSPARENT = { r: 0, g: 0, b: 0, a: 0 };
+export {
+  BLACK,
+  TRANSPARENT,
+  parseColor
+};

package/lib/esm/image-data.js

@@ -0,0 +1,22 @@
+class OurImageData {
+  constructor(swOrData, sh, maybeHeight) {
+    this.colorSpace = "srgb";
+    if (typeof swOrData === "number") {
+      this.width = swOrData;
+      this.height = sh;
+      this.data = new Uint8ClampedArray(this.width * this.height * 4);
+    } else {
+      this.data = swOrData;
+      this.width = sh;
+      this.height = maybeHeight ?? this.data.length / (4 * this.width);
+      if (this.data.length !== this.width * this.height * 4) {
+        throw new RangeError(
+          `Source data length ${this.data.length} is not a multiple of (4 * width=${this.width})`
+        );
+      }
+    }
+  }
+}
+export {
+  OurImageData
+};

package/lib/esm/index.js

@@ -0,0 +1,14 @@
+import { CanvasRenderingContext2D } from "./canvas-rendering-context-2d.js";
+import { CanvasGradient } from "./canvas-gradient.js";
+import { CanvasPattern } from "./canvas-pattern.js";
+import { Path2D } from "./canvas-path.js";
+import { OurImageData } from "./image-data.js";
+import { parseColor } from "./color.js";
+export {
+  CanvasGradient,
+  CanvasPattern,
+  CanvasRenderingContext2D,
+  OurImageData as ImageData,
+  Path2D,
+  parseColor
+};

package/lib/types/cairo-utils.d.ts

@@ -0,0 +1,54 @@
+import type Cairo from 'cairo';
+/**
+ * Convert quadratic Bezier control point to cubic Bezier control points.
+ * Canvas 2D has quadraticCurveTo but Cairo only has cubic curveTo.
+ *
+ * Given current point (cx, cy), quadratic control point (cpx, cpy), and end (x, y):
+ *   cp1 = current + 2/3 * (cp - current)
+ *   cp2 = end + 2/3 * (cp - end)
+ */
+export declare function quadraticToCubic(cx: number, cy: number, cpx: number, cpy: number, x: number, y: number): {
+    cp1x: number;
+    cp1y: number;
+    cp2x: number;
+    cp2y: number;
+};
+/**
+ * Compute arcTo parameters.
+ * Canvas arcTo(x1,y1,x2,y2,radius) draws a line from current point to the tangent point,
+ * then an arc of the given radius tangent to both lines (current→p1 and p1→p2).
+ *
+ * Returns the two tangent points and arc center, or null if degenerate (collinear points).
+ */
+export declare function computeArcTo(x0: number, y0: number, x1: number, y1: number, x2: number, y2: number, radius: number): {
+    tx0: number;
+    ty0: number;
+    tx1: number;
+    ty1: number;
+    cx: number;
+    cy: number;
+    startAngle: number;
+    endAngle: number;
+    counterclockwise: boolean;
+} | null;
+/**
+ * Apply an arcTo operation to a Cairo context.
+ */
+export declare function cairoArcTo(ctx: Cairo.Context, x0: number, y0: number, x1: number, y1: number, x2: number, y2: number, radius: number): void;
+/**
+ * Draw an ellipse on a Cairo context.
+ * Canvas ellipse(x, y, radiusX, radiusY, rotation, startAngle, endAngle, counterclockwise)
+ * is implemented via save/translate/rotate/scale/arc/restore.
+ */
+export declare function cairoEllipse(ctx: Cairo.Context, x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise: boolean): void;
+/**
+ * Draw a rounded rectangle path on a Cairo context.
+ * Implements the Canvas roundRect(x, y, w, h, radii) method.
+ */
+export declare function cairoRoundRect(ctx: Cairo.Context, x: number, y: number, w: number, h: number, radii: number | number[]): void;
+/** Map Canvas globalCompositeOperation to Cairo.Operator values */
+export declare const COMPOSITE_OP_MAP: Record<string, number>;
+/** Map Canvas lineCap to Cairo.LineCap values */
+export declare const LINE_CAP_MAP: Record<string, number>;
+/** Map Canvas lineJoin to Cairo.LineJoin values */
+export declare const LINE_JOIN_MAP: Record<string, number>;

package/lib/types/canvas-gradient.d.ts

@@ -0,0 +1,11 @@
+import Cairo from 'cairo';
+/**
+ * CanvasGradient wrapping a Cairo LinearGradient or RadialGradient.
+ */
+export declare class CanvasGradient {
+    private _pattern;
+    constructor(type: 'linear' | 'radial', x0: number, y0: number, x1: number, y1: number, r0?: number, r1?: number);
+    addColorStop(offset: number, color: string): void;
+    /** @internal Get the underlying Cairo pattern for rendering. */
+    _getCairoPattern(): Cairo.LinearGradient | Cairo.RadialGradient;
+}

package/lib/types/canvas-path.d.ts

@@ -0,0 +1,80 @@
+/** A recorded path operation. */
+type PathOp = {
+    type: 'moveTo';
+    x: number;
+    y: number;
+} | {
+    type: 'lineTo';
+    x: number;
+    y: number;
+} | {
+    type: 'closePath';
+} | {
+    type: 'bezierCurveTo';
+    cp1x: number;
+    cp1y: number;
+    cp2x: number;
+    cp2y: number;
+    x: number;
+    y: number;
+} | {
+    type: 'quadraticCurveTo';
+    cpx: number;
+    cpy: number;
+    x: number;
+    y: number;
+} | {
+    type: 'arc';
+    x: number;
+    y: number;
+    radius: number;
+    startAngle: number;
+    endAngle: number;
+    ccw: boolean;
+} | {
+    type: 'ellipse';
+    x: number;
+    y: number;
+    rx: number;
+    ry: number;
+    rotation: number;
+    startAngle: number;
+    endAngle: number;
+    ccw: boolean;
+} | {
+    type: 'rect';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | {
+    type: 'roundRect';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    radii: number | number[];
+};
+/**
+ * Path2D records path operations for later replay on a CanvasRenderingContext2D.
+ */
+export declare class Path2D {
+    /** @internal Recorded operations */
+    _ops: PathOp[];
+    constructor(pathOrSvg?: Path2D | string);
+    addPath(path: Path2D): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    closePath(): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    rect(x: number, y: number, w: number, h: number): void;
+    roundRect(x: number, y: number, w: number, h: number, radii?: number | number[]): void;
+    /**
+     * @internal Replay all recorded path operations onto a Cairo context.
+     */
+    _replayOnCairo(ctx: import('cairo').default.Context): void;
+}
+export {};

package/lib/types/canvas-pattern.d.ts

@@ -0,0 +1,12 @@
+import Cairo from 'cairo';
+/**
+ * CanvasPattern wrapping a Cairo SurfacePattern.
+ */
+export declare class CanvasPattern {
+    private _pattern;
+    private constructor();
+    /** Create a CanvasPattern from a supported image source. Returns null if unsupported. */
+    static create(image: any, repetition: string | null): CanvasPattern | null;
+    /** @internal Get the underlying Cairo pattern for rendering. */
+    _getCairoPattern(): Cairo.SurfacePattern;
+}

package/lib/types/canvas-rendering-context-2d.d.ts

@@ -0,0 +1,164 @@
+import Cairo from 'cairo';
+import { Path2D } from './canvas-path.js';
+/**
+ * CanvasRenderingContext2D backed by Cairo.ImageSurface.
+ * Implements the Canvas 2D API for GJS.
+ */
+export declare class CanvasRenderingContext2D {
+    readonly canvas: any;
+    private _surface;
+    private _ctx;
+    private _state;
+    private _stateStack;
+    private _surfaceWidth;
+    private _surfaceHeight;
+    constructor(canvas: any, _options?: any);
+    /** Ensure the surface matches the current canvas dimensions. Recreate if resized. */
+    private _ensureSurface;
+    /** Reset drawing state to defaults (called when canvas dimensions are explicitly reset). */
+    _resetState(): void;
+    /** Apply the current fill style (color, gradient, or pattern) to the Cairo context. */
+    private _applyFillStyle;
+    /** Apply the current stroke style to the Cairo context. */
+    private _applyStrokeStyle;
+    /** Apply line properties to the Cairo context. */
+    private _applyLineStyle;
+    /** Apply compositing operator. */
+    private _applyCompositing;
+    /** Get the Cairo ImageSurface (used by other contexts like drawImage). */
+    _getSurface(): Cairo.ImageSurface;
+    /** Check if shadow rendering is needed. */
+    private _hasShadow;
+    /**
+     * Render a shadow for the current path by painting to a temp surface,
+     * applying a simple box blur approximation, and compositing back.
+     * This is called before the actual fill/stroke when shadows are active.
+     */
+    private _renderShadow;
+    save(): void;
+    restore(): void;
+    translate(x: number, y: number): void;
+    rotate(angle: number): void;
+    scale(x: number, y: number): void;
+    /**
+     * Multiply the current transformation matrix by the given values.
+     * Matrix: [a c e]
+     *         [b d f]
+     *         [0 0 1]
+     */
+    transform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+    /**
+     * Reset the transform to identity, then apply the given matrix.
+     */
+    setTransform(matrix?: DOMMatrix2DInit): void;
+    setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+    /**
+     * Return the current transformation matrix as a DOMMatrix-like object.
+     */
+    getTransform(): DOMMatrix;
+    resetTransform(): void;
+    get fillStyle(): string | CanvasGradient | CanvasPattern;
+    set fillStyle(value: string | CanvasGradient | CanvasPattern);
+    get strokeStyle(): string | CanvasGradient | CanvasPattern;
+    set strokeStyle(value: string | CanvasGradient | CanvasPattern);
+    get lineWidth(): number;
+    set lineWidth(value: number);
+    get lineCap(): CanvasLineCap;
+    set lineCap(value: CanvasLineCap);
+    get lineJoin(): CanvasLineJoin;
+    set lineJoin(value: CanvasLineJoin);
+    get miterLimit(): number;
+    set miterLimit(value: number);
+    get globalAlpha(): number;
+    set globalAlpha(value: number);
+    get globalCompositeOperation(): GlobalCompositeOperation;
+    set globalCompositeOperation(value: GlobalCompositeOperation);
+    get imageSmoothingEnabled(): boolean;
+    set imageSmoothingEnabled(value: boolean);
+    get imageSmoothingQuality(): ImageSmoothingQuality;
+    set imageSmoothingQuality(value: ImageSmoothingQuality);
+    setLineDash(segments: number[]): void;
+    getLineDash(): number[];
+    get lineDashOffset(): number;
+    set lineDashOffset(value: number);
+    get shadowColor(): string;
+    set shadowColor(value: string);
+    get shadowBlur(): number;
+    set shadowBlur(value: number);
+    get shadowOffsetX(): number;
+    set shadowOffsetX(value: number);
+    get shadowOffsetY(): number;
+    set shadowOffsetY(value: number);
+    get font(): string;
+    set font(value: string);
+    get textAlign(): CanvasTextAlign;
+    set textAlign(value: CanvasTextAlign);
+    get textBaseline(): CanvasTextBaseline;
+    set textBaseline(value: CanvasTextBaseline);
+    get direction(): CanvasDirection;
+    set direction(value: CanvasDirection);
+    beginPath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    closePath(): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
+    ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    rect(x: number, y: number, w: number, h: number): void;
+    roundRect(x: number, y: number, w: number, h: number, radii?: number | number[]): void;
+    fill(fillRule?: CanvasFillRule): void;
+    fill(path: Path2D, fillRule?: CanvasFillRule): void;
+    stroke(): void;
+    stroke(path: Path2D): void;
+    fillRect(x: number, y: number, w: number, h: number): void;
+    strokeRect(x: number, y: number, w: number, h: number): void;
+    clearRect(x: number, y: number, w: number, h: number): void;
+    clip(fillRule?: CanvasFillRule): void;
+    clip(path: Path2D, fillRule?: CanvasFillRule): void;
+    isPointInPath(x: number, y: number, fillRule?: CanvasFillRule): boolean;
+    isPointInPath(path: Path2D, x: number, y: number, fillRule?: CanvasFillRule): boolean;
+    isPointInStroke(x: number, y: number): boolean;
+    isPointInStroke(path: Path2D, x: number, y: number): boolean;
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number): CanvasGradient;
+    createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): CanvasGradient;
+    createPattern(image: any, repetition: string | null): CanvasPattern | null;
+    createImageData(sw: number, sh: number): ImageData;
+    createImageData(imagedata: ImageData): ImageData;
+    getImageData(sx: number, sy: number, sw: number, sh: number): ImageData;
+    putImageData(imageData: ImageData, dx: number, dy: number, dirtyX?: number, dirtyY?: number, dirtyWidth?: number, dirtyHeight?: number): void;
+    drawImage(image: any, dx: number, dy: number): void;
+    drawImage(image: any, dx: number, dy: number, dw: number, dh: number): void;
+    drawImage(image: any, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): void;
+    private _getDrawImageSource;
+    /** Create a PangoCairo layout configured with current font/text settings. */
+    private _createTextLayout;
+    /** Parse a CSS font string (e.g. "bold 16px Arial") into a Pango.FontDescription. */
+    private _parseFontToDescription;
+    /**
+     * Compute the x-offset for text alignment relative to the given x coordinate.
+     */
+    private _getTextAlignOffset;
+    /**
+     * Compute the y-offset for text baseline positioning.
+     *
+     * PangoCairo.show_layout() places the layout TOP-LEFT at the current Cairo point
+     * (not the baseline). Within the layout, the first line's baseline is at
+     * approximately `ascent` pixels below the layout top.
+     *
+     * For CSS textBaseline semantics, we shift the current point UP (negative offset)
+     * so the layout top lands at the right position relative to the user's y coordinate.
+     */
+    private _getTextBaselineOffset;
+    fillText(text: string, x: number, y: number, _maxWidth?: number): void;
+    strokeText(text: string, x: number, y: number, _maxWidth?: number): void;
+    measureText(text: string): TextMetrics;
+    /**
+     * Write the canvas surface to a PNG file and return as data URL.
+     * Used by HTMLCanvasElement.toDataURL() when a '2d' context is active.
+     */
+    _toDataURL(type?: string, _quality?: number): string;
+    /** Release native Cairo resources. Call when the canvas is discarded. */
+    _dispose(): void;
+}

package/lib/types/canvas-state.d.ts

@@ -0,0 +1,27 @@
+import type { RGBA } from './color.js';
+export interface CanvasState {
+    fillStyle: string | CanvasGradient | CanvasPattern;
+    fillColor: RGBA;
+    strokeStyle: string | CanvasGradient | CanvasPattern;
+    strokeColor: RGBA;
+    lineWidth: number;
+    lineCap: CanvasLineCap;
+    lineJoin: CanvasLineJoin;
+    miterLimit: number;
+    lineDash: number[];
+    lineDashOffset: number;
+    globalAlpha: number;
+    globalCompositeOperation: GlobalCompositeOperation;
+    shadowColor: string;
+    shadowBlur: number;
+    shadowOffsetX: number;
+    shadowOffsetY: number;
+    font: string;
+    textAlign: CanvasTextAlign;
+    textBaseline: CanvasTextBaseline;
+    direction: CanvasDirection;
+    imageSmoothingEnabled: boolean;
+    imageSmoothingQuality: ImageSmoothingQuality;
+}
+export declare function createDefaultState(): CanvasState;
+export declare function cloneState(state: CanvasState): CanvasState;

package/lib/types/color.d.ts

@@ -0,0 +1,15 @@
+export interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/**
+ * Parse a CSS color string into RGBA components (0-1 range).
+ * Supports: #rgb, #rrggbb, #rgba, #rrggbbaa, rgb(), rgba(), named colors, 'transparent'.
+ */
+export declare function parseColor(color: string): RGBA | null;
+/** Default color: opaque black */
+export declare const BLACK: RGBA;
+/** Transparent black */
+export declare const TRANSPARENT: RGBA;

package/lib/types/image-data.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ImageData represents the pixel data of a canvas area.
+ * Each pixel is 4 bytes: R, G, B, A (0-255 each).
+ */
+export declare class OurImageData {
+    readonly data: Uint8ClampedArray;
+    readonly width: number;
+    readonly height: number;
+    readonly colorSpace: PredefinedColorSpace;
+    constructor(sw: number, sh: number);
+    constructor(data: Uint8ClampedArray, sw: number, sh?: number);
+}

package/lib/types/index.d.ts

@@ -0,0 +1,6 @@
+export { CanvasRenderingContext2D } from './canvas-rendering-context-2d.js';
+export { CanvasGradient } from './canvas-gradient.js';
+export { CanvasPattern } from './canvas-pattern.js';
+export { Path2D } from './canvas-path.js';
+export { OurImageData as ImageData } from './image-data.js';
+export { parseColor } from './color.js';