feat(sr): add configurable font-family transform by nottmey · Pull Request #1016 · DataDog/dd-sdk-flutter

nottmey · 2026-04-30T10:44:01Z

What and why?

Add DatadogSessionReplayConfiguration.fontFamilyTransform (FontFamilyStrategy / FontFamilyTransformConfig) so captured font families can be rewritten to web-compatible CSS stacks in the processor isolate before upload (default FontFamilyStrategy.none for backwards compatibility; opt into FontFamilyStrategy.smart for normalization). In smart mode, FontFamilyTransformConfig.rules[''] sets the stack when the captured family is empty or ends up empty after sentinel stripping.

How?

Review checklist

This pull request has appropriate unit and / or integration tests
This pull request references a Github or JIRA issue

fuzzybinary

Minor suggestions if you want to take care of them.

I'm going to actually ask @gonzalezreal to review as I think he has familiarity with how iOS handles this and will be able to give me more insight on whether or not we need separate iOS / Android fallback values.

fuzzybinary · 2026-05-01T14:49:16Z

+    if (lower == 'blinkmacsystemfont') {
+      return 'BlinkMacSystemFont';
+    }
+    if (lower == '-apple-system') {
+      return '-apple-system';
+    }
+    return lower;


nit: You could use pattern matching for this:

return switch (lower) { 'blinkmacsystemfont' => 'BlinkMacSystemFont', '-apple-system' => '-apple-system', _ => lower, };

which I find very slightly cleaner.

fuzzybinary · 2026-05-01T14:51:32Z

+      case FontFamilyStrategy.fallback:
+        return kIosParityFontStack;


Is this only needed on iOS? Is there an Android fallback we should be using as well?

The kIosParityFontStack mirrors the iOS native SDK's Fallback.fontFamily (REPLAY-1421). The Android SDK uses "Roboto, sans-serif" — same effective result without the Apple-specific prefixes. Since the replay player is a web browser, the -apple-system, BlinkMacSystemFont prefixes are harmless CSS fallbacks that improve rendering on Safari/Chrome macOS. Roboto already serves as the Android (and general web) fallback. No separate Android stack needed — one stack covers both platforms.

-> update the naming (now defaultReplayFontStack) and comment

fuzzybinary · 2026-05-01T14:54:42Z

