serverless-ircd 0.4.0 → 0.5.0

package/packages/irc-core/tests/numerics.test.ts

@@ -31,6 +31,68 @@ describe('Numerics registry', () => {
     expect(Numerics.RPL_ENDOFWHOWAS).toBe(369);
   });
 
+  it('maps RPL_TRACELINK to 200', () => {
+    expect(Numerics.RPL_TRACELINK).toBe(200);
+  });
+
+  it('maps RPL_TRACEOPERATOR to 204', () => {
+    expect(Numerics.RPL_TRACEOPERATOR).toBe(204);
+  });
+
+  it('maps RPL_TRACEUSER to 205', () => {
+    expect(Numerics.RPL_TRACEUSER).toBe(205);
+  });
+
+  it('maps RPL_TRACESERVER to 206', () => {
+    expect(Numerics.RPL_TRACESERVER).toBe(206);
+  });
+
+  it('maps RPL_ENDOFTRACE to 262', () => {
+    expect(Numerics.RPL_ENDOFTRACE).toBe(262);
+  });
+
+  // -- LUSERS (RFC 2812 §4.6.2) ----------------------------------------------
+  it('maps RPL_LUSERCLIENT to 251', () => {
+    expect(Numerics.RPL_LUSERCLIENT).toBe(251);
+  });
+
+  it('maps RPL_LUSEROP to 252', () => {
+    expect(Numerics.RPL_LUSEROP).toBe(252);
+  });
+
+  it('maps RPL_LUSERUNKNOWN to 253', () => {
+    expect(Numerics.RPL_LUSERUNKNOWN).toBe(253);
+  });
+
+  it('maps RPL_LUSERCHANNELS to 254', () => {
+    expect(Numerics.RPL_LUSERCHANNELS).toBe(254);
+  });
+
+  it('maps RPL_LUSERME to 255', () => {
+    expect(Numerics.RPL_LUSERME).toBe(255);
+  });
+
+  it('maps RPL_LOCALUSERS to 265', () => {
+    expect(Numerics.RPL_LOCALUSERS).toBe(265);
+  });
+
+  it('maps RPL_GLOBALUSERS to 266', () => {
+    expect(Numerics.RPL_GLOBALUSERS).toBe(266);
+  });
+
+  // -- STATS (RFC 2812 §4.6.3) -----------------------------------------------
+  it('maps RPL_STATSLINKINFO to 211', () => {
+    expect(Numerics.RPL_STATSLINKINFO).toBe(211);
+  });
+
+  it('maps RPL_ENDOFSTATS to 219', () => {
+    expect(Numerics.RPL_ENDOFSTATS).toBe(219);
+  });
+
+  it('maps RPL_STATSUPTIME to 242', () => {
+    expect(Numerics.RPL_STATSUPTIME).toBe(242);
+  });
+
   it('maps ERR_WASNOSUCHNICK to 406', () => {
     expect(Numerics.ERR_WASNOSUCHNICK).toBe(406);
   });
@@ -77,6 +139,26 @@ describe('numericToName', () => {
     expect(numericToName.get(1)).toBe('RPL_WELCOME');
   });
 
+  it('reverses RPL_LUSERCLIENT', () => {
+    expect(numericToName.get(251)).toBe('RPL_LUSERCLIENT');
+  });
+
+  it('reverses RPL_GLOBALUSERS', () => {
+    expect(numericToName.get(266)).toBe('RPL_GLOBALUSERS');
+  });
+
+  it('reverses RPL_STATSLINKINFO', () => {
+    expect(numericToName.get(211)).toBe('RPL_STATSLINKINFO');
+  });
+
+  it('reverses RPL_ENDOFSTATS', () => {
+    expect(numericToName.get(219)).toBe('RPL_ENDOFSTATS');
+  });
+
+  it('reverses RPL_STATSUPTIME', () => {
+    expect(numericToName.get(242)).toBe('RPL_STATSUPTIME');
+  });
+
   it('returns undefined for an unregistered code', () => {
     expect(numericToName.get(600)).toBeUndefined();
   });
@@ -107,4 +189,12 @@ describe('formatNumeric', () => {
   it('zero-pads RPL_ISUPPORT', () => {
     expect(formatNumeric('RPL_ISUPPORT')).toBe('005');
   });
+
+  it('formats RPL_LUSERCLIENT as 251', () => {
+    expect(formatNumeric('RPL_LUSERCLIENT')).toBe('251');
+  });
+
+  it('formats RPL_ENDOFSTATS as 219', () => {
+    expect(formatNumeric('RPL_ENDOFSTATS')).toBe('219');
+  });
 });

