VibePhoto Editor Core – Developer Guide

Framework-agnostic photo editing core with non-destructive state, preview pipeline, pluggable renderers (Canvas/WebGL), and robust history management.

Installation

npm install
npm run build

Quick Start

import { PhotoEditor } from "@vibephoto/editor-core";

const canvas = document.getElementById("editorCanvas");
const editor = new PhotoEditor(canvas, {
  rendererKind: "webgl", // "webgl" or "canvas"
  config: {
     // Optional: Override defaults
     history: { maxEntries: 100 }
  }
});

// Load an image
await editor.loadSource({ kind: "url", url: "/photos/example.jpg" });

// Apply an adjustment
await editor.dispatch({ type: "setAdjustment", path: "exposureEV", value: 0.5 });

Configuration

The editor defaults are defined in src/vpconfig.json. You can override these by passing a config object to the PhotoEditor constructor.

Configurable Options:

• history.maxEntries: Default 50. Maximum number of undo/redo steps.
• thumbnail.triggerSize: Default 1000. Image dimension threshold to generate thumbnails.
• thumbnail.maxDim: Default 500. Maximum thumbnail dimension.
• export.defaultQuality: Default 0.92. Default JPEG/WebP quality.
• export.profileLutSize: Default 32. Grid size (N) for generated .cube 3D LUTs (NxNxN).
• renderer.lutCacheMax: Default 5. Max active LUT textures cached in WebGL.

Core Concepts

• PhotoEditor: High-level facade wiring EditorCore to a renderer.
• EditorCore: The main editor core.
• EditorRenderer: The renderer (Canvas2D or WebGL).

Viewport

Viewport Viewport is a virtual camera that projects the image to the render target. You can control the viewport using the viewport commands. You can zoom in/out, pan, and rotate the viewport. Viewport state is stored in the viewport property of the EditorState. Framebox is a virtual frame that projects the image to the render target. Framebox state is stored in the framebox property of the ViewportState. Viewport represented by the viewport property of the EditorState.

• zoom: Normalized zoom factor for rendering the UI view (1 = default scale).
• centerX: Normalized center point (0,0 is center).
• centerY: Normalized center point (0,0 is center).
• framebox: this is the normalized frame of the image in the viewport. (0,0 is top-left, 1,1 is bottom-right).

Document

• DocumentState: The source of truth for image state (adjustments, geometry, etc.).
• EffectiveState: The resolved state used for rendering (committed + draft).
• History: Use undo/redo commands. History can be saved/restored via VPI files.

API Reference

Initialization

const editor = new PhotoEditor(
  canvas: HTMLCanvasElement,
  initialDocument?: Partial<DocumentState>,
  options?: PhotoEditorOptions,
  lutManifest?: LutManifest
);

Key Commands (editor.dispatch)

• Asset Loading:
  • { type: "loadSource", source: ImageSource }
  • { type: "unloadSource" }
• Adjustments:
  • { type: "setAdjustment", path: "exposureEV", value: 0.5 }
  • { type: "setAdjustment", path: "colorChannels.red.hue", value: 20 }
• Geometry:
  • { type: "geometry:set", patch: { rotation: 90 } }
  • { type: "geometry:setCrop", rect: { x, y, width, height } }
• LUTs:
  • { type: "lut:apply", lutId: "..." }
• History:
  • { type: "undo" }
  • { type: "redo" }

Exporting & Saving

• Save Project (VPI):
  • { type: "export:document", path: "file.vpi", includeHistory: true }
  • Saves state, assets, and optionally history to a JSON file.
• Export Image:
  • { type: "export:image", path: "image.jpg", quality: 0.9 }
• Export Profile (LUT):
  • { type: "export:lut", path: "my-style.cube" }
  • Bakes current adjustments into a standardized 3D LUT file.

License

This project is licensed under a Source Available license. See LICENSE.md for terms regarding use and modification.