Skip to content

The VS Code of video editing, built for agents.

TypeScript
21.7 KB
Raw Blame
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

// Text layout, measurement, and canvas rendering (was engine/utils/text.ts).

import { store } from '../world/store';
import {
	COMPOSITE_OPERATIONS, PaintType, FontStyle,
	TextAlign, TextBaseline, TextCase,
} from '../constants';
import {
	Size, Hidden, Paint, Color, BlendMode,
	Chars, TextStyle, TextRange, TextCache, Cache, Computed, Camera,
	RenderSurface, Root,
} from '../traits';
import { clamp } from '../math/common';
import { colorToHex } from './color';
import { applyStrokeStyle, findWidestStroke } from './stroke';
import { getSurfaceContext } from './surface';
import { createAngularGradientPattern, createLinearGradient, createRadialGradientPattern } from '../systems/gradients';

import type { Entity, World } from 'koota';

type Ctx = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;

export type TokenOptions = {
	/**
	 * Defines the characters to render
	 */
	chars: string;
	/**
	 * Defines the X offset of the token to the left of the line
	 */
	offset: number;
	/**
	 * Defines the metrics of the token
	 */
	metrics: TextMetrics;
	/**
	 * Defines the style of the token (TextRange sub-entities)
	 */
	ranges: Entity[];
}

export type Line = {
	offsetX: number;
	offsetY: number;
	baseline: number;
	height: number;
};

type RenderSplit = {
	words: string[];
	ranges: Entity[];
};

/** Global offscreen canvas used solely for text measurement. */
let measureCanvas: OffscreenCanvas | null = null;
let measureCtx: OffscreenCanvasRenderingContext2D | null = null;

function getMeasureCtx(): OffscreenCanvasRenderingContext2D {
	if (!measureCtx) {
		measureCanvas = new OffscreenCanvas(1, 1);
		measureCtx = measureCanvas.getContext('2d', { willReadFrequently: true, alpha: true })!;
	}
	return measureCtx;
}

export class Token {
	public offset: number;
	public metrics: TextMetrics;
	public ranges: Entity[];
	public chars: string;
	public width: number;
	public height: number;
	public line = { offsetX: 0, offsetY: 0, baseline: 0, height: 0 };

	constructor(options: TokenOptions) {
		this.offset = options.offset;
		this.metrics = options.metrics;
		this.ranges = options.ranges;
		this.width = options.metrics.width;
		this.height = options.metrics.fontBoundingBoxAscent + options.metrics.fontBoundingBoxDescent;
		this.chars = options.chars;
	}

	public get x(): number {
		return (this.offset + this.line.offsetX) | 0;
	}

	public get y(): number {
		return (this.line.offsetY + this.line.baseline) | 0;
	}

	public get left(): number {
		return (
			this.offset +
			this.line.offsetX -
			this.metrics.actualBoundingBoxLeft
		) | 0;
	}

	public get right(): number {
		return (
			this.offset +
			this.line.offsetX +
			this.metrics.actualBoundingBoxRight
		) | 0;
	}

	public get top(): number {
		return (
			this.line.offsetY +
			this.line.baseline -
			this.metrics.actualBoundingBoxAscent
		) | 0
	}

	public get bottom(): number {
		return (
			this.line.offsetY +
			this.line.baseline +
			this.metrics.actualBoundingBoxDescent
		) | 0
	}

	public setLine(line: Line) {
		this.line = { ...line };
	}
}

function applyFont(ctx: Ctx, world: World, entity: Entity, ranges: Entity[]) {
	const size = getFontSize(world, entity, ranges);
	const family = getFontFamily(world, entity, ranges);
	const weight = getFontWeight(world, entity, ranges);
	const style = getFontStyle(world, entity, ranges);
	const baseline = getTextBaseline(world, entity, ranges);
	const spacing = getLetterSpacing(world, entity, ranges);

	const mappedStyle = FontStyle[style]!.toLowerCase();
	const mappedBaseline = TextBaseline[baseline]!.toLowerCase() as CanvasTextBaseline;

	ctx.font = `${mappedStyle} ${weight.toLowerCase()} ${size}px "${family.replace(/"/g, '')}", Inter`;
	ctx.textBaseline = mappedBaseline;
	ctx.letterSpacing = `${spacing}px`;
}

