@ledable/sdk/graphics

function Circle(props: CircleProps): LedElement

function Ellipse(props: EllipseProps): LedElement

function Frame(props: FrameProps): LedElement

function Group(props: GroupProps): LedElement

function Layer(props: LayerProps): LedElement

function Line(props: LineProps): LedElement

function LinearGradient(props: LinearGradientProps): LedElement

function Pixel(props: PixelProps): LedElement

function PixelMap(props: PixelMapProps): LedElement

function Polygon(props: PolygonProps): LedElement

function RadialGradient(props: RadialGradientProps): LedElement

function Rect(props: RectProps): LedElement

function Sprite(props: SpriteProps): LedElement

function Stop(props: StopProps): LedElement

function Text(props: TextProps): LedElement

function anchorOffset(anchor: TextAnchor, layout: TextLayout): AnchorOffset

function blit(dst: Framebuffer, src: Framebuffer, dx: number, dy: number): void

function brightenColor(color: Color, threshold = 150): Color

function clamp(value: number, min: number, max: number): number

function clamp01(value: number): number

function cloneFramebuffer(fb: Framebuffer): Framebuffer

function compositeFramebuffer(
  dst: Framebuffer,
  src: Framebuffer,
  dx: number,
  dy: number,
): void

function containRgb(source: Framebuffer, maxWidth: number, maxHeight: number): Framebuffer

function createFramebuffer(width: number, height: number): Framebuffer

function createFrameContext(frame: number, options: AnimationOptions): FrameContext

function decodeBitmapFont(bytes: Uint8Array): BitmapFont

function easeInCubic(t: number): number

function easeInOutCubic(t: number): number

function easeInOutQuad(t: number): number

function easeInQuad(t: number): number

function easeOutCubic(t: number): number

function easeOutQuad(t: number): number

function evaluateElement(
  element: LedElement,
  limits: EvaluateLimits = DEFAULT_LIMITS,
): IntrinsicNode

function evaluateToNodes(
  element: LedElement,
  limits: EvaluateLimits = DEFAULT_LIMITS,
): IntrinsicNode[]

function fillFramebuffer(fb: Framebuffer, color: RGBA): void

function framebufferToText(
  fb: Framebuffer,
  legend: Readonly<Record<string, Color>>,
): string

function framesToSheet(
  frames: readonly Framebuffer[],
  options: SpriteSheetOptions = {},
): Framebuffer

function getPixel(fb: Framebuffer, x: number, y: number): RGBA

function glyphBit(glyph: Glyph, x: number, y: number): boolean

function halfBrightness(fb: Framebuffer): Framebuffer

function isBitmapFont(value: unknown): value is BitmapFont

function isLedElement(value: unknown): value is LedElement

function layoutText(
  font: BitmapFont,
  text: string,
  options: TextLayoutOptions = {},
): TextLayout

function lerp(a: number, b: number, t: number): number

function measureText(
  font: BitmapFont,
  text: string,
  options: TextLayoutOptions = {},
): TextMetrics

function measureTextBounds(
  font: BitmapFont,
  text: string,
  options: TextLayoutOptions = {},
): { readonly top: number; readonly bottom: number; readonly height: number }

function parseColor(value: Color): RGBA

function renderAnimation(render: RenderFunction, options: AnimationOptions): Framebuffer[]

function renderFrame(element: LedElement, options: RenderOptions = {}): Framebuffer

function renderLedPreview(fb: Framebuffer, options: LedPreviewOptions = {}): Framebuffer

function rgba(r: number, g: number, b: number, a = 255): RGBA

function scaleNearest(fb: Framebuffer, factor: number): Framebuffer

function setPixel(fb: Framebuffer, x: number, y: number, color: RGBA): void

function textPixels(layout: TextLayout): Array<readonly [number, number]>

function withAlpha(color: RGBA, alpha: number): RGBA

const DEFAULT_LIMITS: EvaluateLimits = { maxNodes: 20000, maxDepth: 128 }

const Fragment = "led:fragment"

