punctilio 1.4.1 → 1.7.0

package/src/index.ts

@@ -36,6 +36,21 @@ export {
   symbolTransform,
   type SymbolOptions,
 } from "./symbols.js"
+export {
+  nbspAfterShortWords,
+  nbspBetweenNumberAndUnit,
+  nbspBeforeLastWord,
+  nbspAfterReferenceAbbreviations,
+  nbspAfterSectionSymbols,
+  nbspAfterHonorifics,
+  nbspAfterCopyrightSymbols,
+  nbspBetweenInitials,
+  nbspTransform,
+  UNITS,
+  HONORIFICS,
+  REFERENCE_ABBREVIATIONS,
+  type NbspOptions,
+} from "./nbsp.js"
 
 export interface TransformOptions {
   /**
@@ -115,6 +130,14 @@ export interface TransformOptions {
    */
   ligatures?: boolean
 
+  /**
+   * Whether to insert non-breaking spaces in typographically appropriate
+   * locations (after short words, between numbers and units, before
+   * last words to prevent widows, after honorifics, etc.).
+   * Default: false
+   */
+  nbsp?: boolean
+
   /**
    * Whether to verify that the transformation is idempotent (running twice
    * produces the same result). When enabled, throws an error if the second
@@ -128,6 +151,7 @@ export interface TransformOptions {
 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 { nbspTransform as nbspTransformFn } from "./nbsp.js"
 import { assertSeparatorCountPreserved, formatErrorString } from "./utils.js"
 import { DEFAULT_SEPARATOR } from "./constants.js"
 
@@ -147,7 +171,8 @@ export { DEFAULT_SEPARATOR } from "./constants.js"
  * 6. degrees (disabled by default)
  * 7. superscript (disabled by default)
  * 8. ligatures (disabled by default)
- * 9. collapseSpaces (collapses multiple spaces into one)
+ * 9. nbsp (non-breaking spaces, disabled by default)
+ * 10. collapseSpaces (collapses multiple spaces into one)
  *
  * @param text - The text to transform
  * @param options - Configuration options
@@ -173,6 +198,7 @@ const defaultOpts: Required<Omit<TransformOptions, "separator">> = {
   degrees: false,
   superscript: false,
   ligatures: false,
+  nbsp: false,
   collapseSpaces: true,
   checkIdempotency: true,
   punctuationStyle: "american",
@@ -193,7 +219,7 @@ export function transform(text: string, options: TransformOptions = {}): string
   }
 
   const original = text
-  const { symbols, fractions, degrees, superscript, ligatures, collapseSpaces, checkIdempotency, ...separatorOpts } = { ...defaultOpts, ...options }
+  const { symbols, fractions, degrees, superscript, ligatures, nbsp, collapseSpaces, checkIdempotency, ...separatorOpts } = { ...defaultOpts, ...options }
 
   text = hyphenReplace(text, separatorOpts)
   text = primeMarks(text, separatorOpts)
@@ -219,6 +245,10 @@ export function transform(text: string, options: TransformOptions = {}): string
     text = ligaturesTransform(text, separatorOpts)
   }
 
+  if (nbsp) {
+    text = nbspTransformFn(text, separatorOpts)
+  }
+
   if (collapseSpaces) {
     text = collapseSpacesTransform(text)
   }

package/src/nbsp.ts

@@ -0,0 +1,252 @@
+/**
+ * Non-breaking space transformations for improved typography.
+ *
+ * Inserts non-breaking spaces (U+00A0) in positions where line breaks
+ * would be typographically undesirable: after short words, between
+ * numbers and units, before orphaned last words, etc.
+ *
+ * @module nbsp
+ */
+
+import escapeStringRegexp from "escape-string-regexp"
+
+import { UNICODE_SYMBOLS, ESCAPED_DEFAULT_SEPARATOR, LATIN_LETTERS, wordBoundaryEnd } from "./constants.js"
+import type { SymbolOptions } from "./symbols.js"
+
+const {
+  NBSP,
+  LEFT_DOUBLE_QUOTE,
+  RIGHT_DOUBLE_QUOTE,
+  LEFT_SINGLE_QUOTE,
+  RIGHT_SINGLE_QUOTE,
+  COPYRIGHT,
+  REGISTERED,
+  TRADEMARK,
+} = UNICODE_SYMBOLS
+
+export type NbspOptions = Pick<SymbolOptions, "separator">
+
+function escapedSeparator(options: NbspOptions): string {
+  return options.separator
+    ? escapeStringRegexp(options.separator)
+    : ESCAPED_DEFAULT_SEPARATOR
+}
+
+/** Space pattern matching regular space, tab, and nbsp. */
+const SPACE = `[ \\t${NBSP}]`
+
+const UNICODE_UPPERCASE = "\\p{Lu}"
+
+/**
+ * Common units for the number-unit nbsp pattern. Only matches these specific
+ * abbreviations after a number to avoid false positives like "chapter 3 above".
+ */
+export const UNITS = [
+  // Length
+  "km", "cm", "mm", "mi", "ft", "in", "yd", "nm", "pm", "m",
+  // Mass
+  "kg", "mg", "lbs", "lb", "oz", "g", "t",
+  // Volume
+  "ml", "mL", "gal", "fl", "l", "L",
+  // Time
+  "min", "ms", "hr", "hrs", "h", "s",
+  // Speed / frequency
+  "kHz", "MHz", "GHz", "THz", "rpm", "Hz",
+  // Digital
+  "kbps", "Mbps", "Gbps", "KB", "MB", "GB", "TB", "PB", "kB", "Mb", "Gb",
+  // Energy / power
+  "kWh", "MWh", "kW", "MW", "GW", "kJ", "MJ", "Wh", "W", "J",
+  // Temperature
+  "K",
+  // Electrical
+  "kV", "mV", "mA", "V", "A",
+  // Pressure / area
+  "kPa", "MPa", "bar", "psi", "ha", "Pa",
+  // Typography / CSS
+  "rem", "dpi", "px", "pt", "em", "vw", "vh",
+  // Finance
+  "MM", "M", "B", "T",
+  // Misc
+  "kcal", "mol", "cal", "dB",
+]
+
+export const HONORIFICS = [
+  // English
+  "Mr", "Mrs", "Ms", "Dr", "Prof", "Rev",
+  "St", "Sr", "Jr", "Hon", "Gov", "Sen", "Rep",
+  // French
+  "Mme", "Mlle", "Mgr",
+  // German / Nordic
+  "Hr", "Fr",
+  // Spanish / Portuguese
+  "Sra", "Srta",
+  // Italian
+  "Sig", "Dott",
+  // Dutch
+  "Dhr", "Mevr",
+]
+
+export const REFERENCE_ABBREVIATIONS = [
+  // English / Latin
+  "Fig", "Figs", "Vol", "No", "Nos",
+  "p", "pp", "Ch", "Chap", "Sec",
+  "Eq", "Eqs", "Art", "Tab", "Ex",
+  // German
+  "Abb", "Bd", "Nr", "Kap",
+  // Romance (Spanish / Portuguese / Italian)
+  "Cap",
+]
+
+// Precomputed regex fragments
+const UNIT_PATTERN = UNITS.join("|")
+const HONORIFIC_PATTERN = HONORIFICS.map((h) => `${h}\\.`).join("|")
+const ABBREVIATION_PATTERN = REFERENCE_ABBREVIATIONS.map((a) => `${a}\\.`).join("|")
+const PUNCTUATION_OR_QUOTE = `[.,!?:;)(${LEFT_DOUBLE_QUOTE}${RIGHT_DOUBLE_QUOTE}\u00AB\u00BB${LEFT_SINGLE_QUOTE}${RIGHT_SINGLE_QUOTE}"]`
+const COPYRIGHT_SYMBOLS = `[${COPYRIGHT}${REGISTERED}${TRADEMARK}]`
+
+/**
+ * Adds non-breaking space after short words (1-2 letters) to prevent them from
+ * being left alone at the end of a line.
+ *
+ * @example "a cat" → "a\u00A0cat", "I am" → "I\u00A0am"
+ */
+export function nbspAfterShortWords(text: string, options: NbspOptions = {}): string {
+  const sep = escapedSeparator(options)
+  const pattern = new RegExp(
+    `(?<=^|${SPACE}|${PUNCTUATION_OR_QUOTE}|>)(?<shortWord>[${LATIN_LETTERS}]{1,2})(?<marker>${sep}?)${SPACE}`,
+    "gmu"
+  )
+  return text.replace(pattern, `$<shortWord>$<marker>${NBSP}`)
+}
+
+/**
+ * Adds non-breaking space between numbers and common units.
+ *
+ * @example "100 km" → "100\u00A0km", "5 kg" → "5\u00A0kg"
+ */
+export function nbspBetweenNumberAndUnit(text: string, options: NbspOptions = {}): string {
+  const sep = escapedSeparator(options)
+  const wbe = wordBoundaryEnd(sep)
+  const pattern = new RegExp(
+    `(?<digit>\\d)(?<marker1>${sep}?)${SPACE}(?<marker2>${sep}?)(?<unit>${UNIT_PATTERN})${wbe}`,
+    "gm"
+  )
+  return text.replace(pattern, `$<digit>$<marker1>${NBSP}$<marker2>$<unit>`)
+}
+
+/**
+ * Adds non-breaking space before the last word to prevent widows.
+ *
+ * Only applies to final words of 1-10 characters, at end of string or
+ * paragraph break (\n\n). Uses non-multiline mode so $ matches only the
+ * true end of string.
+ */
+export function nbspBeforeLastWord(text: string, options: NbspOptions = {}): string {
+  const sep = escapedSeparator(options)
+  const pattern = new RegExp(
+    `(?<=[\\w${sep}])${SPACE}(?<lastWord>[^\\s${sep}]{1,10})(?<ending>${sep}?(?:\\n\\n|$))`,
+    "g"
+  )
+  return text.replace(pattern, `${NBSP}$<lastWord>$<ending>`)
+}
+
+/**
+ * Adds non-breaking space after reference abbreviations (Fig., Vol., p., etc.)
+ * when followed by a number.
+ *
+ * @example "Fig. 1" → "Fig.\u00A01", "p. 42" → "p.\u00A042"
+ */
+export function nbspAfterReferenceAbbreviations(text: string, options: NbspOptions = {}): string {
+  const sep = escapedSeparator(options)
+  const pattern = new RegExp(
+    `(?<abbrev>${ABBREVIATION_PATTERN})(?<marker>${sep}?)${SPACE}(?=${sep}?\\d)`,
+    "g"
+  )
+  return text.replace(pattern, `$<abbrev>$<marker>${NBSP}`)
+}
+
+/**
+ * Adds non-breaking space after section (§) and paragraph (¶) symbols
+ * when followed by a number.
+ *
+ * @example "§ 5" → "§\u00A05"
+ */
+export function nbspAfterSectionSymbols(text: string, options: NbspOptions = {}): string {
+  const sep = escapedSeparator(options)
+  const pattern = new RegExp(
+    `(?<symbol>[§¶])(?<marker>${sep}?)${SPACE}(?=${sep}?\\d)`,
+    "g"
+  )
+  return text.replace(pattern, `$<symbol>$<marker>${NBSP}`)
+}
+
+/**
+ * Adds non-breaking space after honorific titles when followed by a capitalized name.
+ *
+ * @example "Dr. Smith" → "Dr.\u00A0Smith", "Mr. Jones" → "Mr.\u00A0Jones"
+ */
+export function nbspAfterHonorifics(text: string, options: NbspOptions = {}): string {
+  const sep = escapedSeparator(options)
+  const pattern = new RegExp(
+    `(?<honorific>${HONORIFIC_PATTERN})(?<marker>${sep}?)${SPACE}(?=${sep}?${UNICODE_UPPERCASE})`,
+    "gu"
+  )
+  return text.replace(pattern, `$<honorific>$<marker>${NBSP}`)
+}
+
+/**
+ * Adds non-breaking space after copyright, registered, and trademark
+ * symbols when followed by a year or capitalized name.
+ *
+ * @example "© 2024" → "©\u00A02024", "® Brand" → "®\u00A0Brand"
+ */
+export function nbspAfterCopyrightSymbols(text: string, options: NbspOptions = {}): string {
+  const sep = escapedSeparator(options)
+  const pattern = new RegExp(
+    `(?<symbol>${COPYRIGHT_SYMBOLS})(?<marker>${sep}?)${SPACE}(?=${sep}?[\\d${UNICODE_UPPERCASE}])`,
+    "gu"
+  )
+  return text.replace(pattern, `$<symbol>$<marker>${NBSP}`)
+}
+
+/**
+ * Adds non-breaking space between initials (e.g., "J. K. Rowling").
+ *
+ * @example "J. K. Rowling" → "J.\u00A0K.\u00A0Rowling"
+ */
+export function nbspBetweenInitials(text: string, options: NbspOptions = {}): string {
+  const sep = escapedSeparator(options)
+  const pattern = new RegExp(
+    `(?<initial>${UNICODE_UPPERCASE}\\.)(?<marker>${sep}?)${SPACE}(?=${sep}?${UNICODE_UPPERCASE})`,
+    "gu"
+  )
+  return text.replace(pattern, `$<initial>$<marker>${NBSP}`)
+}
+
+type NbspFn = (text: string, options: NbspOptions) => string
+
+/**
+ * Ordered list of nbsp transforms. Specific patterns (honorifics, abbreviations,
+ * initials) come first so they claim their matches before the generic
+ * `nbspAfterShortWords`. For example, "No. 5" is matched by
+ * `nbspAfterReferenceAbbreviations` first, preventing `nbspAfterShortWords`
+ * from also matching "No" as a 2-letter short word.
+ */
+const NBSP_TRANSFORMS: NbspFn[] = [
+  nbspAfterHonorifics,
+  nbspAfterReferenceAbbreviations,
+  nbspAfterSectionSymbols,
+  nbspAfterCopyrightSymbols,
+  nbspBetweenInitials,
+  nbspBetweenNumberAndUnit,
+  nbspAfterShortWords,
+  nbspBeforeLastWord,
+]
+
+/** Apply all non-breaking space transformations in sequence. */
+export function nbspTransform(text: string, options: NbspOptions = {}): string {
+  for (const fn of NBSP_TRANSFORMS) {
+    text = fn(text, options)
+  }
+  return text
+}

package/src/symbols.ts

@@ -66,7 +66,7 @@ export function multiplication(text: string, options: SymbolOptions = {}): strin
   // Match entire multiplication chains in one pass: "5 x 5 x 5" or "5x5x5"
   // Pattern matches: digit(s), then one or more (operator, digit(s)) groups
   const chainPattern = new RegExp(
-    `(\\d+)((?:${chr}?\\s*[xX*]\\s*${chr}?\\d+)+)`,
+    `(?<!\\d)(\\d+)((?:${chr}?\\s*[xX*]\\s*${chr}?\\d+)+)`,
     "g"
   )
 
@@ -87,7 +87,7 @@ export function multiplication(text: string, options: SymbolOptions = {}): strin
 
   // Trailing multiplier: 5x (followed by word boundary - space, punctuation, etc.)
   const wbe = wordBoundaryEnd(chr)
-  const trailingPattern = new RegExp(`(?<num>\\d+${chr}?)[xX*]${wbe}`, "g")
+  const trailingPattern = new RegExp(`(?<!\\d)(?<num>\\d+${chr}?)[xX*]${wbe}`, "g")
   text = text.replace(trailingPattern, (match, num: string) => {
     // Skip if this looks like start of hexadecimal
     if (num === "0") return match

package/src/tests/dashes.test.ts

@@ -651,3 +651,31 @@ describe("minusReplace regex-special separators", () => {
     expect(() => minusReplace("-5", { separator: sep })).not.toThrow()
   })
 })
+
+const sep = DEFAULT_SEPARATOR
+
+describe("minusReplace separator boundary", () => {
+  it.each([
+    ["genuine negative at element start", `${sep}-5${sep}`, `${sep}${MINUS}5${sep}`],
+    ["negative in parens across boundary", `(${sep}-5${sep})`, `(${sep}${MINUS}5${sep})`],
+  ])("%s", (_desc, input, expected) => {
+    expect(minusReplace(input, { separator: sep })).toBe(expected)
+  })
+
+  it.each([
+    ["no false negative after digit+sep", `2${sep}-3`],
+    ["no false negative after letter+sep", `GPT${sep}-3`],
+    ["multi-segment 1-2-3 with seps", `1-${sep}2${sep}-3`],
+  ])("%s", (_desc, input) => {
+    expect(minusReplace(input, { separator: sep })).toBe(input)
+  })
+})
+
+describe("hyphenReplace preserves multi-segment numbers across separators", () => {
+  it.each([
+    ["1-2-3 across elements", `1-${sep}2${sep}-3`],
+    ["model name across elements", `${sep}GPT${sep}-3`],
+  ])("%s", (_desc, input) => {
+    expect(hyphenReplace(input, { separator: sep })).toBe(input)
+  })
+})

package/src/tests/index.test.ts

@@ -61,6 +61,8 @@ describe("transform", () => {
       ["superscript enabled", "1st", { superscript: true }, `1${UNICODE_SYMBOLS.SUPERSCRIPT_ST}`],
       ["ligatures disabled", "??", {}, "??"],
       ["ligatures enabled", "??", { ligatures: true }, UNICODE_SYMBOLS.DOUBLE_QUESTION],
+      ["nbsp disabled", "Dr. Smith", {}, "Dr. Smith"],
+      ["nbsp enabled", "Dr. Smith", { nbsp: true }, `Dr.${NBSP}Smith`],
     ] as const)("%s: %s → %s", (_desc, input, options, expected) => {
       expect(transform(input, options)).toBe(expected)
     })
@@ -97,6 +99,31 @@ describe("transform", () => {
     })
   })
 