function shapeTokens(world: World, entity: Entity): void {
	const computed = store(world, Computed);
	const textStyle = store(world, TextStyle);
	const eid = entity.id();
	const lines = store(world, TextCache).tokens[eid];
	const leading = textStyle.leading[eid] ?? 1;
	const textAlign = textStyle.textAlign[eid] ?? TextAlign.LEFT;
	const textBaseline = textStyle.textBaseline[eid] ?? TextBaseline.TOP;
	if (!lines) return;

	// Measure each line's width by summing word widths and spaces
	const lineWidths: number[] = lines.map(line => line.reduce((acc, word) => acc + word.width, 0));
	const lineHeights: number[] = lines.map(line => Math.max(...line.map(word => word.height)));

	// Find the maximum line width
	const maxLineWidth = Math.max(...lineWidths);

	// Calculate total height based on leading
	const totalHeight = lineHeights.reduce((acc, height, i) => acc + height * (i < lineHeights.length - 1 ? leading : 1), 0);

	// When Size is assigned, use Computed for positioning; otherwise set it from text dimensions
	if (!entity.has(Size) || !computed.width[eid] || !computed.height[eid]) {
		computed.width[eid] = Math.ceil(maxLineWidth);
		computed.height[eid] = Math.ceil(totalHeight);
	}

	const containerWidth = computed.width[eid]!;
	const containerHeight = computed.height[eid]!;

	// Calculate initial vertical offset based on text baseline and container height
	let offsetY = 0;
	if (textBaseline === TextBaseline.MIDDLE) {
		offsetY = (containerHeight - totalHeight) / 2;
	} else if (textBaseline === TextBaseline.BOTTOM) {
		offsetY = containerHeight - totalHeight;
	}

	// Calculate coordinates for each word
	const line = {
		offsetX: 0,
		offsetY,
		baseline: 0,
		height: 0,
	};

	for (let l = 0; l < lines.length; l++) {
		line.height = lineHeights[l]!;

		if (textAlign === TextAlign.LEFT) {
			line.offsetX = 0;
		} else if (textAlign === TextAlign.CENTER) {
			line.offsetX = (containerWidth - lineWidths[l]!) / 2;
		} else if (textAlign === TextAlign.RIGHT) {
			line.offsetX = containerWidth - lineWidths[l]!;
		}

		if (textBaseline === TextBaseline.TOP) {
			line.baseline = 0;
		} else if (textBaseline === TextBaseline.MIDDLE) {
			line.baseline = lineHeights[l]! / 2;
		} else if (textBaseline === TextBaseline.BOTTOM) {
			line.baseline = lineHeights[l]!;
		} else if (textBaseline === TextBaseline.ALPHABETIC) {
			const maxAscent = Math.max(...lines[l]!.map(word => word.metrics.fontBoundingBoxAscent));
			line.baseline = maxAscent || lineHeights[l]! * 0.75; // Fallback if no words in line
		}

		for (const word of lines[l]!) {
			word.setLine(line);
		}

		line.offsetY += lineHeights[l]! * leading;
	}
}

function tokenizeText(world: World, entity: Entity) {
	const ctx = getMeasureCtx();

	// Split text into segments based on style overrides first
	const lines: Token[][] = [[]];

	const maxWidth = store(world, Size).width[entity.id()] ?? Number.POSITIVE_INFINITY;

	let offset = 0;
	for (const { words, ranges } of createRenderSplits(world, entity)) {
		applyFont(ctx, world, entity, ranges);

		for (const word of words) {
			const splits = word.split('\n');

			for (let i = 0; i < splits.length; i++) {
				const caseValue = getTextCase(world, entity, ranges);
				const chars = transformText(splits[i]!, caseValue);

				const metrics = ctx.measureText(chars);

				// check if word is too wide for the current line but not the first word
				if (offset + metrics.width > maxWidth && offset > 0) {
					lines.push([]);
					offset = 0;
				}

				// add word to current line
				lines[lines.length - 1]!.push(new Token({ chars, ranges, metrics, offset }));
				offset += metrics.width;

				// add new line if not the last line
				if (i < splits.length - 1) {
					lines.push([]);
					offset = 0;
				}
			}
		}
	}

	if (!entity.has(TextCache)) entity.add(TextCache);
	store(world, TextCache).tokens[entity.id()] = lines;
}

