# lucidedit/x-image architecture

> Architecture diagram of the GitHub repository lucidedit/x-image, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucidedit/x-image
- Repository: https://github.com/lucidedit/x-image

## Overview

##### Project type and purpose
- Type: Standalone client-side NPM library
- Purpose: Convert arbitrary HTML + text into a styled PNG image (download or data URL)
- Audience: Frontend applications (browser) that import `beautiful-text-images`

##### Top-level components
A. Consumer (Browser app / React / Vanilla JS)
B. x-image Package Entry
1. API Layer (`src/index.ts` → `createBeautifulTextImage`)
C. Core Services (inside `src/lib/`)
- get-theme-by-name
- load-fonts
- inject-custom-css
- apply-styles-to-html
D. Themes Module (`src/themes/` + manifest in `src/themes/index.ts`)
E. External Dependencies
- html-to-image (renders styled DOM → Canvas → PNG)
- Google Fonts / external font URLs
F. Browser Environment
- DOM (temporary container)
- Canvas API

##### Data flow & interactions
1. Consumer calls `createBeautifulTextImage(html, options)`
2. API Layer consults Themes Module → `getThemeByName(themeName)`
3. Core Services orchestrate:
a. `loadFonts(theme.fontLinks)` → network fetch to Google Fonts → inject `<link>`
b. Create hidden DOM container → apply `wrapperStyle` + elementStyles via `applyStylesToHtml`
c. `injectCustomCss(theme.customCSS)` → `<style>` tag in `<head>`
4. Hand off styled DOM node to html-to-image → renders to Canvas → PNG blob or dataURL
5. Return to consumer (download trigger or data URL)
6. Cleanup: remove temporary DOM elements

##### Architectural patterns & principles
- Modular separation of concerns (theme lookup vs styling vs rendering)
- Plug-in style theming (themes are simple JS objects, strategy pattern)
- Client-side rendering pipeline (DOM → Canvas → PNG)
- Async operations with Promises (font loading, rendering delay)

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef api fill:#e0f0ff,stroke:#0366d6;
    classDef core fill:#e0f7ff,stroke:#0284c7;
    classDef themes fill:#e6ffed,stroke:#22863a;
    classDef external fill:#fff5b1,stroke:#cf8a00;
    classDef env fill:#f0f0f0,stroke:#6a737d;

    Consumer["Consumer App"]:::env

    subgraph "Browser Environment"
        Consumer
        Canvas["Canvas API"]:::env
        Output["Data URL / Download"]:::env
    end

    subgraph "x-image Package"
        API["createBeautifulTextImage()"]:::api
        getTheme["getThemeByName()"]:::core
        CoreLoad["loadFonts()"]:::core
        CoreInject["injectCustomCss()"]:::core
        CoreApply["applyStylesToHtml()"]:::core

        subgraph "Themes Module"
            ThemeIndex["index.ts"]:::themes
            A4["a4-poster.ts"]:::themes
            BE["book-excerpt.ts"]:::themes
            DM["dark-mono-poster.ts"]:::themes
            HB["highlighted-book.ts"]:::themes
            M["manifesto.ts"]:::themes
        end
    end

    htmlToImage["html-to-image"]:::external
    GoogleFonts["Google Fonts URL"]:::external

    Consumer -->|"calls"| API
    API -->|"lookup theme"| getTheme
    getTheme -->|"reads manifest"| ThemeIndex
    ThemeIndex --> A4
    ThemeIndex --> BE
    ThemeIndex --> DM
    ThemeIndex --> HB
    ThemeIndex --> M
    API --> CoreLoad
    CoreLoad -->|"fetch fonts"| GoogleFonts
    CoreLoad --> CoreInject
    API --> CoreInject
    API --> CoreApply
    CoreApply --> htmlToImage
    htmlToImage --> Canvas
    Canvas --> Output
    Output -->|"returns"| Consumer

    click API "https://github.com/lucidedit/x-image/blob/main/src/index.ts"
    click getTheme "https://github.com/lucidedit/x-image/blob/main/src/lib/get-theme-by-name.ts"
    click CoreLoad "https://github.com/lucidedit/x-image/blob/main/src/lib/load-fonts.ts"
    click CoreInject "https://github.com/lucidedit/x-image/blob/main/src/lib/inject-custom-css.ts"
    click CoreApply "https://github.com/lucidedit/x-image/blob/main/src/lib/apply-styles-to-html.ts"
    click ThemeIndex "https://github.com/lucidedit/x-image/blob/main/src/themes/index.ts"
    click A4 "https://github.com/lucidedit/x-image/blob/main/src/themes/a4-poster.ts"
    click BE "https://github.com/lucidedit/x-image/blob/main/src/themes/book-excerpt.ts"
    click DM "https://github.com/lucidedit/x-image/blob/main/src/themes/dark-mono-poster.ts"
    click HB "https://github.com/lucidedit/x-image/blob/main/src/themes/highlighted-book.ts"
    click M "https://github.com/lucidedit/x-image/blob/main/src/themes/manifesto.ts"
```
