refactor(runtime): tighten internal typing and split render tick contracts

Author: wiedymi

src/fonts/manager/entries.ts

@@ -1,8 +1,8 @@
 import { fontHeightUnits } from "../../grid/grid";
-import type { FontEntry, FontManagerState, ShapedCluster } from "../types";
+import type { Font, FontEntry, FontManagerState, ShapedCluster } from "../types";
 
 /** Create a new FontEntry with empty caches and default metadata. */
-export function createFontEntry(font: any, label: string): FontEntry {
+export function createFontEntry(font: Font, label: string): FontEntry {
   return {
     font,
     label,
@@ -43,7 +43,7 @@ export function createFontManagerState(): FontManagerState {
 }
 
 /** Check whether a font has a non-zero glyph ID for the given character. */
-export function fontHasGlyph(font: any, ch: string): boolean {
+export function fontHasGlyph(font: Font, ch: string): boolean {
   const glyphId = font.glyphIdForChar(ch);
   return glyphId !== undefined && glyphId !== null && glyphId !== 0;
 }
@@ -65,7 +65,7 @@ export function fontAdvanceUnits(
     advance = shapeClusterWithFont(entry, "M").advance;
   }
   if (!advance) {
-    advance = fontHeightUnits(entry.font) || entry.font.upem || 1000;
+    advance = fontHeightUnits(entry.font) || entry.font.unitsPerEm || 1000;
   }
   entry.advanceUnits = advance;
   return advance;

src/fonts/types.ts

@@ -1,9 +1,32 @@
+import type {
+  Bitmap as TextShaperBitmap,
+  Font as TextShaperFont,
+  FontSizeMode as TextShaperFontSizeMode,
+  GlyphAtlas as TextShaperGlyphAtlas,
+  GlyphMetrics as TextShaperGlyphMetrics,
+} from "text-shaper";
+
+/** text-shaper Font used by runtime/font manager. */
+export type Font = TextShaperFont;
+/** text-shaper Bitmap used by atlas builders. */
+export type FontAtlasBitmap = TextShaperBitmap;
+/** text-shaper glyph metrics used inside atlases. */
+export type FontAtlasGlyphMetrics = TextShaperGlyphMetrics;
+/** text-shaper font size mode ("em" | "height"). */
+export type FontSizeMode = TextShaperFontSizeMode;
+/** Restty atlas extends text-shaper atlas with extra caches used internally. */
+export type FontAtlas = TextShaperGlyphAtlas & {
+  glyphsByWidth?: Map<number, Map<number, FontAtlasGlyphMetrics>>;
+  inset?: number;
+  colorGlyphs?: Set<number>;
+};
+
 /**
  * A loaded font with its associated caches and rendering metadata.
  */
 export type FontEntry = {
   /** text-shaper Font instance. */
-  font: any; // text-shaper Font instance
+  font: Font; // text-shaper Font instance
   /** Human-readable font name. */
   label: string;
   /** Cache of shaped glyph clusters keyed by input string. */
@@ -15,7 +38,7 @@ export type FontEntry = {
   /** Set of all glyph IDs available in this font. */
   glyphIds: Set<number>;
   /** GPU texture atlas for this font, or null if not yet built. */
-  atlas: any | null;
+  atlas: FontAtlas | null;
   /** Font size in CSS pixels. */
   fontSizePx: number;
   /** Scale factor applied when rasterizing to the atlas. */
@@ -57,18 +80,13 @@ export type ShapedGlyph = {
  */
 export type FontManagerState = {
   /** Primary text-shaper Font instance, or null before initialization. */
-  font: any | null;
+  font: Font | null;
   /** Loaded font entries in priority order (primary + fallbacks). */
   fonts: FontEntry[];
   /** Current font size in CSS pixels. */
   fontSizePx: number;
-  /**
-   * How font size maps to design units.
-   * - height: size equals cell height
-   * - width: size equals cell width
-   * - upem: size equals units-per-em
-   */
-  sizeMode: "height" | "width" | "upem";
+  /** How font size maps to design units ("em" | "height"). */
+  sizeMode: FontSizeMode;
   /** Cache mapping text strings to the index of the font chosen to render them. */
   fontPickCache: Map<string, number>;
 };

src/grid/grid.ts

@@ -5,7 +5,7 @@ import type { CellMetrics, GridConfig, GridState } from "./types";
  */
 export type FontMetricsProvider = {
   /** Return the scale factor for a given pixel size and sizing mode. */
-  scaleForSize(sizePx: number, sizeMode: string): number;
+  scaleForSize(sizePx: number, sizeMode?: "em" | "height"): number;
   /** Look up the glyph ID for a character, or null/undefined if missing. */
   glyphIdForChar(char: string): number | undefined | null;
   /** Return the advance width of a glyph in font units. */
@@ -17,15 +17,17 @@ export type FontMetricsProvider = {
   /** Explicit font height in font units, if available. */
   readonly height?: number;
   /** Units per em of the font. */
-  readonly upem: number;
+  readonly unitsPerEm: number;
+  /** Legacy alias accepted for compatibility with older font objects. */
+  readonly upem?: number;
 };
 
 /** Result of shaping a text cluster, containing its advance width. */
 export type ShapeResult = {
   advance: number;
 };
 
-/** Resolve the font height in font units, falling back to ascender-descender or upem. */
+/** Resolve the font height in font units, falling back to ascender-descender or units-per-em. */
 export function fontHeightUnits(font: FontMetricsProvider): number {
   if (!font) return 0;
   const height = font.height;
@@ -34,7 +36,7 @@ export function fontHeightUnits(font: FontMetricsProvider): number {
   const desc = font.descender ?? 0;
   const fallback = asc - desc;
   if (Number.isFinite(fallback) && fallback > 0) return fallback;
-  return font.upem || 1000;
+  return font.unitsPerEm || font.upem || 1000;
 }
 
 /**

src/runtime/atlas-builder.ts

@@ -1,3 +1,12 @@
+import type { Font, FontAtlas, FontEntry, FontSizeMode } from "../fonts";
+import type {
+  AtlasOptions,
+  GlyphRasterizeOptions,
+  Matrix2D,
+  Matrix3x3,
+  RasterizedGlyph,
+} from "text-shaper";
+
 /**
  * Metadata for constrained glyph rendering.
  * - cp: Unicode code point
@@ -39,24 +48,82 @@ export type AtlasConstraintContext = {
     iconHeight: number;
     iconHeightSingle: number;
   };
-  fontEntry: any;
+  fontEntry: FontEntry;
+};
+
+type RasterizeGlyphTransformOptions = GlyphRasterizeOptions & {
+  offsetX26?: number;
+  offsetY26?: number;
+};
+
+type RasterizeGlyphFn = (
+  font: Font,
+  glyphId: number,
+  fontSize: number,
+  options?: GlyphRasterizeOptions,
+) => RasterizedGlyph | null;
+
+type RasterizeGlyphWithTransformFn = (
+  font: Font,
+  glyphId: number,
+  fontSize: number,
+  matrix: Matrix2D | Matrix3x3,
+  options?: RasterizeGlyphTransformOptions,
+) => RasterizedGlyph | null;
+
+type BuildGlyphAtlasWithConstraintsOptions = {
+  font: Font;
+  glyphIds: number[];
+  fontSize: number;
+  sizeMode: FontSizeMode;
+  padding: number;
+  maxWidth: number;
+  maxHeight: number;
+  pixelMode: number;
+  hinting: boolean;
+  rasterizeGlyph?: RasterizeGlyphFn;
+  rasterizeGlyphWithTransform?: RasterizeGlyphWithTransformFn;
+  glyphMeta?: Map<number, GlyphConstraintMeta>;
+  constraintContext?: AtlasConstraintContext;
+};
+
+type BuildGlyphAtlasWithConstraintsResult = {
+  atlas: FontAtlas | null;
+  constrainedGlyphWidths?: Map<number, number> | null;
+};
+
+type BuildColorEmojiAtlasWithCanvasOptions = {
+  font: Font;
+  fontEntry: FontEntry;
+  glyphIds: number[];
+  fontSize: number;
+  sizeMode: FontSizeMode;
+  padding: number;
+  maxWidth: number;
+  maxHeight: number;
+  pixelMode: number;
 };
 
 type BuildAtlasDeps = {
   fontScaleOverrides: Array<{ match: RegExp; scale: number }>;
-  sizeMode: string;
-  isSymbolFont: (entry: any) => boolean;
-  fontScaleOverride: (entry: any, overrides: Array<{ match: RegExp; scale: number }>) => number;
-  resolveGlyphPixelMode: (entry: any) => number;
-  atlasBitmapToRGBA: (atlas: any) => Uint8Array | null;
-  padAtlasRGBA: (rgba: Uint8Array, atlas: any, padding: number) => Uint8Array;
-  buildAtlas: (font: any, glyphIds: number[], options: any) => any;
+  sizeMode: FontSizeMode;
+  isSymbolFont: (entry: FontEntry | null | undefined) => boolean;
+  fontScaleOverride: (
+    entry: FontEntry | null | undefined,
+    overrides: Array<{ match: RegExp; scale: number }>,
+  ) => number;
+  resolveGlyphPixelMode: (entry: FontEntry) => number;
+  atlasBitmapToRGBA: (atlas: FontAtlas) => Uint8Array | null;
+  padAtlasRGBA: (rgba: Uint8Array, atlas: FontAtlas, padding: number) => Uint8Array;
+  buildAtlas: (font: Font, glyphIds: number[], options: AtlasOptions) => FontAtlas;
   buildGlyphAtlasWithConstraints: (
-    options: any,
-  ) => { atlas: any; constrainedGlyphWidths?: any } | null;
-  buildColorEmojiAtlasWithCanvas: (options: any) => { atlas: any } | null;
-  rasterizeGlyph?: any;
-  rasterizeGlyphWithTransform?: any;
+    options: BuildGlyphAtlasWithConstraintsOptions,
+  ) => BuildGlyphAtlasWithConstraintsResult | null;
+  buildColorEmojiAtlasWithCanvas: (
+    options: BuildColorEmojiAtlasWithCanvasOptions,
+  ) => { atlas: FontAtlas } | null;
+  rasterizeGlyph?: RasterizeGlyphFn;
+  rasterizeGlyphWithTransform?: RasterizeGlyphWithTransformFn;
   nerdConstraintSignature: (
     glyphMeta: Map<number, GlyphConstraintMeta> | undefined,
     constraintContext: AtlasConstraintContext | null | undefined,
@@ -87,7 +154,7 @@ type BuildAtlasDeps = {
  * - deps: external dependencies for atlas building
  */
 export type BuildFontAtlasParams = {
-  entry: any;
+  entry: FontEntry;
   neededGlyphIds: Set<number>;
   glyphMeta?: Map<number, GlyphConstraintMeta>;
   fontSizePx: number;
@@ -107,7 +174,7 @@ export type BuildFontAtlasParams = {
  */
 export type BuildFontAtlasResult = {
   rebuilt: boolean;
-  atlas: any | null;
+  atlas: FontAtlas | null;
   rgba: Uint8Array | null;
   colorGlyphs?: Set<number>;
   preferNearest: boolean;
@@ -220,7 +287,7 @@ export function buildFontAtlasIfNeeded(params: BuildFontAtlasParams): BuildFontA
   const colorGlyphAtlas = glyphPixelMode === constants.pixelModeRgbaValue || glyphPixelMode === 4;
   const useCanvasColorAtlas = colorGlyphAtlas;
 
-  let atlas = null;
+  let atlas: FontAtlas | null = null;
   if (isSymbol && rasterizeGlyph && rasterizeGlyphWithTransform && constraintContext && glyphMeta) {
     const result = buildGlyphAtlasWithConstraints({
       font: entry.font,

src/runtime/create-runtime/atlas-debug-utils.ts

@@ -1,7 +1,7 @@
-import type { FontEntry } from "../../fonts";
+import type { FontAtlas, FontAtlasGlyphMetrics, FontEntry } from "../../fonts";
 
 export function atlasRegionToImageData(
-  atlas: any,
+  atlas: FontAtlas,
   x: number,
   y: number,
   width: number,
@@ -39,7 +39,7 @@ export function atlasRegionToImageData(
   return new ImageData(rgba, width, height);
 }
 
-export function padAtlasRGBA(rgba: Uint8Array, atlas: any, padding: number): Uint8Array {
+export function padAtlasRGBA(rgba: Uint8Array, atlas: FontAtlas, padding: number): Uint8Array {
   if (!padding || padding <= 0 || !atlas?.glyphs) return rgba;
   const width = atlas.bitmap?.width ?? 0;
   const height = atlas.bitmap?.rows ?? 0;
@@ -57,7 +57,7 @@ export function padAtlasRGBA(rgba: Uint8Array, atlas: any, padding: number): Uin
     out[dstIdx + 3] = out[srcIdx + 3];
   };
 
-  const padMetrics = (metrics: any) => {
+  const padMetrics = (metrics: FontAtlasGlyphMetrics) => {
     const x0 = metrics.atlasX;
     const y0 = metrics.atlasY;
     const x1 = metrics.atlasX + metrics.width - 1;
@@ -110,9 +110,9 @@ export function resolveGlyphPixelMode(
 }
 
 export function atlasBitmapToRGBA(
-  atlas: any,
+  atlas: FontAtlas,
   pixelModeRgba: number,
-  atlasToRGBA: (atlas: any) => Uint8Array,
+  atlasToRGBA: (atlas: FontAtlas) => Uint8Array,
 ): Uint8Array | null {
   const bitmap = atlas?.bitmap;
   if (!bitmap?.width || !bitmap?.rows) return null;