type EllipticalPatterns = Map<Entity, CanvasPattern | CanvasGradient>;

/**
 * A radial or angular paint's pattern, made once per text render and kept in
 * `patterns`: one costs a canvas-sized draw, and it holds for every word,
 * since the words share the box and the matrix.
 */
function getEllipticalPattern(
	world: World,
	ctx: Ctx,
	patterns: EllipticalPatterns,
	paint: Entity,
	paintType: PaintType,
	w: number,
	h: number,
): CanvasPattern | CanvasGradient {
	let pattern = patterns.get(paint);
	if (!pattern) {
		pattern = paintType === PaintType.ANGULAR_GRADIENT
			? createAngularGradientPattern(world, paint, ctx, w, h)
			: createRadialGradientPattern(world, paint, ctx, w, h);
		patterns.set(paint, pattern);
	}
	return pattern;
}

/** Renders text tokens directly to the given canvas context. */
function renderTokens(ctx: Ctx, world: World, entity: Entity): void {
	const eid = entity.id();
	const lines = store(world, TextCache).tokens[eid];
	if (!lines) return;
	const words = lines.flat();

	const computed = store(world, Computed);
	const blendStore = store(world, BlendMode);
	const paintStore = store(world, Paint);

	const savedAlpha = ctx.globalAlpha;

	// Radial and angular paints' patterns, made on first use.
	let patterns: EllipticalPatterns | null = null;

	const cache = store(world, Cache);

	// Draw all text shadows
	{
		ctx.save();
		ctx.textAlign = 'start';
		ctx.textBaseline = 'top';

		// ctx.shadowBlur/OffsetX/OffsetY are in device-pixel space and are not
		// affected by the current transform, so scale them up to match the
		// content transform (camera * resolution).
		const camera = world.get(Root)!.get(Camera);
		const resolution = world.get(RenderSurface)?.resolution ?? 1;
		const shadowScale = (camera?.a ?? 1) * resolution;

		for (const word of words) {
			applyFont(ctx, world, entity, word.ranges);

			const shadows = getShadows(world, entity, word.ranges);

			// A stroked word's shadow is the widest stroke's silhouette.
			const widest = findWidestStroke(world, getStrokes(world, entity, word.ranges));
			if (widest !== null) {
				applyStrokeStyle(ctx, world, widest);
			}

			// Draw shadows first (if any)
			for (const shadow of shadows) {
				if (shadow.has(Hidden)) continue;
				const sid = shadow.id();

				// Computed, not the authored traits: keyframes animate these.
				const color = colorToHex(computed.color[sid]!);
				ctx.shadowOffsetX = computed.offsetX[sid]! * shadowScale;
				ctx.shadowOffsetY = computed.offsetY[sid]! * shadowScale;
				ctx.shadowBlur = computed.blur[sid]! * shadowScale;
				ctx.shadowColor = color;
				ctx.fillStyle = color;
				ctx.globalAlpha = savedAlpha * computed.opacity[sid]!;

				if (widest !== null) {
					ctx.strokeText(word.chars, word.x, word.y);
				} else {
					ctx.fillText(word.chars, word.x, word.y);
				}
			}

			// Reset shadow properties if any shadows are applied
			if (shadows.length) {
				ctx.globalAlpha = savedAlpha;
				ctx.shadowColor = 'transparent';
			}
		}
		ctx.restore();
	}

	// Draw all text strokes
	{
		ctx.save();
		ctx.textAlign = 'start';
		ctx.textBaseline = 'top';

		const w = computed.width[eid]!;
		const h = computed.height[eid]!;

		for (const word of words) {
			const strokes = getStrokes(world, entity, word.ranges);
			if (!strokes.length) continue;

			applyFont(ctx, world, entity, word.ranges);

			// Draw strokes (if any)
			for (const stroke of strokes) {
				if (stroke.has(Hidden)) continue;
				const sid = stroke.id();

				// Recycled-id safety: optional traits only behind has().
				const savedCO = ctx.globalCompositeOperation;
				const blendMode = stroke.has(BlendMode) ? blendStore.value[sid] ?? 0 : 0;
				if (blendMode !== 0) {
					ctx.globalCompositeOperation = COMPOSITE_OPERATIONS[blendMode]!;
				}
				const strokeAlpha = savedAlpha * computed.opacity[sid]!;
				const strokeCO = ctx.globalCompositeOperation;
				applyStrokeStyle(ctx, world, stroke);

				// The stroke's own paint (its `color`, index -1) is intrinsic,
				// beneath its paint children; each child draws through the same
				// line at its own opacity and blend mode.
				const paints = cache.fills[sid] ?? NO_PAINTS;
				for (let i = -1; i < paints.length; i++) {
					const own = i < 0;
					const paint = own ? stroke : paints[i]!;
					if (!own && paint.has(Hidden)) continue;
					const pid = paint.id();

					const paintType = paint.has(Paint) ? paintStore.value[pid] : undefined;
					if (paintType === PaintType.LINEAR_GRADIENT) {
						ctx.strokeStyle = createLinearGradient(world, paint, ctx, w, h);
					} else if (paintType === PaintType.RADIAL_GRADIENT || paintType === PaintType.ANGULAR_GRADIENT) {
						ctx.strokeStyle = getEllipticalPattern(world, ctx, patterns ??= new Map(), paint, paintType, w, h);
					} else if (paint.has(Color)) {
						ctx.strokeStyle = colorToHex(computed.color[pid]!);
					} else {
						// A solid without a Color: a stroke whose color is unset.
						continue;
					}

					const paintBlendMode = !own && paint.has(BlendMode) ? blendStore.value[pid] ?? 0 : 0;
					ctx.globalCompositeOperation = paintBlendMode !== 0 ? COMPOSITE_OPERATIONS[paintBlendMode]! : strokeCO;
					ctx.globalAlpha = own ? strokeAlpha : strokeAlpha * computed.opacity[pid]!;
					ctx.strokeText(word.chars, word.x, word.y);
				}

				ctx.globalCompositeOperation = savedCO;
			}
		}
		ctx.restore();
	}

	// Draw all text fills
	{
		ctx.save();
		ctx.textAlign = 'start';
		ctx.textBaseline = 'top';

		for (const word of words) {
			// The geometry's own Color is an intrinsic solid fill beneath every
			// paint; a range carrying a Color replaces it over the glyphs it spans.
			const intrinsicFill = getIntrinsicColor(world, entity, word.ranges);
			const fills = getFills(world, entity, word.ranges);
			if (!fills.length && intrinsicFill === null) continue;

			applyFont(ctx, world, entity, word.ranges);

			const w = computed.width[eid]!;
			const h = computed.height[eid]!;

			if (intrinsicFill !== null) {
				ctx.globalAlpha = savedAlpha;
				ctx.fillStyle = intrinsicFill;
				ctx.fillText(word.chars, word.x, word.y);
			}

			for (const fill of fills) {
				if (fill.has(Hidden)) continue;
				const fid = fill.id();

				// Store slots outlive destroyed entities and ids are recycled,
				// so an optional trait's slot is only readable behind has().
				const savedCO = ctx.globalCompositeOperation;
				const blendMode = fill.has(BlendMode) ? blendStore.value[fid] ?? 0 : 0;
				if (blendMode !== 0) {
					ctx.globalCompositeOperation = COMPOSITE_OPERATIONS[blendMode]!;
				}
				ctx.globalAlpha = savedAlpha * computed.opacity[fid]!;

				const paintType = paintStore.value[fid];
				if (paintType === PaintType.LINEAR_GRADIENT) {
					ctx.fillStyle = createLinearGradient(world, fill, ctx, w, h);
				} else if (paintType === PaintType.RADIAL_GRADIENT || paintType === PaintType.ANGULAR_GRADIENT) {
					ctx.fillStyle = getEllipticalPattern(world, ctx, patterns ??= new Map(), fill, paintType, w, h);
				} else {
					ctx.fillStyle = colorToHex(computed.color[fid]!);
				}
				ctx.fillText(word.chars, word.x, word.y);
				ctx.globalCompositeOperation = savedCO;
			}
		}
		ctx.restore();
	}
}

