punctilio 1.3.1 → 1.4.0

package/src/constants.ts

@@ -0,0 +1,161 @@
+/**
+ * Shared Unicode constants used throughout the punctilio package.
+ *
+ * This module provides a centralized location for all Unicode symbols
+ * used in typography transformations, making the codebase more maintainable
+ * and self-documenting.
+ *
+ * @module constants
+ */
+
+import escapeStringRegexp from "escape-string-regexp"
+
+/**
+ * Unicode symbols for typography transformations.
+ */
+export const UNICODE_SYMBOLS = {
+  ELLIPSIS: "\u2026",
+  MULTIPLICATION: "\u00D7",
+  NOT_EQUAL: "\u2260",
+  PLUS_MINUS: "\u00B1",
+  COPYRIGHT: "\u00A9",
+  REGISTERED: "\u00AE",
+  TRADEMARK: "\u2122",
+  DEGREE: "\u00B0",
+  ARROW_RIGHT: "\u2192",
+  ARROW_LEFT: "\u2190",
+  ARROW_LEFT_RIGHT: "\u2194",
+  APPROXIMATE: "\u2248",
+  LESS_EQUAL: "\u2264",
+  GREATER_EQUAL: "\u2265",
+  PRIME: "\u2032",
+  DOUBLE_PRIME: "\u2033",
+  FRACTION_1_4: "\u00BC",
+  FRACTION_1_2: "\u00BD",
+  FRACTION_3_4: "\u00BE",
+  FRACTION_1_3: "\u2153",
+  FRACTION_2_3: "\u2154",
+  FRACTION_1_5: "\u2155",
+  FRACTION_2_5: "\u2156",
+  FRACTION_3_5: "\u2157",
+  FRACTION_4_5: "\u2158",
+  FRACTION_1_6: "\u2159",
+  FRACTION_5_6: "\u215A",
+  FRACTION_1_8: "\u215B",
+  FRACTION_3_8: "\u215C",
+  FRACTION_5_8: "\u215D",
+  FRACTION_7_8: "\u215E",
+  EM_DASH: "\u2014",
+  EN_DASH: "\u2013",
+  MINUS: "\u2212",
+  LEFT_DOUBLE_QUOTE: "\u201C",
+  RIGHT_DOUBLE_QUOTE: "\u201D",
+  LEFT_SINGLE_QUOTE: "\u2018",
+  RIGHT_SINGLE_QUOTE: "\u2019",
+  NBSP: "\u00A0",
+  // Superscript ordinal suffixes
+  SUPERSCRIPT_ST: "\u02E2\u1D57", // ˢᵗ
+  SUPERSCRIPT_ND: "\u207F\u1D48", // ⁿᵈ
+  SUPERSCRIPT_RD: "\u02B3\u1D48", // ʳᵈ
+  SUPERSCRIPT_TH: "\u1D57\u02B0", // ᵗʰ
+  // Punctuation ligatures
+  DOUBLE_QUESTION: "\u2047", // ⁇
+  QUESTION_EXCLAMATION: "\u2048", // ⁈
+  EXCLAMATION_QUESTION: "\u2049", // ⁉
+  DOUBLE_EXCLAMATION: "\u203C", // ‼
+} as const
+
+/**
+ * Character class pattern for Latin letters including European accented characters.
+ * Use inside regex character classes: `[${LATIN_LETTERS}]`
+ *
+ * Includes:
+ * - Basic Latin: A-Z, a-z
+ * - Latin-1 Supplement: À-Ö, Ø-ö, ø-ÿ (excludes × and ÷)
+ * - Latin Extended-A: Ā-ſ (U+0100-017F)
+ * - Latin Extended-B: ƀ-ɏ (U+0180-024F)
+ *
+ * Examples of covered characters: é, ñ, ü, ø, ą, ł, ș
+ */
+export const LATIN_LETTERS = "A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u00FF\\u0100-\\u017F\\u0180-\\u024F"
+
+/**
+ * Default separator character for text spanning HTML elements.
+ * Uses Unicode Private Use Area character U+E000.
+ */
+export const DEFAULT_SEPARATOR = "\uE000"
+export const ESCAPED_DEFAULT_SEPARATOR = escapeStringRegexp(DEFAULT_SEPARATOR)
+
+/**
+ * Characters that have special meaning in regular expressions.
+ * Used for testing that separator escaping works correctly.
+ */
+export const REGEX_SPECIAL_CHARS = [".", "*", "+", "?", "^", "$", "[", "]", "\\", "|", "(", ")"] as const
+
+/**
+ * Creates a marker-aware word boundary pattern for the START of a match.
+ *
+ * Standard `\b` can create false boundaries when separator markers appear between
+ * word characters (e.g., `x\uE000ReLU` has a false boundary before `R`).
+ *
+ * This pattern uses a negative lookbehind to reject matches that are preceded
+ * by word characters followed by any number of markers.
+ *
+ * @param escapedSeparator - Regex-escaped separator string
+ * @returns Pattern string: `(?<!\w${sep}*)\b`
+ *
+ * @example
+ * const wb = wordBoundaryStart(ESCAPED_DEFAULT_SEPARATOR)
+ * // With text "x\uE000ReLU": \b would match before R, but wb won't
+ */
+export function wordBoundaryStart(escapedSeparator: string): string {
+  return `(?<!\\w${escapedSeparator}*)\\b`
+}
+
+/**
+ * Creates a marker-aware word boundary pattern for the END of a match.
+ *
+ * Standard `\b` can create false boundaries when separator markers appear between
+ * word characters (e.g., `1st\uE000ly` has a false boundary after `t`).
+ *
+ * This pattern uses a negative lookahead to reject matches that are followed
+ * by markers then word characters.
+ *
+ * @param escapedSeparator - Regex-escaped separator string
+ * @returns Pattern string: `\b(?!${sep}*\w)`
+ *
+ * @example
+ * const wbe = wordBoundaryEnd(ESCAPED_DEFAULT_SEPARATOR)
+ * // With text "1st\uE000ly": \b would match after t, but wbe won't
+ */
+export function wordBoundaryEnd(escapedSeparator: string): string {
+  return `\\b(?!${escapedSeparator}*\\w)`
+}
+
+/**
+ * Pattern string for space characters (regular space and non-breaking space).
+ * Use inside regex character classes: `[${SPACE_CHARS}]`
+ */
+export const SPACE_CHARS = ` ${UNICODE_SYMBOLS.NBSP}`
+
+/**
+ * Creates a lookbehind pattern that matches after whitespace, separator, or start of string.
+ * Used for arrow patterns and other constructs that should appear at word boundaries.
+ *
+ * @param escapedSeparator - Regex-escaped separator string
+ * @returns Pattern string: `(?<=[\\s${sep}]|^)`
+ */
+export function spaceBoundaryStart(escapedSeparator: string): string {
+  return `(?<=[\\s${escapedSeparator}]|^)`
+}
+
+/**
+ * Creates a lookahead pattern that matches before whitespace, separator, or end of string.
+ * Used for arrow patterns and other constructs that should appear at word boundaries.
+ *
+ * @param escapedSeparator - Regex-escaped separator string
+ * @returns Pattern string: `(?=[\\s${sep}]|$)`
+ */
+export function spaceBoundaryEnd(escapedSeparator: string): string {
+  return `(?=[\\s${escapedSeparator}]|$)`
+}

