Files
ersatztv/ErsatzTV.Infrastructure/Streaming/Graphics/Text/TextElement.cs
T
timothy bef3f54798 fix(732): close the review findings on the background box and the default attach
Two independent cold reviews (Codex GPT-5.6 and a worktree-isolated Opus agent) converged on the
same three serious problems; both returned BLOCKED.

Boot safety. The already-seeded branch of SeedOnNowNext used to touch the filesystem not at all,
so a template the app cannot read - one edited as root via `docker exec` while the app runs under
PUID/PGID, or a read-only /config - was harmless. Reading and rewriting it there put unguarded IO
ahead of DatabaseIsReady() in a BackgroundService whose default behavior is StopHost, i.e. a
restart loop triggered by a file permission an operator can set by hand. The upgrade is now
best-effort (broad catch, cancellation still propagates) and CreateDirectory moved back below the
already-seeded check.

Stranding. The backfill wrote its marker even when the built-in GraphicsElement row was merely
undiscovered - the row is normally created by RefreshGraphicsElements, which runs long after
startup. An install upgrading from before #74 seeds the template and backfills on the same boot,
so every pre-existing channel would have been left unattached forever, with no second chance. The
seeder now creates the row itself, so the marker is only ever written against a resolved element.
The test that asserted the old behavior is replaced by one that pins the upgrade case.

Overclaimed records. The never-re-attach guarantee holds from the marker onwards, not across the
upgrade boundary: an operator who cleared the overlay before this landed left no state that
survives, and the one-time backfill re-adds it. That is inherent to "on by default" rather than a
defect, but the record asserted otherwise. Also recorded: the upgrade is a one-way door, because
the loader rejects unknown YAML keys, so a rollback drops the overlay on every channel at once.

Smaller, all with tests: the wrap budget now subtracts the same integer inset the bitmap grows by
(a fractional padding overflowed width_percent by a pixel); an inset that cannot fit is clamped
instead of squeezing the text to 1px and letting the box grow unbounded; FitTextBlock carries halo
and line height across, which only became reachable once a box's insets could push an element into
the Scale path; the built-in lookup filters on Kind so a same-named element in another template
folder cannot win; CreateChannelHandler adds to the collection rather than assigning over it.

width_percent is documented as a budget rather than a guarantee - wrapping cannot break below one
glyph, so it overflows with or without a box. The doc also no longer claims an unparseable colour
is never substituted (true for the box, false for text_color) or that an unset background_color
means no box (a border alone draws one).

The mutation claim is now reproducible: all 19 clause mutations are listed in
docs/graphics-elements.md with the test each one reddens. Two candidate mutations produced NO test
summary because they failed to compile under warnings-as-error, which reads exactly like a pass in
a scrolled log - that is called out there too.

The new pixel tests are the first in the repo to rasterise text, so the CI image's font dependency
is now declared in docs/testing.md rather than incidental (351 fonts present in the pinned image,
measured; they arrive via playwright install --with-deps).

Decisions-Edit: yes
Refs: #732
2026-08-26 20:37:06 +02:00

490 lines
17 KiB
C#

