pagyra-js 0.0.1

package/src/layout/utils/node-math.ts

@@ -0,0 +1,237 @@
+import { LayoutNode } from "../../dom/node.js";
+import { Display, FloatMode, OverflowMode, Position } from "../../css/enums.js";
+import { clampMinMax, resolveLength, isAutoLength, type LengthLike } from "../../css/length.js";
+import type { ContainingBlock, Viewport } from "../../geometry/box.js";
+
+export interface BoxMetrics {
+  paddingLeft: number;
+  paddingRight: number;
+  paddingTop: number;
+  paddingBottom: number;
+  borderLeft: number;
+  borderRight: number;
+  borderTop: number;
+  borderBottom: number;
+  contentBoxX: number;
+  contentBoxY: number;
+}
+
+export function resolveBoxMetrics(node: LayoutNode, widthRef: number, heightRef: number): BoxMetrics {
+  const { style } = node;
+  const paddingLeft = resolveLength(style.paddingLeft, widthRef, { auto: "zero" });
+  const paddingRight = resolveLength(style.paddingRight, widthRef, { auto: "zero" });
+  const paddingTop = resolveLength(style.paddingTop, heightRef, { auto: "zero" });
+  const paddingBottom = resolveLength(style.paddingBottom, heightRef, { auto: "zero" });
+  const borderLeft = resolveLength(style.borderLeft, widthRef, { auto: "zero" });
+  const borderRight = resolveLength(style.borderRight, widthRef, { auto: "zero" });
+  const borderTop = resolveLength(style.borderTop, heightRef, { auto: "zero" });
+  const borderBottom = resolveLength(style.borderBottom, heightRef, { auto: "zero" });
+
+  return {
+    paddingLeft,
+    paddingRight,
+    paddingTop,
+    paddingBottom,
+    borderLeft,
+    borderRight,
+    borderTop,
+    borderBottom,
+    contentBoxX: node.box.x + borderLeft + paddingLeft,
+    contentBoxY: node.box.y + borderTop + paddingTop,
+  };
+}
+
+export function horizontalNonContent(node: LayoutNode, reference: number): number {
+  const { style } = node;
+  return (
+    resolveLength(style.paddingLeft, reference, { auto: "zero" }) +
+    resolveLength(style.paddingRight, reference, { auto: "zero" }) +
+    resolveLength(style.borderLeft, reference, { auto: "zero" }) +
+    resolveLength(style.borderRight, reference, { auto: "zero" })
+  );
+}
+
+export function verticalNonContent(node: LayoutNode, reference: number): number {
+  const { style } = node;
+  return (
+    resolveLength(style.paddingTop, reference, { auto: "zero" }) +
+    resolveLength(style.paddingBottom, reference, { auto: "zero" }) +
+    resolveLength(style.borderTop, reference, { auto: "zero" }) +
+    resolveLength(style.borderBottom, reference, { auto: "zero" })
+  );
+}
+
+export function horizontalMargin(node: LayoutNode, reference: number): number {
+  const { style } = node;
+  return resolveLength(style.marginLeft, reference, { auto: "zero" }) + resolveLength(style.marginRight, reference, { auto: "zero" });
+}
+
+export function verticalMargin(node: LayoutNode, reference: number): number {
+  const { style } = node;
+  return resolveLength(style.marginTop, reference, { auto: "zero" }) + resolveLength(style.marginBottom, reference, { auto: "zero" });
+}
+
+export function inFlow(node: LayoutNode): boolean {
+  const { position, float: floatMode } = node.style;
+  const isFlowPosition = position === Position.Static || position === Position.Relative || position === Position.Sticky;
+  return isFlowPosition && floatMode === FloatMode.None;
+}
+
+export function establishesBFC(node: LayoutNode): boolean {
+  const { style } = node;
+  return (
+    style.float !== FloatMode.None ||
+    style.position === Position.Absolute ||
+    style.position === Position.Fixed ||
+    overflowCreatesBFC(style.overflowX) ||
+    overflowCreatesBFC(style.overflowY) ||
+    style.display === Display.InlineBlock ||
+    style.display === Display.Table ||
+    style.display === Display.InlineTable ||
+    style.display === Display.FlowRoot
+  );
+}
+
+function overflowCreatesBFC(mode: OverflowMode): boolean {
+  switch (mode) {
+    case OverflowMode.Hidden:
+    case OverflowMode.Auto:
+    case OverflowMode.Scroll:
+    case OverflowMode.Clip:
+      return true;
+    default:
+      return false;
+  }
+}
+
+export function nearestPositionedAncestor(node: LayoutNode): LayoutNode | null {
+  return node.nearestAncestor((ancestor) => {
+    const position = ancestor.style.position;
+    return position === Position.Relative || position === Position.Absolute || position === Position.Fixed || position === Position.Sticky;
+  });
+}
+
+export function containingBlock(node: LayoutNode, viewport: Viewport): ContainingBlock {
+  const { style } = node;
+  if (style.position === Position.Fixed) {
+    return { x: 0, y: 0, width: viewport.width, height: viewport.height };
+  }
+  if (style.position === Position.Absolute) {
+    const ancestor = nearestPositionedAncestor(node);
+    if (ancestor) {
+      return {
+        x: ancestor.box.x,
+        y: ancestor.box.y,
+        width: ancestor.box.contentWidth,
+        height: ancestor.box.contentHeight,
+      };
+    }
+    return { x: 0, y: 0, width: viewport.width, height: viewport.height };
+  }
+
+  const parent = node.parent;
+  if (!parent) {
+    return { x: 0, y: 0, width: viewport.width, height: viewport.height };
+  }
+
+  const widthRef = Math.max(parent.box.contentWidth, 0);
+  let heightRef = Math.max(parent.box.contentHeight, 0);
+
+  // If the parent has an explicit height but its content height has not
+  // been resolved yet (common when laying out flex/grid children before
+  // the block container finalizes), fall back to the specified height.
+  // This allows percentage heights like `height: 100%` on flex children
+  // to resolve against a definite containing block height instead of 0.
+  if (heightRef === 0 && parent.style.height !== "auto") {
+    const explicitHeight = resolveLength(parent.style.height, viewport.height, { auto: "reference" });
+    if (Number.isFinite(explicitHeight) && explicitHeight > 0) {
+      heightRef = explicitHeight;
+    }
+  }
+  const xOffset =
+    parent.box.x +
+    resolveLength(parent.style.paddingLeft, widthRef, { auto: "zero" }) +
+    resolveLength(parent.style.borderLeft, widthRef, { auto: "zero" });
+  const yOffset =
+    parent.box.y +
+    resolveLength(parent.style.paddingTop, heightRef, { auto: "zero" }) +
+    resolveLength(parent.style.borderTop, heightRef, { auto: "zero" });
+
+  return {
+    x: xOffset,
+    y: yOffset,
+    width: parent.box.contentWidth,
+    height: heightRef,
+  };
+}
+
+export function resolveWidthBlock(node: LayoutNode, containingBlockWidth: number): number {
+  const style = node.style;
+  const marginLeft = isAutoLength(style.marginLeft)
+    ? 0
+    : resolveLength(style.marginLeft, containingBlockWidth, { auto: "zero" });
+  const marginRight = isAutoLength(style.marginRight)
+    ? 0
+    : resolveLength(style.marginRight, containingBlockWidth, { auto: "zero" });
+  const available = Math.max(
+    0,
+    containingBlockWidth - horizontalNonContent(node, containingBlockWidth) - marginLeft - marginRight,
+  );
+  const width =
+    style.width === "auto"
+      ? available
+      : resolveLength(style.width, containingBlockWidth, {
+        auto: "reference",
+      });
+  const minWidth = style.minWidth ? resolveLength(style.minWidth, containingBlockWidth, { auto: "zero" }) : Number.NEGATIVE_INFINITY;
+  const maxWidth = style.maxWidth ? resolveLength(style.maxWidth, containingBlockWidth, { auto: "reference" }) : Number.POSITIVE_INFINITY;
+  return clampMinMax(width, minWidth, maxWidth);
+}
+
+export function resolveBlockAutoMargins(
+  containingBlockWidth: number,
+  borderBoxWidth: number,
+  marginLeft: LengthLike,
+  marginRight: LengthLike,
+): { marginLeft: number; marginRight: number } {
+  const marginLeftAuto = isAutoLength(marginLeft);
+  const marginRightAuto = isAutoLength(marginRight);
+
+  const resolvedMarginLeft = marginLeftAuto ? 0 : resolveLength(marginLeft, containingBlockWidth, { auto: "zero" });
+  const resolvedMarginRight = marginRightAuto ? 0 : resolveLength(marginRight, containingBlockWidth, { auto: "zero" });
+
+  let usedMarginLeft = resolvedMarginLeft;
+  let usedMarginRight = resolvedMarginRight;
+
+  const remainingSpace = containingBlockWidth - (borderBoxWidth + resolvedMarginLeft + resolvedMarginRight);
+
+  if (!Number.isFinite(remainingSpace)) {
+    return { marginLeft: usedMarginLeft, marginRight: usedMarginRight };
+  }
+
+  if (remainingSpace < 0) {
+    if (marginLeftAuto && marginRightAuto) {
+      usedMarginLeft = 0;
+      usedMarginRight = 0;
+    } else if (marginLeftAuto) {
+      usedMarginLeft = 0;
+    } else if (marginRightAuto) {
+      usedMarginRight = 0;
+    } else {
+      usedMarginRight = resolvedMarginRight + remainingSpace;
+    }
+  } else {
+    if (marginLeftAuto && marginRightAuto) {
+      usedMarginLeft = remainingSpace / 2;
+      usedMarginRight = remainingSpace / 2;
+    } else if (marginLeftAuto) {
+      usedMarginLeft = remainingSpace;
+    } else if (marginRightAuto) {
+      usedMarginRight = remainingSpace;
+    } else {
+      usedMarginRight = resolvedMarginRight + remainingSpace;
+    }
+  }
+
+  return { marginLeft: usedMarginLeft, marginRight: usedMarginRight };
+}

