Embedding API

Relevant source files

The following files were used as context for generating this wiki page:

• src/embed.ts
• src/app/script/embed/bootstrap/embed-wrapper.ts
• src/app/script/main-embed.ts
• examples/embed/example.html
• src/app/script/klecks/kl-config.ts
• src/app/script/bb/base/base.ts

The Embedding API allows developers to integrate the Klecks painting application into external websites and drawing communities. It provides a specialized version of the application that can be instantiated as a widget, enabling features such as project loading, PSD/PNG exporting, and custom submission flows. Sources: README.md, examples/embed/example.html:15-19

The architecture follows a lazy-loading pattern to ensure a fast initial response. A small bootstrap script (embed.ts) defines the global Klecks interface using an EmbedWrapper, which displays a loading screen while the heavier application logic (main-embed.ts) and dependencies are fetched in the background. Sources: src/embed.ts:1-9, src/app/script/embed/bootstrap/embed-wrapper.ts:31-35

Architecture and Components

The embedding system is split into three distinct layers to optimize performance and user experience.

1. Bootstrap Layer (EmbedWrapper)

The EmbedWrapper serves as the primary entry point. It is responsible for:

• Initializing the global Klecks object on the window.
• Creating and managing the initial loading screen UI.
• Lazy-loading the main application bundle via dynamic imports.
• Proxying calls to the internal Embed instance once it is loaded.

Sources: src/app/script/embed/bootstrap/embed-wrapper.ts:38-111, src/embed.ts:7-9

2. Core Embed Logic (Embed)

The Embed class manages the high-level application state for embedded environments. It handles the transition from the loading screen to the active KlApp instance, manages the queue for PSD processing through ag-psd, and implements the public API methods for data retrieval. Sources: src/app/script/main-embed.ts:30-155

3. Application Instance (KlApp)

The final stage of the flow is the instantiation of KlApp, which contains the full painting engine, UI components, and canvas management logic. Sources: src/app/script/main-embed.ts:50-65

Initialization Flow

The following diagram illustrates the sequence of operations from the initial script load to the application being ready for use.

API Reference

Constructor Parameters

The Klecks constructor (aliased from EmbedWrapper) accepts a TEmbedParams configuration object.

Parameter	Type	Description
project	TKlProject	Initial project state with layers and dimensions.
psdBlob	Blob	A PSD file to load as the initial state.
onSubmit	Function	Callback triggered when the user submits their work.
embedUrl	string	Base URL for the embed environment.
logoImg	string | HTMLImageElement	Custom logo for the loading screen.
disableAutoFit	boolean	If true, disables auto-fitting for small canvases.
enableImageDropperImport	boolean	Allows importing images via drag-and-drop.

Sources: src/app/script/main-embed.ts:10-21, src/app/script/embed/bootstrap/embed-wrapper.ts:46-55

Public Methods

Once initialized, the instance provides several methods for interacting with the canvas and project data.

• openProject(project: TKlProjectWithOptionalId): Replaces the current canvas content with a new project. If the instance is still loading, the project is cached and opened automatically upon completion. Sources: src/app/script/embed/bootstrap/embed-wrapper.ts:113-125
• readPSD(blob: Blob): Asynchronously reads a PSD blob and converts it into a Klecks project object. Sources: src/app/script/embed/bootstrap/embed-wrapper.ts:135-155
• getPNG(): Returns a Promise<Blob> containing the current canvas state as a PNG image. Sources: src/app/script/main-embed.ts:117-122
• getPSD(): Returns a Promise<Blob> containing the current project as a multi-layered PSD file. Sources: src/app/script/main-embed.ts:124-129
• initError(error: string): Forces the application into an error state, displaying the provided message on the loading screen. Sources: src/app/script/embed/bootstrap/embed-wrapper.ts:127-133

Project Data Handling

The API processes TKlProject objects, ensuring that layers have required properties such as visibility and unique IDs. If a project is opened without a projectId, the system generates one using randomUuid(). Sources: src/app/script/embed/bootstrap/embed-wrapper.ts:17-26, src/app/script/embed/bootstrap/embed-wrapper.ts:114-117

Data Flow for Project Loading

Implementation Example

The following demonstrates a typical integration for a drawing community where an existing PSD is fetched from a server and loaded into the embed.

const klecks = new Klecks({
    onSubmit: async (onSuccess, onError) => {
        try {
            const png = await klecks.getPNG();
            // Upload logic here
            onSuccess();
        } catch (e) {
            onError();
        }
    }
});

fetch('my-drawing.psd')
    .then(res => res.arrayBuffer())
    .then(buffer => klecks.readPSD(new Blob([buffer])))
    .then(project => klecks.openProject(project))
    .catch(err => klecks.initError('Load failed'));

Sources: examples/embed/example.html:36-61

Conclusion

The Embedding API provides a robust, developer-friendly interface for integrating Klecks into external platforms. By utilizing a wrapper-based architecture, it ensures that users receive immediate visual feedback via a customizable loading screen while complex graphics libraries and project data are processed asynchronously. Sources: src/app/script/embed/bootstrap/embed-wrapper.ts:31-35, src/app/script/main-embed.ts:41-45