Array.from({ length: 26 }, (_, i) => {
  const base = String.fromCharCode(65 + i);
  const styled = String.fromCodePoint(0x1d434 + i);
  return [base, styled];
})

) );

const MATHEMATICAL_ITALIC_LOWER: CharMap = Object.freeze( Object.fromEntries( Array.from({ length: 26 }, (_, i) => { const base = String.fromCharCode(97 + i); const styled = String.fromCodePoint(0x1d44e + i); return [base, styled]; }) ) );

const COMBINING_STRIKETHROUGH = '\u0336'; const COMBINING_UNDERLINE = '\u0332';

interface TypographyPipeline { toBold: (input: string) => string; toItalic: (input: string) => string; withStrikethrough: (input: string) => string; withUnderline: (input: string) => string; }

function createTypographyEngine(): TypographyPipeline { const applyBlockMap = (text: string, upperMap: CharMap, lowerMap: CharMap): string => { return [...text].map((char) => upperMap[char] ?? lowerMap[char] ?? char).join(''); };

const applyOverlay = (text: string, combiningChar: string): string => { return [...text].map((char) => ${char}${combiningChar}).join(''); };

return { toBold: (input: string) => applyBlockMap(input, MATHEMATICAL_BOLD_UPPER, MATHEMATICAL_BOLD_LOWER), toItalic: (input: string) => applyBlockMap(input, MATHEMATICAL_ITALIC_UPPER, MATHEMATICAL_ITALIC_LOWER), withStrikethrough: (input: string) => applyOverlay(input, COMBINING_STRIKETHROUGH), withUnderline: (input: string) => applyOverlay(input, COMBINING_UNDERLINE), }; }

export const typography = createTypographyEngine();

### Step 4: Rationale Behind Design Choices

- **`Object.freeze` & `Readonly`**: Prevents accidental mutation of lookup tables during runtime, ensuring deterministic behavior in concurrent or hot-reload environments.
- **`[...text]` Iteration**: Safely handles surrogate pairs and extended Unicode planes. Unlike `.split('')`, it respects grapheme boundaries for most common cases, preventing emoji or supplementary character corruption.
- **Separation of Concerns**: Block mapping replaces characters; overlay appends diacritics. Mixing these approaches causes rendering conflicts. The pipeline enforces this boundary.
- **Factory Pattern (`createTypographyEngine`)**: Enables dependency injection, testing isolation, and future extension (e.g., adding double-struck or script variants) without polluting global scope.

## Pitfall Guide

Deploying Unicode typography in production requires navigating several subtle failure modes. The following pitfalls are drawn from real-world integration across messaging APIs, terminal emulators, and search pipelines.

| Pitfall | Explanation | Fix |
|---------|-------------|-----|
| **Font Fallback Failure** | Not all operating systems ship with glyphs for U+1D400+. Windows, older Android versions, and some Linux distros render missing characters as tofu boxes. | Test across target OS/font stacks. Implement a graceful degradation strategy: detect rendering failures via canvas measurement or fallback to platform markdown when Unicode styling is unsupported. |
| **Accessibility Breakage** | Screen readers vocalize mathematical symbols literally (e.g., "mathematical bold capital A"). This degrades UX for visually impaired users. | Never use Unicode styling for critical UI text. In web contexts, pair styled output with `aria-label` containing the plain-text equivalent. Document accessibility limitations in internal style guides. |
| **Surrogate Pair Corruption** | Using `.split('')` or `.substring()` on strings containing emoji or supplementary planes splits code units, breaking grapheme integrity. | Always use `[...string]`, `Array.from()`, or `Intl.Segmenter` for iteration. Validate input with Unicode normalization (NFC/NFD) before transformation. |
| **Combining Character Overflow** | Stacking multiple combining marks (e.g., strikethrough + underline) causes rendering artifacts, parser rejection, or invisible characters in strict UTF-8 validators. | Apply only one overlay per character. Validate output with regex `/[\u0300-\u036f]/g` to detect unintended stacking. Strip existing combining marks before applying new ones. |
| **Search & Index Blindness** | Search engines and databases treat `𝗔` and `A` as distinct tokens. Queries for "alert" will not match "𝗮𝗹𝗲𝗿𝘁". | Maintain a parallel plain-text index. Use Unicode styling exclusively at the egress/display layer. Never store styled text as the primary data model. |
| **Performance Degradation on Large Strings** | Naive iteration creates excessive intermediate string allocations, causing GC pressure in high-throughput pipelines. | Pre-allocate result arrays or use `StringBuilder`-style accumulation. Cache character maps at module initialization. Benchmark with payloads >10KB. |
| **Punctuation/Number Assumption** | Developers expect `1`, `!`, or `@` to have bold equivalents. Unicode does not provide styled variants for most ASCII punctuation or digits. | Explicitly map or skip non-Latin ranges. Document limitations in API contracts. Use combining overlays for punctuation if visual emphasis is required, but test rendering carefully. |