package/src/layout/utils/overflow.ts

@@ -0,0 +1,14 @@
+import { LayoutNode } from "../../dom/node.js";
+
+export function finalizeOverflow(node: LayoutNode): void {
+  const contentWidth = node.box.contentWidth;
+  const contentHeight = node.box.contentHeight;
+  node.box.scrollWidth = Math.max(
+    contentWidth,
+    ...node.children.map((child) => child.box.x + child.box.borderBoxWidth - node.box.x),
+  );
+  node.box.scrollHeight = Math.max(
+    contentHeight,
+    ...node.children.map((child) => child.box.y + child.box.borderBoxHeight - node.box.y),
+  );
+}

package/src/layout/utils/sizing.ts

@@ -0,0 +1,12 @@
+import { LayoutNode } from "../../dom/node.js";
+import { resolveLength } from "../../css/length.js";
+
+export function shrinkToFitWidth(node: LayoutNode, availableWidth: number): number {
+  if (typeof node.style.width === "number") {
+    return Math.min(node.style.width, availableWidth);
+  }
+  if (node.style.width !== "auto") {
+    return Math.min(resolveLength(node.style.width, availableWidth), availableWidth);
+  }
+  return availableWidth;
+}

package/src/layout/utils/text-metrics.ts

@@ -0,0 +1,361 @@
+import { LayoutNode } from "../../dom/node.js";
+import { resolvedLineHeight } from "../../css/style.js";
+import type { ComputedStyle } from "../../css/style.js";
+import type { TtfFontMetrics } from "../../types/fonts.js";
+import { normalizeFontWeight } from "../../css/font-weight.js";
+import { base14Widths } from "../../pdf/font/base14-widths.js";
+import { applyTextTransform } from "../../text/text-transform.js";
+
+// Font family pattern for monospace detection
+const MONO_FAMILY_PATTERN = /(mono|code|courier|console)/i;
+
+// Character width coefficients for heuristic text width calculation
+const CHARACTER_WIDTH_FACTORS = {
+  SPACE: 0.32,
+  DIGIT: 0.52,
+  UPPER: 0.58,
+  BASE: 0.5,
+  PUNCTUATION: 0.35,
+  IDEOGRAPHIC: 1.0
+} as const;
+
+// Heuristic width measurements tend to slightly overestimate glyph widths.
+// Apply a calibration factor so line breaking can pack words closer to the real layout.
+const WIDTH_CALIBRATION = 0.9;
+
+// Font weight threshold above which fonts are considered bold for Base14 selection
+const BASE14_BOLD_THRESHOLD = 600;
+
+const BASE14_ALIAS = new Map<string, string>([
+  ["helvetica", "Helvetica"],
+  ["arial", "Helvetica"],
+  ["sans-serif", "Helvetica"],
+  ["times", "Times-Roman"],
+  ["times-roman", "Times-Roman"],
+  ["times new roman", "Times-Roman"],
+  ["georgia", "Times-Roman"],
+  ["serif", "Times-Roman"],
+  ["courier", "Courier"],
+  ["courier new", "Courier"],
+  ["monaco", "Courier"],
+  ["monospace", "Courier"],
+]);
+
+const BASE14_BOLD_VARIANT = new Map<string, string>([
+  ["Times-Roman", "Times-Bold"],
+  ["Helvetica", "Helvetica-Bold"],
+  ["Courier", "Courier-Bold"],
+]);
+
+import type { FontEmbedder } from "../../pdf/font/embedder.js";
+
+export function assignIntrinsicTextMetrics(root: LayoutNode, fontEmbedder: FontEmbedder | null): void {
+  root.walk((node) => {
+    if (!node.textContent) {
+      return;
+    }
+    const trimmed = node.textContent;
+    if (trimmed.length === 0) {
+      node.intrinsicInlineSize = 0;
+      node.intrinsicBlockSize = resolvedLineHeight(node.style);
+      return;
+    }
+    const { inlineSize, blockSize } = measureText(trimmed, node.style, fontEmbedder);
+    node.intrinsicInlineSize = inlineSize;
+    node.intrinsicBlockSize = blockSize;
+  });
+}
+
+function measureText(
+  text: string,
+  style: ComputedStyle,
+  fontEmbedder: FontEmbedder | null
+): { inlineSize: number; blockSize: number } {
+  const effectiveText = applyTextTransform(text, style.textTransform);
+  const lines = effectiveText.split(/\r?\n/);
+  let maxLineWidth = 0;
+
+  const fontWeight = typeof style.fontWeight === "number" ? style.fontWeight : 400;
+  const fontStyle = style.fontStyle ?? "normal";
+  const fontMetrics = fontEmbedder?.getMetrics(style.fontFamily ?? "", fontWeight, fontStyle);
+
+  for (const line of lines) {
+    const glyphWidth = measureTextWithGlyphs(line, style, fontMetrics ?? null);
+    if (glyphWidth !== null) {
+      maxLineWidth = Math.max(maxLineWidth, glyphWidth);
+    } else {
+      maxLineWidth = Math.max(maxLineWidth, estimateLineWidth(line, style));
+    }
+  }
+  const lineHeight = resolvedLineHeight(style);
+  const blockSize = Math.max(lineHeight, lines.length * lineHeight);
+  return { inlineSize: maxLineWidth, blockSize };
+}
+
+export function estimateLineWidth(line: string, style: ComputedStyle): number {
+  if (!line) {
+    return 0;
+  }
+  const fontSize = style.fontSize || 16;
+  const isMonospace = style.fontFamily ? MONO_FAMILY_PATTERN.test(style.fontFamily) : false;
+  const baseFactor = isMonospace ? 0.6 : CHARACTER_WIDTH_FACTORS.BASE;
+  const weightMultiplier = fontWeightWidthMultiplier(normalizeFontWeight(style.fontWeight));
+  const letterSpacing = style.letterSpacing ?? 0;
+  const wordSpacing = style.wordSpacing ?? 0;
+  const spacingContribution = Math.max(line.length - 1, 0) * letterSpacing + countSpaces(line) * wordSpacing;
+
+  const base14Width = measureUsingBase14(line, style);
+  if (base14Width !== null) {
+    return base14Width + spacingContribution;
+  }
+
+  let totalFactor = 0;
+
+  for (const char of line) {
+    totalFactor += factorForChar(char, baseFactor);
+  }
+
+  const heuristicWidth = totalFactor * fontSize * weightMultiplier;
+
+  return heuristicWidth * WIDTH_CALIBRATION + spacingContribution;
+}
+
+function measureUsingBase14(text: string, style: ComputedStyle): number | null {
+  const baseFont = resolveBase14Font(style);
+  if (!baseFont) {
+    return null;
+  }
+  const widths = base14Widths[baseFont];
+  if (!widths) {
+    return null;
+  }
+  const fontSize = style.fontSize || 16;
+  let total = 0;
+  for (const char of text) {
+    const code = char.codePointAt(0);
+    if (code === undefined) {
+      return null;
+    }
+    // Handle Unicode characters that map to WinAnsi bytes (like bullet U+2022 -> 0x95)
+    if (code > 255) {
+      if (code === 0x2022) { // bullet
+        const w = widths[0x95];
+        if (w === undefined) return null;
+        total += w;
+        continue;
+      }
+      // Try diacritic fallback via NFD base letter (e.g., "ê" -> "e")
+      const base = char.normalize("NFD").replace(/\p{M}+/gu, "");
+      if (base && base.length === 1) {
+        const baseCode = base.codePointAt(0)!;
+        if (baseCode !== undefined && baseCode <= 255) {
+          const w2 = widths[baseCode];
+          if (w2 !== undefined) {
+            total += w2;
+            continue;
+          }
+        }
+      }
+      return null;
+    }
+    let w = widths[code];
+    if (w === undefined) {
+      // Try diacritic fallback via base letter
+      const base = char.normalize("NFD").replace(/\p{M}+/gu, "");
+      if (base && base.length === 1) {
+        const baseCode = base.codePointAt(0)!;
+        if (baseCode !== undefined && baseCode <= 255) {
+          w = widths[baseCode];
+        }
+      }
+      if (w === undefined) return null;
+    }
+    // Some extended entries may be overly large in datasets; clamp using base letter width
+    if (w >= 900) {
+      const base = char.normalize("NFD").replace(/\p{M}+/gu, "");
+      if (base && base.length === 1) {
+        const baseCode = base.codePointAt(0)!;
+        if (baseCode !== undefined && baseCode <= 255) {
+          const fallback = widths[baseCode];
+          if (fallback !== undefined) {
+            w = fallback;
+          }
+        }
+      }
+    }
+    total += w;
+  }
+  return (total / 1000) * fontSize;
+}
+
+function resolveBase14Font(style: ComputedStyle): string | null {
+  const tokens = parseFontFamily(style.fontFamily);
+  if (tokens.length === 0) {
+    return null;
+  }
+  const normalizedWeight = normalizeFontWeight(style.fontWeight);
+  for (const token of tokens) {
+    const alias = BASE14_ALIAS.get(token);
+    if (!alias) {
+      continue;
+    }
+    if (normalizedWeight >= BASE14_BOLD_THRESHOLD) {
+      const boldVariant = BASE14_BOLD_VARIANT.get(alias);
+      if (boldVariant) {
+        return boldVariant;
+      }
+    }
+    return alias;
+  }
+  return null;
+}
+
+function parseFontFamily(value: string | undefined): string[] {
+  if (!value) {
+    return [];
+  }
+  return value
+    .split(",")
+    .map((token) => stripQuotes(token.trim()).toLowerCase())
+    .filter((token) => token.length > 0);
+}
+
+function stripQuotes(value: string): string {
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function factorForChar(char: string, baseFactor: number): number {
+  if (char === " ") {
+    return CHARACTER_WIDTH_FACTORS.SPACE;
+  }
+  if (char === "\t") {
+    return CHARACTER_WIDTH_FACTORS.SPACE * 4; // Tab is 4 spaces
+  }
+  if (isDigit(char)) {
+    return CHARACTER_WIDTH_FACTORS.DIGIT;
+  }
+  if (isUpperCase(char)) {
+    return baseFactor + (CHARACTER_WIDTH_FACTORS.UPPER - CHARACTER_WIDTH_FACTORS.BASE);
+  }
+  if (isPunctuation(char)) {
+    return CHARACTER_WIDTH_FACTORS.PUNCTUATION;
+  }
+  if (isIdeograph(char)) {
+    return CHARACTER_WIDTH_FACTORS.IDEOGRAPHIC;
+  }
+  return baseFactor;
+}
+
+function isUpperCase(char: string): boolean {
+  return char >= "A" && char <= "Z";
+}
+
+function isDigit(char: string): boolean {
+  return char >= "0" && char <= "9";
+}
+
+function isPunctuation(char: string): boolean {
+  return /[.,;:!?'"`~\-_/\\()[\]{}<>]/.test(char);
+}
+
+function isIdeograph(char: string): boolean {
+  const code = char.codePointAt(0);
+  if (code === undefined) {
+    return false;
+  }
+  return (
+    (code >= 0x4e00 && code <= 0x9fff) || // CJK Unified Ideographs
+    (code >= 0x3400 && code <= 0x4dbf) || // CJK Unified Ideographs Extension A
+    (code >= 0xf900 && code <= 0xfaff) || // CJK Compatibility Ideographs
+    (code >= 0x3040 && code <= 0x309f) || // Hiragana
+    (code >= 0x30a0 && code <= 0x30ff) || // Katakana
+    (code >= 0xac00 && code <= 0xd7af) // Hangul Syllables
+  );
+}
+
+function countSpaces(line: string): number {
+  let count = 0;
+  for (const char of line) {
+    if (char === " ") {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+export function measureTextWithGlyphs(
+  text: string,
+  style: ComputedStyle,
+  fontMetrics: TtfFontMetrics | null
+): number | null {
+  if (!fontMetrics) {
+    return null;
+  }
+
+  const unitsPerEm = fontMetrics.metrics.unitsPerEm;
+  const kerning = fontMetrics.kerning;
+  let totalWidth = 0;
+  let prevGid: number | null = null;
+  let glyphCount = 0;
+  let spaceCount = 0;
+
+  for (const char of text) {
+    const codePoint = char.codePointAt(0);
+    if (codePoint === undefined) {
+      continue;
+    }
+    const glyphId = fontMetrics.cmap.getGlyphId(codePoint);
+    const glyphMetrics = fontMetrics.glyphMetrics.get(glyphId);
+    if (glyphMetrics) {
+      totalWidth += glyphMetrics.advanceWidth;
+    }
+    if (prevGid !== null && kerning) {
+      const kernAdjust = kerning.get(prevGid)?.get(glyphId) ?? 0;
+      if (kernAdjust !== 0) {
+        totalWidth += kernAdjust;
+      }
+    }
+    prevGid = glyphId;
+    glyphCount += 1;
+    if (char === " ") {
+      spaceCount += 1;
+    }
+  }
+
+  const scale = style.fontSize / unitsPerEm;
+  const baseWidthPx = totalWidth * scale;
+  const letterSpacing = style.letterSpacing ?? 0;
+  const wordSpacing = style.wordSpacing ?? 0;
+  const spacingContribution =
+    Math.max(glyphCount - 1, 0) * letterSpacing + spaceCount * wordSpacing;
+
+  return baseWidthPx + spacingContribution;
+}
+
+function fontWeightWidthMultiplier(weight: number): number {
+  switch (weight) {
+    case 100:
+      return 0.92;
+    case 200:
+      return 0.94;
+    case 300:
+      return 0.96;
+    case 400:
+      return 1;
+    case 500:
+      return 1.02;
+    case 600:
+      return 1.04;
+    case 700:
+      return 1.08;
+    case 800:
+      return 1.1;
+    case 900:
+      return 1.12;
+    default:
+      return 1;
+  }
+}

package/src/logging/debug.ts

@@ -0,0 +1,58 @@
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+type DebugConfig = { level: LogLevel; cats: Set<string> };
+
+const LEVEL_COLORS: Record<LogLevel, string> = {
+  trace: '\x1b[90m',
+  debug: '\x1b[36m',
+  info: '\x1b[32m',
+  warn: '\x1b[33m',
+  error: '\x1b[31m',
+};
+
+const CATEGORY_COLORS: Record<string, string> = {
+  parse: '\x1b[95m',
+  style: '\x1b[94m',
+  layout: '\x1b[96m',
+  paint: '\x1b[93m',
+  font: '\x1b[92m',
+  encoding: '\x1b[35m',
+  pdf: '\x1b[91m',
+};
+
+export const LOG_CATEGORIES = Object.keys(CATEGORY_COLORS);
+
+const RESET = '\x1b[0m';
+const DEFAULT_CAT_COLOR = '\x1b[37m';
+const order: LogLevel[] = ['trace', 'debug', 'info', 'warn', 'error'];
+
+let current: DebugConfig = { level: 'warn', cats: new Set() };
+
+/**
+ * Configure runtime logging. Categories are compared case-insensitively.
+ */
+export function configureDebug(opts?: { level?: LogLevel; cats?: string[] }) {
+  if (!opts) return;
+  if (opts.level) current.level = opts.level;
+  if (opts.cats) current.cats = new Set(opts.cats.map((cat) => cat.toLowerCase()));
+}
+
+export function log(cat: string, level: LogLevel, msg: string, obj?: unknown) {
+  const levelKey = (level as string).toLowerCase() as LogLevel;
+  const normalizedCat = cat.toLowerCase();
+  const configuredLevel = order.includes(current.level) ? current.level : 'warn';
+  if (!order.includes(levelKey)) return;
+  if (order.indexOf(levelKey) < order.indexOf(configuredLevel)) return;
+  if (current.cats.size && !current.cats.has(normalizedCat)) return;
+
+  const levelColor = LEVEL_COLORS[levelKey] ?? '';
+  const catColor = CATEGORY_COLORS[normalizedCat] ?? DEFAULT_CAT_COLOR;
+  const prefix = `${levelColor}[${levelKey.toUpperCase()}]${RESET} ${catColor}${cat}${RESET}`;
+
+  if (obj !== undefined) {
+    console.log(prefix, msg, obj);
+  } else {
+    console.log(prefix, msg);
+  }
+}
+// Note: This is the core logging function for pagyra-js, so it uses console.log directly.
+// All other console.log statements should be replaced with calls to this log function.