using System.Text.RegularExpressions;
using ErsatzTV.Core.Graphics;
using ErsatzTV.Core.Interfaces.Streaming;
using Microsoft.Extensions.Logging;
using NCalc;
using SkiaSharp;
using RichTextKit = Topten.RichTextKit;
namespace ErsatzTV.Infrastructure.Streaming.Graphics;
public partial class TextElement(
GraphicsEngineFonts graphicsEngineFonts,
TextGraphicsElement textElement,
ILogger logger)
: GraphicsElement, IDisposable
{
private static readonly Regex StylePattern = StyleRegex();
private SKBitmap _image;
private SKPointI _location;
private Option<Expression> _maybeOpacityExpression;
private float _opacity;
public override int ZIndex { get; } = textElement.ZIndex ?? 0;
public override string DebugKey { get; } = $"Text {textElement.DebugName()}";
public void Dispose()
{
GC.SuppressFinalize(this);
_image?.Dispose();
_image = null;
}
public override Task InitializeAsync(GraphicsEngineContext context, CancellationToken cancellationToken)
{
try
{
if (!string.IsNullOrWhiteSpace(textElement.OpacityExpression))
{
var expression = new Expression(textElement.OpacityExpression);
expression.EvaluateFunction += OpacityExpressionHelper.EvaluateFunction;
_maybeOpacityExpression = expression;
}
else
{
_opacity = (textElement.OpacityPercent ?? 100) / 100.0f;
}
if (!string.IsNullOrWhiteSpace(textElement.IncludeFontsFrom))
{
if (Directory.Exists(textElement.IncludeFontsFrom))
{
graphicsEngineFonts.LoadFonts(textElement.IncludeFontsFrom);
}
else
{
logger.LogWarning(
"include_fonts_from path {Directory} does not exist",
textElement.IncludeFontsFrom);
}
}
BackgroundBox box = BuildBackgroundBox();
RichTextKit.TextBlock textBlock = BuildTextBlock(textElement.Text);
// Padding and border sit OUTSIDE the laid-out text on every side, so they shrink the
// space the text may occupy and grow the bitmap that holds it. Zero when there is no
// box, which reproduces the pre-#732 geometry exactly.
//
// Round ONCE, here, and use the same integer on both sides: the bitmap grows by
// 2 * insetPixels, so subtracting the unrounded inset from the wrap budget would let a
// fractional padding push the finished box a pixel past width_percent.
var insetPixels = (int)Math.Ceiling(box?.Inset ?? 0f);
if (textElement.WidthPercent.HasValue)
{
var maxWidth = (float)Math.Round(textElement.WidthPercent.Value / 100.0 * context.FrameSize.Width);
// A padding wider than the budget itself cannot be honoured AND stay inside it.
// Clamp the inset rather than squeezing the text to 1px: an unclamped floor turns a
// fat-fingered background_padding into a box several times the requested width.
int maxInset = Math.Max(0, (int)Math.Floor((maxWidth - 1) / 2));
if (insetPixels > maxInset)
{
logger.LogWarning(
"Background padding/border of {Inset}px does not fit within width_percent "
+ "({MaxWidth}px); clamping to {Clamped}px",
insetPixels,
maxWidth,
maxInset);
insetPixels = maxInset;
}
// width_percent bounds the ELEMENT, so the text gets what is left after the insets.
// With no box the budget is passed through untouched -- not through Math.Max -- so a
// width_percent that rounds to 0 keeps its exact pre-#732 behavior.
float textMaxWidth = insetPixels == 0
? maxWidth
: Math.Max(1f, maxWidth - (2 * insetPixels));
switch (textElement.Fit)
{
case TextFit.Wrap:
textBlock.MaxWidth = textMaxWidth;
break;
case TextFit.Scale:
FitTextBlock(textBlock, textMaxWidth);
break;
}
}
_image = new SKBitmap(
(int)Math.Ceiling(textBlock.MeasuredWidth) + (2 * insetPixels),
(int)Math.Ceiling(textBlock.MeasuredHeight) + (2 * insetPixels));
using (var canvas = new SKCanvas(_image))
{
canvas.Clear(SKColors.Transparent);
if (box is not null)
{
DrawBackgroundBox(canvas, box, _image.Width, _image.Height);
}
textBlock.Paint(canvas, new SKPoint(insetPixels, insetPixels));
}
var horizontalMargin =
(int)Math.Round((textElement.HorizontalMarginPercent ?? 0) / 100.0 * context.FrameSize.Width);
var verticalMargin =
(int)Math.Round((textElement.VerticalMarginPercent ?? 0) / 100.0 * context.FrameSize.Height);
_location = CalculatePosition(
textElement.Location,
context.FrameSize.Width,
context.FrameSize.Height,
_image.Width,
_image.Height,
horizontalMargin,
verticalMargin);
}
catch (Exception ex)
{
IsFinished = true;
logger.LogWarning(ex, "Failed to initialize text element; will disable for this content");
}
return Task.CompletedTask;
}
public override ValueTask<Option<PreparedElementImage>> PrepareImage(
TimeSpan timeOfDay,
TimeSpan contentTime,
TimeSpan contentTotalTime,
TimeSpan channelTime,
CancellationToken cancellationToken)
{
float opacity = _opacity;
foreach (Expression expression in _maybeOpacityExpression)
{
opacity = OpacityExpressionHelper.GetOpacity(
expression,
timeOfDay,
contentTime,
contentTotalTime,
channelTime);
}
return opacity == 0
? ValueTask.FromResult(Option<PreparedElementImage>.None)
: new ValueTask<Option<PreparedElementImage>>(new PreparedElementImage(_image, _location, opacity, ZIndex, false));
}
// A background box is drawn only when a colour actually parses. An unparseable colour is
// warned about and skipped rather than substituted, so a typo never silently changes the
// look into something that appears deliberate.
private BackgroundBox BuildBackgroundBox()
{
SKColor? fill = ParseOptionalColor(textElement.BackgroundColor, "background_color");
if (fill.HasValue)
{
fill = ApplyOpacityPercent(fill.Value, textElement.BackgroundOpacityPercent);
}
SKColor? border = ParseOptionalColor(textElement.BorderColor, "border_color");
// A border colour with no explicit width means a hairline border, not an invisible one:
// "border_color set, nothing drawn" is the more confusing of the two readings.
var borderWidth = (float)Math.Max(0, textElement.BorderWidth ?? 1);
if (!border.HasValue)
{
borderWidth = 0;
}
if (!fill.HasValue && borderWidth <= 0)
{
return null;
}
return new BackgroundBox(
fill,
border,
borderWidth,
(float)Math.Max(0, textElement.BackgroundCornerRadius ?? 0),
(float)Math.Max(0, textElement.BackgroundPadding ?? 0));
}
private SKColor? ParseOptionalColor(string value, string fieldName)
{
if (string.IsNullOrWhiteSpace(value))
{
return null;
}
if (SKColor.TryParse(value, out SKColor parsed))
{
return parsed;
}
logger.LogWarning(
"Unable to parse {Field} value {Value}; that part of the background box will not be drawn",
fieldName,
value);
return null;
}
private static SKColor ApplyOpacityPercent(SKColor color, int? opacityPercent)
{
if (opacityPercent is not { } percent)
{
return color;
}
int clamped = Math.Clamp(percent, 0, 100);
return color.WithAlpha((byte)Math.Round(color.Alpha * clamped / 100.0));
}
private static void DrawBackgroundBox(SKCanvas canvas, BackgroundBox box, int width, int height)
{
// Skia strokes centred on the path, so half the border would fall outside the bitmap and
// be clipped. Inset the rect by half the width to keep the whole border visible.
float half = box.BorderWidth / 2f;
var rect = new SKRect(half, half, width - half, height - half);
// A radius larger than half the shorter side is not expressible as a rounded rect.
float radius = Math.Min(box.CornerRadius, Math.Min(rect.Width, rect.Height) / 2f);
radius = Math.Max(0, radius);
if (box.Fill is { } fill)
{
using var fillPaint = new SKPaint
{
Color = fill,
Style = SKPaintStyle.Fill,
IsAntialias = true
};
canvas.DrawRoundRect(rect, radius, radius, fillPaint);
}
if (box.Border is { } border && box.BorderWidth > 0)
{
using var borderPaint = new SKPaint
{
Color = border,
Style = SKPaintStyle.Stroke,
StrokeWidth = box.BorderWidth,
IsAntialias = true
};
canvas.DrawRoundRect(rect, radius, radius, borderPaint);
}
}
private sealed record BackgroundBox(
SKColor? Fill,
SKColor? Border,
float BorderWidth,
float CornerRadius,
float Padding)
{
public float Inset => Padding + BorderWidth;
}
private RichTextKit.TextBlock BuildTextBlock(string textToRender)
{
var textBlock = new RichTextKit.TextBlock
{
FontMapper = graphicsEngineFonts.Mapper,
Alignment = textElement.Align switch
{
TextAlignment.Center => RichTextKit.TextAlignment.Center,
TextAlignment.Right => RichTextKit.TextAlignment.Right,
TextAlignment.Left => RichTextKit.TextAlignment.Left,
_ => RichTextKit.TextAlignment.Auto
}
};
(Dictionary<string, RichTextKit.Style> styles, RichTextKit.Style baseStyle) = BuildTextStyles();
var lastIndex = 0;
foreach (Match match in StylePattern.Matches(textToRender))
{
// unstyled text before match
if (match.Index > lastIndex)
{
textBlock.AddText(textToRender.AsSpan(lastIndex, match.Index - lastIndex), baseStyle);
}
string styleName = match.Groups[1].Value;
string innerText = match.Groups[2].Value;
if (styles.TryGetValue(styleName, out RichTextKit.Style style))
{
textBlock.AddText(innerText, style);
}
else
{
textBlock.AddText(match.Value, baseStyle);
}
lastIndex = match.Index + match.Length;
}
// unstyled text after match
if (lastIndex < textToRender.Length)
{
textBlock.AddText(textToRender.AsSpan(lastIndex), baseStyle);
}
return textBlock;
}
private (Dictionary<string, RichTextKit.Style>, RichTextKit.Style) BuildTextStyles()
{
var styles = new Dictionary<string, RichTextKit.Style>();
StyleDefinition baseStyleDef = textElement.Styles.Find(s => s.Name == textElement.BaseStyle);
if (baseStyleDef == null)
{
throw new InvalidOperationException(
$"The specified base_style '{textElement.BaseStyle}' was not found in the styles list.");
}
foreach (StyleDefinition s in textElement.Styles)
{
// start with base and merge in additional settings
RichTextKit.Style finalStyle = RichTextStyleFromDef(baseStyleDef);
finalStyle.FontFamily = s.FontFamily ?? finalStyle.FontFamily;
finalStyle.FontItalic = s.FontItalic ?? finalStyle.FontItalic;
finalStyle.FontSize = s.FontSize ?? finalStyle.FontSize;
finalStyle.FontWeight = s.FontWeight ?? finalStyle.FontWeight;
finalStyle.LetterSpacing = s.LetterSpacing ?? finalStyle.LetterSpacing;
finalStyle.LineHeight = s.LineHeight ?? finalStyle.LineHeight;
if (s.TextColor != null && SKColor.TryParse(s.TextColor, out SKColor parsedColor))
{
finalStyle.TextColor = parsedColor;
}
styles[s.Name] = finalStyle;
}
return (styles, RichTextStyleFromDef(baseStyleDef));
RichTextKit.Style RichTextStyleFromDef(StyleDefinition def)
{
var style = new RichTextKit.Style
{
FontFamily = def.FontFamily,
FontItalic = def.FontItalic ?? false,
TextColor = SKColor.TryParse(def.TextColor, out SKColor color) ? color : SKColors.White
};
if (SKColor.TryParse(def.HaloColor, out SKColor parsedHaloColor))
{
style.HaloColor = parsedHaloColor;
}
foreach (float haloWidth in Optional(def.HaloWidth))
{
style.HaloWidth = haloWidth;
}
foreach (float haloBlur in Optional(def.HaloBlur))
{
style.HaloBlur = haloBlur;
}
foreach (float fontSize in Optional(def.FontSize))
{
style.FontSize = fontSize;
}
foreach (int fontWeight in Optional(def.FontWeight))
{
style.FontWeight = fontWeight;
}
foreach (float letterSpacing in Optional(def.LetterSpacing))
{
style.LetterSpacing = letterSpacing;
}
foreach (float lineHeight in Optional(def.LineHeight))
{
style.LineHeight = lineHeight;
}
return style;
}
}
private static void FitTextBlock(RichTextKit.TextBlock block, float maxWidth)
{
if (block.MeasuredWidth <= maxWidth)
{
return;
}
var originalContent = block.StyleRuns
.Select(run => (run.ToString(), run.Style))
.ToList();
float scale = maxWidth / block.MeasuredWidth;
const float MIN_FONT_SIZE = 5.0f;
while (true)
{
block.Clear();
var isAtMinSize = false;
foreach ((string text, RichTextKit.IStyle style) in originalContent)
{
// Carry EVERY visual property across, not just the ones the scale needs. Halo and
// line height were being dropped here, which only mattered once #732 gave the box
// insets that can push a previously-fitting element into the Scale path: adding a
// background would then silently remove the halo it sits behind.
var newStyle = new RichTextKit.Style
{
FontFamily = style.FontFamily,
FontItalic = style.FontItalic,
FontSize = style.FontSize,
FontWidth = style.FontWidth,
FontWeight = style.FontWeight,
LetterSpacing = style.LetterSpacing,
LineHeight = style.LineHeight,
TextColor = style.TextColor,
HaloColor = style.HaloColor,
HaloWidth = style.HaloWidth,
HaloBlur = style.HaloBlur
};
float newSize = newStyle.FontSize * scale;
if (newSize < MIN_FONT_SIZE)
{
newSize = MIN_FONT_SIZE;
isAtMinSize = true;
}
newStyle.FontSize = newSize;
block.AddText(text, newStyle);
}
if (block.MeasuredWidth <= maxWidth)
{
break;
}
if (isAtMinSize)
{
break;
}
scale -= 0.01f;
}
}
[GeneratedRegex(@"\[(\w+)\](.*?)\[/\1\]")]
private static partial Regex StyleRegex();
}