declare-render 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CaiZhuo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# Declare Render
+
+A TypeScript library for declaratively drawing canvas graphics using JSON schema.
+
+## Installation
+
+```bash
+pnpm install
+```
+
+## Usage
+
+```typescript
+import { Renderer } from './src/index.ts';
+import { RenderData } from './src/types.ts';
+
+const schema: RenderData = {
+  id: "my-canvas",
+  width: 800,
+  height: 600,
+  renderers: [
+    {
+      id: "text-1",
+      type: "text",
+      x: 50,
+      y: 50,
+      width: 700,
+      height: 100,
+      content: "Hello, World!",
+      style: {
+        fontName: "Arial",
+        fontSize: 32,
+        color: "#000000",
+      },
+    },
+  ],
+};
+
+const renderer = new Renderer(schema);
+const buffer = await renderer.draw();
+// buffer is a PNG or JPG image buffer
+```
+
+## Features
+
+- **Text Renderers**: Render text with various styling options
+- **Image Renderers**: Render images or solid color rectangles
+- **Container Renderers**: Organize renderers with flexbox-like layouts
+- **Multiple Output Formats**: PNG and JPG support

package/examples/sunscreen-guide.ts

@@ -0,0 +1,206 @@
+import { Renderer } from "../src/index";
+import { RenderData, RendererType } from "../src/types";
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Content data in JSON format for easy reading and maintenance
+const contentData = {
+  title: "防晒指南",
+  sections: [
+    {
+      question: "该不该防晒：",
+      answer: "适度防晒"
+    },
+    {
+      question: "怎么防晒：",
+      answer: "做好物理防晒，选适配防晒霜（矿物款更安全，适合敏感肌/儿童，化学款慎选成分），避开正午强紫外线，早晚适度日晒。"
+    },
+    {
+      question: "为什么适度：",
+      answer: "紫外线会致皮肤DNA突变、加速老化，防晒对护肤和防病至关重要；但完全避光不利健康，且长波长光能穿透防晒和衣物，足够满足合成需求，不用刻意不防晒。维生素D能够调节激素，还与更好的生活质量和寿命相关。"
+    }
+  ]
+};
+
+// Dark & Elegant theme canvas configuration (4:3 aspect ratio)
+const CANVAS_CONFIG = {
+  width: 1200,
+  height: 900, // 4:3 ratio
+  padding: 50,
+  colors: {
+    background: "#121212",  // Deep black
+    title: "#FFD700",       // Gold
+    question: "#FFFFFF",    // White
+    answer: "#B0B0B0",      // Light Gray
+    cardBg: "#1E1E1E",      // Dark Gray Card
+    accent: "#FFD700",      // Gold
+    highlight: "#333333"    // Subtle Dark Circle
+  },
+  fonts: {
+    title: "PingFang SC",
+    body: "PingFang SC"
+  }
+};
+
+// Calculate text height based on content and width
+function calcTextHeight(text: string, fontSize: number, containerWidth: number, lineGap = 8): number {
+  // CJK characters are roughly square (width ≈ fontSize)
+  const charsPerLine = Math.floor(containerWidth / fontSize);
+  const lines = Math.ceil(text.length / charsPerLine);
+  return lines * (fontSize + lineGap);
+}
+
+// Build renderers from content data
+function buildRenderers() {
+  const renderers: RenderData["renderers"] = [];
+  const contentWidth = CANVAS_CONFIG.width - CANVAS_CONFIG.padding * 2;
+  let currentY = CANVAS_CONFIG.padding;
+
+  // 1. Background
+  renderers.push({
+    id: "background",
+    type: RendererType.IMG,
+    x: 0,
+    y: 0,
+    width: CANVAS_CONFIG.width,
+    height: CANVAS_CONFIG.height,
+    color: CANVAS_CONFIG.colors.background,
+    objectFit: "cover"
+  });
+
+  // 2. Decorative Dark Sun Circle (top right)
+  renderers.push({
+    id: "sun-circle",
+    type: RendererType.IMG,
+    x: CANVAS_CONFIG.width - 180,
+    y: -60,
+    width: 240,
+    height: 240,
+    color: CANVAS_CONFIG.colors.highlight,
+    radius: 120,
+    objectFit: "cover"
+  });
+
+  // 3. Title
+  const titleHeight = 80;
+  renderers.push({
+    id: "title",
+    type: RendererType.TEXT,
+    x: CANVAS_CONFIG.padding,
+    y: currentY,
+    width: contentWidth,
+    height: titleHeight,
+    content: "☀️ " + contentData.title,
+    style: {
+      fontName: CANVAS_CONFIG.fonts.title,
+      fontSize: 48,
+      color: CANVAS_CONFIG.colors.title,
+      fontWeight: "bold",
+      verticalAlign: "center"
+    }
+  });
+  currentY += titleHeight + 20;
+
+  // 4. Content Sections
+  const questionFontSize = 24;
+  const answerFontSize = 20;
+  const cardPadding = 24;
+
+  contentData.sections.forEach((section, index) => {
+    // Card background first (dark rounded rectangle)
+    const answerTextWidth = contentWidth - cardPadding * 2;
+    const textHeight = calcTextHeight(section.answer, answerFontSize, answerTextWidth, 12);
+    const cardHeight = textHeight + cardPadding * 2 + 50; // Extra space for question
+
+    renderers.push({
+      id: `card-bg-${index}`,
+      type: RendererType.IMG,
+      x: CANVAS_CONFIG.padding,
+      y: currentY,
+      width: contentWidth,
+      height: cardHeight,
+      color: CANVAS_CONFIG.colors.cardBg,
+      radius: 16,
+      objectFit: "cover"
+    });
+
+    // Question label inside card
+    const questionY = currentY + cardPadding;
+    renderers.push({
+      id: `q-${index}`,
+      type: RendererType.TEXT,
+      x: CANVAS_CONFIG.padding + cardPadding,
+      y: questionY,
+      width: contentWidth - cardPadding * 2,
+      height: 32,
+      content: "▸ " + section.question,
+      style: {
+        fontName: CANVAS_CONFIG.fonts.body,
+        fontSize: questionFontSize,
+        color: CANVAS_CONFIG.colors.question,
+        fontWeight: "bold",
+        verticalAlign: "center"
+      }
+    });
+
+    // Answer text inside card
+    const answerY = questionY + 40;
+    renderers.push({
+      id: `a-${index}`,
+      type: RendererType.TEXT,
+      x: CANVAS_CONFIG.padding + cardPadding,
+      y: answerY,
+      width: answerTextWidth,
+      height: textHeight + 20,
+      content: section.answer,
+      style: {
+        fontName: CANVAS_CONFIG.fonts.body,
+        fontSize: answerFontSize,
+        color: CANVAS_CONFIG.colors.answer,
+        verticalGap: 12,
+        verticalAlign: "top"
+      }
+    });
+
+    currentY += cardHeight + 24;
+  });
+
+  return renderers;
+}
+
+// Create canvas schema
+const schema: RenderData = {
+  id: "sunscreen-guide",
+  width: CANVAS_CONFIG.width,
+  height: CANVAS_CONFIG.height,
+  renderers: buildRenderers(),
+  output: {
+    type: "png"
+  }
+};
+
+// Main execution
+async function main() {
+  console.log("Generating fresh sunscreen guide image...");
+  console.log("Content:", JSON.stringify(contentData, null, 2));
+
+  const renderer = new Renderer(schema);
+  const buffer = await renderer.draw();
+
+  // Ensure output directory exists
+  const outputDir = path.join(__dirname, "output");
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  const outputPath = path.join(outputDir, "sunscreen-guide.png");
+  fs.writeFileSync(outputPath, buffer);
+
+  console.log(`Image saved to: ${outputPath}`);
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "declare-render",
+  "version": "1.0.0",
+  "description": "You can declare canvas shapes by JSON format.",
+  "main": "index.js",
+  "keywords": [
+    "JSON",
+    "Canvas",
+    "Renderer"
+  ],
+  "author": "Joey",
+  "license": "ISC",
+  "dependencies": {
+    "canvas": "^3.2.1",
+    "lodash-es": "^4.17.21"
+  },
+  "devDependencies": {
+    "@types/lodash-es": "^4.17.12",
+    "@types/node": "^20.19.30",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3"
+  },
+  "type": "module",
+  "scripts": {
+    "rebuild:canvas": "pnpm rebuild canvas"
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+onlyBuiltDependencies:
+  - canvas

package/src/canvas-renderers/base-renderer.ts

@@ -0,0 +1,16 @@
+import { ContainerRenderData } from "./container-renderer";
+import { ImgRenderData } from "./img-renderer";
+import { TextRenderData } from "./text-renderer/types";
+
+export abstract class BaseRender<
+  T extends TextRenderData | ImgRenderData | ContainerRenderData,
+> {
+  protected data!: T;
+  abstract get container(): { x1: number; x2: number; y1: number; y2: number };
+  abstract layout(): Promise<this>;
+  public setPosition = (x: number, y: number) => {
+    this.data.x = x;
+    this.data.y = y;
+    return this.layout();
+  };
+}

package/src/canvas-renderers/container-renderer/index.ts

@@ -0,0 +1,151 @@
+import { ChildRenderers, RendererType } from "../../types";
+import { type CanvasRenderingContext2D } from "canvas";
+import { cloneDeep, isNumber, isObject, isUndefined } from "lodash-es";
+import { BaseRender } from "../base-renderer";
+import { ImgRenderData, ImgRender } from "../img-renderer/index";
+import { TextRenderData } from "../text-renderer/types";
+import { TextRender } from "../text-renderer/index";
+
+export interface ContainerRenderData {
+  id: string | number
+  type: RendererType.CONTAINER,
+  x: number, // The x coordinate of the container's start point. In container renderers, as a child renderer, 0 means relative to the container's 0; if not declared, its position depends on adjacent renderers and spacing.
+  y: number, // The y coordinate of the container's start point. As a child renderer, 0 means relative to the container's 0; if not declared, its position depends on adjacent renderers and spacing.
+  width: number, // The width of the container renderer
+  height: number // The height of the container renderer
+  direction?: "row" | "column" // The layout direction of the container (horizontal/vertical)
+  itemAlign?: "center" // The alignment of container elements in the secondary direction (vertical/horizontal)
+  gap?: number | {x: number, y: number} // The distance between elements
+  wrap?: boolean; // Whether elements wrap if overflow
+  renderers: ChildRenderers // Child renderers declaration
+}
+
+export class ContainerRenderer extends BaseRender<ContainerRenderData> {
+  private ctx: CanvasRenderingContext2D
+  private renderers: Array<ImgRender | TextRender | ContainerRenderer> = []
+
+  constructor(ctx: CanvasRenderingContext2D, data: ContainerRenderData) {
+    super()
+    this.ctx = ctx
+    this.data = cloneDeep(data)
+    this.ctx.patternQuality = 'best'
+    this.ctx.quality = 'best'
+  }
+
+  get container() {
+    return this.getContainerCoordinates()
+  }
+
+  private createRenderer = (renderData: ImgRenderData | TextRenderData | ContainerRenderData) => {
+    switch (renderData.type) {
+      case RendererType.TEXT: {
+        return new TextRender(this.ctx, renderData, { inFlexFlow: isUndefined(renderData.x) || isUndefined(renderData.y) })
+      }
+      case RendererType.IMG:
+        return new ImgRender(this.ctx, renderData)
+      case RendererType.CONTAINER:
+        return new ContainerRenderer(this.ctx, renderData)
+      default:
+        throw new Error("[Renderer] unknown renderer type")
+    }
+  }
+
+  // TODO center the renderers, vertical center, left align, wrap the renderers;
+  public layout = async () => {
+    const layoutedRenderers = [] as Array<ImgRender | TextRender | ContainerRenderer>
+
+    for (const index in this.data.renderers) {
+      const renderData = cloneDeep(this.data.renderers[index]) as ImgRenderData | TextRenderData | ContainerRenderData
+
+      let renderX = renderData.x
+      let renderY = renderData.y
+      // 子 renderer 的 x、y 相对容器的 x、y 进行定位
+      if (isNumber(renderX)) {
+        renderX += this.data.x
+      }
+
+      if (isNumber(renderY)) {
+        renderY += this.data.y
+      }
+
+      // justify
+      if (isUndefined(renderX) || isUndefined(renderY)) {
+        const preRenderer = layoutedRenderers.at(-1) as undefined | ImgRender | TextRender | ContainerRenderer
+        const { x2, y1, x1, y2 } = preRenderer?.container || { x1: this.data.x, x2: this.data.x, y1: this.data.y, y2: this.data.y }
+
+        const gapX = !preRenderer ?
+          0 : isObject(this.data.gap) ?
+            this.data.gap.x : (this.data.gap || 0)
+
+        const gapY = !preRenderer ?
+          0 : isObject(this.data.gap) ?
+            this.data.gap.y : (this.data.gap || 0)
+
+        if (this.data.direction === 'column') {
+          renderX = renderX || x1
+          renderY = renderY || (y2 + gapY)
+        } else {
+          renderX = renderX || (x2 + gapX)
+          renderY = renderY || y1
+        }
+      }
+
+      const currentRenderer = this.createRenderer({ ...renderData, x: renderX, y: renderY })
+
+      await currentRenderer.layout()
+      
+      layoutedRenderers.push(currentRenderer)
+    }
+
+    // align items
+    if (this.data.itemAlign === 'center') {
+      const squares = layoutedRenderers.map(r => {
+        const { x1, x2, y1, y2 } = r.container
+        return { ...r.container, width: x2 - x1, height: y2 - y1, renderer: r }
+      })
+
+      const maxWidth = Math.max(...squares.map(s => s.width))
+      const maxHeight = Math.max(...squares.map(s => s.height))
+
+      squares.forEach(s => {
+        if (this.data.direction === 'column') {
+          const offset = (maxWidth - s.width) / 2
+          s.renderer.setPosition(s.x1 + offset, s.y1)
+        } else {
+          const offset = (maxHeight - s.height) / 2
+          s.renderer.setPosition(s.x1, s.y1 + offset)
+        }
+      })
+    }
+
+    this.renderers = layoutedRenderers
+    return this
+  }
+
+  // TODO rotate the whole renderer
+  public draw = async() => {
+    if (!this.renderers.length) {
+      return this
+    }
+
+    const pickedOne = this.renderers.shift()!
+    await pickedOne.draw()
+
+    await this.draw()
+
+    return this
+  }
+
+  // TODO handle the renderers wrapping, add gap;
+  private getContainerCoordinates = () => {
+    if (!this.renderers.length) throw new Error("can not get container coordinates before layouted")
+    const firstChild = this.renderers.at(0) as ImgRender | TextRender
+    const lastChild = this.renderers.at(-1) as ImgRender | TextRender
+    return {
+      x1: firstChild.container.x1,
+      y1: firstChild.container.y1,
+      x2: lastChild.container.x2,
+      y2: lastChild.container.y2,
+    }
+  }
+}

package/src/canvas-renderers/img-renderer/index.ts

@@ -0,0 +1,198 @@
+import { BaseRender } from "../base-renderer";
+import { cloneDeep, isNumber } from "lodash-es";
+import { loadImage, Image, type CanvasRenderingContext2D } from "canvas";
+import { getImageHeight, getImageRatio, getImageWidth } from "./utils";
+
+export type ImgRenderData = {
+  id: string;
+  type: "img";
+  x: number; // The x-coordinate of the image container's starting point. When used as a child in a container renderer, 0 means positioned relative to the container's 0. If not specified, the position is determined by adjacent renderers and gap.
+  y: number; // The y-coordinate of the image container's starting point. As a child, 0 means positioned relative to the container's 0. If not specified, the position is determined by adjacent renderers and gap.
+  /*
+  If both width and height are provided, they determine the image's width and height.
+  If only width or height is provided, the other will be determined proportionally.
+  If neither width nor height is provided, the image will be rendered at its original dimensions.
+  */
+  width?: number; // The width of the image container
+  height?: number; // The height of the image container
+  shadow?: {
+    // The shadow of the image container. Can be added directly to the rendered shape, instead of rendering a separate renderer.
+    color: string; // The shadow color
+    blur: number; // Shadow blur
+    X: number; // Shadow offset on the x-axis
+    Y: number; // Shadow offset on the y-axis
+  };
+  radius?: number; // The corner radius of the image container
+  url?: string; // Image source
+  color?: string; // Background color. If url is not provided, a pure color block will be rendered.
+  rotate?: number; // The angle, calculated from the center point
+  globalAlpha?: number; // Opacity
+  objectFit: "contain" | "cover"; // If both width and height are provided, determines how the image fits within the container
+};
+
+export class ImgRender extends BaseRender<ImgRenderData> {
+  ctx: CanvasRenderingContext2D;
+  width: number = 0;
+  height: number = 0;
+  imageWidth: number = 0;
+  imageHeight: number = 0;
+  data: ImgRenderData;
+
+  private image?: Image;
+
+  constructor(ctx: CanvasRenderingContext2D, data: ImgRenderData) {
+    super();
+    this.ctx = ctx;
+    this.data = cloneDeep(data);
+  }
+
+  get container() {
+    return this.getContainerCoordinates();
+  }
+
+  private async drawImage(x: number, y: number, image: Image) {
+    const marginX = this.width - this.imageWidth;
+    const marginY = this.height - this.imageHeight;
+
+    this.ctx.save();
+
+    if (isNumber(this.data.globalAlpha)) {
+      this.ctx.globalAlpha = this.data.globalAlpha;
+    }
+
+    if (this.data.shadow) {
+      this.ctx.shadowBlur = this.data.shadow.blur;
+      this.ctx.shadowColor = this.data.shadow.color;
+      this.ctx.shadowOffsetX = this.data.shadow.X || 0;
+      this.ctx.shadowOffsetY = this.data.shadow.Y || 0;
+    }
+
+    this.ctx.drawImage(
+      image,
+      x + marginX / 2,
+      y + marginY / 2,
+      this.imageWidth,
+      this.imageHeight,
+    );
+    this.ctx.restore();
+  }
+
+  private drawColor(x: number, y: number) {
+    const { width, height } = this;
+    this.ctx.save();
+
+    if (!this.data.color) return;
+
+    this.ctx.fillStyle = this.data.color;
+    this.ctx.beginPath();
+    this.ctx.roundRect(x, y, width, height, this.data.radius || 0);
+    this.ctx.fill();
+    this.ctx.restore();
+  }
+
+  layout = async () => {
+    const { url, width, height } = this.data;
+    const image = url ? await loadImage(url) : null;
+
+    if (!image) {
+      if (!width || !height) {
+        throw new Error("img renderer without url should specify size");
+      }
+      this.width = width;
+      this.height = height;
+      this.imageWidth = 0;
+      this.imageHeight = 0;
+      return this;
+    }
+
+    this.image = image;
+
+    if (!width) {
+      if (!height) {
+        this.imageWidth = image.naturalWidth;
+        this.imageHeight = image.naturalHeight;
+        this.width = this.imageWidth;
+        this.height = this.imageHeight;
+      } else {
+        this.imageWidth = getImageWidth(image, height);
+        this.imageHeight = height;
+        this.width = this.imageWidth;
+        this.height = this.imageHeight;
+      }
+    } else {
+      if (!height) {
+        this.imageWidth = width;
+        this.imageHeight = getImageHeight(image, width);
+        this.width = this.imageWidth;
+        this.height = this.imageHeight;
+      } else {
+        const ratio = getImageRatio(image);
+        const objectFit = this.data.objectFit || "contain";
+
+        if (objectFit === "cover" ? ratio > 1 : ratio <= 1) {
+          this.imageWidth = getImageWidth(image, height);
+          this.imageHeight = height;
+        } else {
+          this.imageWidth = width;
+          this.imageHeight = getImageHeight(image, width);
+        }
+        this.width = width;
+        this.height = height;
+      }
+    }
+    return this;
+  };
+
+  draw = async () => {
+    const { x, y, rotate } = this.data;
+    const drawImpl = async (x: number, y: number) => {
+      if (this.data.color) {
+        this.drawColor(x, y);
+      }
+
+      if (this.image) {
+        await this.drawImage(x, y, this.image);
+      }
+    };
+
+    if (!rotate) {
+      await drawImpl(x, y);
+    } else {
+      const { width, height } = this;
+
+      this.ctx.save();
+
+      const actualHeight = height
+        ? height
+        : !this.image
+          ? 0
+          : (this.image.naturalHeight / this.image.naturalWidth) * width;
+
+      this.ctx.translate(x + width / 2, y + actualHeight / 2);
+
+      this.ctx.rotate((rotate * Math.PI) / 180);
+
+      this.ctx.translate(-(x + width / 2), -(y + actualHeight / 2));
+
+      await drawImpl(x, y);
+      
+      this.ctx.restore();
+    }
+
+    return this;
+  };
+
+  public getContainerCoordinates = () => {
+    const { x, y } = this.data;
+
+    const { width, height } = this;
+    return {
+      x1: x,
+      y1: y,
+
+      x2: x + width,
+
+      y2: y + height!,
+    };
+  };
+}

package/src/canvas-renderers/img-renderer/utils.ts

@@ -0,0 +1,15 @@
+import { Image } from "canvas";
+
+export function getImageRatio(image: Image) {
+  return image.naturalWidth / image.naturalHeight
+}
+
+export function getImageHeight(image: Image, width: number) {
+  const ratio = image.naturalWidth / image.naturalHeight
+  return width / ratio
+}
+
+export function getImageWidth(image: Image, height: number) {
+  const ratio = image.naturalWidth / image.naturalHeight
+  return height * ratio
+}

package/src/canvas-renderers/text-renderer/highlighter.ts

@@ -0,0 +1,78 @@
+import { CanvasRenderingContext2D, Image } from "canvas";
+import { MetricsCharWithCoordinates } from "../../types";
+import { TextRenderData } from "./types";
+
+export enum HighlightType {
+  UNDERLINE = "underline",
+  COLORED = "colored",
+  HALF_RECTANGLE = "halfRectangle",
+  SVG = "svg",
+}
+
+export class Highlighter {
+  ctx: CanvasRenderingContext2D;
+  static highlightByChar = [
+    HighlightType.UNDERLINE,
+    HighlightType.COLORED,
+    HighlightType.HALF_RECTANGLE,
+  ] as const;
+  static highlightByWord = [HighlightType.SVG] as const;
+
+  constructor(ctx: CanvasRenderingContext2D) {
+    this.ctx = ctx;
+  }
+
+  svg(
+    word: MetricsCharWithCoordinates[],
+    svgImage: Image,
+    style: NonNullable<TextRenderData["style"]["highlight"]>["style"],
+  ) {
+    const width = word.reduce((sum, c) => sum + c.metrics.width, 0);
+    const startY = style?.coverText
+      ? word[0].Y - word[0].boundingHeight
+      : word[0].Y;
+    const height = style?.coverText ? word[0].boundingHeight : style?.height;
+    this.ctx.drawImage(
+      svgImage,
+      word[0].X,
+      startY + (style?.offsetY || 0),
+      width,
+      height || word[0].boundingHeight,
+    );
+  }
+
+  colorText = (c: MetricsCharWithCoordinates, color: string) => {
+    this.ctx.save();
+    this.ctx.fillStyle = color;
+    this.ctx.fillText(c.char, c.X, c.Y);
+    this.ctx.restore();
+  };
+
+  rectFill = (c: MetricsCharWithCoordinates, color: string) => {
+    this.ctx.save();
+    this.ctx.fillStyle = color;
+    this.ctx.fillRect(
+      c.X,
+      c.Y - Math.abs(c.metrics.alphabeticBaseline) - 4,
+      c.metrics.width,
+      c.emHeight / 3,
+    );
+    this.ctx.restore();
+    this.ctx.fillText(c.char, c.X, c.Y);
+  };
+
+  underLine = (c: MetricsCharWithCoordinates, color: string) => {
+    const x = c.X;
+    const y = c.Y;
+    this.ctx.beginPath();
+    this.ctx.strokeStyle = color;
+    this.ctx.lineWidth = 8;
+    this.ctx.moveTo(x, y + c.metrics.actualBoundingBoxDescent);
+    this.ctx.lineTo(
+      x + c.metrics.width,
+      y + c.metrics.actualBoundingBoxDescent,
+    );
+    this.ctx.stroke();
+    this.ctx.fillText(c.char, c.X, c.Y);
+  };
+}

package/src/canvas-renderers/text-renderer/index.ts

@@ -0,0 +1,390 @@
+import { Image, loadImage, type CanvasRenderingContext2D } from "canvas";
+import {
+  cloneDeep,
+  groupBy,
+  isNumber,
+  isObject,
+  isUndefined,
+  last,
+  map,
+  values,
+} from "lodash-es";
+import { BaseRender } from "../base-renderer";
+import { TextRenderData, highlightLogics } from "./types";
+
+import { MetricsCharWithCoordinates } from "../../types";
+import { MetricsChar } from "../../types";
+import { Highlighter, HighlightType } from "./highlighter";
+
+const rightFlow =
+  <T>(opts: any[]) =>
+  () =>
+    opts.reverse().reduce((ret, cur) => cur(ret), undefined) as T;
+
+export class TextRender extends BaseRender<TextRenderData> {
+  private ctx: CanvasRenderingContext2D;
+  private highlighter: Highlighter;
+  private lines: MetricsCharWithCoordinates[][] = [];
+  private svg?: Image;
+
+  constructor(
+    ctx: CanvasRenderingContext2D,
+    data: TextRenderData,
+    options?: { inFlexFlow?: boolean },
+  ) {
+    super();
+    this.ctx = ctx;
+    this.data = cloneDeep(data);
+    this.highlighter = new Highlighter(ctx);
+
+    if (options?.inFlexFlow) {
+      this.data.style.verticalAlign = undefined;
+      this.data.style.align = undefined;
+    }
+  }
+
+  get container() {
+    if (!this.lines) {
+      throw new Error("can not get container before layout in text renderer");
+    }
+    return this.getContainerCoordinates(this.lines);
+  }
+
+  public layout = async () => {
+    const highlightSVGUrl = this.data.style.highlight?.style?.url;
+
+    if (highlightSVGUrl) {
+      const image = await loadImage(highlightSVGUrl);
+      this.svg = image;
+    }
+
+    const lines = rightFlow<MetricsCharWithCoordinates[][]>([
+      this.coordinateLines,
+      this.metricsLines,
+      this.ensureFontStyles,
+      this.parseFontSize,
+    ])();
+
+    this.lines = lines;
+    return this;
+  };
+
+  public draw = () => {
+    rightFlow<MetricsCharWithCoordinates[][]>([
+      this.restoreRotatedCanvas,
+      this.drawChars,
+      () => this.drawBackground(this.lines),
+      this.rotateCanvas,
+      this.ensureFontStyles,
+    ])();
+    return this;
+  };
+
+  private restoreRotatedCanvas = () => {
+    const { rotate } = this.data;
+    if (rotate) {
+      this.ctx.restore();
+    }
+  };
+
+  private parseFontSize = () => {
+    const fontSize = this.data.style.fontSize;
+
+    if (isObject(fontSize)) {
+      const fontObject = fontSize as { max: number; min: number };
+      const count = this.data.content.length;
+      const { horizonalGap = 0 } = this.data.style;
+      const maxWidth = this.data.width;
+
+      this.data.style.fontSize = Math.min(
+        Math.max(
+          (maxWidth - (count - 1) * horizonalGap) / count,
+          fontObject.min,
+        ),
+        fontObject.max,
+      );
+    }
+  };
+
+  private rotateCanvas = () => {
+    const { x, y, rotate, width, height } = this.data;
+
+    if (rotate) {
+      this.ctx.save();
+      this.ctx.translate(x + width / 2, y + height / 2);
+      this.ctx.rotate((rotate * Math.PI) / 180);
+      this.ctx.translate(-(x + width / 2), -(y + height / 2));
+    }
+  };
+
+  private ensureFontStyles = () => {
+    const fontSize = this.data.style.fontSize;
+    const fontName = this.data.style.fontName;
+    const fontWeight = this.data.style.fontWeight || "";
+    this.ctx.font = `${fontSize}px ${fontWeight} "${fontName}"`;
+  };
+
+  private metricsLines = () => {
+    const containerWidth = this.data.width;
+    const horizonalGap = this.data.style.horizonalGap || 0;
+    const fontSize = this.data.style.fontSize;
+    const oneLineMaxWidth = containerWidth;
+
+    if (!isNumber(fontSize)) {
+      throw new Error("[Renderer] field fontSize should be number type");
+    }
+
+    return this.data.content
+      .split("")
+      .map((char, index) => {
+        const metrics = this.ctx.measureText(char) as MetricsChar["metrics"];
+        const boundingHeight =
+          metrics.actualBoundingBoxAscent + metrics.actualBoundingBoxDescent;
+        const emHeight = metrics.emHeightAscent + metrics.emHeightDescent;
+        return { char, metrics, index, fontSize, boundingHeight, emHeight };
+      })
+      .reduce<MetricsChar[][]>(
+        (lines, metricsChar) => {
+          const lastLine = lines.at(-1)!;
+
+          const curWidth = lastLine.reduce((sumWidth, cur, index) => {
+            if (index !== 0 && index !== lastLine.length) {
+              return cur.metrics.width + horizonalGap + sumWidth;
+            }
+            return cur.metrics.width + sumWidth;
+          }, 0);
+          if (curWidth + metricsChar.metrics.width > oneLineMaxWidth) {
+            lines.push([metricsChar]);
+          } else {
+            lastLine.push(metricsChar);
+          }
+          return lines;
+        },
+        [[]],
+      );
+  };
+
+  private drawChar = (c: MetricsCharWithCoordinates) => {
+    this.ctx.fillStyle = this.data.style.color;
+    this.ctx.fillText(c.char, c.X, c.Y);
+    if (this.data.style.border) {
+      this.ctx.save();
+
+      this.ctx.lineWidth = this.data.style.border.width || 1;
+      this.ctx.strokeStyle = this.data.style.border.color;
+      this.ctx.strokeText(c.char, c.X, c.Y);
+
+      this.ctx.restore();
+    }
+  };
+
+  private coordinateLines = (lines: MetricsChar[][]) => {
+    const {
+      width: containerWidth,
+      height: containerHeight,
+      x: containerStartX,
+      y: containerStartY,
+    } = this.data;
+    const { fontSize, verticalGap = 0, horizonalGap = 0 } = this.data.style;
+
+    if (!isNumber(fontSize)) {
+      throw new Error("[Renderer] field fontSize should be number type");
+    }
+
+    const boundingHeightsSum = lines
+      .map((line) => Math.max(...line.map((c) => c.boundingHeight)))
+      .reduce((ret, maxHeightAline) => ret + maxHeightAline, 0);
+    const totalVerticalGap = (lines.length - 1) * verticalGap;
+
+    const paddingY = (() => {
+      switch (this.data.style.verticalAlign) {
+        case "center":
+          return (containerHeight - boundingHeightsSum - totalVerticalGap) / 2;
+        case "bottom":
+          return containerHeight - boundingHeightsSum - totalVerticalGap;
+        case "top":
+        default:
+          return 0;
+      }
+    })();
+
+    let preY = containerStartY + paddingY;
+
+    return lines.map((mline, lineIndex) => {
+      const currentLineWidth =
+        mline.reduce((sum, mc) => sum + mc.metrics.width, 0) +
+        (horizonalGap * mline.length - 1);
+
+      const paddingLeft = (() => {
+        switch (this.data.style.align) {
+          case "center":
+            return (containerWidth - currentLineWidth) / 2;
+          case "right":
+            return containerWidth - currentLineWidth;
+          default:
+            return 0;
+        }
+      })();
+
+      let preX = containerStartX + paddingLeft;
+
+      const maxHeightAline = Math.max(
+        ...mline.map((c) => c.metrics.actualBoundingBoxAscent),
+      );
+
+      let Y = (preY =
+        preY + maxHeightAline + (lineIndex === 0 ? 0 : verticalGap));
+
+      return mline.map((mseg, index) => {
+        const _gap = index === 0 ? 0 : horizonalGap;
+
+        const preWidth = mline[index - 1]?.metrics.width || 0;
+
+        let X = (preX = preX + _gap + preWidth);
+
+        return { ...mseg, X, Y };
+      });
+    });
+  };
+
+  private drawChars = (lines: MetricsCharWithCoordinates[][]) => {
+    const { highlight } = this.data.style;
+    if (!highlight || !highlight.type) {
+      lines.flat().forEach(this.drawChar);
+      return lines;
+    }
+
+    const highlightWord = highlightLogics.word;
+
+    const startIndex = this.data.content.indexOf(highlightWord);
+
+    const highlightChars = lines
+      .map((line, lineIndex) => line.map((c) => ({ lineIndex, c })))
+      .flat()
+      .map(({ lineIndex, c }, cIndex) => ({ lineIndex, cIndex, c }))
+      .slice(startIndex, startIndex + highlightWord.length)
+      .map(({ c, cIndex, lineIndex }) => ({
+        ...c,
+        cIndex: cIndex,
+        lineIndex: lineIndex,
+      }));
+
+    const highlightType = highlight.type;
+
+    if (
+      Highlighter.highlightByChar.includes(
+        highlightType as (typeof Highlighter.highlightByChar)[number],
+      )
+    ) {
+      const indexes = map(highlightChars, "cIndex");
+      lines
+        .flat()
+        .filter((c) => indexes.includes(c.index))
+        .forEach((c) => {
+          if (!highlight.color)
+            throw new Error(
+              "color is required for highlight type:" + highlightType,
+            );
+          switch (highlightType) {
+            case HighlightType.COLORED:
+              this.highlighter.colorText(c, highlight.color);
+              break;
+            case HighlightType.HALF_RECTANGLE:
+              this.highlighter.rectFill(c, highlight.color);
+              break;
+            case HighlightType.UNDERLINE:
+              this.highlighter.underLine(c, highlight.color);
+              break;
+            default:
+              throw new Error(
+                `[Renderer] unknown highlight type with ${highlightType})`,
+              );
+          }
+        });
+      lines
+        .flat()
+        .filter((c) =>
+          highlight && indexes.length ? !indexes.includes(c.index) : true,
+        )
+        .forEach(this.drawChar);
+      return lines;
+    }
+
+    switch (highlight.type) {
+      case HighlightType.SVG:
+        values(groupBy(highlightChars, "lineIndex")).forEach((chars) => {
+          if (!highlight.style)
+            throw new Error("style field is required for highlight type: ");
+          if (!this.svg)
+            throw new Error(
+              "svg url in highlight style is not correct: " + highlight.style,
+            );
+          this.highlighter.svg(chars, this.svg, highlight.style);
+        });
+        lines.flat().forEach(this.drawChar);
+        break;
+      default:
+        break;
+    }
+
+    return lines;
+  };
+
+  private drawBackground = (lines: MetricsCharWithCoordinates[][]) => {
+    if (!this.data.style.backgroundColor) return lines;
+    const { x1, y1, x2, y2 } = this.getContainerCoordinates(lines);
+
+    this.ctx.save();
+
+    this.ctx.fillStyle = this.data.style.backgroundColor;
+
+    this.ctx.beginPath();
+
+    this.ctx.roundRect(x1, y1, x2 - x1, y2 - y1, this.data.style.radius || 0);
+
+    this.ctx.fill();
+
+    this.ctx.restore();
+
+    return lines;
+  };
+
+  private getContainerCoordinates = (lines: MetricsCharWithCoordinates[][]) => {
+    const { horizonalGap = 0, padding } = this.data.style;
+
+    if (!lines) throw new Error("can not get text coordinates before layouted");
+
+    const maxWidth = lines.reduce(
+      (maxWidth, line) =>
+        Math.max(
+          maxWidth,
+          line.reduce((sum, mc) => sum + mc.metrics.width, 0) +
+            horizonalGap * (line.length - 1),
+        ),
+      0,
+    );
+
+    const startWord = lines[0][0];
+    const endWord = last(last(lines))!;
+
+    const actualPadding = isUndefined(padding)
+      ? { x: 0, y: 0 }
+      : isObject(padding)
+        ? padding
+        : { x: padding, y: padding };
+
+    const firstLineTopest = Math.max(
+      ...lines[0].map((c) => c.metrics.actualBoundingBoxAscent),
+    );
+
+    const x1 = startWord.X - actualPadding.x;
+    const y1 = startWord.Y - firstLineTopest - actualPadding.y;
+    return {
+      x1,
+      y1,
+      x2: x1 + maxWidth + actualPadding.x * 2,
+      y2:
+        endWord.Y + endWord.metrics.actualBoundingBoxDescent + actualPadding.y,
+    };
+  };
+}

package/src/canvas-renderers/text-renderer/types.ts

@@ -0,0 +1,48 @@
+import { RendererType } from "../../types";
+import { HighlightType } from "./highlighter";
+
+export enum highlightLogics {
+  word = "word",
+}
+
+export interface TextRenderData {
+  id: string | number;
+  type: RendererType.TEXT; // Always "text"
+  x: number; // The x-coordinate of the text container's starting point. As a child, 0 means relative to the container's origin. If not specified, the position depends on adjacent renderers and spacing.
+  y: number; // The y-coordinate of the text container's starting point. As a child, 0 means relative to the container's origin. If not specified, the position depends on adjacent renderers and spacing.
+  width: number; // The width of the text container. Exceeding text will wrap.
+  height: number; // The height of the text container. Exceeding text will overflow.
+  rotate?: number; // Rotation angle, calculated from the center of the object
+  content: string; // Text content
+  style: {
+    // Text style customization
+    /* This property should currently be disabled when under a container; */
+    align?: "center" | "right"; // Text horizontal alignment
+    /* This property should currently be disabled when under a container; */
+    verticalAlign?: "center" | "top" | "bottom"; // Text vertical alignment
+    fontName: string; // Font name. Supported fonts are:
+    fontSize: number | { max: number; min: number }; // Font size. Supports objects for adaptive width to fill container.
+    backgroundColor?: string; // Text background color
+    padding?: number | { x: number; y: number }; // Text padding
+    border?: { color: string; width?: number }; // Text border
+    color: string; // Text color
+    radius?: number; // Text background border radius
+    verticalGap?: number; // Line gap
+    horizonalGap?: number; // Gap between characters in the same line
+    fontWeight?: string; // Font weight, same as CSS
+    highlight?: {
+      // Text highlight style
+      logics: highlightLogics; // Highlight word logic
+      color?: string; // Highlight color. When highlight type is not svg, this field is optional.
+      content?: string; // Highlighted text content. When highlight type is not svg, this field is optional.
+      type?: HighlightType; // Highlight style
+      style?: {
+        // When highlight type is not svg, this field should be empty
+        height?: number; // Height of the highlight graphic
+        offsetY?: number; // Vertical offset of the highlight graphic from the top, starting at the text rectangle point
+        coverText?: boolean; // Whether the highlight should cover the text. If true, height is set to text height
+        url: string; // Source of the highlight graphic
+      };
+    };
+  };
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+import { Canvas, createCanvas, type CanvasRenderingContext2D } from "canvas";
+import { RenderData, RendererType } from "./types";
+import { ContainerRenderer } from "./canvas-renderers/container-renderer/index";
+
+export class Renderer {
+  canvas: Canvas;
+  schema: RenderData;
+  ctx: CanvasRenderingContext2D;
+
+  constructor(schema: RenderData) {
+    const { width, height } = schema;
+    this.schema = schema;
+    this.canvas = createCanvas(width, height);
+    this.ctx = this.canvas.getContext("2d");
+  }
+
+  draw = async () => {
+    if (!this.schema.renderers.length) {
+      throw new Error("[Renderer] empty canvas with no renderers");
+    }
+    const container = new ContainerRenderer(this.ctx, {
+      id: this.schema.id,
+      type: RendererType.CONTAINER,
+      x: 0,
+      y: 0,
+      width: this.canvas.width,
+      height: this.canvas.height,
+      renderers: this.schema.renderers,
+    });
+    await container.layout().then((d) => d.draw());
+    return this.toBuffer();
+  };
+
+  private toBuffer() {
+    const type = this.schema.output?.type || "png";
+    switch (type) {
+      case "jpg":
+        // @ts-ignore
+        return this.canvas.toBuffer("image/jpeg", { alpha: true });
+      case "png":
+        // @ts-ignore
+        return this.canvas.toBuffer("image/png", { alpha: true });
+      default:
+        throw new Error("[Renderer] unknown output type");
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,40 @@
+import { ContainerRenderData } from "./canvas-renderers/container-renderer";
+import { ImgRenderData } from "./canvas-renderers/img-renderer";
+import { TextRenderData } from "./canvas-renderers/text-renderer/types";
+import type { TextMetrics } from "canvas";
+
+export interface RenderData {
+  id: string;
+  width: number;
+  height: number;
+  renderers: (ImgRenderData | TextRenderData | ContainerRenderData)[];
+  output?: {
+    type?: "png" | "jpg";
+  };
+}
+
+export enum RendererType {
+  CONTAINER = "container",
+  TEXT = "text",
+  IMG = "img",
+}
+
+export interface MetricsChar {
+  char: string;
+  index: number;
+  emHeight: number;
+  fontSize: number;
+  metrics: TextMetrics & {
+    alphabeticBaseline: number;
+    emHeightAscent: number;
+    emHeightDescent: number;
+  };
+  boundingHeight: number;
+}
+
+export interface MetricsCharWithCoordinates extends MetricsChar {
+  X: number;
+  Y: number;
+}
+
+export type ChildRenderers = (ImgRenderData | TextRenderData | ContainerRenderData)[];

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020"],
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "ts-node": {
+    "esm": true,
+    "experimentalSpecifierResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}