@payez/next-mvp 4.1.10 → 4.1.20

package/src/utils/circuitBreaker.ts

@@ -1,40 +1,40 @@
-// Circuit breaker (lifted)
-import { circuitBreakerLogger } from '../config/logger';
-
-const CIRCUIT_BREAKER_KEY = 'idp-circuit-breaker';
-const isDev = process.env.NODE_ENV === 'development';
-const isTest = process.env.NODE_ENV === 'test';
-const DEV_CONFIG = { FAILURE_THRESHOLD: 5, RECOVERY_TIME: 10000, RECOVERY_BACKOFF_MULTIPLIER: 1.5, MAX_RECOVERY_TIME: 120000 };
-const PROD_CONFIG = { FAILURE_THRESHOLD: 3, RECOVERY_TIME: 30000, RECOVERY_BACKOFF_MULTIPLIER: 2, MAX_RECOVERY_TIME: 300000 };
-const TEST_CONFIG = { FAILURE_THRESHOLD: 3, RECOVERY_TIME: 30000, RECOVERY_BACKOFF_MULTIPLIER: 2, MAX_RECOVERY_TIME: 300000 };
-const config = isTest ? TEST_CONFIG : (isDev ? DEV_CONFIG : PROD_CONFIG);
-const FAILURE_THRESHOLD = config.FAILURE_THRESHOLD;
-const RECOVERY_TIME = config.RECOVERY_TIME;
-const RECOVERY_BACKOFF_MULTIPLIER = config.RECOVERY_BACKOFF_MULTIPLIER;
-const MAX_RECOVERY_TIME = config.MAX_RECOVERY_TIME;
-
-export enum CircuitBreakerStateType { CLOSED = 'CLOSED', OPEN = 'OPEN', HALF_OPEN = 'HALF_OPEN' }
-export interface CircuitBreakerState { failures: number; lastFailure: number; isOpen: boolean; state: CircuitBreakerStateType; recoveryTime: number; testRequestInProgress: boolean; recoveryAttempts: number; }
-const circuitBreakerStore = new Map<string, CircuitBreakerState>();
-
-export function getCircuitBreakerState(): CircuitBreakerState {
-  const state = circuitBreakerStore.get(CIRCUIT_BREAKER_KEY);
-  if (!state) { const newState: CircuitBreakerState = { failures: 0, lastFailure: 0, isOpen: false, state: CircuitBreakerStateType.CLOSED, recoveryTime: RECOVERY_TIME, testRequestInProgress: false, recoveryAttempts: 0 }; circuitBreakerStore.set(CIRCUIT_BREAKER_KEY, newState); return newState; }
-  if (state.state === CircuitBreakerStateType.OPEN && Date.now() - state.lastFailure > state.recoveryTime) { state.state = CircuitBreakerStateType.HALF_OPEN; state.isOpen = true; state.testRequestInProgress = false; }
-  return state;
-}
-
-export function canAttemptRefresh() { const state = getCircuitBreakerState(); if (state.state === CircuitBreakerStateType.CLOSED) return true; if (state.state === CircuitBreakerStateType.HALF_OPEN && !state.testRequestInProgress) { state.testRequestInProgress = true; return true; } return false; }
-export function recordFailure(error?: any) { const state = getCircuitBreakerState(); if (state.state === CircuitBreakerStateType.HALF_OPEN) { state.state = CircuitBreakerStateType.OPEN; state.isOpen = true; state.testRequestInProgress = false; state.failures++; state.lastFailure = Date.now(); state.recoveryAttempts++; state.recoveryTime = Math.min(RECOVERY_TIME * Math.pow(RECOVERY_BACKOFF_MULTIPLIER, state.recoveryAttempts), MAX_RECOVERY_TIME); } else { state.failures++; state.lastFailure = Date.now(); if (state.failures >= FAILURE_THRESHOLD) { state.state = CircuitBreakerStateType.OPEN; state.isOpen = true; state.testRequestInProgress = false; state.recoveryAttempts = 0; } } }
-export function recordSuccess() { const state = getCircuitBreakerState(); state.state = CircuitBreakerStateType.CLOSED; state.isOpen = false; state.failures = 0; state.testRequestInProgress = false; state.recoveryTime = RECOVERY_TIME; state.recoveryAttempts = 0; }
-export function isConnectionRefusedError(error: any): boolean { return error?.cause?.code === 'ECONNREFUSED' || error?.code === 'ECONNREFUSED' || error?.message?.includes('ECONNREFUSED'); }
-export function isNetworkError(error: any): boolean { return isConnectionRefusedError(error) || error?.message?.includes('fetch failed') || error?.message?.includes('ENOTFOUND') || error?.message?.includes('ETIMEDOUT') || error?.message?.includes('ECONNRESET') || error?.code === 'ENOTFOUND' || error?.code === 'ETIMEDOUT' || error?.code === 'ECONNRESET'; }
-export function getCircuitBreakerStateName(): string { const state = getCircuitBreakerState(); return state.state; }
-export function isCircuitBreakerOpen(): boolean { const state = getCircuitBreakerState(); return state.state === CircuitBreakerStateType.OPEN; }
-export function isCircuitBreakerHalfOpen(): boolean { const state = getCircuitBreakerState(); return state.state === CircuitBreakerStateType.HALF_OPEN; }
-export function isCircuitBreakerClosed(): boolean { const state = getCircuitBreakerState(); return state.state === CircuitBreakerStateType.CLOSED; }
-export function attemptRecovery(): boolean { const state = getCircuitBreakerState(); if (state.state === CircuitBreakerStateType.OPEN && Date.now() - state.lastFailure > state.recoveryTime) { state.state = CircuitBreakerStateType.HALF_OPEN; state.isOpen = true; state.testRequestInProgress = false; return true; } return false; }
-export function getTimeUntilRecovery(): number { const state = getCircuitBreakerState(); if (state.state !== CircuitBreakerStateType.OPEN) return 0; const timeSinceLastFailure = Date.now() - state.lastFailure; const timeUntilRecovery = state.recoveryTime - timeSinceLastFailure; return Math.max(0, timeUntilRecovery); }
-export function resetCircuitBreaker() { const state = getCircuitBreakerState(); state.state = CircuitBreakerStateType.CLOSED; state.isOpen = false; state.failures = 0; state.testRequestInProgress = false; state.recoveryTime = RECOVERY_TIME; state.lastFailure = 0; state.recoveryAttempts = 0; }
-export function clearCircuitBreakerStore() { circuitBreakerStore.clear(); }
-export const circuitBreaker = { getCircuitBreakerState, recordFailure, recordSuccess, isNetworkError, isConnectionRefusedError, canAttemptRefresh, getCircuitBreakerStateName, isCircuitBreakerOpen, isCircuitBreakerHalfOpen, isCircuitBreakerClosed, resetCircuitBreaker, attemptRecovery, getTimeUntilRecovery };
+// Circuit breaker (lifted)
+import { circuitBreakerLogger } from '../config/logger';
+
+const CIRCUIT_BREAKER_KEY = 'idp-circuit-breaker';
+const isDev = process.env.NODE_ENV === 'development';
+const isTest = process.env.NODE_ENV === 'test';
+const DEV_CONFIG = { FAILURE_THRESHOLD: 5, RECOVERY_TIME: 10000, RECOVERY_BACKOFF_MULTIPLIER: 1.5, MAX_RECOVERY_TIME: 120000 };
+const PROD_CONFIG = { FAILURE_THRESHOLD: 3, RECOVERY_TIME: 30000, RECOVERY_BACKOFF_MULTIPLIER: 2, MAX_RECOVERY_TIME: 300000 };
+const TEST_CONFIG = { FAILURE_THRESHOLD: 3, RECOVERY_TIME: 30000, RECOVERY_BACKOFF_MULTIPLIER: 2, MAX_RECOVERY_TIME: 300000 };
+const config = isTest ? TEST_CONFIG : (isDev ? DEV_CONFIG : PROD_CONFIG);
+const FAILURE_THRESHOLD = config.FAILURE_THRESHOLD;
+const RECOVERY_TIME = config.RECOVERY_TIME;
+const RECOVERY_BACKOFF_MULTIPLIER = config.RECOVERY_BACKOFF_MULTIPLIER;
+const MAX_RECOVERY_TIME = config.MAX_RECOVERY_TIME;
+
+export enum CircuitBreakerStateType { CLOSED = 'CLOSED', OPEN = 'OPEN', HALF_OPEN = 'HALF_OPEN' }
+export interface CircuitBreakerState { failures: number; lastFailure: number; isOpen: boolean; state: CircuitBreakerStateType; recoveryTime: number; testRequestInProgress: boolean; recoveryAttempts: number; }
+const circuitBreakerStore = new Map<string, CircuitBreakerState>();
+
+export function getCircuitBreakerState(): CircuitBreakerState {
+  const state = circuitBreakerStore.get(CIRCUIT_BREAKER_KEY);
+  if (!state) { const newState: CircuitBreakerState = { failures: 0, lastFailure: 0, isOpen: false, state: CircuitBreakerStateType.CLOSED, recoveryTime: RECOVERY_TIME, testRequestInProgress: false, recoveryAttempts: 0 }; circuitBreakerStore.set(CIRCUIT_BREAKER_KEY, newState); return newState; }
+  if (state.state === CircuitBreakerStateType.OPEN && Date.now() - state.lastFailure > state.recoveryTime) { state.state = CircuitBreakerStateType.HALF_OPEN; state.isOpen = true; state.testRequestInProgress = false; }
+  return state;
+}
+
+export function canAttemptRefresh() { const state = getCircuitBreakerState(); if (state.state === CircuitBreakerStateType.CLOSED) return true; if (state.state === CircuitBreakerStateType.HALF_OPEN && !state.testRequestInProgress) { state.testRequestInProgress = true; return true; } return false; }
+export function recordFailure(error?: any) { const state = getCircuitBreakerState(); if (state.state === CircuitBreakerStateType.HALF_OPEN) { state.state = CircuitBreakerStateType.OPEN; state.isOpen = true; state.testRequestInProgress = false; state.failures++; state.lastFailure = Date.now(); state.recoveryAttempts++; state.recoveryTime = Math.min(RECOVERY_TIME * Math.pow(RECOVERY_BACKOFF_MULTIPLIER, state.recoveryAttempts), MAX_RECOVERY_TIME); } else { state.failures++; state.lastFailure = Date.now(); if (state.failures >= FAILURE_THRESHOLD) { state.state = CircuitBreakerStateType.OPEN; state.isOpen = true; state.testRequestInProgress = false; state.recoveryAttempts = 0; } } }
+export function recordSuccess() { const state = getCircuitBreakerState(); state.state = CircuitBreakerStateType.CLOSED; state.isOpen = false; state.failures = 0; state.testRequestInProgress = false; state.recoveryTime = RECOVERY_TIME; state.recoveryAttempts = 0; }
+export function isConnectionRefusedError(error: any): boolean { return error?.cause?.code === 'ECONNREFUSED' || error?.code === 'ECONNREFUSED' || error?.message?.includes('ECONNREFUSED'); }
+export function isNetworkError(error: any): boolean { return isConnectionRefusedError(error) || error?.message?.includes('fetch failed') || error?.message?.includes('ENOTFOUND') || error?.message?.includes('ETIMEDOUT') || error?.message?.includes('ECONNRESET') || error?.code === 'ENOTFOUND' || error?.code === 'ETIMEDOUT' || error?.code === 'ECONNRESET'; }
+export function getCircuitBreakerStateName(): string { const state = getCircuitBreakerState(); return state.state; }
+export function isCircuitBreakerOpen(): boolean { const state = getCircuitBreakerState(); return state.state === CircuitBreakerStateType.OPEN; }
+export function isCircuitBreakerHalfOpen(): boolean { const state = getCircuitBreakerState(); return state.state === CircuitBreakerStateType.HALF_OPEN; }
+export function isCircuitBreakerClosed(): boolean { const state = getCircuitBreakerState(); return state.state === CircuitBreakerStateType.CLOSED; }
+export function attemptRecovery(): boolean { const state = getCircuitBreakerState(); if (state.state === CircuitBreakerStateType.OPEN && Date.now() - state.lastFailure > state.recoveryTime) { state.state = CircuitBreakerStateType.HALF_OPEN; state.isOpen = true; state.testRequestInProgress = false; return true; } return false; }
+export function getTimeUntilRecovery(): number { const state = getCircuitBreakerState(); if (state.state !== CircuitBreakerStateType.OPEN) return 0; const timeSinceLastFailure = Date.now() - state.lastFailure; const timeUntilRecovery = state.recoveryTime - timeSinceLastFailure; return Math.max(0, timeUntilRecovery); }
+export function resetCircuitBreaker() { const state = getCircuitBreakerState(); state.state = CircuitBreakerStateType.CLOSED; state.isOpen = false; state.failures = 0; state.testRequestInProgress = false; state.recoveryTime = RECOVERY_TIME; state.lastFailure = 0; state.recoveryAttempts = 0; }
+export function clearCircuitBreakerStore() { circuitBreakerStore.clear(); }
+export const circuitBreaker = { getCircuitBreakerState, recordFailure, recordSuccess, isNetworkError, isConnectionRefusedError, canAttemptRefresh, getCircuitBreakerStateName, isCircuitBreakerOpen, isCircuitBreakerHalfOpen, isCircuitBreakerClosed, resetCircuitBreaker, attemptRecovery, getTimeUntilRecovery };