package/src/dashes.ts

@@ -0,0 +1,211 @@
+/**
+ * Dash transformation: hyphens → em-dashes, en-dashes, minus signs.
+ */
+
+import escapeStringRegexp from "escape-string-regexp"
+import { UNICODE_SYMBOLS, DEFAULT_SEPARATOR, ESCAPED_DEFAULT_SEPARATOR, LATIN_LETTERS, wordBoundaryStart, wordBoundaryEnd } from "./constants.js"
+
+export type DashStyle = "american" | "british" | "none"
+
+export interface DashOptions {
+  /** Boundary marker for HTML element boundaries. Default: "\uE000" */
+  separator?: string
+  /** "american" (unspaced em), "british" (spaced en), "none". Default: "american" */
+  dashStyle?: DashStyle
+}
+
+const { EN_DASH, EM_DASH, MINUS, LEFT_DOUBLE_QUOTE, RIGHT_DOUBLE_QUOTE, LEFT_SINGLE_QUOTE, RIGHT_SINGLE_QUOTE } = UNICODE_SYMBOLS
+
+/**
+ * Characters that, when preceding a number, prevent it from being
+ * treated as the start of a number range. This prevents false positives
+ * in model names like "Llama-2-7B" where "2-7" should not become "2–7".
+ */
+export const numberRangeDisallowedPrefixes = ["-", EN_DASH, EM_DASH, MINUS] as const
+
+export const months = [
+  "January", "February", "March", "April", "May", "June",
+  "July", "August", "September", "October", "November", "December",
+  "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+  "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+].join("|")
+
+/** Convert number ranges to en-dash (e.g., "1-5" → "1–5"). */
+export function enDashNumberRange(text: string, options: DashOptions = {}): string {
+  const chr = options.separator ? escapeStringRegexp(options.separator) : ESCAPED_DEFAULT_SEPARATOR
+  const wb = wordBoundaryStart(chr)
+  const wbe = wordBoundaryEnd(chr)
+
+  // Escape dash-like chars for lookbehind: prevents matching after dashes (e.g., Llama-2-7B)
+  const disallowed = numberRangeDisallowedPrefixes.map(c => c === "-" ? c : `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`).join("")
+
+  // Common currency symbols for price ranges
+  const currencies = "$€£¥₹"
+
+  // Build positive range pattern from readable components
+  const phoneAreaCode = `(?<precedingAreaCode>\\d{3}-|\\(\\d{3}\\) ?)?`  // 555- or (555)
+  const notAfterDash = `(?<![${disallowed}${LATIN_LETTERS}.])`           // prevent Llama-2-7B
+  const rangeStart = `(?<start>(?:p\\.?|[${currencies}])?\\d[\\d.,]*${chr}?)`  // p.10, $100, 1,000
+  const rangeEnd = `(?<end>${chr}?[${currencies}]?\\d[\\d.,]*)`          // 20, $200, 2,000
+  const moreSegments = `(?<following>(?:${chr}?-${chr}?\\d+)*)`          // -4567 in phone numbers
+  const unitSuffix = `(?<suffix>${chr}?(?:[AaPp][Mm]|[xKBTM]))?`         // am/pm, K/M/B
+
+  // Positive ranges: 1-5, $100-$200, €5-€10, p.10-15
+  const positiveRangePattern = [
+    phoneAreaCode, wb, notAfterDash, rangeStart, "-", rangeEnd, moreSegments, unitSuffix, wbe
+  ].join("")
+
+  text = text.replace(
+    new RegExp(positiveRangePattern, "g"),
+    (match, precedingAreaCode, start, end, following, suffix = "") => {
+      if (following) return match
+      const startNum = start.replace(new RegExp(chr, "g"), "")
+      const endNum = end.replace(new RegExp(chr, "g"), "")
+      if (/^(?:19|20)\d{2}$/.test(startNum) && /^(?:0[1-9]|1[0-2])$/.test(endNum)) return match
+      // Skip phone number patterns: 3 digits followed by 4 digits with preceding area code
+      // e.g., 555-123-4567 or (555) 123-4567 where we're matching the "123-4567" part
+      if (precedingAreaCode && /^\d{3}$/.test(startNum) && /^\d{4}$/.test(endNum)) return match
+      // Skip US country code + area code pattern: 1-800, 1-888, etc.
+      // These look like truncated phone numbers, not ranges
+      if (/^1$/.test(startNum) && /^\d{3}$/.test(endNum)) return match
+      return `${precedingAreaCode || ""}${start}${EN_DASH}${end}${suffix || ""}`
+    }
+  )
+
+  // Negative ranges: −5-5 → −5–5, −5--2 → −5–−2
+  // Separate regex because MINUS isn't a word char, so \b in ${wb} would match after it
+  text = text.replace(
+    new RegExp(
+      `(?<![${LATIN_LETTERS}])(?<start>${MINUS}\\d[\\d.,]*${chr}?)-(?<neg>-)?(?<end>${chr}?\\d[\\d.,]*)(?<following>(?:${chr}?-${chr}?\\d+)*)(?<suffix>${chr}?[xKBTM])?${wbe}`,
+      "g"
+    ),
+    (match, start, neg, end, following, suffix = "") => {
+      if (following) return match
+      return `${start}${EN_DASH}${neg ? MINUS : ""}${end}${suffix || ""}`
+    }
+  )
+
+  return text
+}
+
+/** Convert month ranges to en-dash (e.g., "January-March" → "January–March"). */
+export function enDashDateRange(text: string, options: DashOptions = {}): string {
+  const chr = options.separator ? escapeStringRegexp(options.separator) : ESCAPED_DEFAULT_SEPARATOR
+  const dashStyle = options.dashStyle ?? "american"
+  const wb = wordBoundaryStart(chr)
+  const wbe = wordBoundaryEnd(chr)
+
+  return text.replace(
+    new RegExp(`${wb}(?<startMonth>${months})(?<startYear>${chr}? \\d{4})?(?<preSep>${chr}?)(?<preSpace> ?)-(?<postSpace> ?)(?<postSep>${chr}?)(?<endMonth>${months})(?<endYear> \\d{4})?${wbe}`, "g"),
+    (...args) => {
+      const g = args.at(-1) as Record<string, string>
+      const [pre, post] = dashStyle === "british" ? [" ", " "] : dashStyle === "none" ? [g.preSpace, g.postSpace] : ["", ""]
+      return `${g.startMonth}${g.startYear || ""}${g.preSep}${pre}${EN_DASH}${post}${g.postSep}${g.endMonth}${g.endYear || ""}`
+    }
+  )
+}
+
+/** Convert hyphens to minus signs in numeric contexts (e.g., "-5" → "−5"). */
+export function minusReplace(text: string, options: DashOptions = {}): string {
+  const chr = escapeStringRegexp(options.separator ?? DEFAULT_SEPARATOR)
+
+  // Pattern 1a: Subtraction of negative number (e.g., "5 - -3" → "5 − −3")
+  // Must come before Pattern 1b so the negative hyphen is consumed first
+  text = text.replaceAll(
+    new RegExp(`(?<=\\d${chr}?) - -(?<num>${chr}?\\d*\\.?\\d+)`, "g"),
+    ` ${MINUS} ${MINUS}$<num>`
+  )
+
+  // Pattern 1b: Spaced math subtraction (e.g., "5 - 3" → "5 − 3")
+  // Only when preceded by a digit - this distinguishes "5 - 3" from "Safari) - 9"
+  text = text.replaceAll(
+    new RegExp(`(?<=\\d${chr}?) - (?<num>${chr}?\\d*\\.?\\d+)`, "g"),
+    ` ${MINUS} $<num>`
+  )
+
+  // Pattern 2: Direct negative numbers (e.g., "-5" → "−5", "(-3)" → "(−3)")
+  // Match after: start of line, whitespace, (, separator, or quotes (straight or curly)
+  // No space allowed between hyphen and digit
+  text = text.replaceAll(
+    new RegExp(`(?<before>^|[\\s\\("${chr}${LEFT_DOUBLE_QUOTE}${RIGHT_DOUBLE_QUOTE}])-(?<num>\\d*\\.?\\d+)`, "gm"),
+    `$<before>${MINUS}$<num>`
+  )
+
+  return text
+}
+
+/**
+ * Convert surrounded dashes to em/en dashes.
+ * Handles patterns like "word - word" → "word—word" (Chicago) or "word – word" (Oxford).
+ */
+function convertParentheticalDashes(text: string, sep: string, style: DashStyle): string {
+  if (style === "none") return text
+  const localizedDash = style === "british" ? EN_DASH : EM_DASH
+  const maybeSpace = style === "british" ? " " : ""
+  const escapedSep = escapeStringRegexp(sep)
+
+  // Convert spaced dashes: "word - word" or "word — word"
+  // When a separator follows the dash, preserve trailing spaces (they belong to the next text segment).
+  const spacedDashPattern = new RegExp(
+    `(?<=[^\\s]|^)(?<sepBefore>${escapedSep}?)[ ]+[~${EN_DASH}${EM_DASH}-]+(?!-*>)[ ]*(?<sepAfter>${escapedSep}?)(?<trailing>[ ]*)(?=\\S|$)`, "g"
+  )
+  text = text.replace(spacedDashPattern, (_match, sepBefore, sepAfter, trailing) => {
+    // For British style (spaced en-dash), preserve trailing spaces after separator
+    // For American style (unspaced em-dash), consume trailing spaces (em-dash replaces surrounding space)
+    const keepTrailing = maybeSpace && sepAfter ? trailing : ""
+    return `${sepBefore}${maybeSpace}${localizedDash}${maybeSpace}${sepAfter}${keepTrailing}`
+  })
+  // Convert multiple dashes: "word--word" or "word---word" or "quote"--"quote"
+  const quoteChars = `"'${LEFT_DOUBLE_QUOTE}${RIGHT_DOUBLE_QUOTE}${LEFT_SINGLE_QUOTE}${RIGHT_SINGLE_QUOTE}`
+  text = text.replace(
+    new RegExp(`(?<=[${LATIN_LETTERS}\\d${quoteChars}])(?<sepBefore>${escapedSep}?)[~${EN_DASH}${EM_DASH}-]{2,}(?<sepAfter>${escapedSep}?)(?=[${LATIN_LETTERS}${quoteChars} ])`, "g"),
+    `$<sepBefore>${maybeSpace}${localizedDash}${maybeSpace}$<sepAfter>`
+  )
+  // Convert dashes at start of line
+  text = text.replace(new RegExp(`^(?<leadingSep>${escapedSep})?[-]+ `, "gm"), `$<leadingSep>${localizedDash} `)
+  // British: convert unspaced em-dashes to spaced en-dashes (word—word → word – word)
+  if (style === "british") {
+    text = text.replace(
+      new RegExp(`(?<=[${LATIN_LETTERS}.!?'"])(?<sepBefore>${escapedSep}?)${EM_DASH}(?<sepAfter>${escapedSep}?)(?=[${LATIN_LETTERS}])`, "g"),
+      `$<sepBefore>${maybeSpace}${localizedDash}${maybeSpace}$<sepAfter>`
+    )
+  }
+  return text
+}
+
+/**
+ * Normalize em-dash spacing for Chicago style (American).
+ * Removes all spaces around em-dashes per Chicago Manual of Style.
+ *
+ * TODO: Handle interrupted-then-resumed speech within quotes, where Chicago
+ * allows a space after the dash: "Don't inter— Hey! Who threw that?"
+ */
+function normalizeEmDashSpacing(text: string, sep: string): string {
+  const escapedSep = escapeStringRegexp(sep)
+
+  // Remove all spaces around em-dashes
+  text = text.replace(
+    new RegExp(`(?<before>${escapedSep}?)[ ]*${EM_DASH}[ ]*(?<after>${escapedSep}?)`, "g"),
+    `$<before>${EM_DASH}$<after>`
+  )
+
+  // Preserve space after em-dash at start of line (e.g., attribution)
+  text = text.replace(
+    new RegExp(`^(?<sep>${escapedSep}?)${EM_DASH}(?<after>[A-Z0-9])`, "gm"),
+    `$<sep>${EM_DASH} $<after>`
+  )
+
+  return text
+}
+
+/** Full dash transformation. */
+export function hyphenReplace(text: string, options: DashOptions = {}): string {
+  const sep = options.separator ?? DEFAULT_SEPARATOR
+  const style = options.dashStyle ?? "american"
+  text = minusReplace(text, options)
+  text = convertParentheticalDashes(text, sep, style)
+  if (style === "american") text = normalizeEmDashSpacing(text, sep)
+  text = enDashNumberRange(text, options)
+  text = enDashDateRange(text, options)
+  return text
+}

