diff --git a/ErsatzTV.Application/Channels/ChannelGraphicsDefaults.cs b/ErsatzTV.Application/Channels/ChannelGraphicsDefaults.cs
new file mode 100644
index 000000000..f9d519e17
--- /dev/null
+++ b/ErsatzTV.Application/Channels/ChannelGraphicsDefaults.cs
@@ -0,0 +1,43 @@
+using ErsatzTV.Core.Domain;
+using ErsatzTV.FFmpeg.State;
+using ErsatzTV.Infrastructure.Data;
+using ErsatzTV.Infrastructure.Streaming.Graphics;
+
+namespace ErsatzTV.Application.Channels;
+
+///
+/// #732: the On Now / Next overlay is a default rather than an opt-in, so every newly created channel
+/// gets the built-in element attached.
+///
+///
+/// This lives in one place because there is more than one channel-creation path and they diverged
+/// once already: CreateChannelHandler had it and CreateChannelFromLineupHandler -- the
+/// SPA's primary "Add Channel" flow, and the one Auto-Tune bulk-creates through -- did not. Any new
+/// site that persists a Channel must call this. The third site, DbInitializer 's default
+/// channel, needs no call: it runs before AttachOnNowNextByDefault in the same startup, so the
+/// backfill covers it.
+///
+public static class ChannelGraphicsDefaults
+{
+ public static async Task Attach(TvContext dbContext, Channel channel, CancellationToken cancellationToken)
+ {
+ // HLS Direct is skipped because ErsatzTV is not transcoding there -- there is no frame
+ // pipeline to draw into, and the editor disables the toggle for the same reason. Identity is
+ // the element's filename, never its user-editable Name (the #67 lesson).
+ if (channel.StreamingMode is StreamingMode.HttpLiveStreamingDirect)
+ {
+ return;
+ }
+
+ Option maybeElementId =
+ await GraphicsElementSeeder.GetBuiltInElementId(dbContext, cancellationToken);
+
+ foreach (int elementId in maybeElementId)
+ {
+ // Add rather than assign: a future create path that carries graphics ids would otherwise
+ // be silently discarded here.
+ channel.ChannelGraphicsElements ??= [];
+ channel.ChannelGraphicsElements.Add(new ChannelGraphicsElement { GraphicsElementId = elementId });
+ }
+ }
+}
diff --git a/ErsatzTV.Application/Channels/Commands/CreateChannelFromLineupHandler.cs b/ErsatzTV.Application/Channels/Commands/CreateChannelFromLineupHandler.cs
index 32228491c..924264e51 100644
--- a/ErsatzTV.Application/Channels/Commands/CreateChannelFromLineupHandler.cs
+++ b/ErsatzTV.Application/Channels/Commands/CreateChannelFromLineupHandler.cs
@@ -85,6 +85,7 @@ public class CreateChannelFromLineupHandler(
await using var transaction = await dbContext.Database.BeginTransactionAsync(cancellationToken);
try
{
+ await ChannelGraphicsDefaults.Attach(dbContext, prepared.Channel, cancellationToken);
dbContext.Channels.Add(prepared.Channel);
if (prepared.Playlist is not null)
{
diff --git a/ErsatzTV.Application/Channels/Commands/CreateChannelHandler.cs b/ErsatzTV.Application/Channels/Commands/CreateChannelHandler.cs
index ea1c58778..d0884f102 100644
--- a/ErsatzTV.Application/Channels/Commands/CreateChannelHandler.cs
+++ b/ErsatzTV.Application/Channels/Commands/CreateChannelHandler.cs
@@ -7,6 +7,7 @@ using ErsatzTV.Core.Domain.Filler;
using ErsatzTV.Core.Interfaces.Images;
using ErsatzTV.Core.Interfaces.Search;
using ErsatzTV.Infrastructure.Data;
+using ErsatzTV.Infrastructure.Streaming.Graphics;
using ErsatzTV.Infrastructure.Extensions;
using Microsoft.EntityFrameworkCore;
using static ErsatzTV.Application.Channels.ChannelValidations;
@@ -35,7 +36,8 @@ public class CreateChannelHandler(
Right: async logoPath =>
{
ApplyResolvedLogo(request, channel, logoPath);
- return Right(await PersistChannel(dbContext, channel));
+ return Right(
+ await PersistChannel(dbContext, channel, cancellationToken));
},
Left: e => Task.FromResult(Left(e)));
},
@@ -75,8 +77,12 @@ public class CreateChannelHandler(
}
}
- private async Task PersistChannel(TvContext dbContext, Channel channel)
+ private async Task PersistChannel(
+ TvContext dbContext,
+ Channel channel,
+ CancellationToken cancellationToken)
{
+ await ChannelGraphicsDefaults.Attach(dbContext, channel, cancellationToken);
await dbContext.Channels.AddAsync(channel);
await dbContext.SaveChangesAsync();
searchTargets.SearchTargetsChanged();
diff --git a/ErsatzTV.Core/Domain/ConfigElementKey.cs b/ErsatzTV.Core/Domain/ConfigElementKey.cs
index d26dd1c50..98aaf6ade 100644
--- a/ErsatzTV.Core/Domain/ConfigElementKey.cs
+++ b/ErsatzTV.Core/Domain/ConfigElementKey.cs
@@ -26,6 +26,9 @@ public class ConfigElementKey
public static ConfigElementKey ChannelTemplatesDefaultTemplateId => new("channel_templates.default_template_id");
public static ConfigElementKey WatermarkChannelBugSeeded => new("watermark.channel_bug_seeded");
public static ConfigElementKey GraphicsOnNowNextSeeded => new("graphics.on_now_next_seeded");
+
+ public static ConfigElementKey GraphicsOnNowNextDefaultAttached =>
+ new("graphics.on_now_next_default_attached");
public static ConfigElementKey FFmpegSegmenterTimeout => new("ffmpeg.segmenter.timeout_seconds");
public static ConfigElementKey FFmpegWorkAheadSegmenters => new("ffmpeg.segmenter.work_ahead_limit");
public static ConfigElementKey FFmpegInitialSegmentCount => new("ffmpeg.segmenter.initial_segment_count");
diff --git a/ErsatzTV.Core/Graphics/GraphicsElementDefaults.cs b/ErsatzTV.Core/Graphics/GraphicsElementDefaults.cs
index cb6917fee..6b5c6f778 100644
--- a/ErsatzTV.Core/Graphics/GraphicsElementDefaults.cs
+++ b/ErsatzTV.Core/Graphics/GraphicsElementDefaults.cs
@@ -4,4 +4,7 @@ public static class GraphicsElementDefaults
{
// Built-in "On Now / Next" text element; identity is by filename, never by user-editable Name.
public const string OnNowNextFileName = "on-now-next.yml";
+
+ // Display name only. Never use it for identity -- that is the filename above (#67 / #74).
+ public const string OnNowNextName = "On Now / Next";
}
diff --git a/ErsatzTV.Core/Graphics/TextGraphicsElement.cs b/ErsatzTV.Core/Graphics/TextGraphicsElement.cs
index 1f4866372..6ff335972 100644
--- a/ErsatzTV.Core/Graphics/TextGraphicsElement.cs
+++ b/ErsatzTV.Core/Graphics/TextGraphicsElement.cs
@@ -31,6 +31,28 @@ public class TextGraphicsElement : BaseGraphicsElement
[YamlMember(Alias = "z_index", ApplyNamingConventions = false)]
public int? ZIndex { get; set; }
+ // Background box (ersatztv#732). Element-level, not per-style: the graphics engine renders one
+ // TextBlock into one bitmap, so a single box behind the whole element is the only shape the
+ // renderer can express. Unset background_color means no FILL; a border_color alone still draws
+ // an outlined box. With neither there is no box and no insets -- the pre-#732 geometry.
+ [YamlMember(Alias = "background_color", ApplyNamingConventions = false)]
+ public string BackgroundColor { get; set; }
+
+ [YamlMember(Alias = "background_opacity_percent", ApplyNamingConventions = false)]
+ public int? BackgroundOpacityPercent { get; set; }
+
+ [YamlMember(Alias = "background_padding", ApplyNamingConventions = false)]
+ public double? BackgroundPadding { get; set; }
+
+ [YamlMember(Alias = "background_corner_radius", ApplyNamingConventions = false)]
+ public double? BackgroundCornerRadius { get; set; }
+
+ [YamlMember(Alias = "border_color", ApplyNamingConventions = false)]
+ public string BorderColor { get; set; }
+
+ [YamlMember(Alias = "border_width", ApplyNamingConventions = false)]
+ public double? BorderWidth { get; set; }
+
public List Styles { get; set; } = [];
[YamlMember(Alias = "base_style", ApplyNamingConventions = false)]
diff --git a/ErsatzTV.Infrastructure/Streaming/Graphics/GraphicsElementSeeder.cs b/ErsatzTV.Infrastructure/Streaming/Graphics/GraphicsElementSeeder.cs
index ea3abee80..98067ebb7 100644
--- a/ErsatzTV.Infrastructure/Streaming/Graphics/GraphicsElementSeeder.cs
+++ b/ErsatzTV.Infrastructure/Streaming/Graphics/GraphicsElementSeeder.cs
@@ -4,12 +4,16 @@ using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Graphics;
using ErsatzTV.Infrastructure.Data;
using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Logging;
namespace ErsatzTV.Infrastructure.Streaming.Graphics;
public static class GraphicsElementSeeder
{
- private const string OnNowNextYaml =
+ // The pre-#732 default, kept verbatim so an installation still carrying it byte-for-byte can
+ // be recognised as unmodified and upgraded. Never edit an entry here -- it is a fingerprint of
+ // what we shipped, not a template. Add a new entry when the current default changes again.
+ private const string OnNowNextYamlV1 =
"""
name: On Now / Next
epg_entries: 2
@@ -51,18 +55,88 @@ public static class GraphicsElementSeeder
{{ if (array.size Epg) > 1 }}[next]NEXT {{ Epg[1].Title }}[/next]{{ end }}
""";
- public static async Task SeedOnNowNext(TvContext context, IFileSystem fileSystem, CancellationToken cancellationToken)
- {
- string seededKey = ConfigElementKey.GraphicsOnNowNextSeeded.Key;
- bool alreadySeeded = await context.ConfigElements.AnyAsync(c => c.Key == seededKey, cancellationToken);
- if (alreadySeeded)
- {
- return;
- }
+ private const string OnNowNextYaml =
+ """
+ name: On Now / Next
+ epg_entries: 2
+ location: BottomLeft
+ horizontal_margin_percent: 4
+ vertical_margin_percent: 8
+ width_percent: 42
+ text_fit: Wrap
+ text_align: Left
+ z_index: 100
+ # transparent until 4s in, fade in 1s, hold 6s, fade out 1s
+ opacity_expression: "LinearFadeDuration(content_seconds, 4, 1, 6)"
+ # #732: a translucent box carries legibility over both bright and dark content. The halo is
+ # cut from 2 to 1 rather than dropped -- the box is translucent, so bright content still
+ # shows through behind the glyphs, but 2px of halo ON TOP of a box over-darkens the text.
+ background_color: "#000000"
+ background_opacity_percent: 65
+ background_padding: 14
+ background_corner_radius: 8
+ # A translucent black box vanishes into dark content, so the box needs an edge of its own.
+ # Low-alpha white reads as a hairline on dark frames without becoming a hard line on bright ones.
+ border_color: "#59FFFFFF"
+ border_width: 1
+ base_style: now
+ styles:
+ - name: now
+ font_family: "Noto Sans"
+ font_size: 30
+ font_weight: 700
+ text_color: "#FFFFFF"
+ halo_color: "#000000"
+ halo_width: 1
+ - name: sub
+ font_family: "Noto Sans"
+ font_size: 22
+ font_weight: 400
+ text_color: "#DDDDDD"
+ halo_color: "#000000"
+ halo_width: 1
+ - name: next
+ font_family: "Noto Sans"
+ font_size: 22
+ font_weight: 400
+ text_color: "#DDDDDD"
+ halo_color: "#000000"
+ halo_width: 1
+ text: |
+ [now]NOW {{ Epg[0].Title }}[/now]
+ {{ if Epg[0].SubTitle }}[sub]{{ Epg[0].SubTitle }}[/sub]{{ end }}
+ {{ if (array.size Epg) > 1 }}[next]NEXT {{ Epg[1].Title }}[/next]{{ end }}
+ """;
+ // Every default we have ever shipped, most recent first. A file matching one of these was
+ // written by us and never touched, so replacing it is an upgrade rather than a clobber.
+ private static readonly string[] SupersededDefaults = [OnNowNextYamlV1];
+
+ public static async Task SeedOnNowNext(
+ TvContext context,
+ IFileSystem fileSystem,
+ ILogger logger,
+ CancellationToken cancellationToken)
+ {
string folder = FileSystemLayout.GraphicsElementsTextTemplatesFolder;
string target = fileSystem.Path.Combine(folder, GraphicsElementDefaults.OnNowNextFileName);
+ string seededKey = ConfigElementKey.GraphicsOnNowNextSeeded.Key;
+ bool alreadySeeded = await context.ConfigElements.AnyAsync(c => c.Key == seededKey, cancellationToken);
+
+ if (alreadySeeded)
+ {
+ // Already-seeded installations never revisit the file, so a change to the default would
+ // otherwise reach new databases only. Upgrade the ones still carrying an untouched
+ // earlier default; anything an operator edited no longer matches and is left alone.
+ //
+ // Deliberately no CreateDirectory on this branch: before #732 it touched the filesystem
+ // not at all, so an already-seeded install stays bootable on a read-only /config.
+ await UpgradeUnmodifiedTemplate(fileSystem, target, logger, cancellationToken);
+ await EnsureBuiltInElementRow(context, fileSystem, target, cancellationToken);
+ return;
+ }
+
if (!fileSystem.Directory.Exists(folder))
{
fileSystem.Directory.CreateDirectory(folder);
@@ -78,5 +152,218 @@ public static class GraphicsElementSeeder
new ConfigElement { Key = seededKey, Value = "true" },
cancellationToken);
await context.SaveChangesAsync(cancellationToken);
+
+ await EnsureBuiltInElementRow(context, fileSystem, target, cancellationToken);
}
+
+ ///
+ /// `RefreshGraphicsElements` is what normally turns a template file into a `GraphicsElement` row,
+ /// but it runs on the scheduler/stream-start path -- long after startup. Creating the row here
+ /// removes that ordering dependency, so `AttachOnNowNextByDefault` below can never mark itself
+ /// done against an element that simply had not been discovered yet.
+ ///
+ private static async Task EnsureBuiltInElementRow(
+ TvContext context,
+ IFileSystem fileSystem,
+ string target,
+ CancellationToken cancellationToken)
+ {
+ if (!fileSystem.File.Exists(target))
+ {
+ return;
+ }
+
+ bool exists = await context.GraphicsElements.AnyAsync(e => e.Path == target, cancellationToken);
+ if (exists)
+ {
+ return;
+ }
+
+ // Name is display-only (identity is the filename), but leaving it null sorts the built-in
+ // element into the unnamed bucket at the bottom of the SPA list until the first refresh.
+ await context.GraphicsElements.AddAsync(
+ new Core.Domain.GraphicsElement
+ {
+ Path = target,
+ Kind = GraphicsElementKind.Text,
+ Name = GraphicsElementDefaults.OnNowNextName
+ },
+ cancellationToken);
+ await context.SaveChangesAsync(cancellationToken);
+ }
+
+ ///
+ /// #732: the On Now / Next overlay is a default, not an opt-in. Existing channels predate that
+ /// decision, so attach the built-in element to them once.
+ ///
+ ///
+ /// The marker is written only once the built-in element RESOLVES, so an install whose row does
+ /// not exist yet is retried on the next startup rather than stranded permanently. Once written,
+ /// no channel is ever re-attached. While still armed the backfill cannot tell a deliberately
+ /// cleared channel from an untouched one -- a single global flag cannot express both
+ /// properties; see graphics.on-now-next-on-by-default for why that trade is made this
+ /// way. Every channel created after the marker gets the element from
+ /// ChannelGraphicsDefaults.Attach instead, which BOTH create paths call.
+ ///
+ public static async Task AttachOnNowNextByDefault(TvContext context, CancellationToken cancellationToken)
+ {
+ string key = ConfigElementKey.GraphicsOnNowNextDefaultAttached.Key;
+ if (await context.ConfigElements.AnyAsync(c => c.Key == key, cancellationToken))
+ {
+ return;
+ }
+
+ Option maybeElementId = await GetBuiltInElementId(context, cancellationToken);
+ if (maybeElementId.IsNone)
+ {
+ // Nothing to attach TO. Writing the marker here would strand every channel permanently
+ // on the one population this exists for, so stay armed and try again next startup.
+ return;
+ }
+
+ foreach (int elementId in maybeElementId)
+ {
+ // HLS Direct has no frame pipeline to draw into, so an attachment there would be inert
+ // while still reading as "on" in the editor.
+ List channelIds = await context.Channels
+ .Where(c => c.StreamingMode != StreamingMode.HttpLiveStreamingDirect)
+ .Where(c => c.ChannelGraphicsElements.All(cge => cge.GraphicsElementId != elementId))
+ .Select(c => c.Id)
+ .ToListAsync(cancellationToken);
+
+ foreach (int channelId in channelIds)
+ {
+ await context.AddAsync(
+ new ChannelGraphicsElement { ChannelId = channelId, GraphicsElementId = elementId },
+ cancellationToken);
+ }
+ }
+
+ await context.ConfigElements.AddAsync(
+ new ConfigElement { Key = key, Value = "true" },
+ cancellationToken);
+ await context.SaveChangesAsync(cancellationToken);
+ }
+
+ ///
+ /// Identity is the filename, never the user-editable Name (the #67 lesson carried into #74).
+ /// The Kind is part of it: the five template folders are separate namespaces, so an unrelated
+ /// image/motion/subtitle/script element may legitimately be named `on-now-next.yml` too, and
+ /// filename alone would hand back whichever row the unordered query happened to return first.
+ ///
+ public static async Task> GetBuiltInElementId(
+ TvContext context,
+ CancellationToken cancellationToken)
+ {
+ List<(int Id, string Path)> candidates = await context.GraphicsElements
+ .Where(e => e.Kind == GraphicsElementKind.Text)
+ .Select(e => new { e.Id, e.Path })
+ .ToListAsync(cancellationToken)
+ .Map(rows => rows.Select(r => (r.Id, r.Path)).ToList());
+
+ var matches = candidates
+ .Where(c => System.IO.Path.GetFileName(c.Path) == GraphicsElementDefaults.OnNowNextFileName)
+ .OrderBy(c => c.Id)
+ .ToList();
+
+ // Lowest id wins if two text templates somehow share the filename, so the choice is stable
+ // across restarts rather than dependent on query order.
+ return matches.Count == 0 ? Option.None : matches[0].Id;
+ }
+
+ private static async Task UpgradeUnmodifiedTemplate(
+ IFileSystem fileSystem,
+ string target,
+ ILogger logger,
+ CancellationToken cancellationToken)
+ {
+ // This runs inside the blocking database-startup path, ahead of DatabaseIsReady(). Before
+ // #732 the already-seeded branch never touched the filesystem at all, so an unreadable or
+ // read-only template is a state that used to boot fine -- it must not become a failure to
+ // start. Cosmetic upgrade, best effort.
+ try
+ {
+ if (!fileSystem.File.Exists(target))
+ {
+ return;
+ }
+
+ string existing = await fileSystem.File.ReadAllTextAsync(target, cancellationToken);
+ if (!SupersededDefaults.Any(d => IsSameTemplate(existing, d)))
+ {
+ return;
+ }
+
+ // Write-then-move, never write in place. WriteAllTextAsync truncates first, so an
+ // interrupted write (disk full, IO fault, cancellation) would leave a partial file that
+ // matches no fingerprint and is therefore never repaired on a later boot -- the overlay
+ // would just be gone, permanently, on every channel carrying it.
+ //
+ // The temp name is random per call. A fixed one is shared by two containers on the same
+ // config volume, where one can truncate it while the other is mid-write and then rename
+ // the partial file over the live template. The process id is NOT good enough here: the
+ // image uses an exec-form ENTRYPOINT, so every container's PID namespace makes this
+ // process 1 and every container computes the same name. A random name also means a temp
+ // left by a crashed earlier boot is never reused. Only ever delete the path this call
+ // created.
+ string temp = $"{target}.{fileSystem.Path.GetRandomFileName()}.upgrade.tmp";
+ try
+ {
+ await fileSystem.File.WriteAllTextAsync(temp, OnNowNextYaml, cancellationToken);
+
+ // Deliberately NO in-place fallback when this throws. rename(2) onto a mountpoint
+ // is EBUSY, so a single-file bind mount of this template will not be upgraded --
+ // accepted, because reaching that case needs a pinned file that is ALSO byte-identical
+ // to a shipped default, and the alternative is reintroducing the truncation this
+ // whole dance exists to prevent, on every IO fault rather than just that one.
+ fileSystem.File.Move(temp, target, true);
+ }
+ finally
+ {
+ // Cleanup must never REPLACE the exception that brought us here. Without this inner
+ // catch, a delete that throws while unwinding a cancellation swaps the
+ // OperationCanceledException for an IOException, which the outer filter then
+ // swallows -- so a real shutdown would be silently downgraded to a warning.
+ try
+ {
+ if (fileSystem.File.Exists(temp))
+ {
+ fileSystem.File.Delete(temp);
+ }
+ }
+ catch (Exception cleanupEx)
+ {
+ logger.LogDebug(cleanupEx, "Could not remove the temporary upgrade file {Path}", temp);
+ }
+ }
+ }
+ // Recoverable filesystem faults only. Catching everything would swallow genuinely fatal
+ // runtime failures (OutOfMemory and friends) and continue booting a compromised process;
+ // letting IO escape would turn a file permission into a restart loop. Cancellation
+ // propagates so shutdown is not swallowed.
+ // OperationCanceledException is deliberately absent from this list so a real shutdown
+ // propagates -- but only a real one: an OCE raised while the token is NOT cancelled is just
+ // another faulty read, and letting it escape is the restart loop this catch exists to stop.
+ catch (Exception ex) when ((ex is IOException
+ or UnauthorizedAccessException
+ or NotSupportedException
+ or System.Security.SecurityException)
+ || (ex is OperationCanceledException
+ && !cancellationToken.IsCancellationRequested))
+ {
+ logger.LogWarning(
+ ex,
+ "Could not upgrade the built-in graphics template at {Path}; leaving it as-is",
+ target);
+ }
+ }
+
+ // Compare on content, ignoring the line endings and trailing whitespace an editor or a volume
+ // mount may rewrite. This is a fingerprint check, not a parse: anything that is not one of our
+ // own shipped defaults must fall through untouched.
+ private static bool IsSameTemplate(string left, string right) =>
+ string.Equals(Normalize(left), Normalize(right), StringComparison.Ordinal);
+
+ private static string Normalize(string value) =>
+ value.Replace("\r\n", "\n", StringComparison.Ordinal).TrimEnd();
}
diff --git a/ErsatzTV.Infrastructure/Streaming/Graphics/Text/TextElement.cs b/ErsatzTV.Infrastructure/Streaming/Graphics/Text/TextElement.cs
index 70ecf9b7c..bf7ba41fe 100644
--- a/ErsatzTV.Infrastructure/Streaming/Graphics/Text/TextElement.cs
+++ b/ErsatzTV.Infrastructure/Streaming/Graphics/Text/TextElement.cs
@@ -14,6 +14,10 @@ public partial class TextElement(
ILogger logger)
: GraphicsElement, IDisposable
{
+ // Far larger than any sane overlay on an 8K frame, and small enough that every downstream
+ // int cast stays well inside range.
+ private const float MaxBoxDimension = 10_000f;
+
private static readonly Regex StylePattern = StyleRegex();
private SKBitmap _image;
private SKPointI _location;
@@ -62,30 +66,96 @@ public partial class TextElement(
}
}
+ BackgroundBox box = BuildBackgroundBox();
+
+
RichTextKit.TextBlock textBlock = BuildTextBlock(textElement.Text);
- if (textElement.WidthPercent.HasValue)
+ // 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);
+
+ // Bound the inset against the FRAME even when there is no width_percent. Sanitize caps
+ // each field individually, but padding and border add up, and without a budget nothing
+ // else clamps them -- a two-field fat-finger would otherwise allocate a bitmap far
+ // larger than the frame it is drawn onto. Pre-#732 no config value could inflate the
+ // bitmap independently of the measured text.
+ int frameInsetCap = Math.Max(0, Math.Min(context.FrameSize.Width, context.FrameSize.Height) / 2);
+ if (insetPixels > frameInsetCap)
+ {
+ logger.LogWarning(
+ "Background padding/border of {Inset}px exceeds the frame; clamping to {Clamped}px",
+ insetPixels,
+ frameInsetCap);
+
+ insetPixels = frameInsetCap;
+ box = box?.ClampedTo(frameInsetCap);
+ }
+
+ // A width_percent of 1e300 makes maxWidth Infinity, and every int cast below it is then
+ // unspecified. Treat a non-finite budget as "no budget", which is what an absent
+ // width_percent already means.
+ if (textElement.WidthPercent.HasValue
+ && float.IsFinite((float)(textElement.WidthPercent.Value / 100.0 * context.FrameSize.Width)))
{
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);
+
+ // Clamp the BOX, not just the bitmap's inset. Shrinking insetPixels alone leaves
+ // DrawBackgroundBox stroking at the original border width, which is centred on a
+ // rect that no longer has room for it -- the stroke then floods the element.
+ insetPixels = maxInset;
+ box = box?.ClampedTo(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 = maxWidth;
+ textBlock.MaxWidth = textMaxWidth;
break;
case TextFit.Scale:
- FitTextBlock(textBlock, maxWidth);
+ FitTextBlock(textBlock, textMaxWidth);
break;
}
}
_image = new SKBitmap(
- (int)Math.Ceiling(textBlock.MeasuredWidth),
- (int)Math.Ceiling(textBlock.MeasuredHeight));
+ (int)Math.Ceiling(textBlock.MeasuredWidth) + (2 * insetPixels),
+ (int)Math.Ceiling(textBlock.MeasuredHeight) + (2 * insetPixels));
using (var canvas = new SKCanvas(_image))
{
canvas.Clear(SKColors.Transparent);
- textBlock.Paint(canvas, new SKPoint(0, 0));
+
+ if (box is not null)
+ {
+ DrawBackgroundBox(canvas, box, _image.Width, _image.Height);
+ }
+
+ textBlock.Paint(canvas, new SKPoint(insetPixels, insetPixels));
}
var horizontalMargin =
@@ -134,6 +204,158 @@ public partial class TextElement(
: new ValueTask>(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.
+ float borderWidth = Sanitize(textElement.BorderWidth ?? 1, "border_width");
+ if (!border.HasValue)
+ {
+ borderWidth = 0;
+ }
+
+ if (!fill.HasValue && borderWidth <= 0)
+ {
+ return null;
+ }
+
+ return new BackgroundBox(
+ fill,
+ border,
+ borderWidth,
+ Sanitize(textElement.BackgroundCornerRadius, "background_corner_radius"),
+ Sanitize(textElement.BackgroundPadding, "background_padding"));
+ }
+
+ // YAML happily yields 1e100 or NaN. Cast to float those become Infinity/NaN, and
+ // (int)Math.Ceiling(Infinity) is an unspecified value -- in practice int.MinValue, which sails
+ // straight past every `> maxInset` clamp and can wrap 2 * inset back to zero. Sanitize at the
+ // boundary so no downstream arithmetic ever sees a non-finite value.
+ private float Sanitize(double? value, string fieldName)
+ {
+ if (value is not { } raw)
+ {
+ return 0f;
+ }
+
+ if (double.IsNaN(raw) || raw < 0)
+ {
+ logger.LogWarning("Ignoring out-of-range {Field} value {Value}", fieldName, raw);
+ return 0f;
+ }
+
+ if (raw > MaxBoxDimension)
+ {
+ logger.LogWarning(
+ "Clamping {Field} value {Value} to {Max}",
+ fieldName,
+ raw,
+ MaxBoxDimension);
+
+ return MaxBoxDimension;
+ }
+
+ return (float)raw;
+ }
+
+ 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;
+
+ // Border first, then whatever is left goes to padding: a border that cannot be drawn inside
+ // the bitmap is worse than a thin one, and padding degrades gracefully to zero.
+ public BackgroundBox ClampedTo(float maxInset)
+ {
+ float borderWidth = Math.Min(BorderWidth, maxInset);
+ float padding = Math.Max(0, maxInset - borderWidth);
+ return this with { BorderWidth = borderWidth, Padding = padding };
+ }
+ }
+
private RichTextKit.TextBlock BuildTextBlock(string textToRender)
{
var textBlock = new RichTextKit.TextBlock
@@ -211,6 +433,17 @@ public partial class TextElement(
finalStyle.TextColor = parsedColor;
}
+ // Halo is per-style in the schema and was being dropped here, so a non-base style's
+ // halo_* silently inherited the base style's. The seeded template only looked correct
+ // because all three of its styles declare the same halo.
+ finalStyle.HaloWidth = s.HaloWidth ?? finalStyle.HaloWidth;
+ finalStyle.HaloBlur = s.HaloBlur ?? finalStyle.HaloBlur;
+
+ if (s.HaloColor != null && SKColor.TryParse(s.HaloColor, out SKColor parsedHalo))
+ {
+ finalStyle.HaloColor = parsedHalo;
+ }
+
styles[s.Name] = finalStyle;
}
@@ -286,6 +519,11 @@ public partial class TextElement(
foreach ((string text, RichTextKit.IStyle style) in originalContent)
{
+ // Carry across every property the YAML schema can set, not just the ones the scale
+ // needs (the rest are RichTextKit defaults we never touch). 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,
@@ -294,7 +532,11 @@ public partial class TextElement(
FontWidth = style.FontWidth,
FontWeight = style.FontWeight,
LetterSpacing = style.LetterSpacing,
- TextColor = style.TextColor
+ LineHeight = style.LineHeight,
+ TextColor = style.TextColor,
+ HaloColor = style.HaloColor,
+ HaloWidth = style.HaloWidth,
+ HaloBlur = style.HaloBlur
};
float newSize = newStyle.FontSize * scale;
diff --git a/ErsatzTV.Tests/Application/Channels/CreateChannelDefaultGraphicsElementTests.cs b/ErsatzTV.Tests/Application/Channels/CreateChannelDefaultGraphicsElementTests.cs
new file mode 100644
index 000000000..1769def48
--- /dev/null
+++ b/ErsatzTV.Tests/Application/Channels/CreateChannelDefaultGraphicsElementTests.cs
@@ -0,0 +1,92 @@
+using ErsatzTV.Application.Channels;
+using ErsatzTV.Core;
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Core.Graphics;
+using ErsatzTV.FFmpeg.State;
+using ErsatzTV.Infrastructure.Data;
+using ErsatzTV.Tests.Support;
+using LanguageExt;
+using Microsoft.EntityFrameworkCore;
+using NUnit.Framework;
+using Shouldly;
+
+namespace ErsatzTV.Tests.Application.Channels;
+
+///
+/// #732: the On Now / Next overlay is a default rather than an opt-in, so a channel created after
+/// that decision gets the built-in element without the operator toggling anything.
+///
+[TestFixture]
+public class CreateChannelDefaultGraphicsElementTests : ChannelHandlerTestBase
+{
+ private CreateChannelHandler MakeHandler() => new(Worker, Db.Factory, SearchTargets, RemoteLogoCacher);
+
+ private async Task SeedBuiltInElement()
+ {
+ await using TvContext context = Db.CreateContext();
+ var element = new GraphicsElement
+ {
+ Path = $"/templates/text/{GraphicsElementDefaults.OnNowNextFileName}",
+ Kind = GraphicsElementKind.Text
+ };
+
+ context.GraphicsElements.Add(element);
+ await context.SaveChangesAsync();
+ return element.Id;
+ }
+
+ private async Task> AttachedElementIds(int channelId)
+ {
+ await using TvContext context = Db.CreateContext();
+ Channel reloaded = await context.Channels
+ .Include(c => c.ChannelGraphicsElements)
+ .SingleAsync(c => c.Id == channelId);
+
+ return reloaded.ChannelGraphicsElements.Select(x => x.GraphicsElementId).ToList();
+ }
+
+ [Test]
+ public async Task Attaches_The_Built_In_Element_To_A_New_Channel()
+ {
+ await SeedFFmpegProfile();
+ int elementId = await SeedBuiltInElement();
+
+ Either result =
+ await MakeHandler().Handle(MakeCreate(), CancellationToken.None);
+
+ result.IsRight.ShouldBeTrue();
+ int channelId = result.RightToSeq().Head().ChannelId;
+
+ (await AttachedElementIds(channelId)).ShouldBe([elementId]);
+ }
+
+ [Test]
+ public async Task Leaves_An_Hls_Direct_Channel_Alone_Because_Nothing_Can_Render_There()
+ {
+ await SeedFFmpegProfile();
+ await SeedBuiltInElement();
+
+ Either result = await MakeHandler().Handle(
+ MakeCreate(streamingMode: StreamingMode.HttpLiveStreamingDirect),
+ CancellationToken.None);
+
+ result.IsRight.ShouldBeTrue();
+ int channelId = result.RightToSeq().Head().ChannelId;
+
+ (await AttachedElementIds(channelId)).ShouldBeEmpty();
+ }
+
+ [Test]
+ public async Task Creates_The_Channel_Even_When_The_Built_In_Element_Does_Not_Exist()
+ {
+ await SeedFFmpegProfile();
+
+ Either result =
+ await MakeHandler().Handle(MakeCreate(), CancellationToken.None);
+
+ result.IsRight.ShouldBeTrue();
+ int channelId = result.RightToSeq().Head().ChannelId;
+
+ (await AttachedElementIds(channelId)).ShouldBeEmpty();
+ }
+}
diff --git a/ErsatzTV.Tests/Application/Channels/CreateChannelFromLineupHandlerTests.cs b/ErsatzTV.Tests/Application/Channels/CreateChannelFromLineupHandlerTests.cs
index cbf8da5c9..706c11ecb 100644
--- a/ErsatzTV.Tests/Application/Channels/CreateChannelFromLineupHandlerTests.cs
+++ b/ErsatzTV.Tests/Application/Channels/CreateChannelFromLineupHandlerTests.cs
@@ -9,9 +9,11 @@ using ErsatzTV.Core.Api.LibraryBrowse;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Domain.Filler;
using ErsatzTV.Core.Errors;
+using ErsatzTV.Core.Graphics;
using ErsatzTV.Core.Interfaces.Images;
using ErsatzTV.Core.Interfaces.Search;
using ErsatzTV.Core.Scheduling;
+using ErsatzTV.FFmpeg.State;
using ErsatzTV.Infrastructure.Data;
using ErsatzTV.Tests.Support;
using LanguageExt;
@@ -964,4 +966,66 @@ public class CreateChannelFromLineupHandlerTests
private static TR RightOf(Either either) =>
either.Match(Left: e => throw new AssertionException($"Expected a Right result, got {e.Value}"), Right: r => r);
+
+ // #732: this is the SPA's primary "Add Channel" flow and the one Auto-Tune bulk-creates through.
+ // It was the channel-creation site the default attach originally missed, so a channel made here
+ // would silently never get the overlay once the one-time backfill marker had landed.
+ [Test]
+ public async Task Should_Attach_The_Built_In_On_Now_Next_Element()
+ {
+ await SeedTemplateDependencies();
+ await SeedTemplate();
+ await SeedMovie(42);
+ int elementId = await SeedBuiltInGraphicsElement();
+
+ Either result =
+ await MakeHandler().Handle(MakeRequest(), CancellationToken.None);
+
+ CreateChannelFromLineupResponseModel response = RightOf(result);
+
+ await using TvContext context = _db.CreateContext();
+ DomainChannel channel = await context.Channels
+ .Include(c => c.ChannelGraphicsElements)
+ .SingleAsync(c => c.Id == response.ChannelId);
+
+ channel.ChannelGraphicsElements.Select(x => x.GraphicsElementId).ShouldBe([elementId]);
+ }
+
+ [Test]
+ public async Task Should_Not_Attach_The_Overlay_To_An_Hls_Direct_Channel()
+ {
+ await SeedTemplateDependencies();
+ await SeedTemplate();
+ await SeedMovie(42);
+ await SeedBuiltInGraphicsElement();
+
+ Either result = await MakeHandler().Handle(
+ MakeRequest(advanced: new CreateChannelFromLineupAdvancedOptions(
+ PlaybackOrder.Shuffle,
+ StreamingMode: StreamingMode.HttpLiveStreamingDirect)),
+ CancellationToken.None);
+
+ CreateChannelFromLineupResponseModel response = RightOf(result);
+
+ await using TvContext context = _db.CreateContext();
+ DomainChannel channel = await context.Channels
+ .Include(c => c.ChannelGraphicsElements)
+ .SingleAsync(c => c.Id == response.ChannelId);
+
+ channel.ChannelGraphicsElements.ShouldBeEmpty();
+ }
+
+ private async Task SeedBuiltInGraphicsElement()
+ {
+ await using TvContext context = _db.CreateContext();
+ var element = new GraphicsElement
+ {
+ Path = $"/templates/text/{GraphicsElementDefaults.OnNowNextFileName}",
+ Kind = GraphicsElementKind.Text
+ };
+
+ context.GraphicsElements.Add(element);
+ await context.SaveChangesAsync();
+ return element.Id;
+ }
}
diff --git a/ErsatzTV.Tests/Infrastructure/Graphics/TextElementBackgroundBoxTests.cs b/ErsatzTV.Tests/Infrastructure/Graphics/TextElementBackgroundBoxTests.cs
new file mode 100644
index 000000000..81c948b54
--- /dev/null
+++ b/ErsatzTV.Tests/Infrastructure/Graphics/TextElementBackgroundBoxTests.cs
@@ -0,0 +1,674 @@
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Core.Graphics;
+using ErsatzTV.Core.Interfaces.Streaming;
+using ErsatzTV.FFmpeg;
+using ErsatzTV.FFmpeg.State;
+using ErsatzTV.Infrastructure.Streaming.Graphics;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
+using NUnit.Framework;
+using Shouldly;
+using LanguageExt;
+using SkiaSharp;
+
+namespace ErsatzTV.Tests.Infrastructure.Graphics;
+
+///
+/// Pixel-level cover for the #732 background box. These assert the RENDERED BITMAP rather than the
+/// parsed model, because every failure mode this feature has is a silent no-op: the YAML parses, the
+/// element initializes, and nothing is drawn. Geometry assertions are all RELATIVE to a no-box
+/// baseline so they do not depend on which typeface the host resolves.
+///
+[TestFixture]
+public class TextElementBackgroundBoxTests
+{
+ private const int FrameWidth = 1920;
+
+ // Derived from the documented rule, not a hardcoded 1080p result: hardcoding it makes correct
+ // production code fail the moment the test frame size changes.
+ private static int FrameInsetCap => Math.Min(FrameWidth, FrameHeight) / 2;
+ private const int FrameHeight = 1080;
+
+ private static TextGraphicsElement BaseElement() =>
+ new()
+ {
+ Name = "test",
+ Location = WatermarkLocation.BottomLeft,
+ BaseStyle = "body",
+ Styles =
+ [
+ new StyleDefinition
+ {
+ Name = "body",
+ // Required: a null font_family makes CustomFontMapper throw on a null dictionary
+ // key, which TextElement swallows into "disable for this content" (the #570 trap).
+ // The family need not resolve -- an unknown one falls back to Skia's default.
+ FontFamily = "Roboto",
+ FontSize = 40,
+ TextColor = "#FFFFFF"
+ }
+ ],
+ Text = "Hello"
+ };
+
+ // TextElement swallows every initialization failure into a logged warning, so a broken render
+ // would otherwise surface as a null bitmap with no explanation. Capture the warning and rethrow.
+ private sealed class ThrowingLogger : ILogger
+ {
+ public IDisposable BeginScope(TState state) where TState : notnull => null!;
+
+ public bool IsEnabled(LogLevel logLevel) => true;
+
+ public void Log(
+ LogLevel logLevel,
+ EventId eventId,
+ TState state,
+ Exception exception,
+ Func formatter)
+ {
+ if (logLevel >= LogLevel.Warning && exception is not null)
+ {
+ throw new InvalidOperationException(formatter(state, exception), exception);
+ }
+ }
+ }
+
+ private static SKBitmap Render(TextGraphicsElement element)
+ {
+ var fonts = new GraphicsEngineFonts(new CustomFontMapper(NullLogger.Instance));
+ var textElement = new TextElement(fonts, element, new ThrowingLogger());
+
+ var context = new GraphicsEngineContext(
+ "1",
+ null,
+ [],
+ new Dictionary(),
+ new Resolution { Width = FrameWidth, Height = FrameHeight },
+ new Resolution { Width = FrameWidth, Height = FrameHeight },
+ new FrameRate("30"),
+ DateTimeOffset.UnixEpoch,
+ DateTimeOffset.UnixEpoch,
+ TimeSpan.Zero,
+ TimeSpan.FromMinutes(1),
+ TimeSpan.FromMinutes(1));
+
+ textElement.InitializeAsync(context, CancellationToken.None).GetAwaiter().GetResult();
+
+ Option maybeImage = textElement
+ .PrepareImage(TimeSpan.Zero, TimeSpan.Zero, TimeSpan.FromMinutes(1), TimeSpan.Zero, CancellationToken.None)
+ .AsTask().GetAwaiter().GetResult();
+
+ PreparedElementImage prepared = maybeImage.IfNone(() => throw new InvalidOperationException(
+ "the element produced no image; initialization failed"));
+
+ return prepared.Image;
+ }
+
+ // The whole suite is meaningless if the host cannot lay out any text at all, so prove the
+ // baseline is non-degenerate rather than letting a 0x0 bitmap pass every relative assertion.
+ [Test]
+ public void Baseline_Renders_A_Non_Empty_Bitmap()
+ {
+ SKBitmap baseline = Render(BaseElement());
+
+ baseline.Width.ShouldBeGreaterThan(0);
+ baseline.Height.ShouldBeGreaterThan(0);
+ }
+
+ [Test]
+ public void No_Background_Fields_Leaves_Corner_Transparent()
+ {
+ SKBitmap baseline = Render(BaseElement());
+
+ baseline.GetPixel(0, 0).Alpha.ShouldBe((byte)0);
+ baseline.GetPixel(baseline.Width - 1, baseline.Height - 1).Alpha.ShouldBe((byte)0);
+ }
+
+ [Test]
+ public void Background_Color_Fills_The_Box()
+ {
+ TextGraphicsElement element = BaseElement();
+ element.BackgroundColor = "#FF0000";
+
+ SKBitmap rendered = Render(element);
+
+ SKColor corner = rendered.GetPixel(0, 0);
+ corner.Alpha.ShouldBe((byte)255);
+ corner.Red.ShouldBe((byte)255);
+ corner.Green.ShouldBe((byte)0);
+ corner.Blue.ShouldBe((byte)0);
+ }
+
+ [Test]
+ public void Background_Padding_Grows_The_Bitmap_On_Every_Side()
+ {
+ const int Padding = 12;
+
+ SKBitmap baseline = Render(BaseElement());
+
+ TextGraphicsElement element = BaseElement();
+ element.BackgroundColor = "#000000";
+ element.BackgroundPadding = Padding;
+
+ SKBitmap padded = Render(element);
+
+ padded.Width.ShouldBe(baseline.Width + (2 * Padding));
+ padded.Height.ShouldBe(baseline.Height + (2 * Padding));
+ }
+
+ // Growing the bitmap is not the same as moving the text into it. If the text were still painted
+ // at (0,0) the geometry assertions above would all still hold while the glyphs sat on the box
+ // edge, so pin the padding band itself as pure background.
+ [Test]
+ public void Background_Padding_Actually_Insets_The_Text()
+ {
+ const int Padding = 16;
+
+ TextGraphicsElement element = BaseElement();
+ element.BackgroundColor = "#FF0000";
+ element.BackgroundPadding = Padding;
+
+ SKBitmap rendered = Render(element);
+
+ // A full-width band inside the top padding must contain nothing but the fill colour.
+ for (var x = 0; x < rendered.Width; x++)
+ {
+ SKColor pixel = rendered.GetPixel(x, Padding / 2);
+ pixel.Red.ShouldBe((byte)255, $"pixel at x={x} in the padding band is not the fill colour");
+ pixel.Green.ShouldBe((byte)0, $"pixel at x={x} in the padding band is not the fill colour");
+ pixel.Blue.ShouldBe((byte)0, $"pixel at x={x} in the padding band is not the fill colour");
+ }
+ }
+
+ [Test]
+ public void Background_Opacity_Percent_Scales_The_Alpha()
+ {
+ TextGraphicsElement element = BaseElement();
+ element.BackgroundColor = "#FF0000";
+ element.BackgroundOpacityPercent = 50;
+
+ SKBitmap rendered = Render(element);
+
+ // 255 * 0.5, rounded. Skia stores premultiplied alpha, so assert the alpha channel only.
+ rendered.GetPixel(0, 0).Alpha.ShouldBe((byte)128);
+ }
+
+ [Test]
+ public void Corner_Radius_Rounds_The_Corner_Away()
+ {
+ TextGraphicsElement element = BaseElement();
+ element.BackgroundColor = "#FF0000";
+ element.BackgroundPadding = 20;
+ element.BackgroundCornerRadius = 20;
+
+ SKBitmap rendered = Render(element);
+
+ // The extreme corner falls outside a 20px radius, the middle of the left edge does not.
+ rendered.GetPixel(0, 0).Alpha.ShouldBe((byte)0);
+ rendered.GetPixel(0, rendered.Height / 2).Alpha.ShouldBe((byte)255);
+ }
+
+ [Test]
+ public void Border_Color_Draws_A_Border_Distinct_From_The_Fill()
+ {
+ TextGraphicsElement element = BaseElement();
+ element.BackgroundColor = "#FF0000";
+ element.BackgroundPadding = 20;
+ element.BorderColor = "#00FF00";
+ element.BorderWidth = 4;
+
+ SKBitmap rendered = Render(element);
+
+ // On the border ring...
+ SKColor edge = rendered.GetPixel(1, rendered.Height / 2);
+ edge.Green.ShouldBeGreaterThan((byte)200);
+ edge.Red.ShouldBeLessThan((byte)100);
+
+ // ...and inside it, still the fill.
+ SKColor inside = rendered.GetPixel(10, rendered.Height / 2);
+ inside.Red.ShouldBe((byte)255);
+ inside.Green.ShouldBe((byte)0);
+ }
+
+ [Test]
+ public void Border_Width_Is_Included_In_The_Bitmap_So_The_Border_Is_Not_Clipped()
+ {
+ const int BorderWidth = 6;
+
+ SKBitmap baseline = Render(BaseElement());
+
+ TextGraphicsElement element = BaseElement();
+ element.BorderColor = "#00FF00";
+ element.BorderWidth = BorderWidth;
+
+ SKBitmap bordered = Render(element);
+
+ bordered.Width.ShouldBe(baseline.Width + (2 * BorderWidth));
+ bordered.Height.ShouldBe(baseline.Height + (2 * BorderWidth));
+ }
+
+ [Test]
+ public void Unparseable_Background_Color_Draws_No_Box_Rather_Than_Substituting_One()
+ {
+ SKBitmap baseline = Render(BaseElement());
+
+ TextGraphicsElement element = BaseElement();
+ element.BackgroundColor = "not-a-color";
+ element.BackgroundPadding = 25;
+
+ SKBitmap rendered = Render(element);
+
+ // No box means no padding either: the geometry is the untouched baseline.
+ rendered.Width.ShouldBe(baseline.Width);
+ rendered.Height.ShouldBe(baseline.Height);
+ rendered.GetPixel(0, 0).Alpha.ShouldBe((byte)0);
+ }
+
+ [Test]
+ public void Border_Color_Without_An_Explicit_Width_Draws_A_Hairline()
+ {
+ SKBitmap baseline = Render(BaseElement());
+
+ TextGraphicsElement element = BaseElement();
+ element.BorderColor = "#00FF00";
+
+ SKBitmap rendered = Render(element);
+
+ rendered.Width.ShouldBe(baseline.Width + 2);
+ rendered.GetPixel(0, rendered.Height / 2).Green.ShouldBeGreaterThan((byte)200);
+ }
+
+ // A box with no padding or border must not move anything: this is the seam where "adding a
+ // background" could silently change an existing overlay's geometry.
+ [Test]
+ public void A_Fill_With_No_Padding_Or_Border_Leaves_The_Geometry_Untouched()
+ {
+ SKBitmap baseline = Render(BaseElement());
+
+ TextGraphicsElement element = BaseElement();
+ element.BackgroundColor = "#FF0000";
+
+ SKBitmap filled = Render(element);
+
+ filled.Width.ShouldBe(baseline.Width);
+ filled.Height.ShouldBe(baseline.Height);
+ }
+
+ // The inset is rounded up to a whole pixel and the SAME integer is used on both sides. Subtracting
+ // the unrounded value from the wrap budget while adding its ceiling to the bitmap overflows
+ // width_percent by a rounding remainder, which an integer padding cannot expose.
+ [Test]
+ public void Fractional_Padding_Still_Respects_Width_Percent()
+ {
+ const double WidthPercent = 20;
+
+ foreach (double padding in new[] { 12.3, 14.0, 29.7, 0.5 })
+ {
+ TextGraphicsElement element = BaseElement();
+ element.Text = "The quick brown fox jumps over the lazy dog and keeps running past the edge";
+ element.Fit = TextFit.Wrap;
+ element.WidthPercent = WidthPercent;
+ element.BackgroundColor = "#000000";
+ element.BackgroundPadding = padding;
+
+ SKBitmap rendered = Render(element);
+
+ var budget = (int)Math.Round(WidthPercent / 100.0 * FrameWidth);
+ rendered.Width.ShouldBeLessThanOrEqualTo(budget, $"padding {padding} overflowed the budget");
+ }
+ }
+
+ // An inset wider than the budget cannot be honoured AND stay inside it, so the INSET is clamped
+ // rather than the text being squeezed to nothing. Asserting a width bound here would be wrong:
+ // wrapping cannot break below one glyph, so a narrow width_percent overflows with or without a
+ // box (pre-existing). What the clamp guarantees is that the box's own contribution stops growing
+ // at the budget -- so a runaway padding renders identically to the largest one that fits.
+ [Test]
+ public void An_Oversized_Padding_Is_Clamped_To_The_Largest_That_Fits()
+ {
+ const double WidthPercent = 20;
+ var budget = (int)Math.Round(WidthPercent / 100.0 * FrameWidth);
+ int maxInset = (budget - 1) / 2;
+
+ static TextGraphicsElement WithPadding(double padding)
+ {
+ TextGraphicsElement element = BaseElement();
+ element.Text = "The quick brown fox jumps over the lazy dog";
+ element.Fit = TextFit.Wrap;
+ element.WidthPercent = WidthPercent;
+ element.BackgroundColor = "#000000";
+ element.BackgroundPadding = padding;
+ return element;
+ }
+
+ SKBitmap runaway = Render(WithPadding(400));
+ SKBitmap clamped = Render(WithPadding(maxInset));
+
+ runaway.Width.ShouldBe(clamped.Width);
+ runaway.Height.ShouldBe(clamped.Height);
+
+ // and the clamp actually bit -- an unclamped 400px padding would add 800px of box
+ runaway.Width.ShouldBeLessThan(budget + (2 * maxInset));
+ }
+
+ // FitTextBlock rebuilds every style from scratch. It used to drop the halo, which only became
+ // reachable once a box's insets could push a previously-fitting element into the Scale path --
+ // adding a background would then silently remove the halo behind the text.
+ [Test]
+ public void The_Scale_Path_Preserves_The_Halo()
+ {
+ static TextGraphicsElement Scaled(bool withHalo)
+ {
+ TextGraphicsElement element = BaseElement();
+ element.Text = "The quick brown fox jumps over the lazy dog";
+ element.Fit = TextFit.Scale;
+ element.WidthPercent = 15;
+ element.BackgroundColor = "#000000";
+ element.BackgroundPadding = 12;
+ element.Styles[0].HaloColor = withHalo ? "#00FF00" : null;
+ element.Styles[0].HaloWidth = withHalo ? 3 : null;
+ return element;
+ }
+
+ SKBitmap withHalo = Render(Scaled(true));
+ SKBitmap withoutHalo = Render(Scaled(false));
+
+ withHalo.Width.ShouldBe(withoutHalo.Width);
+ withHalo.Height.ShouldBe(withoutHalo.Height);
+
+ var differing = 0;
+ for (var x = 0; x < withHalo.Width; x++)
+ {
+ for (var y = 0; y < withHalo.Height; y++)
+ {
+ if (withHalo.GetPixel(x, y) != withoutHalo.GetPixel(x, y))
+ {
+ differing++;
+ }
+ }
+ }
+
+ // If the Scale path dropped the halo, the two renders would be pixel-identical.
+ differing.ShouldBeGreaterThan(0, "the halo made no difference through the Scale path");
+ }
+
+ // width_percent bounds the ELEMENT. If the insets were not subtracted from the wrap width the
+ // box would overflow the budget by 2*inset, which is exactly the bug this pins.
+ [Test]
+ public void Width_Percent_Bounds_The_Whole_Box_Including_Padding()
+ {
+ const double WidthPercent = 20;
+ const int Padding = 30;
+
+ TextGraphicsElement element = BaseElement();
+ element.Text = "The quick brown fox jumps over the lazy dog and keeps on running well past the edge";
+ element.Fit = TextFit.Wrap;
+ element.WidthPercent = WidthPercent;
+ element.BackgroundColor = "#000000";
+ element.BackgroundPadding = Padding;
+
+ SKBitmap rendered = Render(element);
+
+ var budget = (int)Math.Round(WidthPercent / 100.0 * FrameWidth);
+ rendered.Width.ShouldBeLessThanOrEqualTo(budget);
+ }
+
+ // YAML yields doubles, so 1e100 and NaN are reachable from a config file. Cast to float they
+ // become Infinity/NaN, and (int)Math.Ceiling of those is an unspecified value that sails past
+ // every clamp and can wrap the doubled inset back to zero.
+ [Test]
+ public void Non_Finite_And_Absurd_Box_Values_Do_Not_Corrupt_The_Geometry()
+ {
+ SKBitmap baseline = Render(BaseElement());
+
+ foreach (double bad in new[] { 1e100, double.NaN, double.PositiveInfinity, -5.0 })
+ {
+ TextGraphicsElement element = BaseElement();
+ element.BackgroundColor = "#FF0000";
+ element.BackgroundPadding = bad;
+
+ SKBitmap rendered = Render(element);
+
+ rendered.Width.ShouldBeGreaterThan(0, $"padding {bad} produced a degenerate width");
+ rendered.Height.ShouldBeGreaterThan(0, $"padding {bad} produced a degenerate height");
+ rendered.Width.ShouldBeGreaterThanOrEqualTo(baseline.Width, $"padding {bad} shrank the element");
+ rendered.Width.ShouldBeLessThanOrEqualTo(baseline.Width + (2 * FrameInsetCap), $"padding {bad} was not clamped");
+ }
+ }
+
+ [Test]
+ public void A_Non_Finite_Width_Percent_Is_Treated_As_No_Budget()
+ {
+ SKBitmap baseline = Render(BaseElement());
+
+ // This pins the OUTCOME -- a non-finite budget behaves like no budget -- not the
+ // float.IsFinite guard, which no mutation can distinguish because .NET saturates float-to-int
+ // conversion. See the "Not covered by any mutation" note in docs/graphics-elements.md.
+ const int Padding = 10;
+
+ TextGraphicsElement element = BaseElement();
+ element.Fit = TextFit.Wrap;
+ element.WidthPercent = 1e300;
+ element.BackgroundColor = "#FF0000";
+ element.BackgroundPadding = Padding;
+
+ SKBitmap rendered = Render(element);
+
+ rendered.Width.ShouldBe(baseline.Width + (2 * Padding));
+ rendered.Height.ShouldBe(baseline.Height + (2 * Padding));
+ }
+
+ // Clamping insetPixels alone leaves DrawBackgroundBox stroking at the ORIGINAL border width,
+ // centred on a rect that no longer has room for it -- the stroke then floods the whole element
+ // and paints over the interior. The box's own fields must be clamped too.
+ [Test]
+ public void An_Oversized_Border_Is_Clamped_And_Does_Not_Flood_The_Element()
+ {
+ TextGraphicsElement element = BaseElement();
+ element.Text = "The quick brown fox jumps over the lazy dog";
+ element.Fit = TextFit.Wrap;
+ element.WidthPercent = 20;
+ element.BackgroundColor = "#0000FF";
+ element.BorderColor = "#FF0000";
+ element.BorderWidth = 400;
+
+ SKBitmap rendered = Render(element);
+
+ // Somewhere inside the element there must still be fill, not solid border.
+ var fillPixels = 0;
+ for (var x = 0; x < rendered.Width; x++)
+ {
+ for (var y = 0; y < rendered.Height; y++)
+ {
+ SKColor px = rendered.GetPixel(x, y);
+ if (px.Blue > 200 && px.Red < 100)
+ {
+ fillPixels++;
+ }
+ }
+ }
+
+ fillPixels.ShouldBeGreaterThan(0, "the border flooded the element; no fill survived");
+ }
+
+ // Sanitize bounds each field on its own, but padding and border ADD UP, and with no
+ // width_percent nothing else bounded them -- two fields could allocate a bitmap far larger than
+ // the frame it is drawn onto. This pins the frame cap itself; the non-finite test above cannot,
+ // because its bound is looser than the growth this clause prevents.
+ [Test]
+ public void The_Inset_Is_Capped_Against_The_Frame_Even_With_No_Width_Percent()
+ {
+ SKBitmap baseline = Render(BaseElement());
+
+ TextGraphicsElement element = BaseElement();
+ element.BackgroundColor = "#FF0000";
+ element.BackgroundPadding = 4000;
+ element.BorderColor = "#00FF00";
+ element.BorderWidth = 4000;
+
+ SKBitmap rendered = Render(element);
+
+ // 8000px of requested inset collapses to the frame cap, not to 16000px of bitmap growth.
+ rendered.Width.ShouldBe(baseline.Width + (2 * FrameInsetCap));
+ rendered.Height.ShouldBe(baseline.Height + (2 * FrameInsetCap));
+ }
+
+ // halo_* is documented as a per-style field. The merge loop used to rebuild each style from the
+ // base and then override only font/colour, so a non-base style's halo silently inherited the
+ // base one -- invisible in the seeded template, whose three styles declare identical halos.
+ [Test]
+ public void A_Non_Base_Style_Uses_Its_Own_Halo_Not_The_Base_Styles()
+ {
+ static TextGraphicsElement WithSubHalo(float haloWidth)
+ {
+ TextGraphicsElement element = BaseElement();
+ element.Styles.Add(new StyleDefinition
+ {
+ Name = "sub",
+ FontFamily = "Roboto",
+ FontSize = 40,
+ TextColor = "#FFFFFF",
+ HaloColor = "#00FF00",
+ HaloWidth = haloWidth
+ });
+ element.Text = "[sub]Hello[/sub]";
+ return element;
+ }
+
+ SKBitmap thin = Render(WithSubHalo(1));
+ SKBitmap thick = Render(WithSubHalo(6));
+
+ static int HaloPixels(SKBitmap b)
+ {
+ var n = 0;
+ for (var x = 0; x < b.Width; x++)
+ {
+ for (var y = 0; y < b.Height; y++)
+ {
+ SKColor px = b.GetPixel(x, y);
+ if (px.Green > 150 && px.Red < 120)
+ {
+ n++;
+ }
+ }
+ }
+
+ return n;
+ }
+
+ // If the style's own halo were ignored, both renders would use the base style's (none) and
+ // neither would contain halo pixels.
+ HaloPixels(thin).ShouldBeGreaterThan(0, "the style's own halo was not applied");
+ HaloPixels(thick).ShouldBeGreaterThan(HaloPixels(thin), "halo_width had no effect per style");
+ }
+
+ private static int PixelsMatching(SKBitmap b, Func predicate)
+ {
+ var n = 0;
+ for (var x = 0; x < b.Width; x++)
+ {
+ for (var y = 0; y < b.Height; y++)
+ {
+ if (predicate(b.GetPixel(x, y)))
+ {
+ n++;
+ }
+ }
+ }
+
+ return n;
+ }
+
+ // halo_blur is a per-style field too, and the merge loop drops it just as silently as halo_color
+ // did. Blur spreads the halo over more pixels at lower alpha, so a blurred halo covers more area.
+ [Test]
+ public void A_Non_Base_Style_Uses_Its_Own_Halo_Blur()
+ {
+ static TextGraphicsElement WithSubBlur(float blur)
+ {
+ TextGraphicsElement element = BaseElement();
+ element.Styles.Add(new StyleDefinition
+ {
+ Name = "sub",
+ FontFamily = "Roboto",
+ FontSize = 40,
+ TextColor = "#FFFFFF",
+ HaloColor = "#00FF00",
+ HaloWidth = 3,
+ HaloBlur = blur
+ });
+ element.Text = "[sub]Hello[/sub]";
+ return element;
+ }
+
+ SKBitmap sharp = Render(WithSubBlur(0));
+ SKBitmap blurred = Render(WithSubBlur(5));
+
+ static bool Greenish(SKColor px) => px.Green > 60 && px.Red < 140 && px.Alpha > 0;
+
+ PixelsMatching(blurred, Greenish)
+ .ShouldNotBe(PixelsMatching(sharp, Greenish), "halo_blur had no effect per style");
+ }
+
+ // FitTextBlock rebuilds every style from scratch on the Scale path. line_height and halo_blur are
+ // carried across there; without them a scaled element silently loses line spacing and halo blur.
+ [Test]
+ public void The_Scale_Path_Preserves_Line_Height()
+ {
+ static TextGraphicsElement Scaled(float lineHeight)
+ {
+ TextGraphicsElement element = BaseElement();
+ element.Text = "The quick brown fox jumps over the lazy dog";
+ element.Fit = TextFit.Scale;
+ element.WidthPercent = 15;
+ element.Styles[0].LineHeight = lineHeight;
+ return element;
+ }
+
+ SKBitmap tight = Render(Scaled(1.0f));
+ SKBitmap loose = Render(Scaled(2.5f));
+
+ loose.Height.ShouldBeGreaterThan(tight.Height, "line_height was dropped by the Scale path");
+ }
+
+ [Test]
+ public void The_Scale_Path_Preserves_Halo_Blur()
+ {
+ static TextGraphicsElement Scaled(float blur)
+ {
+ TextGraphicsElement element = BaseElement();
+ element.Text = "The quick brown fox jumps over the lazy dog";
+ element.Fit = TextFit.Scale;
+ element.WidthPercent = 15;
+ element.Styles[0].HaloColor = "#00FF00";
+ element.Styles[0].HaloWidth = 3;
+ element.Styles[0].HaloBlur = blur;
+ return element;
+ }
+
+ SKBitmap sharp = Render(Scaled(0));
+ SKBitmap blurred = Render(Scaled(5));
+
+ static bool Greenish(SKColor px) => px.Green > 60 && px.Red < 140 && px.Alpha > 0;
+
+ PixelsMatching(blurred, Greenish)
+ .ShouldNotBe(PixelsMatching(sharp, Greenish), "halo_blur was dropped by the Scale path");
+ }
+
+ // The documented range is 0-100. The sole opacity test used 50, so Math.Clamp could be removed
+ // with everything green while an out-of-range value wrapped to an unrelated alpha.
+ [Test]
+ public void Background_Opacity_Percent_Is_Clamped_To_Its_Documented_Range()
+ {
+ static SKColor CornerAt(int percent)
+ {
+ TextGraphicsElement element = BaseElement();
+ element.BackgroundColor = "#FF0000";
+ element.BackgroundOpacityPercent = percent;
+ return Render(element).GetPixel(0, 0);
+ }
+
+ CornerAt(-50).Alpha.ShouldBe((byte)0, "a negative opacity did not clamp to 0");
+ CornerAt(400).Alpha.ShouldBe((byte)255, "an opacity over 100 did not clamp to 100");
+ }
+}
diff --git a/ErsatzTV.Tests/Infrastructure/GraphicsElementDefaultAttachTests.cs b/ErsatzTV.Tests/Infrastructure/GraphicsElementDefaultAttachTests.cs
new file mode 100644
index 000000000..f06c129bf
--- /dev/null
+++ b/ErsatzTV.Tests/Infrastructure/GraphicsElementDefaultAttachTests.cs
@@ -0,0 +1,288 @@
+using ErsatzTV.Core.Domain;
+using GraphicsElement = ErsatzTV.Core.Domain.GraphicsElement;
+using ErsatzTV.Core.Graphics;
+using ErsatzTV.FFmpeg.State;
+using ErsatzTV.Infrastructure.Data;
+using ErsatzTV.Infrastructure.Streaming.Graphics;
+using ErsatzTV.Tests.Support;
+using Microsoft.EntityFrameworkCore;
+using System.IO.Abstractions;
+using Microsoft.Extensions.Logging.Abstractions;
+using Testably.Abstractions.Testing;
+using ErsatzTV.Core;
+using NUnit.Framework;
+using Shouldly;
+
+namespace ErsatzTV.Tests.Infrastructure;
+
+///
+/// #732 part 2: the On Now / Next overlay is a default rather than an opt-in. Channels that predate
+/// that decision are backfilled once -- and only once, so a channel an operator deliberately clears
+/// is never silently re-attached on the next restart.
+///
+[TestFixture]
+public class GraphicsElementDefaultAttachTests
+{
+ private InMemoryTvContext _db = null!;
+
+ [SetUp]
+ public async Task SetUp() => _db = await InMemoryTvContext.CreateAsync();
+
+ [TearDown]
+ public async Task TearDown() => await _db.DisposeAsync();
+
+ private static async Task SeedBuiltInElement(TvContext context)
+ {
+ var element = new GraphicsElement
+ {
+ Path = $"/templates/text/{GraphicsElementDefaults.OnNowNextFileName}",
+ Name = "On Now / Next",
+ Kind = GraphicsElementKind.Text
+ };
+
+ await context.GraphicsElements.AddAsync(element);
+ await context.SaveChangesAsync();
+ return element.Id;
+ }
+
+ private static async Task SeedChannel(
+ TvContext context,
+ string number,
+ StreamingMode mode = StreamingMode.HttpLiveStreamingSegmenter)
+ {
+ var channel = new Channel(Guid.NewGuid())
+ {
+ Name = $"Channel {number}",
+ Number = number,
+ StreamingMode = mode,
+ ChannelGraphicsElements = []
+ };
+
+ await context.Channels.AddAsync(channel);
+ await context.SaveChangesAsync();
+ return channel;
+ }
+
+ private static async Task> AttachedElementIds(TvContext context, int channelId) =>
+ await context.Set()
+ .AsNoTracking()
+ .Where(cge => cge.ChannelId == channelId)
+ .Select(cge => cge.GraphicsElementId)
+ .ToListAsync();
+
+ [Test]
+ public async Task Attaches_The_Built_In_Element_To_Existing_Channels()
+ {
+ await using TvContext context = _db.CreateContext();
+ int elementId = await SeedBuiltInElement(context);
+ Channel one = await SeedChannel(context, "1");
+ Channel two = await SeedChannel(context, "2");
+
+ await GraphicsElementSeeder.AttachOnNowNextByDefault(context, CancellationToken.None);
+
+ (await AttachedElementIds(context, one.Id)).ShouldBe([elementId]);
+ (await AttachedElementIds(context, two.Id)).ShouldBe([elementId]);
+ }
+
+ [Test]
+ public async Task Skips_Hls_Direct_Channels_Where_The_Overlay_Cannot_Render()
+ {
+ await using TvContext context = _db.CreateContext();
+ await SeedBuiltInElement(context);
+ Channel direct = await SeedChannel(context, "1", StreamingMode.HttpLiveStreamingDirect);
+
+ await GraphicsElementSeeder.AttachOnNowNextByDefault(context, CancellationToken.None);
+
+ (await AttachedElementIds(context, direct.Id)).ShouldBeEmpty();
+ }
+
+ [Test]
+ public async Task Does_Not_Duplicate_An_Existing_Attachment()
+ {
+ await using TvContext context = _db.CreateContext();
+ int elementId = await SeedBuiltInElement(context);
+ Channel channel = await SeedChannel(context, "1");
+
+ await context.AddAsync(
+ new ChannelGraphicsElement { ChannelId = channel.Id, GraphicsElementId = elementId });
+ await context.SaveChangesAsync();
+
+ await GraphicsElementSeeder.AttachOnNowNextByDefault(context, CancellationToken.None);
+
+ (await AttachedElementIds(context, channel.Id)).Count.ShouldBe(1);
+ }
+
+ // The load-bearing property: a default must not fight the operator.
+ [Test]
+ public async Task Does_Not_Re_Attach_After_An_Operator_Clears_It()
+ {
+ await using TvContext context = _db.CreateContext();
+ await SeedBuiltInElement(context);
+ Channel channel = await SeedChannel(context, "1");
+
+ await GraphicsElementSeeder.AttachOnNowNextByDefault(context, CancellationToken.None);
+ (await AttachedElementIds(context, channel.Id)).Count.ShouldBe(1);
+
+ // operator turns the overlay off for this channel
+ context.Set()
+ .RemoveRange(context.Set().Where(cge => cge.ChannelId == channel.Id));
+ await context.SaveChangesAsync();
+
+ // ...and the app restarts
+ await GraphicsElementSeeder.AttachOnNowNextByDefault(context, CancellationToken.None);
+
+ (await AttachedElementIds(context, channel.Id)).ShouldBeEmpty();
+ }
+
+ // The upgrade population this backfill exists for -- an install seeding the template for the
+ // first time on this boot -- must not be stranded. The GraphicsElement row is normally created
+ // by RefreshGraphicsElements, which runs long after startup, so the seeder ensures it itself.
+ // Without that, the marker would be written against an unresolved element and every pre-existing
+ // channel would go permanently unattached.
+ [Test]
+ public async Task Backfills_On_The_Same_Boot_That_First_Seeds_The_Template()
+ {
+ var fs = new MockFileSystem();
+ await using TvContext context = _db.CreateContext();
+ Channel channel = await SeedChannel(context, "1");
+
+ // no ConfigElement markers and no GraphicsElement row: a pre-#74 install meeting #732
+ await GraphicsElementSeeder.SeedOnNowNext(context, fs, NullLogger.Instance, CancellationToken.None);
+ await GraphicsElementSeeder.AttachOnNowNextByDefault(context, CancellationToken.None);
+
+ (await AttachedElementIds(context, channel.Id)).Count.ShouldBe(1);
+ }
+
+ // Filename alone is ambiguous: the five template folders are separate namespaces, so an element
+ // of another kind may legitimately carry the same filename.
+ [Test]
+ public async Task Ignores_A_Same_Named_Element_Of_A_Different_Kind()
+ {
+ await using TvContext context = _db.CreateContext();
+ await context.GraphicsElements.AddAsync(
+ new GraphicsElement
+ {
+ Path = $"/templates/image/{GraphicsElementDefaults.OnNowNextFileName}",
+ Kind = GraphicsElementKind.Image
+ });
+ await context.SaveChangesAsync();
+
+ Channel channel = await SeedChannel(context, "1");
+
+ await GraphicsElementSeeder.AttachOnNowNextByDefault(context, CancellationToken.None);
+
+ (await AttachedElementIds(context, channel.Id)).ShouldBeEmpty();
+ }
+
+ [Test]
+ public async Task Ignores_A_Non_Built_In_Element_With_A_Different_Filename()
+ {
+ await using TvContext context = _db.CreateContext();
+ await context.GraphicsElements.AddAsync(
+ new GraphicsElement { Path = "/templates/text/something-else.yml", Kind = GraphicsElementKind.Text });
+ await context.SaveChangesAsync();
+
+ Channel channel = await SeedChannel(context, "1");
+
+ await GraphicsElementSeeder.AttachOnNowNextByDefault(context, CancellationToken.None);
+
+ (await AttachedElementIds(context, channel.Id)).ShouldBeEmpty();
+ }
+
+ // The marker is permanent, so writing it with nothing resolved would strand every channel. Stay
+ // armed instead and pick the work up once the element exists.
+ [Test]
+ public async Task Stays_Armed_When_There_Is_No_Built_In_Element_To_Attach()
+ {
+ await using TvContext context = _db.CreateContext();
+ Channel channel = await SeedChannel(context, "1");
+
+ await GraphicsElementSeeder.AttachOnNowNextByDefault(context, CancellationToken.None);
+
+ (await context.ConfigElements
+ .AnyAsync(c => c.Key == ConfigElementKey.GraphicsOnNowNextDefaultAttached.Key))
+ .ShouldBeFalse("the marker was written with nothing to attach");
+
+ // the element turns up later; the backfill must still do its job
+ await SeedBuiltInElement(context);
+ await GraphicsElementSeeder.AttachOnNowNextByDefault(context, CancellationToken.None);
+
+ (await AttachedElementIds(context, channel.Id)).Count.ShouldBe(1);
+ }
+
+ // The already-seeded branch of SeedOnNowNext has its own EnsureBuiltInElementRow call. Removing
+ // it reddened nothing until this test existed -- the other tests all exercise a FRESH seed.
+ [Test]
+ public async Task An_Already_Seeded_Install_Missing_Its_Element_Row_Gets_One()
+ {
+ var fs = new MockFileSystem();
+ fs.Directory.CreateDirectory(FileSystemLayout.GraphicsElementsTextTemplatesFolder);
+ string target = Path.Combine(
+ FileSystemLayout.GraphicsElementsTextTemplatesFolder,
+ GraphicsElementDefaults.OnNowNextFileName);
+ await fs.File.WriteAllTextAsync(target, "name: On Now / Next\n");
+
+ await using TvContext context = _db.CreateContext();
+ context.ConfigElements.Add(
+ new ConfigElement { Key = ConfigElementKey.GraphicsOnNowNextSeeded.Key, Value = "true" });
+ await context.SaveChangesAsync();
+
+ (await context.GraphicsElements.CountAsync()).ShouldBe(0);
+
+ await GraphicsElementSeeder.SeedOnNowNext(context, fs, NullLogger.Instance, CancellationToken.None);
+
+ // Assert the ROW, not just that one exists: a lookup-only assertion is satisfied by a row
+ // with a null Name, which sorts the built-in element into the unnamed bucket in the SPA.
+ List rows = await context.GraphicsElements.ToListAsync();
+ rows.Count.ShouldBe(1);
+ rows[0].Path.ShouldBe(target);
+ rows[0].Kind.ShouldBe(GraphicsElementKind.Text);
+ rows[0].Name.ShouldBe(GraphicsElementDefaults.OnNowNextName);
+
+ (await GraphicsElementSeeder.GetBuiltInElementId(context, CancellationToken.None)).IsSome.ShouldBeTrue();
+ }
+
+ // The armed path is a real, reachable state: an operator deletes the template, refresh reaps the
+ // row, and the backfill then has nothing to resolve. Pin what happens when the element comes
+ // back -- a single global marker cannot both avoid stranding and avoid re-adding, and this is
+ // the half we accept. See graphics.on-now-next-on-by-default.
+ [Test]
+ public async Task While_Armed_A_Restored_Element_Is_Attached_To_Every_Eligible_Channel()
+ {
+ await using TvContext context = _db.CreateContext();
+ Channel kept = await SeedChannel(context, "1");
+ Channel cleared = await SeedChannel(context, "2");
+
+ // nothing to resolve yet -> stays armed, no marker
+ await GraphicsElementSeeder.AttachOnNowNextByDefault(context, CancellationToken.None);
+ (await context.ConfigElements
+ .AnyAsync(c => c.Key == ConfigElementKey.GraphicsOnNowNextDefaultAttached.Key))
+ .ShouldBeFalse();
+
+ // The element reappears and is attached to BOTH channels; the operator then clears `cleared`.
+ // Doing the attach-then-remove for real matters: seeding `cleared` with no join at all would
+ // only prove an untouched channel gets backfilled, which is not the claim.
+ int elementId = await SeedBuiltInElement(context);
+ await context.AddAsync(new ChannelGraphicsElement { ChannelId = kept.Id, GraphicsElementId = elementId });
+ await context.AddAsync(new ChannelGraphicsElement { ChannelId = cleared.Id, GraphicsElementId = elementId });
+ await context.SaveChangesAsync();
+
+ (await AttachedElementIds(context, cleared.Id)).Count.ShouldBe(1);
+
+ context.Set()
+ .RemoveRange(context.Set().Where(cge => cge.ChannelId == cleared.Id));
+ await context.SaveChangesAsync();
+ (await AttachedElementIds(context, cleared.Id)).ShouldBeEmpty();
+
+ await GraphicsElementSeeder.AttachOnNowNextByDefault(context, CancellationToken.None);
+
+ // documented consequence: the still-armed backfill cannot see that deliberate clear
+ (await AttachedElementIds(context, kept.Id)).Count.ShouldBe(1);
+ (await AttachedElementIds(context, cleared.Id)).Count.ShouldBe(1);
+
+ // ...but it is now marked, so it never fires again
+ (await context.ConfigElements
+ .AnyAsync(c => c.Key == ConfigElementKey.GraphicsOnNowNextDefaultAttached.Key))
+ .ShouldBeTrue();
+ }
+}
diff --git a/ErsatzTV.Tests/Infrastructure/GraphicsElementSeederTests.cs b/ErsatzTV.Tests/Infrastructure/GraphicsElementSeederTests.cs
index fb6adb616..a163b57ac 100644
--- a/ErsatzTV.Tests/Infrastructure/GraphicsElementSeederTests.cs
+++ b/ErsatzTV.Tests/Infrastructure/GraphicsElementSeederTests.cs
@@ -6,6 +6,7 @@ using ErsatzTV.Infrastructure.Data;
using ErsatzTV.Infrastructure.Streaming.Graphics;
using ErsatzTV.Tests.Support;
using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Logging.Abstractions;
using NUnit.Framework;
using Shouldly;
using YamlDotNet.Serialization;
@@ -36,7 +37,7 @@ public class GraphicsElementSeederTests
var fs = new MockFileSystem();
await using TvContext context = _db.CreateContext();
- await GraphicsElementSeeder.SeedOnNowNext(context, fs, CancellationToken.None);
+ await GraphicsElementSeeder.SeedOnNowNext(context, fs, NullLogger.Instance, CancellationToken.None);
fs.File.Exists(_seededPath).ShouldBeTrue();
fs.File.ReadAllText(_seededPath).ShouldContain("epg_entries: 2");
@@ -51,7 +52,7 @@ public class GraphicsElementSeederTests
await fs.File.WriteAllTextAsync(_seededPath, "name: Operator Custom\nepg_entries: 2\n");
await using TvContext context = _db.CreateContext();
- await GraphicsElementSeeder.SeedOnNowNext(context, fs, CancellationToken.None);
+ await GraphicsElementSeeder.SeedOnNowNext(context, fs, NullLogger.Instance, CancellationToken.None);
fs.File.ReadAllText(_seededPath).ShouldContain("Operator Custom");
}
@@ -62,9 +63,9 @@ public class GraphicsElementSeederTests
var fs = new MockFileSystem();
await using TvContext context = _db.CreateContext();
- await GraphicsElementSeeder.SeedOnNowNext(context, fs, CancellationToken.None);
+ await GraphicsElementSeeder.SeedOnNowNext(context, fs, NullLogger.Instance, CancellationToken.None);
fs.File.Delete(_seededPath);
- await GraphicsElementSeeder.SeedOnNowNext(context, fs, CancellationToken.None);
+ await GraphicsElementSeeder.SeedOnNowNext(context, fs, NullLogger.Instance, CancellationToken.None);
fs.File.Exists(_seededPath).ShouldBeFalse();
}
@@ -77,7 +78,7 @@ public class GraphicsElementSeederTests
{
var fs = new MockFileSystem();
await using TvContext context = _db.CreateContext();
- await GraphicsElementSeeder.SeedOnNowNext(context, fs, CancellationToken.None);
+ await GraphicsElementSeeder.SeedOnNowNext(context, fs, NullLogger.Instance, CancellationToken.None);
string yaml = await fs.File.ReadAllTextAsync(_seededPath);
IDeserializer deserializer = new DeserializerBuilder()
diff --git a/ErsatzTV.Tests/Infrastructure/GraphicsElementSeederUpgradeTests.cs b/ErsatzTV.Tests/Infrastructure/GraphicsElementSeederUpgradeTests.cs
new file mode 100644
index 000000000..8f0d9b63c
--- /dev/null
+++ b/ErsatzTV.Tests/Infrastructure/GraphicsElementSeederUpgradeTests.cs
@@ -0,0 +1,365 @@
+using System.IO.Abstractions;
+using ErsatzTV.Core;
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Core.Graphics;
+using ErsatzTV.Infrastructure.Data;
+using ErsatzTV.Infrastructure.Streaming.Graphics;
+using ErsatzTV.Tests.Support;
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.EntityFrameworkCore;
+using NUnit.Framework;
+using Shouldly;
+using Testably.Abstractions.Testing;
+using Testably.Abstractions.Testing.FileSystem;
+using YamlDotNet.Serialization;
+using YamlDotNet.Serialization.NamingConventions;
+
+namespace ErsatzTV.Tests.Infrastructure;
+
+///
+/// #732: the seeder writes the On Now / Next template once and never revisits it, so a change to the
+/// shipped default would reach new databases only. These pin the upgrade path that fixes that, and
+/// the boundary that keeps it from clobbering an operator's edits.
+///
+[TestFixture]
+public class GraphicsElementSeederUpgradeTests
+{
+ // Byte-for-byte the default shipped before #732. Verified 2026-08-26 against the live prod
+ // install at 192.168.1.29 (md5 ef9afc088cf6dba252f725babbf3334f), so this is a real
+ // fingerprint rather than a copy of the constant it is meant to detect.
+ private const string OnNowNextYamlV1 =
+ """
+ name: On Now / Next
+ epg_entries: 2
+ location: BottomLeft
+ horizontal_margin_percent: 4
+ vertical_margin_percent: 8
+ width_percent: 42
+ text_fit: Wrap
+ text_align: Left
+ z_index: 100
+ # transparent until 4s in, fade in 1s, hold 6s, fade out 1s
+ opacity_expression: "LinearFadeDuration(content_seconds, 4, 1, 6)"
+ base_style: now
+ styles:
+ - name: now
+ font_family: "Noto Sans"
+ font_size: 30
+ font_weight: 700
+ text_color: "#FFFFFF"
+ halo_color: "#000000"
+ halo_width: 2
+ - name: sub
+ font_family: "Noto Sans"
+ font_size: 22
+ font_weight: 400
+ text_color: "#DDDDDD"
+ halo_color: "#000000"
+ halo_width: 2
+ - name: next
+ font_family: "Noto Sans"
+ font_size: 22
+ font_weight: 400
+ text_color: "#DDDDDD"
+ halo_color: "#000000"
+ halo_width: 2
+ text: |
+ [now]NOW {{ Epg[0].Title }}[/now]
+ {{ if Epg[0].SubTitle }}[sub]{{ Epg[0].SubTitle }}[/sub]{{ end }}
+ {{ if (array.size Epg) > 1 }}[next]NEXT {{ Epg[1].Title }}[/next]{{ end }}
+ """;
+
+ private InMemoryTvContext _db = null!;
+ private string _target = null!;
+
+ [SetUp]
+ public async Task SetUp()
+ {
+ _db = await InMemoryTvContext.CreateAsync();
+ _target = Path.Combine(
+ FileSystemLayout.GraphicsElementsTextTemplatesFolder,
+ GraphicsElementDefaults.OnNowNextFileName);
+ }
+
+ [TearDown]
+ public async Task TearDown() => await _db.DisposeAsync();
+
+ private async Task RunSeederOverAlreadySeededDatabase(string existingContent)
+ {
+ var fs = new MockFileSystem();
+ fs.Directory.CreateDirectory(FileSystemLayout.GraphicsElementsTextTemplatesFolder);
+
+ if (existingContent is not null)
+ {
+ await fs.File.WriteAllTextAsync(_target, existingContent);
+ }
+
+ await using TvContext context = _db.CreateContext();
+
+ // The fixture DB is shared across calls within a test, so only seed the marker once.
+ string key = ConfigElementKey.GraphicsOnNowNextSeeded.Key;
+ if (!context.ConfigElements.Any(c => c.Key == key))
+ {
+ context.ConfigElements.Add(new ConfigElement { Key = key, Value = "true" });
+ await context.SaveChangesAsync();
+ }
+
+ await GraphicsElementSeeder.SeedOnNowNext(context, fs, NullLogger.Instance, CancellationToken.None);
+ return fs;
+ }
+
+ [Test]
+ public async Task Upgrades_An_Untouched_Previous_Default()
+ {
+ MockFileSystem fs = await RunSeederOverAlreadySeededDatabase(OnNowNextYamlV1);
+
+ string result = await fs.File.ReadAllTextAsync(_target);
+
+ result.ShouldNotBe(OnNowNextYamlV1);
+ result.ShouldContain("background_color");
+ result.ShouldContain("background_padding");
+ }
+
+ [Test]
+ public async Task Upgrades_An_Untouched_Previous_Default_With_Windows_Line_Endings()
+ {
+ MockFileSystem fs = await RunSeederOverAlreadySeededDatabase(
+ OnNowNextYamlV1.Replace("\n", "\r\n"));
+
+ string result = await fs.File.ReadAllTextAsync(_target);
+
+ result.ShouldContain("background_color");
+ }
+
+ [Test]
+ public async Task Leaves_An_Operator_Modified_File_Alone()
+ {
+ // One changed value is enough to stop matching the fingerprint.
+ string edited = OnNowNextYamlV1.Replace("width_percent: 42", "width_percent: 30");
+
+ MockFileSystem fs = await RunSeederOverAlreadySeededDatabase(edited);
+
+ string result = await fs.File.ReadAllTextAsync(_target);
+
+ result.ShouldBe(edited);
+ result.ShouldNotContain("background_color");
+ }
+
+ [Test]
+ public async Task Leaves_The_Current_Default_Alone_So_The_Upgrade_Is_Idempotent()
+ {
+ MockFileSystem first = await RunSeederOverAlreadySeededDatabase(OnNowNextYamlV1);
+ string upgraded = await first.File.ReadAllTextAsync(_target);
+
+ MockFileSystem second = await RunSeederOverAlreadySeededDatabase(upgraded);
+ string again = await second.File.ReadAllTextAsync(_target);
+
+ again.ShouldBe(upgraded);
+ }
+
+ // The upgrade runs inside DatabaseMigratorService, ahead of DatabaseIsReady(). Before #732 the
+ // already-seeded branch touched the filesystem not at all, so a template the app cannot read --
+ // e.g. edited as root via `docker exec` while the app runs as PUID/PGID -- used to boot fine.
+ // It must not become a failure to start.
+ [Test]
+ public async Task An_Unwritable_Template_Does_Not_Fail_Startup()
+ {
+ var fs = new MockFileSystem();
+ fs.Directory.CreateDirectory(FileSystemLayout.GraphicsElementsTextTemplatesFolder);
+ await fs.File.WriteAllTextAsync(_target, OnNowNextYamlV1);
+ // the file matches a shipped default, so the upgrade WILL try to rewrite it -- and that write
+ // is denied, standing in for a root-owned or read-only template
+ var intercepted = 0;
+ fs.Intercept.Changing(
+ FileSystemTypes.File,
+ _ =>
+ {
+ intercepted++;
+ throw new UnauthorizedAccessException("simulated permission denial");
+ });
+
+ await using TvContext context = _db.CreateContext();
+ string key = ConfigElementKey.GraphicsOnNowNextSeeded.Key;
+ context.ConfigElements.Add(new ConfigElement { Key = key, Value = "true" });
+ await context.SaveChangesAsync();
+
+ await Should.NotThrowAsync(
+ () => GraphicsElementSeeder.SeedOnNowNext(context, fs, NullLogger.Instance, CancellationToken.None));
+
+ // Without this the test would pass just as happily if the upgrade never reached the write.
+ intercepted.ShouldBeGreaterThan(0, "the write interceptor never fired");
+
+ // and the original template survives the denied write
+ (await fs.File.ReadAllTextAsync(_target)).ShouldBe(OnNowNextYamlV1);
+ }
+
+ // The write path is not the only one that can fault. A template the app cannot READ used to be
+ // harmless on an already-seeded install; it must stay that way. An exclusive lock produces a
+ // genuine ReadAllTextAsync failure rather than an intercepted write dressed up as one.
+ [Test]
+ public async Task A_Read_Failure_On_The_Template_Does_Not_Fail_Startup()
+ {
+ var fs = new MockFileSystem();
+ fs.Directory.CreateDirectory(FileSystemLayout.GraphicsElementsTextTemplatesFolder);
+ await fs.File.WriteAllTextAsync(_target, OnNowNextYamlV1);
+
+ await using TvContext context = _db.CreateContext();
+ context.ConfigElements.Add(
+ new ConfigElement { Key = ConfigElementKey.GraphicsOnNowNextSeeded.Key, Value = "true" });
+ await context.SaveChangesAsync();
+
+ await using Stream exclusive = fs.File.Open(_target, FileMode.Open, FileAccess.Read, FileShare.None);
+
+ // prove the lock actually denies a read, so the test cannot pass by never hitting one
+ Should.Throw(() => fs.File.ReadAllText(_target));
+
+ await Should.NotThrowAsync(
+ () => GraphicsElementSeeder.SeedOnNowNext(context, fs, NullLogger.Instance, CancellationToken.None));
+ }
+
+ [Test]
+ public async Task Does_Not_Create_The_File_When_It_Is_Absent()
+ {
+ MockFileSystem fs = await RunSeederOverAlreadySeededDatabase(null);
+
+ fs.File.Exists(_target).ShouldBeFalse();
+ }
+
+ [Test]
+ public async Task The_Upgraded_Template_Still_Deserializes_With_A_Resolvable_Base_Style()
+ {
+ MockFileSystem fs = await RunSeederOverAlreadySeededDatabase(OnNowNextYamlV1);
+ string yaml = await fs.File.ReadAllTextAsync(_target);
+
+ IDeserializer deserializer = new DeserializerBuilder()
+ .WithNamingConvention(CamelCaseNamingConvention.Instance)
+ .Build();
+
+ var element = deserializer.Deserialize(yaml);
+
+ element.ShouldNotBeNull();
+ element.BackgroundColor.ShouldBe("#000000");
+ element.BackgroundOpacityPercent.ShouldBe(65);
+ element.BackgroundPadding.ShouldBe(14);
+ element.BackgroundCornerRadius.ShouldBe(8);
+
+ // The border is what makes the box visible over dark content; without it the translucent
+ // black fill is indistinguishable from the frame behind it.
+ element.BorderColor.ShouldBe("#59FFFFFF");
+ element.BorderWidth.ShouldBe(1);
+
+ // #570: every style needs a font_family, and base_style must resolve.
+ element.Styles.ShouldNotBeEmpty();
+ element.Styles.ShouldAllBe(s => s.FontFamily != null);
+ element.Styles.ShouldContain(s => s.Name == element.BaseStyle);
+ }
+
+ // Without the duplicate guard in EnsureBuiltInElementRow the already-seeded branch inserts a
+ // fresh row on EVERY boot: RefreshGraphicsElements will neither reap them (the file exists) nor
+ // dedupe them, so the row set grows without bound. Idempotence of the FILE is not idempotence
+ // of the ROW, and the existing idempotence test only looks at the file.
+ [Test]
+ public async Task Repeated_Seeding_Does_Not_Accumulate_Element_Rows()
+ {
+ var fs = new MockFileSystem();
+ fs.Directory.CreateDirectory(FileSystemLayout.GraphicsElementsTextTemplatesFolder);
+ await fs.File.WriteAllTextAsync(_target, OnNowNextYamlV1);
+
+ await using TvContext context = _db.CreateContext();
+ context.ConfigElements.Add(
+ new ConfigElement { Key = ConfigElementKey.GraphicsOnNowNextSeeded.Key, Value = "true" });
+ await context.SaveChangesAsync();
+
+ for (var i = 0; i < 3; i++)
+ {
+ await GraphicsElementSeeder.SeedOnNowNext(context, fs, NullLogger.Instance, CancellationToken.None);
+ }
+
+ (await context.GraphicsElements.ToListAsync()).Count.ShouldBe(1);
+ }
+
+ // A failed write must not leave a truncated template behind: it would match no fingerprint, so
+ // the upgrade could never repair it, and the loader rejects malformed YAML outright.
+ [Test]
+ public async Task A_Failed_Write_Leaves_The_Original_Template_Intact()
+ {
+ var fs = new MockFileSystem();
+ fs.Directory.CreateDirectory(FileSystemLayout.GraphicsElementsTextTemplatesFolder);
+ await fs.File.WriteAllTextAsync(_target, OnNowNextYamlV1);
+
+ // Capture WHICH path the write targets. Asserting only "the original survived" cannot tell
+ // an atomic write from an in-place one here: Testably raises the interception BEFORE it
+ // truncates, so a plain WriteAllTextAsync(target) would leave the file intact too -- on a
+ // real filesystem it would not. The path is what actually distinguishes them.
+ var writtenPaths = new List();
+ fs.Intercept.Changing(
+ FileSystemTypes.File,
+ c =>
+ {
+ writtenPaths.Add(c.Path);
+ throw new IOException("simulated disk full");
+ });
+
+ await using TvContext context = _db.CreateContext();
+ context.ConfigElements.Add(
+ new ConfigElement { Key = ConfigElementKey.GraphicsOnNowNextSeeded.Key, Value = "true" });
+ await context.SaveChangesAsync();
+
+ await Should.NotThrowAsync(
+ () => GraphicsElementSeeder.SeedOnNowNext(context, fs, NullLogger.Instance, CancellationToken.None));
+
+ writtenPaths.ShouldNotBeEmpty("the write interceptor never fired");
+ writtenPaths.ShouldAllBe(path => path.EndsWith(".upgrade.tmp"), "the upgrade wrote the live template in place instead of a temp file");
+ (await fs.File.ReadAllTextAsync(_target)).ShouldBe(OnNowNextYamlV1);
+ fs.Directory.GetFiles(FileSystemLayout.GraphicsElementsTextTemplatesFolder, "*.upgrade.tmp")
+ .ShouldBeEmpty("a temp file was left behind");
+ }
+
+ // The sibling test faults on the FIRST write, so it never reaches File.Move or the cleanup. Fault
+ // the replace instead, after a complete temp write: that is the path where a non-atomic
+ // implementation would already have truncated the live template.
+ [Test]
+ public async Task A_Failed_Replace_After_A_Complete_Temp_Write_Leaves_The_Original_Intact()
+ {
+ var fs = new MockFileSystem();
+ fs.Directory.CreateDirectory(FileSystemLayout.GraphicsElementsTextTemplatesFolder);
+ await fs.File.WriteAllTextAsync(_target, OnNowNextYamlV1);
+
+ var seenPaths = new List();
+ fs.Intercept.Event(
+ c =>
+ {
+ seenPaths.Add($"{c.ChangeType}:{c.Path}");
+
+ // let the temp file be written in full; fail only when the live template is touched
+ if (c.Path == _target)
+ {
+ throw new IOException("simulated replace failure");
+ }
+ },
+ _ => true);
+
+ await using TvContext context = _db.CreateContext();
+ context.ConfigElements.Add(
+ new ConfigElement { Key = ConfigElementKey.GraphicsOnNowNextSeeded.Key, Value = "true" });
+ await context.SaveChangesAsync();
+
+ await Should.NotThrowAsync(
+ () => GraphicsElementSeeder.SeedOnNowNext(context, fs, NullLogger.Instance, CancellationToken.None));
+
+ seenPaths.ShouldContain(path => path.EndsWith(".upgrade.tmp"), "no temp file was ever written");
+
+ // Assert the replace is a RENAME, not merely "the target was touched after the temp was".
+ // A File.Copy(temp, target, true) also touches both in that order and would leave the
+ // original intact under this mock (interception runs before the change), so path ordering
+ // alone cannot tell an atomic replace from a truncating one -- the change TYPE can.
+ seenPaths.ShouldContain($"Renamed:{_target}", "the replace was not an atomic rename");
+
+ // The whole point of write-then-move: the live template is untouched by a failed replace.
+ (await fs.File.ReadAllTextAsync(_target)).ShouldBe(OnNowNextYamlV1);
+
+ // and nothing this call created is left behind
+ fs.Directory.GetFiles(FileSystemLayout.GraphicsElementsTextTemplatesFolder, "*.upgrade.tmp")
+ .ShouldBeEmpty("a temp file was left behind");
+ }
+}
diff --git a/ErsatzTV.Tests/Support/ChannelHandlerTestBase.cs b/ErsatzTV.Tests/Support/ChannelHandlerTestBase.cs
index 79efa8c1e..dc2a9ca1d 100644
--- a/ErsatzTV.Tests/Support/ChannelHandlerTestBase.cs
+++ b/ErsatzTV.Tests/Support/ChannelHandlerTestBase.cs
@@ -88,7 +88,8 @@ public abstract class ChannelHandlerTestBase
bool showInEpg = false,
string logoPath = "",
string name = "Test",
- string group = "ErsatzTV") =>
+ string group = "ErsatzTV",
+ StreamingMode streamingMode = StreamingMode.TransportStreamHybrid) =>
new(
name,
number,
@@ -105,7 +106,7 @@ public abstract class ChannelHandlerTestBase
ChannelPlayoutMode.Continuous,
null,
null,
- StreamingMode.TransportStreamHybrid,
+ streamingMode,
null,
null,
string.Empty,
diff --git a/ErsatzTV/Services/RunOnce/DatabaseMigratorService.cs b/ErsatzTV/Services/RunOnce/DatabaseMigratorService.cs
index 9ab4c383a..ae7719c09 100644
--- a/ErsatzTV/Services/RunOnce/DatabaseMigratorService.cs
+++ b/ErsatzTV/Services/RunOnce/DatabaseMigratorService.cs
@@ -90,7 +90,8 @@ public class DatabaseMigratorService : BackgroundService
await DbInitializer.Initialize(dbContext, stoppingToken);
var fileSystem = scope.ServiceProvider.GetRequiredService();
- await GraphicsElementSeeder.SeedOnNowNext(dbContext, fileSystem, stoppingToken);
+ await GraphicsElementSeeder.SeedOnNowNext(dbContext, fileSystem, _logger, stoppingToken);
+ await GraphicsElementSeeder.AttachOnNowNextByDefault(dbContext, stoppingToken);
_systemStartup.DatabaseIsReady();
diff --git a/docs/README.md b/docs/README.md
index d27bd3ff7..fd7029577 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -21,6 +21,7 @@ doc below, or that changes which sections a task signal points to.**
| Adding/changing a `/api/*` endpoint | `docs/api-conventions.md` checklist + `docs/endpoint-index.md` |
| Adding a ChicoryTV SPA screen | `docs/spa-conventions.md` |
| Explaining a consequential settings field in the SPA (summary → hover/tap panel → docs link) | `docs/spa-conventions.md` §15 — use the shared `FieldHelp` trigger and put the copy in the screen's own `FIELD_HELP` record; the icon, the gesture and the a11y contract are fixed |
+| Graphics element / overlay work (text bug, On Now / Next, watermark-vs-`[vge]`) | `docs/graphics-elements.md`, then decisions catalog rows keyed `graphics.*` |
| Scheduling / playout engine work | `docs/domain-model.md` + decisions catalog rows keyed `sched.*` (`docs/decisions/README.md`) |
| Adding or changing a paged list handler (a page plus a `TotalCount`) | Resolve `api.paged-count-matches-page-query` via `docs/decisions/README.md` — for an EF-backed filtered list, count the SAME query you page, with includes appended to the page chain only; where the count and the page are separate methods, a test pins their agreement. Then `api.paging-zero-based` for the `pageNum`/`pageSize` contract |
| Concurrency / optimistic-locking work | `docs/api-conventions.md` §7a/b/c + `docs/decisions/optimistic-concurrency.md` |
@@ -100,6 +101,10 @@ bounds, what's mined per issue): `docs/handoffs/chicorytv-issue-queue.md` → "K
Largely superseded day-to-day by `docs/api-conventions.md`; read this for the original rationale.
- **`docs/mcp.md`** — the `ErsatzTV.Mcp` stdio JSON-RPC MCP server (#58): how it wraps `/api/v1` as
read + cautious-write tools, its config/env vars, auth, security posture, and the tool catalog.
+- **`docs/graphics-elements.md`** — graphics element (overlay) schema reference: how elements are
+ discovered and attached, the YAML parsing traps (an unknown key disables the element outright), the
+ full text-element field table including the #732 background box, and why `[vge]` in a filter graph
+ does not imply a graphics element is bound.
- **`docs/channels.md`** — Channel entity field reference.
- **`docs/m3u-xmltv.md`** — M3U/XMLTV generation overview (`ChannelPlaylist`, `GetChannelGuideHandler`).
- **`docs/fork-strategy.md`** — divergence policy vs upstream ErsatzTV.
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index 928492189..0812f20e3 100644
--- a/docs/decisions/README.md
+++ b/docs/decisions/README.md
@@ -97,6 +97,8 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera
| `ffmpeg.work-ahead-slot-release-never-negative` | `Release()` reads the count and compare-exchanges `current - 1` only when `current > 0`; a release against an empty pool records an unbalanced release and returns `false` **without ever writing a negative value**. It never decrements first and clamps afterward. The single caller (`HlsSessionWorker.Transcode`'s `finally`) logs a warning on the `false` return. | 2026-07-21 | [link](records/ffmpeg/work-ahead-slot-release-never-negative.md) |
| `graphics.channel-level-attachment` | A channel can attach `GraphicsElement`s directly via a new `ChannelGraphicsElement` join table (a base layer under deco/playout-item elements), and a built-in text element (`on-now-next.yml`) is seeded once per database so the On Now/Next overlay works out of the box. | 2026-07-22 | [link](records/graphics/channel-level-attachment.md) |
| `graphics.channel-logo-caching` | An external `http(s)` channel-logo URL is fetched, decode-budget-validated, and stored in the image cache under a content-hash name at SAVE time — becoming byte-identical to an uploaded logo — so the render path never fetches a logo over HTTP; a bad URL fails the save with a 422 (BaseError → ValidationProblemDetails). | 2026-07-21 | [link](records/graphics/channel-logo-caching.md) |
+| `graphics.on-now-next-on-by-default` | The built-in On Now / Next element is attached to new channels by `ChannelGraphicsDefaults.Attach`, called from BOTH create paths, and to pre-existing channels by a one-time `AttachOnNowNextByDefault` backfill guarded by `graphics.on_now_next_default_attached`. The marker is written only once the built-in element RESOLVES, so an install whose element row does not exist yet is retried rather than stranded; the cost is that while the backfill is still armed it cannot tell a deliberately cleared channel from an untouched one. HLS Direct is excluded at both sites. | 2026-08-26 | [link](records/graphics/on-now-next-on-by-default.md) |
+| `graphics.seeded-template-upgrade-by-fingerprint` | `GraphicsElementSeeder` keeps every default it has ever shipped as a verbatim fingerprint; on an already-seeded database it rewrites the on-disk template only when the file still matches one of them (line-endings and trailing whitespace normalised), so an untouched install gets the new default while any operator edit is left alone. | 2026-08-26 | [link](records/graphics/seeded-template-upgrade-by-fingerprint.md) |
| `iptv.base-url` | An optional advertised base URL (`iptv.base_url`) is resolved centrally via a pure Core helper (`AdvertisedBaseUrl`) inside the two IPTV generation handlers (M3U + XMLTV); unset/malformed values fall back byte-identical to the request-derived host, and it's a new `iptv` settings group distinct from `ETV_BASE_URL` and out of scope for HDHomeRun. | 2026-07-16 | [link](records/iptv/base-url.md) |
| `iptv.logo-drives-bug-preset` | One uploaded channel logo drives both the listing logo and the on-screen bug via a shared, seeded `ChannelLogo`-sourced watermark preset (`Channel Bug`), not new per-channel schema. | 2026-07-20 | [link](records/iptv/logo-drives-bug-preset.md) |
| `locking.entitylocker-atomic-flags` | `EntityLocker` uses `Interlocked.CompareExchange`-guarded atomic flags plus a documented single-owner-release discipline (no owner tokens/leases); `Unlock*` on an already-unlocked slot returns `false` and logs a Warning rather than throwing. | 2026-07-11 | [link](records/locking/entitylocker-atomic-flags.md) |
diff --git a/docs/decisions/records/graphics/on-now-next-on-by-default.md b/docs/decisions/records/graphics/on-now-next-on-by-default.md
new file mode 100644
index 000000000..f925cd269
--- /dev/null
+++ b/docs/decisions/records/graphics/on-now-next-on-by-default.md
@@ -0,0 +1,81 @@
+---
+key: graphics.on-now-next-on-by-default
+title: 2026-08-26 — The On Now / Next overlay is on by default, backfilled exactly once (#732)
+status: active
+since: '2026-08-26'
+supersedes: none
+superseded-by: none
+rule: 'The built-in On Now / Next element is attached to new channels by `ChannelGraphicsDefaults.Attach`, called from BOTH create paths, and to pre-existing channels by a one-time `AttachOnNowNextByDefault` backfill guarded by `graphics.on_now_next_default_attached`. The marker is written only once the built-in element RESOLVES, so an install whose element row does not exist yet is retried rather than stranded; the cost is that while the backfill is still armed it cannot tell a deliberately cleared channel from an untouched one. HLS Direct is excluded at both sites.'
+signals: 'AttachOnNowNextByDefault, GraphicsOnNowNextDefaultAttached, ChannelGraphicsDefaults.Attach, ChannelGraphicsElement default, On Now Next default on, create-time graphics default, CreateChannelFromLineup graphics · paths: `ErsatzTV.Infrastructure/Streaming/Graphics/GraphicsElementSeeder.cs`, `ErsatzTV.Application/Channels/ChannelGraphicsDefaults.cs`, `ErsatzTV.Application/Channels/Commands/CreateChannelHandler.cs`, `ErsatzTV.Application/Channels/Commands/CreateChannelFromLineupHandler.cs` · issues: #732, #74'
+---
+
+#74 shipped the overlay as a per-channel opt-in toggle. #732 made it a default. The binding level is
+`ChannelGraphicsElement` — the base layer added at `GraphicsElementSelector`'s final fall-through, so a
+deco in `Override`/`Disable` mode still suppresses it exactly as before (`graphics.channel-level-attachment`).
+
+Two mechanisms, because they answer different questions:
+
+- **New channels** — `ChannelGraphicsDefaults.Attach` is called as the channel is persisted. The
+ create requests carry no graphics field and the SPA's channel editor is update-only, so the server
+ is the only place a create-time default can live.
+- **Pre-existing channels** — `AttachOnNowNextByDefault` runs once at startup, after the seeder.
+
+**The create-time mechanism has more than one call site, and enumerating them from the source is the
+only reliable way to find them.** There are three places that persist a `Channel`:
+`CreateChannelHandler` (the SPA's "New blank channel"), `CreateChannelFromLineupHandler` (the SPA's
+primary "Add Channel" flow, and what Auto-Tune bulk-creates through), and `DbInitializer`'s default
+channel. The first two both call the shared helper — they diverged once, with only the first covered,
+which silently excluded the busier path. The third needs no call because it runs before
+`AttachOnNowNextByDefault` in the same startup, so the backfill picks it up. A new persisting site
+must call the helper; `grep` for `Channels.Add` rather than trusting this list to stay complete.
+
+**The marker is written only once the element resolves**, and the built-in `GraphicsElement` row is
+created by the seeder (`EnsureBuiltInElementRow`) rather than waited for. Those two go together.
+
+Writing the marker unconditionally is the tempting simplification, and it is wrong: on an install
+upgrading from before #74 the template is seeded on the same boot, so a marker written while the row
+is merely *undiscovered* strands every pre-existing channel permanently — the exact population the
+backfill exists for. Creating the row in the seeder removes that ordering dependency for every normal
+path, and skipping the marker when nothing resolves covers the rest.
+
+**This is a real trade, not a free win, and a single global marker cannot represent both halves.**
+The two properties wanted here are "never re-add to a channel the operator cleared" and "never strand
+a channel that had no element to attach". A boolean that means *the backfill has run* can express one
+or the other, never both:
+
+- While the backfill is **armed** (nothing has resolved yet — the template file is absent, e.g. an
+ operator deleted it and `RefreshGraphicsElements` reaped the row), a channel cleared by the
+ operator is indistinguishable from one never considered. If the element is later restored, the
+ next boot attaches it to every eligible channel, including that one.
+- Once the marker is **written**, no channel is ever re-attached, on any restart.
+
+The armed window is narrow (it requires the built-in template to be absent at startup) and the
+failure is visible and reversible — an overlay reappears — whereas stranding is silent and permanent.
+That is why it is resolved this way. Closing it properly needs per-channel "considered / opted-out"
+state rather than one global flag, which is a schema change and is tracked separately.
+
+**It also cannot reconstruct pre-upgrade operator intent.** On an install that predates #732, an
+operator who enabled the overlay and later turned it off left no record that survives — the join row
+is simply absent, indistinguishable from never having enabled it — so the one-time backfill
+re-attaches it. That is inherent to "enable it on all channels by default" rather than a defect. The
+never-re-attach guarantee therefore holds *from the marker onwards*, not across the upgrade boundary.
+
+Identity is the element's **filename** (`GraphicsElementDefaults.OnNowNextFileName`), never the
+user-editable `Name` — the #67 lesson carried through #74.
+
+**HLS Direct is excluded at both sites.** ErsatzTV is not transcoding there, so `GraphicsElementSelector`
+returns empty and the editor disables the toggle; an attachment would be inert while still reading as
+"on". Excluding it keeps the stored state honest rather than merely harmless.
+
+HLS Direct is **not** the only inert case: `FFmpegLibraryProcessService` gates the graphics engine on
+`videoFormat != VideoFormat.Copy`, so a channel whose FFmpeg profile is set to `Copy` also renders
+nothing while showing the toggle on. That one is deliberately *not* excluded here — the profile is
+mutable and shared, so the streaming-mode exclusion is a property of the channel while the `Copy`
+gate is a property of a setting that can change under it. The render-site gate is the only correct
+place for it.
+
+**Residual risk, stated rather than reassured away.** On 2026-08-26 all 43 channels on the live
+install already carried the element (measured by reading `graphicsElementIds` from
+`GET /api/v1/channels/{id}` for every id in `GET /api/v1/channels`). The backfill is therefore a no-op
+in the only place it has ever run, and its behaviour against real pre-existing data is covered by
+tests and a local live run, not by production evidence.
diff --git a/docs/decisions/records/graphics/seeded-template-upgrade-by-fingerprint.md b/docs/decisions/records/graphics/seeded-template-upgrade-by-fingerprint.md
new file mode 100644
index 000000000..8b4f9642f
--- /dev/null
+++ b/docs/decisions/records/graphics/seeded-template-upgrade-by-fingerprint.md
@@ -0,0 +1,67 @@
+---
+key: graphics.seeded-template-upgrade-by-fingerprint
+title: 2026-08-26 — A seeded graphics template is upgraded only when it still matches a shipped default (#732)
+status: active
+since: '2026-08-26'
+supersedes: none
+superseded-by: none
+rule: '`GraphicsElementSeeder` keeps every default it has ever shipped as a verbatim fingerprint; on an already-seeded database it rewrites the on-disk template only when the file still matches one of them (line-endings and trailing whitespace normalised), so an untouched install gets the new default while any operator edit is left alone.'
+signals: 'GraphicsElementSeeder, OnNowNextYamlV1, SupersededDefaults, UpgradeUnmodifiedTemplate, on-now-next.yml upgrade, graphics.on_now_next_seeded · paths: `ErsatzTV.Infrastructure/Streaming/Graphics/GraphicsElementSeeder.cs` · issues: #732, #74'
+---
+
+#74 seeded `on-now-next.yml` behind the `graphics.on_now_next_seeded` `ConfigElement` marker, writing
+the file only when absent so operator edits are never clobbered. That is the right rule for *content*,
+but it has a consequence nobody stated at the time: **an already-seeded installation never revisits the
+file at all**, so a change to the shipped default reaches new databases only. #732 hit this directly —
+the background box is useless if the one install that has the overlay keeps rendering the pre-#732
+template forever.
+
+**Decision: upgrade by fingerprint, not by version number or by marker bump.** Every default we have
+shipped stays in the source as a verbatim constant (`OnNowNextYamlV1`, …) collected in
+`SupersededDefaults`. On an already-seeded database the seeder reads the file and rewrites it **only**
+if it still normalises equal to one of those. The comparison ignores line endings and trailing
+whitespace, because a volume mount or an editor rewrites those without the operator touching content.
+
+Why this shape:
+
+- **The safety property is derived, not asserted.** "Did the operator edit this file?" is answered by
+ comparing bytes against what we wrote, rather than assumed — which is exactly the assumption #74
+ refused to make, and which a marker bump would have to make.
+
+ The comparison is not byte-exact in one direction: line endings are normalised and the result is
+ `TrimEnd`ed, so an edit consisting *only* of trailing whitespace at end-of-file does not opt the
+ file out and would be overwritten. That is deliberate (a volume mount or editor rewrites those
+ without operator intent) and the cost is bounded to whitespace nobody can see. Every edit with any
+ visible effect opts out permanently.
+- **It is self-limiting, so it needs no new marker.** After the rewrite the content equals the
+ *current* default, which is not in `SupersededDefaults`, so the next startup is a no-op.
+- **A fingerprint entry is not a template.** Never edit an entry in `SupersededDefaults` — it is a
+ record of what we shipped. Changing the current default means adding a new constant and pushing the
+ outgoing one into the list; editing an existing entry silently un-recognises every install carrying
+ it, and the failure is invisible (the upgrade just never fires).
+
+**The rewrite is write-then-move, with no in-place fallback.** `WriteAllTextAsync` truncates before
+it writes, so an interrupted write would leave a partial file matching no fingerprint — never
+repairable by a later boot, and rejected outright by the loader. The temp name is random per call,
+because a fixed one is shared by two containers on the same config volume — and a process id is not
+random enough: the image's ENTRYPOINT is exec-form, so every container is PID 1 in its own namespace
+and would compute the same name. The accepted cost: a
+template bind-mounted as a single file cannot be replaced by `rename(2)` (EBUSY), so that install
+never receives the upgrade. Reaching that needs a pinned file that is *also* byte-identical to a
+shipped default, and the alternative — falling back to an in-place copy — reintroduces the truncation
+on every IO fault rather than just that one.
+
+**The upgrade is a one-way door, and a downgrade is lossy.** `GraphicsElementLoader.FromYaml` does
+not set `IgnoreUnmatchedProperties`, so an unknown YAML key throws and the element is dropped with
+only a logged warning. Once a template has been upgraded, rolling ErsatzTV back to a build that does
+not know the new keys makes that element fail to load on **every** channel it is attached to — which,
+since `graphics.on-now-next-on-by-default`, is every eligible channel that still has it (HLS Direct
+was never attached, and an operator may have cleared individual channels). The symptom is "the overlay vanished
+everywhere" and recovery is hand-editing the YAML back. Rollback is a supported operation here
+(`:prod` is a floating tag promoted manually), so this belongs in the release notes of any version
+that adds fields to a seeded template, not only in this record.
+
+**Verify the fingerprint against a real install, not against the constant it was copied from.** The
+#732 V1 entry was checked byte-for-byte against the live install (md5 `ef9afc088cf6dba252f725babbf3334f`,
+2026-08-26) before being trusted. A fingerprint that does not match anything in the field is a
+permanent silent no-op, and no test written from the same source can detect that.
diff --git a/docs/graphics-elements.md b/docs/graphics-elements.md
new file mode 100644
index 000000000..2e1bd9d06
--- /dev/null
+++ b/docs/graphics-elements.md
@@ -0,0 +1,218 @@
+# Graphics elements — schema reference
+
+Graphics elements are YAML-authored overlays composited onto a channel's **transcoded** frames by the
+SkiaSharp graphics engine (`ErsatzTV.Infrastructure/Streaming/Graphics/`). They appear in the FFmpeg
+filter graph as the `[vge]` stage.
+
+`[vge]` is **not** proof that a graphics element is bound. Watermarks are a separate, older system that
+falls back onto the graphics engine whenever it cannot use ffmpeg's native `overlay` shortcut — an
+`Intermittent`/`OpacityExpression` mode, more than one active watermark, or an external-URL image all
+route a *watermark* through `[vge]` with zero graphics-element rows. The native shortcut is only taken
+for a single `Permanent` local-file watermark
+(`ErsatzTV.Core/FFmpeg/FFmpegLibraryProcessService.cs`, `CanUseFFmpegNativeWatermark`).
+
+`StreamingMode.HttpLiveStreamingDirect` renders nothing: ErsatzTV is not transcoding, so there is no
+frame pipeline to draw into and `GraphicsElementSelector` returns empty.
+
+## Discovery and attachment
+
+- Files live under `FileSystemLayout.GraphicsElements*TemplatesFolder` (`text/`, `image/`, `motion/`,
+ `subtitle/`, `script/`). `RefreshGraphicsElementsHandler` scans them and maintains one
+ `GraphicsElement` row per file, removing rows whose file vanished.
+- Five join tables attach an element: `ChannelGraphicsElement`, `PlayoutItemGraphicsElement`,
+ `ProgramScheduleItemGraphicsElement`, `BlockItemGraphicsElement`, `DecoGraphicsElement`.
+ Resolution order and the deco `Merge`/`Override`/`Disable`/`Inherit` semantics are in
+ `graphics.channel-level-attachment`; the channel level is the **base layer**.
+
+## Parsing rules that bite
+
+- Deserialization is YamlDotNet **without** `IgnoreUnmatchedProperties`, so **an unknown key throws**
+ and the whole element is silently disabled for that content with only a logged warning
+ (`GraphicsElementLoader.FromYaml`). A typo is not a partial render — it is no render.
+- There is no schema validation (`GraphicsElementLoader` carries an explicit `TODO: validate schema`).
+- Colour strings are parsed with SkiaSharp's `SKColor.TryParse` (`#RRGGBB`, `#AARRGGBB`, named
+ colours). Failure handling differs by field and by whether the style is the base one. An unparseable
+ **background/border** colour is warned about and that part of the box is skipped. Everywhere else it
+ is silent: on the **base** style an unparseable `text_color` falls back to white and an unparseable
+ `halo_color` leaves the halo unset; on a **non-base** style an unparseable `text_color` OR
+ `halo_color` is simply not applied, so the value inherited from the base style stands.
+- **`font_family` is required on the base style.** Non-base styles inherit it; a null one reaching
+ the mapper makes `CustomFontMapper` throw on a null
+ dictionary key, which the renderer swallows into "disable for this content" (#570).
+- `{{ … }}` template expressions are rendered by Scriban before the YAML is parsed.
+
+## Text element fields
+
+Element level (`TextGraphicsElement`):
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `name` | string | Display name; **never** used for identity. |
+| `text` | string | Scriban-templated. `[styleName]…[/styleName]` selects a style for a span. |
+| `base_style` | string | Must name an entry in `styles`, or initialization throws. |
+| `styles` | list | See below. |
+| `epg_entries` | int | How many EPG entries to expose as `Epg[…]`. |
+| `location` | enum | `TopLeft`, `BottomLeft`, … |
+| `horizontal_margin_percent` / `vertical_margin_percent` | double | Percent of frame width/height. |
+| `width_percent` | double | Percent of frame width. A wrapping/scaling **budget** for the whole element, box included — not a hard clamp; see the geometry notes. |
+| `text_fit` | `None` \| `Wrap` \| `Scale` | Only meaningful with `width_percent`. |
+| `text_align` | `Left` \| `Center` \| `Right` | |
+| `z_index` | int | |
+| `opacity_percent` | int | Ignored when `opacity_expression` is set. |
+| `opacity_expression` | string | NCalc expression, e.g. `LinearFadeDuration(content_seconds, 4, 1, 6)`. |
+| `include_fonts_from` | string | Directory of `.ttf`/`.otf` to load. |
+
+Background box (#732) — element level, because the engine lays the whole element out as one text block
+and rasterises it into one bitmap, so there is exactly one box per element:
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `background_color` | string | unset | Unset means no **fill**. A `border_color` alone still draws an outlined box; with neither, there is no box and no insets. |
+| `background_opacity_percent` | int | 100 | Clamped to 0–100; multiplies the colour's own alpha, so `#AARRGGBB` and this field compose. |
+| `background_padding` | double px | 0 | Space between the text and the box edge, on all four sides. |
+| `background_corner_radius` | double px | 0 | Clamped to half the shorter side. |
+| `border_color` | string | unset | |
+| `border_width` | double px | 1 when `border_color` is set | A border colour with no width draws a hairline rather than nothing. |
+
+Geometry notes:
+
+- Padding and border grow the element's bitmap and are subtracted from the text's wrap/scale budget, so
+ `width_percent` applies to the visible box rather than to the text inside it. The inset is rounded up
+ to a whole pixel once and the same integer is used on both sides, so the box cannot exceed the budget
+ by a rounding remainder.
+- **`width_percent` is a budget, not a guarantee.** Wrapping cannot break below a single glyph, so a
+ narrow `width_percent` overflows with or without a box — that is pre-existing behaviour, not
+ something the box introduced. `text_fit: Scale` shrinks the font instead, down to a 5px floor.
+- If the inset does not fit inside the budget at all, the **inset is clamped** (with a logged warning)
+ rather than the text being squeezed to nothing, so an oversized `background_padding` stops growing
+ its box at the budget instead of producing one several times the requested width.
+- The inset is **also capped at `min(frameWidth, frameHeight) / 2`**, with a logged warning, whether or
+ not `width_percent` is set. Each field is bounded on its own, but padding and border add up, so
+ without this a two-field mistake could allocate a bitmap far larger than the frame it is drawn onto.
+- With no box fields set the wrap/scale budget is passed through untouched, so existing overlays keep
+ their exact pre-#732 geometry.
+- The box is drawn behind the text and fades with the element, so `opacity_expression` dims box and
+ text together.
+- Sizes are in **pixels at frame scale**, matching `font_size`. They do not scale with resolution.
+
+Per-style (`StyleDefinition`): `name`, `font_family` (required), `font_size`, `font_weight`,
+`font_italic`, `text_color`, `letter_spacing`, `line_height`, `halo_color`, `halo_width`, `halo_blur`.
+Every one of these overrides the `base_style`'s value when the style declares it — the halo fields
+did not until #732, so before that a non-base style silently rendered the base style's halo. The
+seeded `on-now-next.yml` is unaffected because all three of its styles declare the same halo: its
+rendered bitmap is byte-identical either way. That invariant holds on any host; a specific hash would
+not, because the render depends on the host's fonts (see `docs/testing.md`). Re-derive it by rendering
+`OnNowNextYaml` through `TextElement` at 1920x1080 with and without the per-style halo merge and
+comparing the encoded PNGs — they must be equal, whatever their hash is.
+
+**This is an operator-visible change and belongs in the release notes.** A custom template whose
+non-base style declares its own `halo_color` / `halo_width` / `halo_blur` renders differently after
+this version — correctly, but differently. So does one using `line_height` with `text_fit: Scale`:
+the Scale path now carries line height through, which changes measured height and therefore where the
+element anchors.
+Halo is drawn by RichTextKit as part of the text, not by the box code — a wide halo **on top of** a
+background box over-darkens the glyphs, which is why the seeded template cuts it to 1px.
+
+## The built-in On Now / Next element
+
+`GraphicsElementSeeder` writes `on-now-next.yml` once per database (`graphics.on_now_next_seeded`) and
+never overwrites an operator's file. Two rules govern it after that:
+
+- Updating the shipped default → `graphics.seeded-template-upgrade-by-fingerprint`.
+- It is attached to channels by default → `graphics.on-now-next-on-by-default`.
+
+Identity is the **filename** (`GraphicsElementDefaults.OnNowNextFileName`), never the editable `Name`;
+`GraphicsElementResponseModel.BuiltIn` is derived from it server-side so the SPA never name-matches.
+
+## Tests
+
+`ErsatzTV.Tests/Infrastructure/Graphics/TextElementBackgroundBoxTests.cs` renders real bitmaps and
+asserts pixels — the box's failure mode is a silent no-op, which a model-level test cannot see.
+Geometry assertions are relative to a no-box baseline so they do not depend on the host's typeface,
+and `Baseline_Renders_A_Non_Empty_Bitmap` turns a fontless host into a loud red instead of a suite
+that passes vacuously on a 0x0 bitmap (see `docs/testing.md` → font dependency).
+
+Attachment behaviour is covered by `GraphicsElementDefaultAttachTests`,
+`GraphicsElementSeederUpgradeTests` and `CreateChannelDefaultGraphicsElementTests`.
+
+### Mutation record (#732)
+
+Every clause below was mutated in turn against this tree and **the whole `ErsatzTV.Tests` project**
+re-run; the "Reddens" column is the measured failure set. The working tree was confirmed clean after
+each run. Reproduce one by making the edit and running
+`dotnet test ErsatzTV.Tests/ErsatzTV.Tests.csproj` — **not** a `--filter`ed run.
+
+Three traps this table is built to avoid:
+
+- **Measure against the whole project, never a per-fixture filter.** A filtered run structurally
+ cannot observe a red in another fixture, so it under-reports the failure set while looking precise.
+ Thirteen rows below redden more than one test, and two of them span two fixture classes — those two
+ are exactly what a per-fixture filter cannot see.
+- **A mutation that fails to COMPILE is not a result.** Warnings-as-error turn the obvious mutation
+ shapes into build failures — `CS0162` for `if (true) { return; }`, `CS1717` for self-assignment,
+ Sonar `S3981` for a constant-folded condition — and a build failure emits no test summary at all,
+ which reads exactly like a pass in a scrolled log. Require a summary line, and detect build failure
+ with `: error `, not `error CS`.
+- **Re-measure the red set; never carry it over.** Test renames and added cases both change which
+ tests a clause reddens, so a row written from anything but a fresh run describes a tree that no
+ longer exists.
+
+**This table is not an enumeration of the change.** It lists the clauses that have a measured proof;
+it makes no claim about the ones that do not appear. A clause absent from it has no proof — which is a
+reason to go and check, never evidence that none is possible. A "the only uncovered clause is X"
+sentence was tried here and abandoned: it was falsified three times, each time by a different clause,
+because it silently becomes false the moment a guard is added without its row.
+
+Known clauses with no red, as examples rather than a closed set. Each was measured, and each is
+recorded with why a test could not reach it — an unreachable clause is a reason to say so, not to ship
+a test that cannot fail:
+
+- the `float.IsFinite` guard on the `width_percent` budget — .NET saturates float→int conversion, so
+ removing it changes nothing observable;
+- the `insetPixels == 0 ? maxWidth : …` compatibility branch — a `width_percent` that rounds to zero
+ renders identically whether RichTextKit is given a `MaxWidth` of 0 or 1;
+- the absent-target early return and the temp-file existence check in `UpgradeUnmodifiedTemplate` —
+ behaviourally redundant; the first re-raises as a caught `IOException`, the second guards a delete
+ that is already a no-op;
+- the inner `catch` around that cleanup delete — it stops a failing delete from replacing the
+ exception being unwound (which C# otherwise does, and which would downgrade a real cancellation to a
+ swallowed warning). `MockFileSystem` does not propagate an interceptor throw raised during the
+ delete, so the clause is correct by language semantics but not reachable from a test here.
+
+Rows are written per clause, not per block: a row naming a whole `if` or a whole style-merge block
+hides which individual fields inside it are actually reachable from a test.
+
+| # | Clause mutated | Reddens (measured) |
+|---|---|---|
+| 1 | DrawBackgroundBox returns immediately | `An_Oversized_Border_Is_Clamped_And_Does_Not_Flood_The_Element` `Background_Color_Fills_The_Box` `Background_Opacity_Percent_Is_Clamped_To_Its_Documented_Range` `Background_Opacity_Percent_Scales_The_Alpha` `Background_Padding_Actually_Insets_The_Text` `Border_Color_Draws_A_Border_Distinct_From_The_Fill` `Border_Color_Without_An_Explicit_Width_Draws_A_Hairline` `Corner_Radius_Rounds_The_Corner_Away` |
+| 2 | inset not subtracted from the wrap budget | `Fractional_Padding_Still_Respects_Width_Percent` `Width_Percent_Bounds_The_Whole_Box_Including_Padding` |
+| 3 | text painted at (0,0) instead of the inset | `Background_Padding_Actually_Insets_The_Text` |
+| 4 | ApplyOpacityPercent returns the colour unchanged | `Background_Opacity_Percent_Is_Clamped_To_Its_Documented_Range` `Background_Opacity_Percent_Scales_The_Alpha` |
+| 5 | UpgradeUnmodifiedTemplate call removed | `A_Failed_Replace_After_A_Complete_Temp_Write_Leaves_The_Original_Intact` `A_Failed_Write_Leaves_The_Original_Template_Intact` `An_Unwritable_Template_Does_Not_Fail_Startup` `The_Upgraded_Template_Still_Deserializes_With_A_Resolvable_Base_Style` `Upgrades_An_Untouched_Previous_Default` `Upgrades_An_Untouched_Previous_Default_With_Windows_Line_Endings` |
+| 6 | fingerprint check ignored (upgrade unconditionally) | `Leaves_An_Operator_Modified_File_Alone` |
+| 7 | line-ending normalisation dropped from Normalize | `Upgrades_An_Untouched_Previous_Default_With_Windows_Line_Endings` |
+| 8 | HLS-Direct exclusion removed from the backfill | `Skips_Hls_Direct_Channels_Where_The_Overlay_Cannot_Render` |
+| 9 | already-attached filter removed | `Does_Not_Duplicate_An_Existing_Attachment` `While_Armed_A_Restored_Element_Is_Attached_To_Every_Eligible_Channel` |
+| 10 | filename check removed from the built-in lookup | `Ignores_A_Non_Built_In_Element_With_A_Different_Filename` |
+| 11 | graphics.on_now_next_default_attached guard never fires | `Does_Not_Re_Attach_After_An_Operator_Clears_It` |
+| 12 | create-time `ChannelGraphicsDefaults.Attach` call removed from `CreateChannelHandler` | `Attaches_The_Built_In_Element_To_A_New_Channel` |
+| 13 | HLS-Direct skip removed from the create path | `Leaves_An_Hls_Direct_Channel_Alone_Because_Nothing_Can_Render_There` `Should_Not_Attach_The_Overlay_To_An_Hls_Direct_Channel` |
+| 14 | upgrade no longer catches filesystem exceptions | `A_Failed_Replace_After_A_Complete_Temp_Write_Leaves_The_Original_Intact` `A_Failed_Write_Leaves_The_Original_Template_Intact` `A_Read_Failure_On_The_Template_Does_Not_Fail_Startup` `An_Unwritable_Template_Does_Not_Fail_Startup` |
+| 15 | FitTextBlock drops HaloColor again | `The_Scale_Path_Preserves_Halo_Blur` `The_Scale_Path_Preserves_The_Halo` |
+| 16 | unrounded inset subtracted from the budget | `Fractional_Padding_Still_Respects_Width_Percent` |
+| 17 | inset clamp removed | `An_Oversized_Padding_Is_Clamped_To_The_Largest_That_Fits` |
+| 18 | Kind == Text filter dropped from the lookup | `Ignores_A_Same_Named_Element_Of_A_Different_Kind` |
+| 19 | Sanitize passes values through unchecked | `Non_Finite_And_Absurd_Box_Values_Do_Not_Corrupt_The_Geometry` |
+| 20 | the BOX itself is no longer clamped (only insetPixels) | `An_Oversized_Border_Is_Clamped_And_Does_Not_Flood_The_Element` |
+| 21 | duplicate guard removed from EnsureBuiltInElementRow | `Repeated_Seeding_Does_Not_Accumulate_Element_Rows` |
+| 22 | EnsureBuiltInElementRow removed from the ALREADY-SEEDED branch | `An_Already_Seeded_Install_Missing_Its_Element_Row_Gets_One` `Repeated_Seeding_Does_Not_Accumulate_Element_Rows` |
+| 23 | non-atomic in-place write restored | `A_Failed_Replace_After_A_Complete_Temp_Write_Leaves_The_Original_Intact` `A_Failed_Write_Leaves_The_Original_Template_Intact` |
+| 24 | marker written even with nothing resolved | `Stays_Armed_When_There_Is_No_Built_In_Element_To_Attach` `While_Armed_A_Restored_Element_Is_Attached_To_Every_Eligible_Channel` |
+| 25 | the atomic replace becomes a non-atomic copy | `A_Failed_Replace_After_A_Complete_Temp_Write_Leaves_The_Original_Intact` |
+| 26 | the frame cap on the inset is disarmed | `Non_Finite_And_Absurd_Box_Values_Do_Not_Corrupt_The_Geometry` `The_Inset_Is_Capped_Against_The_Frame_Even_With_No_Width_Percent` |
+| 27 | per-style halo overrides dropped from the style merge | `A_Non_Base_Style_Uses_Its_Own_Halo_Blur` `A_Non_Base_Style_Uses_Its_Own_Halo_Not_The_Base_Styles` |
+| 28 | FitTextBlock drops HaloBlur from the rebuilt style | `The_Scale_Path_Preserves_Halo_Blur` |
+| 29 | FitTextBlock drops LineHeight from the rebuilt style | `The_Scale_Path_Preserves_Line_Height` |
+| 30 | per-style halo_blur override dropped from the style merge | `A_Non_Base_Style_Uses_Its_Own_Halo_Blur` |
+| 31 | the 0-100 opacity clamp is removed | `Background_Opacity_Percent_Is_Clamped_To_Its_Documented_Range` |
+| 32 | the lineup create path stops attaching the built-in element | `Should_Attach_The_Built_In_On_Now_Next_Element` |
diff --git a/docs/testing.md b/docs/testing.md
index 6c2df48fa..dc0be608d 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -5,9 +5,17 @@ before adding tests, not just `docs/contributing.md` §8 (which now just points
## Test projects
+> **Font dependency (ersatztv#732).** `Infrastructure/Graphics/TextElementBackgroundBoxTests` is the
+> only suite that rasterises text, so it needs at least one system font to lay anything out. The CI
+> image installs none explicitly — fonts arrive via `playwright install --with-deps` in
+> `docker/ci/Dockerfile` (351 present in the pinned image, measured 2026-08-26). This is a real
+> dependency, declared here so a future slimming of that install produces a known cause rather than a
+> mystery red. `Baseline_Renders_A_Non_Empty_Bitmap` exists to make that failure loud: without it a
+> fontless host would render a 0x0 bitmap and every relative geometry assertion would pass vacuously.
+
| Project | Covers | Notes |
|---|---|---|
-| `ErsatzTV.Tests` | API controllers + MediatR handlers | In-memory SQLite fixture: a shared `SqliteConnection("Data Source=:memory:;Foreign Keys=False")` kept open + `EnsureCreatedAsync()` (**not** full migration replay) + `PRAGMA foreign_keys=OFF`, then seed; a tiny `IDbContextFactory` wraps `new TvContext(...)`. ~1,870 tests (approximate on purpose — an exact count goes stale on every PR that adds one; the previous hardcoded 828 was off by over a thousand). |
+| `ErsatzTV.Tests` | API controllers + MediatR handlers, plus the SkiaSharp text-overlay rasteriser (`Infrastructure/Graphics/`) | In-memory SQLite fixture: a shared `SqliteConnection("Data Source=:memory:;Foreign Keys=False")` kept open + `EnsureCreatedAsync()` (**not** full migration replay) + `PRAGMA foreign_keys=OFF`, then seed; a tiny `IDbContextFactory` wraps `new TvContext(...)`. ~1,870 tests (approximate on purpose — an exact count goes stale on every PR that adds one; the previous hardcoded 828 was off by over a thousand). |
| `ErsatzTV.Core.Tests` | Domain logic, scheduling, IPTV/XMLTV generation | References `ErsatzTV.Application` directly — there is no separate `Application.Tests` project. ~650 tests + 1 skipped under `TZ=UTC` (the Block playout golden additionally skips under a non-UTC `TZ`; see Golden-file nets). |
| `ErsatzTV.Scanner.Tests` | Library scanning: scan handlers, folder scanners, NFO readers | Handler tests substitute the folder scanners + `ILibraryRepository` and assert the resulting repository writes (e.g. `ScanLocalLibraryHandlerTests` pins which `LastScan` levels a scan records — ersatztv#264). Fakes/`Testably` back the file-system-facing scanners. ~1,485 tests (approximate on purpose — an exact count goes stale on every PR that adds one). Additionally contains `Core/FFmpeg/TranscodingTests` — `[Explicit]` + `[Combinatorial]`, so it never runs in CI or a plain `dotnet test` (it needs real ffmpeg/hardware) and contributes 0 to that count; run it by name when touching the transcoding pipeline. |
| `ErsatzTV.Architecture.Tests` | Layering rules via NetArchTest.eNhancedEdition | Core↛Infra/App/EF; FFmpeg↛all; App↛concrete providers. 5 tests. See `docs/contributing.md` §1. |