/** Render text tokens directly to the world's render surface. */
export function renderText(world: World, entity: Entity) {
	const ctx = getSurfaceContext(world);
	if (!ctx) return;
	tokenizeText(world, entity);
	shapeTokens(world, entity);
	renderTokens(ctx, world, entity);
}

/**
 * Splits text into segments based on overlapping text range entities.
 * Handles overlapping ranges by merging them.
 * @returns Array of RenderSplit objects with words and contributing ranges
 */
function createRenderSplits(world: World, entity: Entity): RenderSplit[] {
	const eid = entity.id();
	const chars = store(world, Computed).chars[eid] ?? store(world, Chars).value[eid] ?? '';

	const textRanges = store(world, Cache).textRanges[eid] ?? [];

	// Fast path: no styles
	if (textRanges.length === 0) {
		return [{
			words: tokenize(chars),
			ranges: [],
		}];
	}

	// Fast path: empty text
	if (chars.length === 0) {
		return [{
			words: [],
			ranges: [],
		}];
	}

	const rangeStore = store(world, TextRange);

	// Collect all unique boundary points
	const boundaries = new Set<number>();
	boundaries.add(0);
	boundaries.add(chars.length);

	for (const range of textRanges) {
		let start = rangeStore.start[range.id()] ?? 0;
		let end = rangeStore.end[range.id()] ?? chars.length;

		// Clamp boundaries to valid text range
		start = clamp(start, 0, chars.length);
		end = clamp(end, 0, chars.length);

		boundaries.add(start);
		boundaries.add(end);
	}

	// Sort boundaries in ascending order
	const sortedBoundaries = Array.from(boundaries).sort((a, b) => a - b);

	// Create segments between each pair of boundaries
	const segments: RenderSplit[] = [];

	for (let i = 0; i < sortedBoundaries.length - 1; i++) {
		const segStart = sortedBoundaries[i]!;
		const segEnd = sortedBoundaries[i + 1]!;

		// Skip empty segments
		if (segStart >= segEnd) continue;

		// Find all active styles for this segment
		const ranges: Entity[] = [];

		for (const range of textRanges) {
			let start = rangeStore.start[range.id()] ?? 0;
			let end = rangeStore.end[range.id()] ?? chars.length;

			// Clamp boundaries to valid text range
			start = clamp(start, 0, chars.length);
			end = clamp(end, 0, chars.length);

			// A style is active if segment falls within its range [start, end)
			// Using < for end to treat ranges as [start, end)
			if (start <= segStart && end > segStart) {
				ranges.push(range);
			}
		}

		segments.push({
			words: tokenize(chars.slice(segStart, segEnd)),
			ranges: ranges,
		});
	}

	return segments;
}