package/src/utils/error-message.ts

@@ -1,108 +1,108 @@
-// Utility to convert unknown errors or standardized API JSON into a friendly string
-// Keeps UI clean by avoiding raw JSON rendering.
-
-export function toFriendlyErrorMessage(err: unknown): string {
-  try {
-    // If it's already a string, try to parse JSON first
-    if (typeof err === 'string') {
-      const trimmed = err.trim();
-      if (looksLikeJson(trimmed)) {
-        const parsed = JSON.parse(trimmed);
-        return fromStructured(parsed);
-      }
-      return normalizeMessage(trimmed);
-    }
-
-    // If it's an Error
-    if (err instanceof Error) {
-      return normalizeMessage(err.message);
-    }
-
-    // Try to handle plain objects
-    if (err && typeof err === 'object') {
-      return fromStructured(err as Record<string, any>);
-    }
-
-    // Fallback
-    return 'Something went wrong. Please try again.';
-  } catch {
-    return 'Something went wrong. Please try again.';
-  }
-}
-
-function looksLikeJson(input: string) {
-  return (input.startsWith('{') && input.endsWith('}')) || (input.startsWith('[') && input.endsWith(']'));
-}
-
-function fromStructured(obj: Record<string, any>): string {
-  // StandardizedResponse shapes we use across the app
-  const success = get<boolean>(obj, ['success']);
-  const message = get<string>(obj, ['message']) || get<string>(obj, ['error', 'message']);
-  const code = get<string>(obj, ['error', 'code']) || get<string>(obj, ['error_code']);
-  const status = get<number>(obj, ['status']) || get<number>(obj, ['error', 'status']);
-
-  // Prefer the message if present
-  if (message) {
-    return normalizeMessage(message, code, status);
-  }
-
-  // If we have a code or status, map it
-  if (code || status) {
-    return normalizeMessage(undefined, code, status);
-  }
-
-  // As a last resort, do not dump raw JSON — provide generic fallback
-  return 'We could not complete your request. Please try again.';
-}
-
-function normalizeMessage(message?: string, code?: string, status?: number): string {
-  const msg = (message || '').toLowerCase();
-  const c = (code || '').toUpperCase();
-
-  // Map well-known codes first
-  switch (c) {
-    case 'TIMEOUT':
-    case 'REQUEST_TIMEOUT':
-      return 'Request timed out. Please try again.';
-    case 'TOO_MANY_REQUESTS':
-    case 'RATE_LIMIT_EXCEEDED':
-      return 'Too many attempts. Please wait a moment and try again.';
-    case 'SERVICE_UNAVAILABLE':
-      return 'Service temporarily unavailable. Please try again shortly.';
-    case 'UNAUTHORIZED':
-    case 'INVALID_SESSION':
-    case 'TOKEN_EXPIRED':
-      return 'Your session has expired. Please log in again.';
-    case 'VALIDATION_ERROR':
-      return 'Please check the code and try again.';
-  }
-
-  // Map by HTTP-ish status if provided
-  if (status === 408) return 'Request timed out. Please try again.';
-  if (status === 429) return 'Too many attempts. Please wait a moment and try again.';
-  if (status === 401) return 'Your session has expired. Please log in again.';
-  if (status === 503) return 'Service temporarily unavailable. Please try again shortly.';
-
-  // Heuristic by message content
-  if (msg.includes('timeout')) return 'Request timed out. Please try again.';
-  if (msg.includes('too many request') || msg.includes('rate limit'))
-    return 'Too many attempts. Please wait a moment and try again.';
-  if (msg.includes('unauthorized') || msg.includes('authentication failed') || msg.includes('session expired'))
-    return 'Your session has expired. Please log in again.';
-  if (msg.includes('network') || msg.includes('failed to fetch'))
-    return 'Network error. Check your connection and try again.';
-
-  // Default to the original message if we have one
-  if (message && message.trim()) return message;
-
-  return 'We could not complete your request. Please try again.';
-}
-
-function get<T = unknown>(obj: Record<string, any>, path: (string | number)[]): T | undefined {
-  let cur: any = obj;
-  for (const p of path) {
-    if (cur == null || typeof cur !== 'object' || !(p in cur)) return undefined;
-    cur = cur[p as any];
-  }
-  return cur as T;
-}
+// Utility to convert unknown errors or standardized API JSON into a friendly string
+// Keeps UI clean by avoiding raw JSON rendering.
+
+export function toFriendlyErrorMessage(err: unknown): string {
+  try {
+    // If it's already a string, try to parse JSON first
+    if (typeof err === 'string') {
+      const trimmed = err.trim();
+      if (looksLikeJson(trimmed)) {
+        const parsed = JSON.parse(trimmed);
+        return fromStructured(parsed);
+      }
+      return normalizeMessage(trimmed);
+    }
+
+    // If it's an Error
+    if (err instanceof Error) {
+      return normalizeMessage(err.message);
+    }
+
+    // Try to handle plain objects
+    if (err && typeof err === 'object') {
+      return fromStructured(err as Record<string, any>);
+    }
+
+    // Fallback
+    return 'Something went wrong. Please try again.';
+  } catch {
+    return 'Something went wrong. Please try again.';
+  }
+}
+
+function looksLikeJson(input: string) {
+  return (input.startsWith('{') && input.endsWith('}')) || (input.startsWith('[') && input.endsWith(']'));
+}
+
+function fromStructured(obj: Record<string, any>): string {
+  // StandardizedResponse shapes we use across the app
+  const success = get<boolean>(obj, ['success']);
+  const message = get<string>(obj, ['message']) || get<string>(obj, ['error', 'message']);
+  const code = get<string>(obj, ['error', 'code']) || get<string>(obj, ['error_code']);
+  const status = get<number>(obj, ['status']) || get<number>(obj, ['error', 'status']);
+
+  // Prefer the message if present
+  if (message) {
+    return normalizeMessage(message, code, status);
+  }
+
+  // If we have a code or status, map it
+  if (code || status) {
+    return normalizeMessage(undefined, code, status);
+  }
+
+  // As a last resort, do not dump raw JSON — provide generic fallback
+  return 'We could not complete your request. Please try again.';
+}
+
+function normalizeMessage(message?: string, code?: string, status?: number): string {
+  const msg = (message || '').toLowerCase();
+  const c = (code || '').toUpperCase();
+
+  // Map well-known codes first
+  switch (c) {
+    case 'TIMEOUT':
+    case 'REQUEST_TIMEOUT':
+      return 'Request timed out. Please try again.';
+    case 'TOO_MANY_REQUESTS':
+    case 'RATE_LIMIT_EXCEEDED':
+      return 'Too many attempts. Please wait a moment and try again.';
+    case 'SERVICE_UNAVAILABLE':
+      return 'Service temporarily unavailable. Please try again shortly.';
+    case 'UNAUTHORIZED':
+    case 'INVALID_SESSION':
+    case 'TOKEN_EXPIRED':
+      return 'Your session has expired. Please log in again.';
+    case 'VALIDATION_ERROR':
+      return 'Please check the code and try again.';
+  }
+
+  // Map by HTTP-ish status if provided
+  if (status === 408) return 'Request timed out. Please try again.';
+  if (status === 429) return 'Too many attempts. Please wait a moment and try again.';
+  if (status === 401) return 'Your session has expired. Please log in again.';
+  if (status === 503) return 'Service temporarily unavailable. Please try again shortly.';
+
+  // Heuristic by message content
+  if (msg.includes('timeout')) return 'Request timed out. Please try again.';
+  if (msg.includes('too many request') || msg.includes('rate limit'))
+    return 'Too many attempts. Please wait a moment and try again.';
+  if (msg.includes('unauthorized') || msg.includes('authentication failed') || msg.includes('session expired'))
+    return 'Your session has expired. Please log in again.';
+  if (msg.includes('network') || msg.includes('failed to fetch'))
+    return 'Network error. Check your connection and try again.';
+
+  // Default to the original message if we have one
+  if (message && message.trim()) return message;
+
+  return 'We could not complete your request. Please try again.';
+}
+
+function get<T = unknown>(obj: Record<string, any>, path: (string | number)[]): T | undefined {
+  let cur: any = obj;
+  for (const p of path) {
+    if (cur == null || typeof cur !== 'object' || !(p in cur)) return undefined;
+    cur = cur[p as any];
+  }
+  return cur as T;
+}

