The BB Utility Library
Relevant source files
The following files were used as context for generating this wiki page:
The BB (Bitbof Base) Utility Library is a foundational toolkit within the Rocreate project that provides essential low-level functionalities for browser environment handling, mathematical operations, canvas manipulation, color conversion, and UI management. It serves as a centralized internal API that abstracts common tasks required for a high-performance painting application.
The library is structured into specialized modules including base, math, canvas, color, input, and ui, all of which are aggregated and exported via the primary BB constant. This organization ensures that complex application logic, such as brush engines or filter pipelines, can rely on consistent and tested utility functions.
Sources: src/app/script/bb/bb.ts:1-177, CLAUDE.md:21-21
Core Modules and Architecture
The BB library is designed as a multi-functional utility belt. It aggregates functions from various sub-directories to provide a unified interface for the application.
Module Structure Overview
| Module | Responsibility | Key Components |
|---|---|---|
| Browser | Environment detection and web APIs | HAS_POINTER_EVENTS, canShareFiles, unsetEventHandler |
| Base | General helpers and DOM manipulation | css, append, loadImage, copyObj, randomUuid |
| Math | Geometric and arithmetic operations | Matrix, Vec2, clamp, dist, mix, rotateAround |
| Canvas | Low-level Skia/2D context operations | createCanvas, copyCanvas, resizeCanvas, canvasBounds |
| Color | Color space conversions and contrast | RGB, HSV, CMYK, ColorConverter |
| Input | Event handling and gesture logic | PointerListener, KeyListener, EventChain |
Sources: src/app/script/bb/bb.ts:68-175, src/app/script/bb/base/base.ts:1-255
Mathematical and Geometric Operations
The library provides robust mathematical utilities specialized for 2D graphics, including vector manipulation, matrix transformations, and distance calculations.
Geometric Utilities Flow
This diagram illustrates how points and bounds are processed within the math module to determine spatial relationships.
Key functions in the math module include:
clamp(val, min, max): Restricts a value within a specific range.dist(x1, y1, x2, y2): Calculates Euclidean distance between two points.mix(a, b, t): Performs linear interpolation between two values.rotateAround(center, point, angle): Rotates a point around a specific origin.
Sources: src/app/script/bb/bb.ts:108-128, src/app/script/bb/math/math.ts
Canvas and Rendering Utilities
The canvas module handles the lifecycle of HTMLCanvasElement objects and provides utilities for pixel-level analysis and transformations.
Pixel Analysis and Bounds Calculation
The library includes logic to determine the non-transparent boundaries of a canvas, which is critical for cropping and layer management.
Key Canvas Functions
copyCanvas(original): Creates a new canvas instance with cloned pixel data.freeCanvas(canvas): Optimizes memory by resizing a canvas to 1x1 before disposal.testShouldPixelate(transform, scale): Determines if an image should use pixelated scaling based on its alignment and rotation.htmlCanvasToBlobAsync(canvas, type): Promisified wrapper for the nativetoBlobmethod.
Sources: src/app/script/bb/base/canvas.ts:1-135, src/app/script/bb/base/tests/canvas.test.ts:11-125
Base Utilities and DOM Manipulation
The base module provides general-purpose helpers that handle common JavaScript and DOM tasks.
DOM and Environment Helpers
- Style Management: The
css()function applies multiple styles to an element while ensuring Safari compatibility for properties likeuserSelect. - Object Handling:
copyObj()performs a deep copy usingJSON.parse(JSON.stringify(obj)). - Type Safety:
throwIfNull()andthrowIfUndefined()act as assertions to ensure runtime stability. - Unique Identification:
randomUuid()generates version 4 UUIDs, usingcrypto.randomUUID()where available with a manual fallback.
// Example: Styling and Attribute Application
// src/app/script/bb/base/base.ts:41-60
export function css(el: HTMLElement | SVGElement, styleObj: Partial<CSSStyleDeclaration>): void {
const elStyle: any = el.style;
Object.keys(styleObj).forEach((key) => {
const property = key as keyof CSSStyleDeclaration;
elStyle[property] = styleObj[property];
if (property === 'userSelect') {
elStyle.webkitUserSelect = styleObj[property];
}
});
}
Sources: src/app/script/bb/base/base.ts:41-60, src/app/script/bb/base/tests/base.test.ts:114-150
Color Conversion and Contrast
The color module handles conversions between different color spaces (RGB, HSV, CMYK) and utility logic for UI accessibility.
Color Conversion API
The ColorConverter class is the primary interface for shifting between color formats:
RGBToHSV(r, g, b)/HSVToRGB(h, s, v)RGBToCMYK(r, g, b)/CMYKToRGB(c, m, y, k)testIsWhiteBestContrast(rgb): Determines if white or black text should be used on a background color based on contrast ratios.
Sources: src/app/script/bb/bb.ts:147-152, src/app/script/bb/color/color.ts
Input Handling and Event Chains
BB provides a structured approach to user input through listeners and the EventChain system, which processes raw pointer events into stabilized drawing data.
Event Processing Flow
The EventChain allows multiple filters (like sanitizers and stabilizers) to be applied to an input stream sequentially.
Summary
The BB Utility Library is the backbone of Rocreate's technical architecture. By providing standardized modules for math, canvas, and event handling, it allows the higher-level application logic to remain focused on creative features while maintaining high performance and cross-browser reliability. Its comprehensive test suite ensures that basic operations—from UUID generation to complex canvas boundary detection—remain stable during development.