+  describe("nbsp option", () => {
+    it("inserts nbsp in typographically appropriate places", () => {
+      expect(transform("Dr. Smith wrote Fig. 1 on p. 42", { nbsp: true }))
+        .toBe(`Dr.${NBSP}Smith wrote Fig.${NBSP}1 on${NBSP}p.${NBSP}42`)
+    })
+
+    it("collapseSpaces cleans up after nbsp", () => {
+      expect(transform("Prof. Wilson arrived", { nbsp: true }))
+        .toBe(`Prof.${NBSP}Wilson${NBSP}arrived`)
+    })
+
+    it("is idempotent with nbsp enabled", () => {
+      const input = "Dr. Smith has 5 kg of items in § 3"
+      const first = transform(input, { nbsp: true })
+      const second = transform(first, { nbsp: true })
+      expect(second).toBe(first)
+    })
+
+    it("preserves separator count with nbsp enabled", () => {
+      const sep = DEFAULT_SEPARATOR
+      const input = `Dr.${sep} Smith has${sep} 5 kg`
+      expect(() => transform(input, { nbsp: true, separator: sep })).not.toThrow()
+    })
+  })
+
   describe("separator preservation", () => {
     it.each([
       [`Wait.${DEFAULT_SEPARATOR}.${DEFAULT_SEPARATOR}. for it`, 2],

package/src/tests/nbsp.test.ts

@@ -0,0 +1,255 @@
+import {
+  nbspAfterShortWords,
+  nbspBetweenNumberAndUnit,
+  nbspBeforeLastWord,
+  nbspAfterReferenceAbbreviations,
+  nbspAfterSectionSymbols,
+  nbspAfterHonorifics,
+  nbspAfterCopyrightSymbols,
+  nbspBetweenInitials,
+  nbspTransform,
+  UNITS,
+  HONORIFICS,
+  REFERENCE_ABBREVIATIONS,
+  type NbspOptions,
+} from "../nbsp.js"
+import { UNICODE_SYMBOLS, DEFAULT_SEPARATOR } from "../constants.js"
+
+const NBSP = UNICODE_SYMBOLS.NBSP
+const SEP = DEFAULT_SEPARATOR
+
+/** Calls fn with separator option, checking all cases produce correct nbsp. */
+function expectSep(
+  fn: (text: string, options?: NbspOptions) => string,
+  cases: [string, string][],
+) {
+  for (const [input, expected] of cases) {
+    expect(fn(input, { separator: SEP })).toBe(expected)
+  }
+}
+
+describe("nbspAfterShortWords", () => {
+  it.each([
+    ["a cat", `a${NBSP}cat`],
+    ["I am", `I${NBSP}am`],
+    ["an apple", `an${NBSP}apple`],
+    ["to go", `to${NBSP}go`],
+    ["of the", `of${NBSP}the`],
+    ["in on", `in${NBSP}on`],
+    ["is it", `is${NBSP}it`],
+    ["or if", `or${NBSP}if`],
+    ["I think", `I${NBSP}think`],
+    ['"a cat"', `"a${NBSP}cat"`],
+    ["the cat sat on a mat", `the cat sat on${NBSP}a${NBSP}mat`],
+    ["Go to the store", `Go${NBSP}to${NBSP}the store`],
+    ["the cat", "the cat"],
+    // Accented Latin short words
+    ["à chat", `à${NBSP}chat`],
+    ["où aller", `où${NBSP}aller`],
+    ["ça va", `ça${NBSP}va`],
+  ])('"%s" → "%s"', (input, expected) => {
+    expect(nbspAfterShortWords(input)).toBe(expected)
+  })
+
+  it("preserves separators at node boundaries", () => {
+    expectSep(nbspAfterShortWords, [
+      [`a${SEP} cat`, `a${SEP}${NBSP}cat`],
+      [`a ${SEP}cat${SEP}`, `a${NBSP}${SEP}cat${SEP}`],
+    ])
+  })
+})
+
+describe("nbspBetweenNumberAndUnit", () => {
+  it.each(UNITS.map((u) => [`5 ${u}`, `5${NBSP}${u}`]))(
+    '"%s" → "%s"',
+    (input, expected) => {
+      expect(nbspBetweenNumberAndUnit(input)).toBe(expected)
+    },
+  )
+
+  it.each([
+    ["100km", "100km"],
+    ["5 kms", "5 kms"],
+    ["chapter 3 above", "chapter 3 above"],
+    ["item 5 here", "item 5 here"],
+    ["5 3", "5 3"],
+    ["page 42 of", "page 42 of"],
+  ])('no match: "%s"', (input, expected) => {
+    expect(nbspBetweenNumberAndUnit(input)).toBe(expected)
+  })
+
+  it("preserves separators at node boundaries", () => {
+    expectSep(nbspBetweenNumberAndUnit, [
+      [`5${SEP} kg`, `5${SEP}${NBSP}kg`],
+      [`5 ${SEP}kg`, `5${NBSP}${SEP}kg`],
+      [`5${SEP} ${SEP}kg`, `5${SEP}${NBSP}${SEP}kg`],
+    ])
+  })
+
+  it("does not match unit letter that starts a cross-element word", () => {
+    // "5 m" + SEP + "ade" simulates <span>5 m</span><span>ade</span> ("made")
+    expect(nbspBetweenNumberAndUnit(`5 m${SEP}ade`, { separator: SEP }))
+      .toBe(`5 m${SEP}ade`)
+  })
+})
+
+describe("nbspBeforeLastWord", () => {
+  it.each([
+    ["the end", `the${NBSP}end`],
+    ["hello world", `hello${NBSP}world`],
+    ["a b c", `a b${NBSP}c`],
+    ["hello abcdefghij", `hello${NBSP}abcdefghij`],
+    ["hello abcdefghijk", "hello abcdefghijk"],
+    ["hello international", "hello international"],
+    ["hello", "hello"],
+    ["   ", "   "],
+    ["the end\n\nNew paragraph", `the${NBSP}end\n\nNew${NBSP}paragraph`],
+    ["the end\ncontinues", `the end\ncontinues`],
+  ])('"%s" → "%s"', (input, expected) => {
+    expect(nbspBeforeLastWord(input)).toBe(expected)
+  })
+
+  it("preserves separator before end", () => {
+    expectSep(nbspBeforeLastWord, [
+      [`the end${SEP}`, `the${NBSP}end${SEP}`],
+    ])
+  })
+})
+
+describe("nbspAfterReferenceAbbreviations", () => {
+  it.each([
+    ...REFERENCE_ABBREVIATIONS.map((abbr, i) => [`${abbr}. ${i + 1}`, `${abbr}.${NBSP}${i + 1}`]),
+    ["Fig. caption", "Fig. caption"],
+  ] as [string, string][])('"%s" → "%s"', (input, expected) => {
+    expect(nbspAfterReferenceAbbreviations(input)).toBe(expected)
+  })
+
+  it("preserves separators at node boundaries", () => {
+    expectSep(nbspAfterReferenceAbbreviations, [
+      [`Fig.${SEP} 1`, `Fig.${SEP}${NBSP}1`],
+      [`Fig. ${SEP}1`, `Fig.${NBSP}${SEP}1`],
+    ])
+  })
+})
+
+describe("nbspAfterSectionSymbols", () => {
+  it.each([
+    ["§ 5", `§${NBSP}5`],
+    ["¶ 3", `¶${NBSP}3`],
+    ["See § 12 for details", `See §${NBSP}12 for details`],
+    ["§ title", "§ title"],
+  ])('"%s" → "%s"', (input, expected) => {
+    expect(nbspAfterSectionSymbols(input)).toBe(expected)
+  })
+
+  it("preserves separator after symbol", () => {
+    expectSep(nbspAfterSectionSymbols, [
+      [`§${SEP} 5`, `§${SEP}${NBSP}5`],
+    ])
+  })
+})
+
+describe("nbspAfterHonorifics", () => {
+  const names = [
+    // English
+    "Smith", "Jones", "Brown", "Davis", "Wilson", "King", "Patrick", "Martinez", "Judge", "Brown", "Warren", "Lee", "Lee",
+    // French
+    "Dupont", "Laurent", "Lefebvre",
+    // German / Nordic
+    "Schmidt", "Weber",
+    // Spanish / Portuguese
+    "García", "Rodríguez",
+    // Italian
+    "Rossi", "Bianchi",
+    // Dutch
+    "Bakker", "Jansen",
+  ]
+  it.each([
+    ...HONORIFICS.map((h, i) => [`${h}. ${names[i]}`, `${h}.${NBSP}${names[i]}`]),
+    ["Dr. Élodie", `Dr.${NBSP}Élodie`],
+    ["Jr. here", "Jr. here"],
+    ["Dr. said", "Dr. said"],
+  ] as [string, string][])('"%s" → "%s"', (input, expected) => {
+    expect(nbspAfterHonorifics(input)).toBe(expected)
+  })
+
+  it("preserves separators at node boundaries", () => {
+    expectSep(nbspAfterHonorifics, [
+      [`Dr.${SEP} Smith`, `Dr.${SEP}${NBSP}Smith`],
+      [`Dr. ${SEP}Smith`, `Dr.${NBSP}${SEP}Smith`],
+    ])
+  })
+})
+
+describe("nbspAfterCopyrightSymbols", () => {
+  it.each([
+    ["© 2024", `©${NBSP}2024`],
+    ["® Brand", `®${NBSP}Brand`],
+    ["™ Product", `™${NBSP}Product`],
+    ["© 2024 Company", `©${NBSP}2024 Company`],
+    ["© company", "© company"],
+  ])('"%s" → "%s"', (input, expected) => {
+    expect(nbspAfterCopyrightSymbols(input)).toBe(expected)
+  })
+
+  it("preserves separator after symbol", () => {
+    expectSep(nbspAfterCopyrightSymbols, [
+      [`©${SEP} 2024`, `©${SEP}${NBSP}2024`],
+    ])
+  })
+})
+
+describe("nbspBetweenInitials", () => {
+  it.each([
+    ["J. K. Rowling", `J.${NBSP}K.${NBSP}Rowling`],
+    ["A. B. C.", `A.${NBSP}B.${NBSP}C.`],
+    ["J. Smith", `J.${NBSP}Smith`],
+    ["É. Piaf", `É.${NBSP}Piaf`],
+    ["A. test", "A. test"],
+  ])('"%s" → "%s"', (input, expected) => {
+    expect(nbspBetweenInitials(input)).toBe(expected)
+  })
+
+  it("preserves separator between initials", () => {
+    expectSep(nbspBetweenInitials, [
+      [`J.${SEP} K. Rowling`, `J.${SEP}${NBSP}K.${NBSP}Rowling`],
+    ])
+  })
+})
+
+describe("nbspTransform", () => {
+  it("applies all nbsp transformations", () => {
+    expect(nbspTransform("Dr. Smith wrote Fig. 1 on p. 42"))
+      .toBe(`Dr.${NBSP}Smith wrote Fig.${NBSP}1 on${NBSP}p.${NBSP}42`)
+  })
+
+  it("handles multiple rules on the same text", () => {
+    expect(nbspTransform("© 2024 by J. K. Rowling"))
+      .toBe(`©${NBSP}2024 by${NBSP}J.${NBSP}K.${NBSP}Rowling`)
+  })
+
+  it("nbspBeforeLastWord fires on plain text", () => {
+    expect(nbspTransform("Hello world")).toBe(`Hello${NBSP}world`)
+  })
+
+  it("passes separator through to all functions", () => {
+    expect(nbspTransform(`Dr.${SEP} Smith`, { separator: SEP }))
+      .toBe(`Dr.${SEP}${NBSP}Smith`)
+  })
+
+  describe("ordering: specific patterns before generic", () => {
+    it("abbreviation claims nbsp before short-word rule", () => {
+      const result = nbspTransform("No. 5")
+      expect(result).toBe(`No.${NBSP}5`)
+      expect(result.split(NBSP).length - 1).toBe(1)
+    })
+
+    it("honorific + initials compose correctly", () => {
+      expect(nbspTransform("Dr. J. K. Smith")).toBe(`Dr.${NBSP}J.${NBSP}K.${NBSP}Smith`)
+    })
+
+    it("honorific + unit don't double-apply with short words", () => {
+      expect(nbspTransform("St. Anne had 5 kg")).toBe(`St.${NBSP}Anne had 5${NBSP}kg`)
+    })
+  })
+})