const MAX_TEXT_LENGTH = 4096

const NOTDEF_CODEPOINT = 0x110000

class LedError extends Error

interface AnimationOptions {
  readonly frameCount: number;
  readonly fps: number;
  readonly width?: number;
  readonly height?: number;
  readonly limits?: EvaluateLimits;
}

interface BitmapFont {
  readonly $$ledFont: true;
  readonly name: string;
  readonly size: number;
  readonly ascent: number;
  readonly descent: number;
  readonly lineRef: number;
  glyphCount(): number;
  /** Glyph for a codepoint, falling back to .notdef; null if neither exists. */
  glyph(codepoint: number): Glyph | null;
  has(codepoint: number): boolean;
}

interface CircleProps extends CommonPaintProps {
  readonly x: number;
  readonly y: number;
  readonly diameter: number;
}

interface ClipRect {
  readonly x: number;
  readonly y: number;
  readonly width: number;
  readonly height: number;
}

interface CommonPaintProps {
  readonly fill?: Fill;
  readonly stroke?: Fill;
  readonly strokeWidth?: number;
  readonly opacity?: number;
  readonly blendMode?: BlendMode;
  readonly name?: string;
}

interface EllipseProps extends CommonPaintProps {
  readonly x: number;
  readonly y: number;
  readonly width: number;
  readonly height: number;
}

interface EvaluateLimits {
  readonly maxNodes: number;
  readonly maxDepth: number;
}

interface Framebuffer {
  readonly width: number;
  readonly height: number;
  /** Non-premultiplied RGBA, row-major. */
  readonly data: Uint8ClampedArray;
}

interface FrameContext {
  readonly width: number;
  readonly height: number;
  readonly frame: number;
  readonly frameCount: number;
  readonly fps: number;
  readonly timeMs: number;
  readonly progress: number;
}

interface FrameProps {
  readonly width: number;
  readonly height: number;
  readonly background?: Color;
  readonly children?: LedChild;
}

interface Glyph {
  /** Horizontal advance in 26.6 fixed point (1/64 px). */
  readonly adv64: number;
  /** Ink offset from the pen position (left/ascender-top origin). */
  readonly x0: number;
  readonly y0: number;
  readonly w: number;
  readonly h: number;
  /** Row-major 1-bit bitmap, MSB first, bit index = y * w + x. */
  readonly bits: Uint8Array;
}

interface GroupProps {
  readonly x?: number;
  readonly y?: number;
  /** Box width for flip/rotate. Required when flipX/flipY/rotate is used. */
  readonly width?: number;
  /** Box height for flip/rotate. Required when flipX/flipY/rotate is used. */
  readonly height?: number;
  readonly flipX?: boolean;
  readonly flipY?: boolean;
  readonly rotate?: 0 | 90 | 180 | 270;
  /** Integer nearest-neighbor scale factor. */
  readonly scale?: number;
  /** Clip rect in the group's inner (children) coordinate space. */
  readonly clip?: ClipRect;
  readonly name?: string;
  readonly children?: LedChild;
}

interface IntrinsicNode {
  readonly kind: string;
  readonly props: Readonly<Record<string, unknown>>;
  readonly children: readonly IntrinsicNode[];
}

interface LayerProps {
  readonly opacity?: number;
  readonly blendMode?: BlendMode;
  readonly mask?: LedElement;
  readonly name?: string;
  readonly children?: LedChild;
}

interface LedNode {
  readonly $$led: true;
  readonly type: string | LedComponent;
  readonly props: Readonly<Record<string, unknown>>;
  readonly key: string | number | undefined;
}

interface LedPreviewOptions {
  /** Emitter size in output pixels. */
  readonly size?: number;
  /** Dark gap between emitters in output pixels. */
  readonly gap?: number;
  readonly shape?: "square" | "circle";
  readonly background?: Color;
}

interface LinearGradientProps {
  readonly from: Point;
  readonly to: Point;
  readonly space?: GradientSpace;
  readonly children?: LedChild;
}