package/packages/irc-core/tests/outbound.test.ts

@@ -9,6 +9,7 @@ import {
 } from '../src/protocol/outbound';
 import { parse } from '../src/protocol/parser';
 import { serialize } from '../src/protocol/serializer';
+import { MAX_WS_MESSAGE_BYTES } from '../src/ws-framing';
 
 const L = (text: string): RawLine => ({ text });
 
@@ -192,6 +193,56 @@ describe('enforceLineLimit', () => {
   });
 });
 
+// ============================================================================
+// enforceLineLimit — budget-aware optional WsFrameMode parameter
+// ============================================================================
+
+describe('enforceLineLimit — WsFrameMode budget', () => {
+  // The optional `mode` parameter selects the byte budget. Spec modes cap at
+  // MAX_WS_MESSAGE_BYTES (510) directly — there is no trailing CRLF on a WS
+  // message. Legacy mode caps at MAX_LINE_BYTES - 2 (512 - 2 = 510). Both
+  // resolve to 510 today, but the API is mode-aware so a future change to
+  // either constant needs no call-site edits.
+  const SPEC_BUDGET = MAX_WS_MESSAGE_BYTES;
+
+  it('accepts an optional spec-text mode and caps at MAX_WS_MESSAGE_BYTES', () => {
+    const exact: RawLine = L('x'.repeat(SPEC_BUDGET));
+    expect(enforceLineLimit(exact, new Set<string>(), 'spec-text')).toBe(exact);
+
+    const tooLong: RawLine = L('x'.repeat(SPEC_BUDGET + 5));
+    const out = enforceLineLimit(tooLong, new Set<string>(), 'spec-text');
+    expect(out.text.length).toBe(SPEC_BUDGET);
+  });
+
+  it('accepts an optional spec-binary mode and caps at MAX_WS_MESSAGE_BYTES', () => {
+    const tooLong: RawLine = L('x'.repeat(SPEC_BUDGET + 5));
+    const out = enforceLineLimit(tooLong, new Set<string>(), 'spec-binary');
+    expect(out.text.length).toBe(SPEC_BUDGET);
+  });
+
+  it('uses the legacy budget when mode is explicitly "legacy"', () => {
+    const tooLong: RawLine = L('x'.repeat(SPEC_BUDGET + 5));
+    const out = enforceLineLimit(tooLong, new Set<string>(), 'legacy');
+    expect(out.text.length).toBe(SPEC_BUDGET);
+  });
+
+  it('omitting mode defaults to the legacy budget (backward compatible)', () => {
+    const tooLong: RawLine = L('x'.repeat(SPEC_BUDGET + 5));
+    const withDefault = enforceLineLimit(tooLong, new Set<string>());
+    const withLegacy = enforceLineLimit(tooLong, new Set<string>(), 'legacy');
+    expect(withDefault).toEqual(withLegacy);
+  });
+
+  it('preserves the tag section in spec-text mode just as in legacy mode', () => {
+    const tagPrefix = '@time=2024-01-15T12:34:56.789Z ';
+    const body = `:alice PRIVMSG #foo :${'x'.repeat(500)}`;
+    const line: RawLine = L(`${tagPrefix}${body}`);
+    const out = enforceLineLimit(line, new Set<string>(['message-tags']), 'spec-text');
+    expect(out.text.length).toBe(SPEC_BUDGET);
+    expect(out.text.startsWith(tagPrefix)).toBe(true);
+  });
+});
+
 // ============================================================================
 // Round-trip through serialize -> applyServerTime -> parse
 // ============================================================================

package/packages/irc-core/tests/ports.test.ts