function tokenize(input: string): string[] {
	// Fast path for inputs without spaces
	if (input.indexOf(' ') === -1) {
		return [input];
	}

	// Use regex to match:
	// 1. Any characters up to and including a space
	// 2. OR any remaining characters to the end
	return input.match(/[^]*? |[^]+$/g) || [input];
}

export function transformText(text: string, textCase?: number): string {
	if (textCase == TextCase.LOWER) {
		return text.toLocaleLowerCase();
	}

	if (textCase == TextCase.UPPER) {
		return text.toUpperCase();
	}

	return text;
}

/**
 * The intrinsic glyph color for a run: the last of `ranges` carrying a Color
 * wins over the text's own, as a hex string; null when neither has one.
 */
function getIntrinsicColor(world: World, entity: Entity, ranges: Entity[]): string | null {
	const computed = store(world, Computed);
	let value: number | undefined = entity.has(Color) ? computed.color[entity.id()] ?? 0 : undefined;

	for (const range of ranges) {
		if (range.has(Color)) {
			value = computed.color[range.id()] ?? store(world, Color).value[range.id()] ?? 0;
		}
	}

	return value === undefined ? null : colorToHex(value);
}

function getFills(world: World, entity: Entity, ranges: Entity[]): Entity[] {
	const cache = store(world, Cache);
	let value = cache.fills[entity.id()] ?? [];

	for (const range of ranges) {
		const rangeValue = cache.fills[range.id()];
		if (rangeValue?.length) {
			value = rangeValue;
		}
	}

	return value;
}