package/src/utils/layout/reservedSpace.ts

@@ -1,124 +1,124 @@
-/**
- * Deterministic Reserved Space Utilities
- * 
- * PURPOSE: Measure exact computed typography and box metrics to calculate precise
- * reserved heights for dynamic UI regions, eliminating layout shift.
- * 
- * MATHEMATICAL FOUNDATION:
- * MaxHeight = (LineHeight × MaxLines) + (VerticalPadding × 2) 
- *           + (MarginBetweenItems × (MaxLines - 1)) + BorderWidths
- * 
- * All measurements are DOM-computed px values (zoom-safe, sub-pixel precision).
- */
-
-export type TypographyMetrics = {
-  fontSizePx: number;
-  lineHeightPx: number; // already in px (computed)
-  fontFamily: string;
-  fontWeight: string;
-  letterSpacingPx: number;
-};
-
-export type BoxMetrics = {
-  paddingTop: number;
-  paddingBottom: number;
-  borderTop: number;
-  borderBottom: number;
-  marginTop: number;
-  marginBottom: number;
-};
-
-/**
- * Extract precise typography metrics from an element's computed styles
- */
-export function getTypographyMetrics(el: Element): TypographyMetrics {
-  const cs = getComputedStyle(el);
-  const fontSizePx = parseFloat(cs.fontSize);
-  const lineHeightPx =
-    cs.lineHeight === "normal" ? fontSizePx * 1.2 : parseFloat(cs.lineHeight);
-  const letterSpacingPx = parseFloat(cs.letterSpacing || "0") || 0;
-  return {
-    fontSizePx,
-    lineHeightPx,
-    fontFamily: cs.fontFamily,
-    fontWeight: cs.fontWeight,
-    letterSpacingPx,
-  };
-}
-
-/**
- * Extract box model metrics from an element's computed styles
- */
-export function getBoxMetrics(el: Element): BoxMetrics {
-  const cs = getComputedStyle(el);
-  return {
-    paddingTop: parseFloat(cs.paddingTop),
-    paddingBottom: parseFloat(cs.paddingBottom),
-    borderTop: parseFloat(cs.borderTopWidth),
-    borderBottom: parseFloat(cs.borderBottomWidth),
-    marginTop: parseFloat(cs.marginTop),
-    marginBottom: parseFloat(cs.marginBottom),
-  };
-}
-
-/**
- * Mathematical formula per spec:
- * MaxHeight = (LineHeight × MaxLines) + (VerticalPadding × 2) 
- *           + (MarginBetweenItems × (MaxLines - 1)) + BorderWidths
- */
-export function calcHeightFromLines(args: {
-  lineHeightPx: number;
-  maxLines: number;
-  verticalPaddingPx: number; // paddingTop + paddingBottom
-  marginBetweenItemsPx: number; // applied between lines/items
-  borderWidthsPx: number; // borderTop + borderBottom
-}): number {
-  const { lineHeightPx, maxLines, verticalPaddingPx, marginBetweenItemsPx, borderWidthsPx } = args;
-  const content = lineHeightPx * maxLines;
-  const gaps = Math.max(0, maxLines - 1) * marginBetweenItemsPx;
-  return content + verticalPaddingPx + gaps + borderWidthsPx;
-}
-
-/**
- * Measure arbitrary DOM subtree height at a constrained width using an offscreen probe.
- * This leverages the browser layout engine for exact results at any zoom level.
- * 
- * CRITICAL: The probe uses contain: layout style size to isolate layout cost.
- */
-export function measureNodeHeightAtWidth(nodeFactory: () => HTMLElement, widthPx: number): number {
-  const probeHost = document.createElement("div");
-  probeHost.style.position = "absolute";
-  probeHost.style.visibility = "hidden";
-  probeHost.style.pointerEvents = "none";
-  probeHost.style.left = "-100000px";
-  probeHost.style.top = "0";
-  probeHost.style.width = widthPx + "px";
-  probeHost.style.contain = "layout style size";
-  const node = nodeFactory();
-  probeHost.appendChild(node);
-  document.body.appendChild(probeHost);
-  const h = probeHost.getBoundingClientRect().height;
-  document.body.removeChild(probeHost);
-  return h;
-}
-
-/**
- * Observe size changes and DPR to keep measurements exact across zoom/viewport changes.
- * Returns cleanup function.
- */
-export function observeForRecalc(target: Element, cb: () => void): () => void {
-  const ro = new ResizeObserver(() => cb());
-  ro.observe(target as Element);
-  const onResize = () => cb();
-  window.addEventListener("resize", onResize);
-  if (window.visualViewport) {
-    window.visualViewport.addEventListener("resize", onResize);
-  }
-  return () => {
-    ro.disconnect();
-    window.removeEventListener("resize", onResize);
-    if (window.visualViewport) {
-      window.visualViewport.removeEventListener("resize", onResize);
-    }
-  };
-}
+/**
+ * Deterministic Reserved Space Utilities
+ * 
+ * PURPOSE: Measure exact computed typography and box metrics to calculate precise
+ * reserved heights for dynamic UI regions, eliminating layout shift.
+ * 
+ * MATHEMATICAL FOUNDATION:
+ * MaxHeight = (LineHeight × MaxLines) + (VerticalPadding × 2) 
+ *           + (MarginBetweenItems × (MaxLines - 1)) + BorderWidths
+ * 
+ * All measurements are DOM-computed px values (zoom-safe, sub-pixel precision).
+ */
+
+export type TypographyMetrics = {
+  fontSizePx: number;
+  lineHeightPx: number; // already in px (computed)
+  fontFamily: string;
+  fontWeight: string;
+  letterSpacingPx: number;
+};
+
+export type BoxMetrics = {
+  paddingTop: number;
+  paddingBottom: number;
+  borderTop: number;
+  borderBottom: number;
+  marginTop: number;
+  marginBottom: number;
+};
+
+/**
+ * Extract precise typography metrics from an element's computed styles
+ */
+export function getTypographyMetrics(el: Element): TypographyMetrics {
+  const cs = getComputedStyle(el);
+  const fontSizePx = parseFloat(cs.fontSize);
+  const lineHeightPx =
+    cs.lineHeight === "normal" ? fontSizePx * 1.2 : parseFloat(cs.lineHeight);
+  const letterSpacingPx = parseFloat(cs.letterSpacing || "0") || 0;
+  return {
+    fontSizePx,
+    lineHeightPx,
+    fontFamily: cs.fontFamily,
+    fontWeight: cs.fontWeight,
+    letterSpacingPx,
+  };
+}
+
+/**
+ * Extract box model metrics from an element's computed styles
+ */
+export function getBoxMetrics(el: Element): BoxMetrics {
+  const cs = getComputedStyle(el);
+  return {
+    paddingTop: parseFloat(cs.paddingTop),
+    paddingBottom: parseFloat(cs.paddingBottom),
+    borderTop: parseFloat(cs.borderTopWidth),
+    borderBottom: parseFloat(cs.borderBottomWidth),
+    marginTop: parseFloat(cs.marginTop),
+    marginBottom: parseFloat(cs.marginBottom),
+  };
+}
+
+/**
+ * Mathematical formula per spec:
+ * MaxHeight = (LineHeight × MaxLines) + (VerticalPadding × 2) 
+ *           + (MarginBetweenItems × (MaxLines - 1)) + BorderWidths
+ */
+export function calcHeightFromLines(args: {
+  lineHeightPx: number;
+  maxLines: number;
+  verticalPaddingPx: number; // paddingTop + paddingBottom
+  marginBetweenItemsPx: number; // applied between lines/items
+  borderWidthsPx: number; // borderTop + borderBottom
+}): number {
+  const { lineHeightPx, maxLines, verticalPaddingPx, marginBetweenItemsPx, borderWidthsPx } = args;
+  const content = lineHeightPx * maxLines;
+  const gaps = Math.max(0, maxLines - 1) * marginBetweenItemsPx;
+  return content + verticalPaddingPx + gaps + borderWidthsPx;
+}
+
+/**
+ * Measure arbitrary DOM subtree height at a constrained width using an offscreen probe.
+ * This leverages the browser layout engine for exact results at any zoom level.
+ * 
+ * CRITICAL: The probe uses contain: layout style size to isolate layout cost.
+ */
+export function measureNodeHeightAtWidth(nodeFactory: () => HTMLElement, widthPx: number): number {
+  const probeHost = document.createElement("div");
+  probeHost.style.position = "absolute";
+  probeHost.style.visibility = "hidden";
+  probeHost.style.pointerEvents = "none";
+  probeHost.style.left = "-100000px";
+  probeHost.style.top = "0";
+  probeHost.style.width = widthPx + "px";
+  probeHost.style.contain = "layout style size";
+  const node = nodeFactory();
+  probeHost.appendChild(node);
+  document.body.appendChild(probeHost);
+  const h = probeHost.getBoundingClientRect().height;
+  document.body.removeChild(probeHost);
+  return h;
+}
+
+/**
+ * Observe size changes and DPR to keep measurements exact across zoom/viewport changes.
+ * Returns cleanup function.
+ */
+export function observeForRecalc(target: Element, cb: () => void): () => void {
+  const ro = new ResizeObserver(() => cb());
+  ro.observe(target as Element);
+  const onResize = () => cb();
+  window.addEventListener("resize", onResize);
+  if (window.visualViewport) {
+    window.visualViewport.addEventListener("resize", onResize);
+  }
+  return () => {
+    ro.disconnect();
+    window.removeEventListener("resize", onResize);
+    if (window.visualViewport) {
+      window.visualViewport.removeEventListener("resize", onResize);
+    }
+  };
+}