@@ -5,6 +5,7 @@ import {
   ConsoleLogger,
   FakeClock,
   type IdFactory,
+  InMemoryMtlsIdentityProvider,
   LogLevel,
   type LogRecord,
   type Logger,
@@ -362,3 +363,24 @@ const _assertLogRecord: LogRecord = {
   msg: '',
 };
 void _assertLogRecord;
+
+describe('InMemoryMtlsIdentityProvider', () => {
+  it('returns the certificate subject for a known connection id', () => {
+    const provider = new InMemoryMtlsIdentityProvider([
+      { connId: 'c1', identity: 'CN=alice' },
+      { connId: 'c2', identity: 'CN=bob' },
+    ]);
+    expect(provider.getIdentity('c1')).toBe('CN=alice');
+    expect(provider.getIdentity('c2')).toBe('CN=bob');
+  });
+
+  it('returns undefined for an unknown connection id', () => {
+    const provider = new InMemoryMtlsIdentityProvider([{ connId: 'c1', identity: 'CN=alice' }]);
+    expect(provider.getIdentity('nope')).toBeUndefined();
+  });
+
+  it('handles an empty identity table', () => {
+    const provider = new InMemoryMtlsIdentityProvider([]);
+    expect(provider.getIdentity('c1')).toBeUndefined();
+  });
+});

package/packages/irc-core/tests/raw-modules.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Ambient declaration so `?raw` imports (Vite's built-in transform that
+ * inlines a file's text at bundle time) typecheck under the strict
+ * `tsconfig.test.json`. Used by source-level regression guards that
+ * assert removed numerics stay removed.
+ */
+declare module '*?raw' {
+  const content: string;
+  // eslint-disable-next-line import/no-default-export
+  export default content;
+}

package/packages/irc-core/tests/stats-store.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it } from 'vitest';
+import {
+  FakeClock,
+  InMemoryStats,
+  type ServerStats,
+  type ServerStatsSnapshot,
+  computeStatsSnapshot,
+} from '../src/ports';
+import type { ChannelState } from '../src/state/channel';
+import { createChannel } from '../src/state/channel';
+import type { ConnId, ConnectionState } from '../src/state/connection';
+import { createConnection } from '../src/state/connection';
+
+/** Builds a registered connection with the supplied modes. */
+function makeConn(
+  id: ConnId,
+  opts: { oper?: boolean; invisible?: boolean; registered?: boolean } = {},
+): ConnectionState {
+  const s = createConnection({ id, connectedSince: 0 });
+  s.nick = id;
+  s.user = id;
+  s.host = 'example.com';
+  s.realname = id;
+  s.registration = opts.registered === false ? 'pre-registration' : 'registered';
+  if (opts.oper !== undefined) s.userModes.oper = opts.oper;
+  if (opts.invisible !== undefined) s.userModes.invisible = opts.invisible;
+  return s;
+}
+
+function emptyChannel(name: string): ChannelState {
+  return createChannel({ name, nameLower: name.toLowerCase(), createdAt: 0 });
+}
+
+describe('InMemoryStats', () => {
+  it('implements the ServerStats port', () => {
+    const stats: ServerStats = new InMemoryStats({
+      connections: new Map(),
+      channels: new Map(),
+      uptimeStartedAt: 0,
+    });
+    expect(stats).toBeDefined();
+  });
+
+  it('returns zero counts for an empty deployment', async () => {
+    const stats = new InMemoryStats({
+      connections: new Map(),
+      channels: new Map(),
+      uptimeStartedAt: 0,
+    });
+
+    const snap = await stats.getStats();
+
+    expect(snap).toEqual<ServerStatsSnapshot>({
+      users: 0,
+      invisible: 0,
+      opers: 0,
+      unknownConnections: 0,
+      channels: 0,
+      servers: 1,
+      localConns: 0,
+      globalConns: 0,
+      uptimeStartedAt: 0,
+      maxLocalConns: 0,
+      maxGlobalConns: 0,
+    });
+  });
+
+  it('derives the seed counts from the maps (3 conns, 1 oper, 2 channels)', async () => {
+    const conns = new Map<ConnId, ConnectionState>([
+      ['c1', makeConn('c1')],
+      ['c2', makeConn('c2', { invisible: true })],
+      ['c3', makeConn('c3', { oper: true })],
+    ]);
+    const channels = new Map<string, ChannelState>([
+      ['#a', emptyChannel('#a')],
+      ['#b', emptyChannel('#b')],
+    ]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels,
+      uptimeStartedAt: 1_000,
+    });
+
+    const snap = await stats.getStats();
+
+    // 3 registered (2 visible + 1 invisible), 1 oper, 0 unknown, 2 channels.
+    expect(snap.users).toBe(2); // visible registered
+    expect(snap.invisible).toBe(1);
+    expect(snap.opers).toBe(1);
+    expect(snap.unknownConnections).toBe(0);
+    expect(snap.channels).toBe(2);
+    expect(snap.servers).toBe(1);
+    expect(snap.localConns).toBe(3);
+    expect(snap.globalConns).toBe(3);
+    expect(snap.uptimeStartedAt).toBe(1_000);
+  });
+
+  it('counts pre-registration connections as unknown', async () => {
+    const conns = new Map<ConnId, ConnectionState>([
+      ['c1', makeConn('c1')],
+      ['c2', makeConn('c2', { registered: false })],
+    ]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels: new Map(),
+      uptimeStartedAt: 0,
+    });
+
+    const snap = await stats.getStats();
+
+    expect(snap.users).toBe(1);
+    expect(snap.unknownConnections).toBe(1);
+    expect(snap.localConns).toBe(2);
+  });
+
+  it('reports the live max as equal to current count when never higher', async () => {
+    const conns = new Map<ConnId, ConnectionState>([['c1', makeConn('c1')]]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels: new Map(),
+      uptimeStartedAt: 0,
+      maxLocalConns: 5,
+      maxGlobalConns: 7,
+    });
+
+    const snap = await stats.getStats();
+
+    expect(snap.maxLocalConns).toBe(5);
+    expect(snap.maxGlobalConns).toBe(7);
+  });
+
+  it('clamps max to the current count when the live count exceeds the recorded max', async () => {
+    const conns = new Map<ConnId, ConnectionState>([
+      ['c1', makeConn('c1')],
+      ['c2', makeConn('c2')],
+      ['c3', makeConn('c3')],
+    ]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels: new Map(),
+      uptimeStartedAt: 0,
+      maxLocalConns: 2,
+      maxGlobalConns: 2,
+    });
+
+    const snap = await stats.getStats();
+
+    // Live count (3) > seeded max (2); the snapshot reports the live value
+    // so the wire numeric never claims a max below the current count.
+    expect(snap.maxLocalConns).toBe(3);
+    expect(snap.maxGlobalConns).toBe(3);
+  });
+
+  it('reflects map mutations on subsequent getStats() calls', async () => {
+    const conns = new Map<ConnId, ConnectionState>([['c1', makeConn('c1')]]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels: new Map(),
+      uptimeStartedAt: 0,
+    });
+
+    let snap = await stats.getStats();
+    expect(snap.users).toBe(1);
+
+    conns.set('c2', makeConn('c2'));
+    conns.set('c3', makeConn('c3', { invisible: true }));
+    snap = await stats.getStats();
+    expect(snap.users).toBe(2);
+    expect(snap.invisible).toBe(1);
+    expect(snap.localConns).toBe(3);
+  });
+});
+
+describe('computeStatsSnapshot', () => {
+  it('counts opers separately from users (an oper still counts as a user)', () => {
+    const snap = computeStatsSnapshot([makeConn('c1'), makeConn('c2', { oper: true })], 0, 0);
+    expect(snap.users).toBe(2);
+    expect(snap.opers).toBe(1);
+  });
+
+  it('counts an oper who is also invisible under invisible + opers (not users)', () => {
+    const snap = computeStatsSnapshot([makeConn('c1', { oper: true, invisible: true })], 0, 0);
+    expect(snap.invisible).toBe(1);
+    expect(snap.opers).toBe(1);
+    // users = visible registered (total registered − invisible).
+    expect(snap.users).toBe(0);
+  });
+
+  it('reports users as the visible-only count (total registered − invisible)', () => {
+    const snap = computeStatsSnapshot(
+      [
+        makeConn('c1'),
+        makeConn('c2'),
+        makeConn('c3', { invisible: true }),
+        makeConn('c4', { invisible: true }),
+      ],
+      0,
+      0,
+    );
+    expect(snap.users).toBe(2);
+    expect(snap.invisible).toBe(2);
+    expect(snap.localConns).toBe(4);
+  });
+
+  it('defaults maxConns to the live count when seed omitted', () => {
+    const snap = computeStatsSnapshot([makeConn('c1'), makeConn('c2')], 0, 0);
+    expect(snap.maxLocalConns).toBe(2);
+    expect(snap.maxGlobalConns).toBe(2);
+  });
+
+  it('uses the FakeClock only for uptime (not in the snapshot)', async () => {
+    const clock = new FakeClock(99_000);
+    const stats = new InMemoryStats({
+      connections: new Map(),
+      channels: new Map(),
+      uptimeStartedAt: 1_000,
+      clock,
+    });
+    const snap = await stats.getStats();
+    expect(snap.uptimeStartedAt).toBe(1_000);
+  });
+});