interface LineProps {
  readonly from: Point;
  readonly to: Point;
  readonly color: Color;
  readonly opacity?: number;
  readonly blendMode?: BlendMode;
  readonly name?: string;
}

interface PixelMapProps {
  readonly x?: number;
  readonly y?: number;
  readonly color: Color;
  readonly pixels: readonly Point[];
  readonly opacity?: number;
  readonly blendMode?: BlendMode;
  readonly name?: string;
}

interface PixelProps {
  readonly x: number;
  readonly y: number;
  readonly color: Color;
  readonly opacity?: number;
  readonly blendMode?: BlendMode;
  readonly name?: string;
}

interface PolygonProps extends CommonPaintProps {
  readonly points: readonly Point[];
}

interface RadialGradientProps {
  readonly center: Point;
  readonly radius: number;
  readonly space?: GradientSpace;
  readonly children?: LedChild;
}

interface RectProps extends CommonPaintProps {
  readonly x: number;
  readonly y: number;
  readonly width: number;
  readonly height: number;
}

interface RenderOptions {
  readonly limits?: EvaluateLimits | undefined;
}

interface RGBA {
  readonly r: number;
  readonly g: number;
  readonly b: number;
  readonly a: number;
}

interface SpriteProps {
  readonly x?: number;
  readonly y?: number;
  /** Single-character keys; null means transparent. */
  readonly palette: Readonly<Record<string, Color | null>>;
  readonly rows: readonly string[];
  readonly opacity?: number;
  readonly blendMode?: BlendMode;
  readonly name?: string;
}

interface SpriteSheetOptions {
  readonly columns?: number;
}

interface StopProps {
  readonly offset: number;
  readonly color: Color;
}

interface TextLayout {
  readonly placed: readonly PlacedGlyph[];
  /** Block dimensions in output px. */
  readonly width: number;
  readonly height: number;
  readonly lines: readonly string[];
  readonly scale: number;
  readonly ascentPx: number;
}

interface TextLayoutOptions {
  /** Output size in px; must be a positive integer multiple of font.size. */
  readonly size?: number | undefined;
  /** Wrap lines to this many output px (UAX#14 subset line breaking). */
  readonly maxWidth?: number | undefined;
  /** Extra px between lines in output px (PIL default: 4). */
  readonly lineSpacing?: number | undefined;
  readonly align?: TextAlign | undefined;
}

interface TextMetrics {
  /** Width of the widest line in output px. */
  readonly width: number;
  /** Total block height in output px. */
  readonly height: number;
  readonly lines: readonly string[];
}

interface TextProps {
  readonly x: number;
  readonly y: number;
  readonly text: string;
  /** A BitmapFont decoded from a `.ledfont` asset (see decodeBitmapFont). */
  readonly font: unknown;
  readonly color: Color;
  /** Output size in px; must be a positive integer multiple of the font's native size. */
  readonly size?: number;
  /** PIL-style 2-char anchor (l|m|r + a|t|m|s|b|d). Default "la". */
  readonly anchor?: string;
  /** Wrap lines to this many px using UAX#14-subset line breaking. */
  readonly maxWidth?: number;
  readonly align?: "left" | "center" | "right";
  /** Extra px between lines. Default 4 (PIL's default). */
  readonly lineSpacing?: number;
  readonly opacity?: number;
  readonly blendMode?: BlendMode;
  readonly name?: string;
}

type BlendMode = "normal" | "multiply" | "screen" | "add";

type Color = string;

type Fill = Color | LedElement;

type GradientSpace = "bounds" | "canvas";

type LedChild = LedElement | null | undefined | boolean | readonly LedChild[];

type LedComponent<P = any> = (props: P) => LedElement | null;

type LedElement = LedNode;

type Point = readonly [number, number];

type RenderFunction = (ctx: FrameContext) => LedElement;

type TextAlign = "left" | "center" | "right";

type TextAnchor = `${"l" | "m" | "r"}${"a" | "t" | "i" | "j" | "m" | "s" | "b" | "d"}`;