## Production Bundle

### Action Checklist
- [ ] **Audit target channels**: Verify which platforms (Discord, WhatsApp, SMS, email) support Mathematical Alphanumeric Symbols and combining marks.
- [ ] **Implement grapheme-safe iteration**: Replace all `.split('')` or `.charCodeAt()` loops with `[...string]` or `Intl.Segmenter`.
- [ ] **Cache character maps**: Initialize lookup tables at module load time; freeze them to prevent runtime mutation.
- [ ] **Add plain-text fallback**: Maintain a parallel unstyled version for search indexing, logging, and accessibility attributes.
- [ ] **Validate combining overlays**: Strip existing diacritics before applying new ones; limit to one overlay per character.
- [ ] **Test font rendering**: Deploy to staging environments across Windows, macOS, iOS, Android, and Linux to verify glyph availability.
- [ ] **Document accessibility impact**: Add internal guidelines specifying where Unicode styling is appropriate and where semantic markup must be used.

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Cross-platform messaging (WhatsApp, Discord, SMS) | Unicode Mathematical Characters | Survives transport layers; no platform dependency | Low (one-time implementation) |
| Web application UI | HTML/CSS with semantic markup | Native accessibility, search indexability, and performance | Low (framework-native) |
| Platform-specific bots (Discord/Slack) | Native Markdown (`**text**`) | Higher compatibility within ecosystem; better screen reader support | Low (syntax-dependent) |
| Search-heavy data pipelines | Plain text + Unicode at egress | Preserves tokenization; avoids index fragmentation | Medium (dual-storage pipeline) |
| Terminal/CLI tools | Unicode combining overlays | Terminal emulators reliably render diacritics; offset math may fail | Low |

### Configuration Template

Copy this module into your typography utilities directory. It includes validation, caching, and safe iteration patterns ready for production integration.

```typescript
// typography-engine.ts
type CharMap = Readonly<Record<string, string>>;

const buildMap = (baseStart: number, targetStart: number, count: number): CharMap => {
  const entries: [string, string][] = Array.from({ length: count }, (_, i) => {
    const base = String.fromCharCode(baseStart + i);
    const styled = String.fromCodePoint(targetStart + i);
    return [base, styled];
  });
  return Object.freeze(Object.fromEntries(entries));
};

const BOLD_UPPER = buildMap(65, 0x1d400, 26);
const BOLD_LOWER = buildMap(97, 0x1d41a, 26);
const ITALIC_UPPER = buildMap(65, 0x1d434, 26);
const ITALIC_LOWER = buildMap(97, 0x1d44e, 26);

const STRIKETHROUGH = '\u0336';
const UNDERLINE = '\u0332';

const stripCombining = (text: string): string => 
  [...text].filter(c => !/[\u0300-\u036f]/.test(c)).join('');

export const formatText = {
  bold: (input: string) => 
    [...input].map(c => BOLD_UPPER[c] ?? BOLD_LOWER[c] ?? c).join(''),
  
  italic: (input: string) => 
    [...input].map(c => ITALIC_UPPER[c] ?? ITALIC_LOWER[c] ?? c).join(''),
  
  strike: (input: string) => 
    [...stripCombining(input)].map(c => `${c}${STRIKETHROUGH}`).join(''),
  
  underline: (input: string) => 
    [...stripCombining(input)].map(c => `${c}${UNDERLINE}`).join(''),
};

Quick Start Guide

1. Install & Import: Place the configuration template in your utilities directory. Import formatText into your message builder or egress layer.
2. Apply at Egress: Transform plain text immediately before serialization to target channels. Do not store styled text in databases.
3. Validate Output: Run a quick test with formatText.bold("System Alert") and paste the result into Discord, WhatsApp, and a plain-text email client to verify rendering.
4. Add Fallback Logic: If your pipeline supports multiple channels, conditionally apply Unicode styling only when the target platform lacks native markdown support.
5. Monitor Rendering: Log font fallback failures in production. If a channel consistently renders tofu boxes, disable Unicode styling for that destination and fall back to plain text or platform-specific syntax.