package/packages/irc-core/tests/ws-framing.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, it } from 'vitest';
+import {
+  MAX_WS_MESSAGE_BYTES,
+  type WsFrameMode,
+  frameToLines,
+  isWithinWsByteBudget,
+  sanitizeForTextMode,
+  stripTrailingCrLf,
+  wsFrameModeFor,
+} from '../src/ws-framing';
+
+// ============================================================================
+// MAX_WS_MESSAGE_BYTES constant
+// ============================================================================
+
+describe('MAX_WS_MESSAGE_BYTES', () => {
+  it('is 510 (the IRC line-content limit; WS spec omits the trailing CRLF)', () => {
+    expect(MAX_WS_MESSAGE_BYTES).toBe(510);
+  });
+});
+
+// ============================================================================
+// wsFrameModeFor — subprotocol → WsFrameMode mapping
+// ============================================================================
+
+describe('wsFrameModeFor', () => {
+  it('maps text.ircv3.net to spec-text', () => {
+    expect(wsFrameModeFor('text.ircv3.net')).toBe('spec-text');
+  });
+
+  it('maps binary.ircv3.net to spec-binary', () => {
+    expect(wsFrameModeFor('binary.ircv3.net')).toBe('spec-binary');
+  });
+
+  it('maps undefined (no subprotocol) to legacy', () => {
+    expect(wsFrameModeFor(undefined)).toBe('legacy');
+  });
+});
+
+// ============================================================================
+// stripTrailingCrLf
+// ============================================================================
+
+describe('stripTrailingCrLf', () => {
+  it('strips a trailing CR-LF', () => {
+    expect(stripTrailingCrLf('NICK bob\r\n')).toBe('NICK bob');
+  });
+
+  it('strips a trailing bare LF', () => {
+    expect(stripTrailingCrLf('NICK bob\n')).toBe('NICK bob');
+  });
+
+  it('leaves a string with no trailing terminator unchanged', () => {
+    expect(stripTrailingCrLf('NICK bob')).toBe('NICK bob');
+  });
+
+  it('strips only a single trailing terminator', () => {
+    expect(stripTrailingCrLf('a\r\n\r\n')).toBe('a\r\n');
+  });
+
+  it('returns the empty string unchanged', () => {
+    expect(stripTrailingCrLf('')).toBe('');
+  });
+
+  it('does not strip a leading CR-LF', () => {
+    expect(stripTrailingCrLf('\r\nNICK bob')).toBe('\r\nNICK bob');
+  });
+});
+
+// ============================================================================
+// frameToLines — spec-text / spec-binary modes (one IRC message per frame)
+// ============================================================================
+
+describe('frameToLines — spec-text', () => {
+  it('strips a trailing CR-LF and returns a single-element array', () => {
+    expect(frameToLines('NICK bob\r\n', 'spec-text')).toEqual(['NICK bob']);
+  });
+
+  it('strips a trailing bare LF', () => {
+    expect(frameToLines('NICK bob\n', 'spec-text')).toEqual(['NICK bob']);
+  });
+
+  it('does not split on an embedded LF (one WS message === one IRC line)', () => {
+    expect(frameToLines('NICK bob\nextra', 'spec-text')).toEqual(['NICK bob\nextra']);
+  });
+
+  it('returns an empty array for an empty frame', () => {
+    expect(frameToLines('', 'spec-text')).toEqual([]);
+  });
+
+  it('returns an empty array for a frame that is only a terminator', () => {
+    expect(frameToLines('\r\n', 'spec-text')).toEqual([]);
+  });
+
+  it('returns a single bare line unchanged when there is no terminator', () => {
+    expect(frameToLines('PING :tok', 'spec-text')).toEqual(['PING :tok']);
+  });
+});
+
+describe('frameToLines — spec-binary', () => {
+  it('behaves identically to spec-text (single line, terminator stripped)', () => {
+    expect(frameToLines('NICK bob\n', 'spec-binary')).toEqual(['NICK bob']);
+  });
+
+  it('does not split on an embedded LF', () => {
+    expect(frameToLines('a\nb', 'spec-binary')).toEqual(['a\nb']);
+  });
+});
+
+// ============================================================================
+// frameToLines — legacy mode (the pre-spec split-on-/\r?\n/ behaviour)
+// ============================================================================
+
+describe('frameToLines — legacy', () => {
+  it('splits on CR-LF into separate lines', () => {
+    expect(frameToLines('a\r\nb', 'legacy')).toEqual(['a', 'b']);
+  });
+
+  it('splits on bare LF', () => {
+    expect(frameToLines('a\nb', 'legacy')).toEqual(['a', 'b']);
+  });
+
+  it('returns an empty array for the empty string', () => {
+    expect(frameToLines('', 'legacy')).toEqual([]);
+  });
+
+  it('returns a single bare line with no terminator unchanged', () => {
+    expect(frameToLines('PING :tok', 'legacy')).toEqual(['PING :tok']);
+  });
+
+  it('emits a trailing empty string for a terminated frame', () => {
+    expect(frameToLines('PING :tok\r\n', 'legacy')).toEqual(['PING :tok', '']);
+  });
+
+  it('splits several joined messages keeping a trailing empty string', () => {
+    expect(frameToLines('a\r\nb\r\n', 'legacy')).toEqual(['a', 'b', '']);
+  });
+});
+
+// Exhaustiveness guard: every declared mode is covered by the specs above.
+describe('frameToLines — mode coverage', () => {
+  const modes: WsFrameMode[] = ['spec-text', 'spec-binary', 'legacy'];
+  for (const mode of modes) {
+    it(`accepts the '${mode}' mode without throwing`, () => {
+      expect(Array.isArray(frameToLines('x', mode))).toBe(true);
+    });
+  }
+});
+
+// ============================================================================
+// isWithinWsByteBudget — the IRCv3 WS message byte cap
+// ============================================================================
+
+describe('isWithinWsByteBudget', () => {
+  it('accepts a frame whose length equals the 510-byte budget', () => {
+    expect(isWithinWsByteBudget('a'.repeat(510))).toBe(true);
+  });
+
+  it('rejects a frame whose length is one byte over the budget', () => {
+    expect(isWithinWsByteBudget('a'.repeat(511))).toBe(false);
+  });
+
+  it('accepts the empty string', () => {
+    expect(isWithinWsByteBudget('')).toBe(true);
+  });
+
+  it('accepts a short frame', () => {
+    expect(isWithinWsByteBudget('NICK bob')).toBe(true);
+  });
+});
+
+// ============================================================================
+// sanitizeForTextMode — replace lone surrogates with U+FFFD
+// ============================================================================
+
+describe('sanitizeForTextMode', () => {
+  it('replaces a lone high surrogate with U+FFFD', () => {
+    expect(sanitizeForTextMode('\uD800')).toBe('\uFFFD');
+  });
+
+  it('replaces a lone low surrogate with U+FFFD', () => {
+    expect(sanitizeForTextMode('\uDC00')).toBe('\uFFFD');
+  });
+
+  it('leaves a valid surrogate pair (a supplementary code point) unchanged', () => {
+    // U+10000 = \uD800\uDC00
+    expect(sanitizeForTextMode('\uD800\uDC00')).toBe('\uD800\uDC00');
+  });
+
+  it('leaves plain ASCII text unchanged', () => {
+    expect(sanitizeForTextMode('hello')).toBe('hello');
+  });
+
+  it('replaces a lone surrogate embedded in normal text', () => {
+    expect(sanitizeForTextMode('a\uD800b')).toBe('a\uFFFDb');
+  });
+
+  it('replaces two consecutive lone high surrogates with two U+FFFD', () => {
+    expect(sanitizeForTextMode('\uD800\uD800')).toBe('\uFFFD\uFFFD');
+  });
+
+  it('preserves a valid pair surrounded by normal text', () => {
+    expect(sanitizeForTextMode('x\uD83D\uDE00y')).toBe('x\uD83D\uDE00y');
+  });
+
+  it('replaces a lone high surrogate followed later by a lone low surrogate', () => {
+    expect(sanitizeForTextMode('\uD800a\uDC00')).toBe('\uFFFDa\uFFFD');
+  });
+
+  it('returns the empty string unchanged', () => {
+    expect(sanitizeForTextMode('')).toBe('');
+  });
+});