package/src/index.ts

@@ -0,0 +1,243 @@
+/**
+ * punctilio - Smart typography transformations
+ *
+ * A library for converting plain ASCII punctuation into typographically
+ * correct Unicode characters. Handles smart quotes, em-dashes, en-dashes,
+ * minus signs, ellipses, multiplication signs, and more.
+ *
+ * @packageDocumentation
+ */
+
+export { niceQuotes, type QuoteOptions, type PunctuationStyle } from "./quotes.js"
+import type { PunctuationStyle } from "./quotes.js"
+export {
+  hyphenReplace,
+  enDashNumberRange,
+  enDashDateRange,
+  minusReplace,
+  months,
+  numberRangeDisallowedPrefixes,
+  type DashOptions,
+  type DashStyle,
+} from "./dashes.js"
+import type { DashStyle } from "./dashes.js"
+export {
+  ellipsis,
+  multiplication,
+  mathSymbols,
+  legalSymbols,
+  arrows,
+  degrees,
+  fractions,
+  primeMarks,
+  collapseSpaces,
+  superscriptOrdinal,
+  punctuationLigatures,
+  symbolTransform,
+  type SymbolOptions,
+} from "./symbols.js"
+
+export interface TransformOptions {
+  /**
+   * A boundary marker character used when transforming text that spans
+   * multiple HTML elements. This character is treated as "transparent"
+   * in the regex patterns.
+   *
+   * Should be a character that doesn't appear in your text.
+   * Default: "\uE000" (Unicode Private Use Area)
+   */
+  separator?: string
+
+  /**
+   * Whether to include symbol transforms (ellipsis, multiplication, etc.)
+   * Default: true
+   */
+  symbols?: boolean
+
+  /**
+   * Whether to collapse multiple consecutive spaces (including non-breaking
+   * spaces) into a single space. Keeps the first space in the sequence.
+   *
+   * - `true` (default): "hello  world" → "hello world"
+   * - `false`: Preserve multiple spaces
+   *
+   * Default: true
+   */
+  collapseSpaces?: boolean
+
+  /**
+   * How to handle punctuation placement around quotation marks.
+   *
+   * - `"american"` (default): Chicago style. Periods and commas go inside quotes.
+   *   Example: "Hello." and "Hello,"
+   * - `"british"`: Oxford style. Periods and commas go outside quotes.
+   *   Example: "Hello". and "Hello",
+   * - `"none"`: Don't modify punctuation placement
+   *
+   * Default: "american"
+   */
+  punctuationStyle?: PunctuationStyle
+
+  /**
+   * How to style parenthetical dashes.
+   *
+   * - `"american"` (default): Chicago style. Unspaced em dash (word—word)
+   * - `"british"`: Oxford style. Spaced en dash (word – word)
+   * - `"none"`: Don't convert parenthetical dashes
+   *
+   * Default: "american"
+   */
+  dashStyle?: DashStyle
+
+  /**
+   * Whether to include fraction transforms (1/2 → ½)
+   * Default: false (can be aggressive)
+   */
+  fractions?: boolean
+
+  /**
+   * Whether to include degree symbol transforms (20 C → 20 °C)
+   * Default: false (can be aggressive)
+   */
+  degrees?: boolean
+
+  /**
+   * Whether to convert ordinal suffixes to Unicode superscript characters.
+   * Transforms numbers like "1st", "2nd", "3rd", "4th" to "1ˢᵗ", "2ⁿᵈ", "3ʳᵈ", "4ᵗʰ".
+   * Default: false
+   */
+  superscript?: boolean
+
+  /**
+   * Whether to convert repeated punctuation marks to Unicode ligature characters.
+   * Squashes multiple marks: "???" → "⁇", "?!" → "⁈", "!?" → "⁉", "!!!" → "!"
+   * Default: false (poor font support)
+   */
+  ligatures?: boolean
+
+  /**
+   * Whether to verify that the transformation is idempotent (running twice
+   * produces the same result). When enabled, throws an error if the second
+   * pass produces a different result than the first.
+   *
+   * Default: true
+   */
+  checkIdempotency?: boolean
+}
+
+import { niceQuotes } from "./quotes.js"
+import { hyphenReplace } from "./dashes.js"
+import { symbolTransform, fractions as fractionsTransform, degrees as degreesTransform, superscriptOrdinal as superscriptTransform, primeMarks, collapseSpaces as collapseSpacesTransform, punctuationLigatures as ligaturesTransform } from "./symbols.js"
+import { assertSeparatorCountPreserved, formatErrorString } from "./utils.js"
+import { DEFAULT_SEPARATOR } from "./constants.js"
+
+export { assertSeparatorCountPreserved, countSeparators } from "./utils.js"
+export { DEFAULT_SEPARATOR } from "./constants.js"
+
+/**
+ * Applies all typography transformations: smart quotes, proper dashes,
+ * and symbol improvements.
+ *
+ * This is a convenience function that applies transformations in sequence:
+ * 1. hyphenReplace (em-dashes, en-dashes, minus signs)
+ * 2. primeMarks (feet/inches, arcminutes/arcseconds)
+ * 3. niceQuotes (smart quotes)
+ * 4. symbolTransform (ellipses, multiplication, math symbols, legal symbols, arrows)
+ * 5. fractions (disabled by default)
+ * 6. degrees (disabled by default)
+ * 7. superscript (disabled by default)
+ * 8. ligatures (disabled by default)
+ * 9. collapseSpaces (collapses multiple spaces into one)
+ *
+ * @param text - The text to transform
+ * @param options - Configuration options
+ * @returns The text with all typography improvements applied
+ *
+ * @example
+ * ```ts
+ * import { transform } from 'punctilio'
+ *
+ * transform('"Hello," she said - "it\'s pages 1-5."')
+ * // → '"Hello," she said—"it's pages 1–5."'
+ *
+ * transform('Wait... 5x5 != 25 (c) 2024')
+ * // → 'Wait… 5×5 ≠ 25 © 2024'
+ *
+ * transform('Add 1/2 cup', { fractions: true })
+ * // → 'Add ½ cup'
+ * ```
+ */
+const defaultOpts: Required<Omit<TransformOptions, "separator">> = {
+  symbols: true,
+  fractions: false,
+  degrees: false,
+  superscript: false,
+  ligatures: false,
+  collapseSpaces: true,
+  checkIdempotency: true,
+  punctuationStyle: "american",
+  dashStyle: "american",
+}
+
+export function transform(text: string, options: TransformOptions = {}): string {
+  const separator = options.separator ?? DEFAULT_SEPARATOR
+
+  // Validate separator: must be a single UTF-16 code unit (BMP character)
+  // Multi-codepoint characters (surrogate pairs like emoji) cause issues with regex patterns
+  if (separator.length !== 1) {
+    throw new Error(
+      `Invalid separator: must be a single character. ` +
+      `Received "${separator}" (length: ${separator.length}). ` +
+      `Use a single-codepoint character like the default "\\uE000".`
+    )
+  }
+
+  const original = text
+  const { symbols, fractions, degrees, superscript, ligatures, collapseSpaces, checkIdempotency, ...separatorOpts } = { ...defaultOpts, ...options }
+
+  text = hyphenReplace(text, separatorOpts)
+  text = primeMarks(text, separatorOpts)
+  text = niceQuotes(text, separatorOpts)
+
+  if (symbols) {
+    text = symbolTransform(text, separatorOpts)
+  }
+
+  if (fractions) {
+    text = fractionsTransform(text)
+  }
+
+  if (degrees) {
+    text = degreesTransform(text)
+  }
+
+  if (superscript) {
+    text = superscriptTransform(text, separatorOpts)
+  }
+
+  if (ligatures) {
+    text = ligaturesTransform(text, separatorOpts)
+  }
+
+  if (collapseSpaces) {
+    text = collapseSpacesTransform(text)
+  }
+
+  assertSeparatorCountPreserved(original, text, separator, "transform")
+
+  if (checkIdempotency) {
+    const secondPass = transform(text, { ...options, checkIdempotency: false })
+    /* istanbul ignore if -- defensive check that should never trigger */
+    if (text !== secondPass) {
+      throw new Error(
+        `Transform is not idempotent.\n` +
+        `First pass:  ${formatErrorString(text, "first-pass")}\n` +
+        `Second pass: ${formatErrorString(secondPass, "second-pass")}\n` +
+        `This is a bug in punctilio. Please file an issue at https://github.com/alexander-turner/punctilio/issues\n` +
+        `Include the input text that caused this error.`
+      )
+    }
+  }
+
+  return text
+}