// Stable empty list for strokes without paint children, so the render loop allocates none.
const NO_PAINTS: Entity[] = [];

function getStrokes(world: World, entity: Entity, ranges: Entity[]): Entity[] {
	const cache = store(world, Cache);
	let value = cache.strokes[entity.id()] ?? [];

	for (const range of ranges) {
		const rangeValue = cache.strokes[range.id()];
		if (rangeValue?.length) {
			value = rangeValue;
		}
	}

	return value;
}

function getShadows(world: World, entity: Entity, ranges: Entity[]): Entity[] {
	const cache = store(world, Cache);
	let value = cache.shadows[entity.id()] ?? [];

	for (const range of ranges) {
		const rangeValue = cache.shadows[range.id()];
		if (rangeValue?.length) {
			value = rangeValue;
		}
	}

	return value;
}

function getTextCase(world: World, entity: Entity, ranges: Entity[]) {
	const textStyle = store(world, TextStyle);
	let value = textStyle.textCase[entity.id()] ?? 0;

	for (const range of ranges) {
		const rangeValue = textStyle.textCase[range.id()];
		if (rangeValue !== undefined) {
			value = rangeValue;
		}
	}

	return value;
}

function getFontSize(world: World, entity: Entity, ranges: Entity[]) {
	const textStyle = store(world, TextStyle);
	let value = textStyle.fontSize[entity.id()] ?? 16;

	for (const range of ranges) {
		const rangeValue = textStyle.fontSize[range.id()];
		if (rangeValue !== undefined) {
			value = rangeValue;
		}
	}

	return value;
}

function getFontFamily(world: World, entity: Entity, ranges: Entity[]) {
	const textStyle = store(world, TextStyle);
	let value = textStyle.fontFamily[entity.id()] || 'Inter';

	for (const range of ranges) {
		const rangeValue = textStyle.fontFamily[range.id()];
		if (rangeValue !== undefined) {
			value = rangeValue;
		}
	}

	return value;
}

function getFontWeight(world: World, entity: Entity, ranges: Entity[]) {
	const textStyle = store(world, TextStyle);
	let value = textStyle.fontWeight[entity.id()] ?? '400';

	for (const range of ranges) {
		const rangeValue = textStyle.fontWeight[range.id()];
		if (rangeValue !== undefined) {
			value = rangeValue;
		}
	}

	return value;
}

function getFontStyle(world: World, entity: Entity, ranges: Entity[]) {
	const textStyle = store(world, TextStyle);
	let value = textStyle.fontStyle[entity.id()] ?? FontStyle.NORMAL;

	for (const range of ranges) {
		const rangeValue = textStyle.fontStyle[range.id()];
		if (rangeValue !== undefined) {
			value = rangeValue;
		}
	}

	return value;
}

function getTextBaseline(world: World, entity: Entity, ranges: Entity[]) {
	const textStyle = store(world, TextStyle);
	let value = textStyle.textBaseline[entity.id()] ?? TextBaseline.TOP;

	for (const range of ranges) {
		const rangeValue = textStyle.textBaseline[range.id()];
		if (rangeValue !== undefined) {
			value = rangeValue;
		}
	}

	return value;
}

function getLetterSpacing(world: World, entity: Entity, ranges: Entity[]) {
	const textStyle = store(world, TextStyle);
	let value = textStyle.letterSpacing[entity.id()] ?? 0;

	for (const range of ranges) {
		const rangeValue = textStyle.letterSpacing[range.id()];
		if (rangeValue !== undefined) {
			value = rangeValue;
		}
	}

	return value;
}