+    }
+  }
+
+  SRTextWireframe rewrite(SRTextWireframe wireframe) {


I think it makes sense for this method to be called apply and to potentially change the name of the String transform method. I can see a situation where we might need multiple of these Transforms in the future, and having them all implement a method called apply makes sense to me, whereas rewrite doesn't quite seem like the right term for generalized application of a transform.

I'll leave it to your discretion if you want to change it though.

rewrite(SRTextWireframe) → apply(SRTextWireframe) — the wireframe-level method now called apply, which is the generalized name that future transforms can all share

apply(String) → transformFamily(String) — the string-level helper renamed to transformFamily so it no longer collides and better describes what it does (transforms the font family string specifically)

Updated the one call site in processor_worker.dart and all 27 references in tests

fuzzybinary · 2026-05-01T14:59:37Z

+      if (stripped.isEmpty) {
+        continue;
+      }


Should this be above the check in _flutterFontSentinels?

yes, good call!

fuzzybinary · 2026-05-01T15:02:44Z


 import 'dart:isolate';

+import '../../datadog_session_replay.dart';


This should be below the package imports... I'm surprised the linter didn't complain about that....

updated, neither flutter_lints nor the underlying package:lints/recommended.yaml seem to enable directives_ordering

enabled it for sr

fuzzybinary · 2026-05-01T15:04:55Z

 import 'dart:async';
 import 'dart:convert';

+import '../../datadog_session_replay.dart';


Same here, this should move down to be with the other relative imports.

fuzzybinary · 2026-05-01T15:06:09Z

+/// wireframes in a background isolate, which cannot serialize Dart closures—use
+/// [FontFamilyTransformConfig.rules] instead.


Suggested change

/// wireframes in a background isolate, which cannot serialize Dart closures—use

/// [FontFamilyTransformConfig.rules] instead.

/// wireframes in a background isolate, which cannot serialize Dart closures —

/// use [FontFamilyTransformConfig.rules] instead.

fuzzybinary · 2026-05-01T15:08:15Z

+  /// Always emits the single hardcoded CSS stack
+  /// `-apple-system, BlinkMacSystemFont, Roboto, sans-serif`,
+  /// regardless of the captured family. Matches the current iOS SDK
+  /// behavior and is the safest choice if you do not want any
+  /// Flutter font names leaving the device.
+  fallback,


Does it make sense to check the current Platform and supply an Android fallback as well?

updated the comment, we already use a android compatible fallback

fuzzybinary · 2026-05-01T15:14:09Z

+## Unreleased
+
+* Add `DatadogSessionReplayConfiguration.fontFamilyTransform` (`FontFamilyStrategy` / `FontFamilyTransformConfig`) so captured font families can be rewritten to web-compatible CSS stacks in the processor isolate before upload (default `FontFamilyStrategy.none` for backwards compatibility; opt into `FontFamilyStrategy.smart` for normalization). In smart mode, `FontFamilyTransformConfig.rules['']` sets the stack when the captured family is empty or ends up empty after sentinel stripping.
+


We pull CHANGELOG items from the commit message now. I can add in the extra details during the release.

ok, removed

fuzzybinary · 2026-05-01T15:22:06Z

If you want, we could actually setup a golden test for this as well. Since goldens can only render one specific font, you could take any of the tests that render text and setup the transformer to make the switch.

Add FontFamilyStrategy and FontFamilyTransformConfig to rewrite text wireframe font families in the processor isolate. Smart mode normalizes Flutter-specific names for web replay; default strategy is none to preserve prior behavior. Document in CHANGELOG. Made-with: Cursor

nottmey · 2026-05-07T15:38:29Z

@fuzzybinary I'm not sure whether goldens make sense here, created a separate PR for it: #1028 (commit 1103307)

Co-authored-by: Cursor <cursoragent@cursor.com>

nottmey requested a review from a team as a code owner April 30, 2026 10:44

nottmey changed the title ~~feat(session_replay): add configurable font-family transform~~ feat(session-replay): add configurable font-family transform Apr 30, 2026

fuzzybinary reviewed May 1, 2026

View reviewed changes

fuzzybinary assigned gonzalezreal May 1, 2026

nottmey force-pushed the feat/smart-font-family-handling branch 2 times, most recently from 9b6b366 to 779b8a2 Compare May 7, 2026 14:51

nottmey changed the title ~~feat(session-replay): add configurable font-family transform~~ feat(sr): add configurable font-family transform May 7, 2026

nottmey force-pushed the feat/smart-font-family-handling branch from 779b8a2 to ba9f0b3 Compare May 7, 2026 15:22

nottmey requested a review from fuzzybinary May 7, 2026 15:23

fuzzybinary previously approved these changes May 7, 2026

View reviewed changes

chore(sr): dart format font_family_transform_test for CI

1479369

Co-authored-by: Cursor <cursoragent@cursor.com>

nottmey dismissed fuzzybinary’s stale review via 1479369 May 7, 2026 16:07

nottmey requested a review from fuzzybinary May 7, 2026 16:29

fuzzybinary approved these changes May 7, 2026

View reviewed changes

fuzzybinary merged commit d50ba33 into DataDog:develop May 7, 2026
11 checks passed

		case FontFamilyStrategy.fallback:
		return kIosParityFontStack;


		import 'dart:isolate';

		import '../../datadog_session_replay.dart';

		/// wireframes in a background isolate, which cannot serialize Dart closures—use
		/// [FontFamilyTransformConfig.rules] instead.

		## Unreleased

		* Add `DatadogSessionReplayConfiguration.fontFamilyTransform` (`FontFamilyStrategy` / `FontFamilyTransformConfig`) so captured font families can be rewritten to web-compatible CSS stacks in the processor isolate before upload (default `FontFamilyStrategy.none` for backwards compatibility; opt into `FontFamilyStrategy.smart` for normalization). In smart mode, `FontFamilyTransformConfig.rules['']` sets the stack when the captured family is empty or ends up empty after sentinel stripping.

Conversation

nottmey commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What and why?

How?

Review checklist

Uh oh!

fuzzybinary left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fuzzybinary commented May 1, 2026

Uh oh!

nottmey commented May 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nottmey commented Apr 30, 2026 •

edited

Loading