Commit Graph
13 Commits
Author SHA1 Message Date
timothy 4804aa90f2 docs(732): sweep the shared create-time helper through the prose it did not reach
Build ErsatzTV Image / CI toolchain image resolves (pull_request) Successful in 6s
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 10s
PR Gates / Docs update reminder (pull_request) Successful in 12s
Build ErsatzTV Image / Delimiter ban (release path) (pull_request) Successful in 21s
PR Gates / Fix proofs (Proves trailers) (pull_request) Successful in 13s
Review verdict / Set review-verdict status (pull_request_target) Successful in 15s
PR Gates / decisions lifecycle (pull_request) Successful in 22s
PR Gates / Script lint and tests (ruff + pytest) (pull_request) Successful in 5m51s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 8m40s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 5m59s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Skipped
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Successful in 6m6s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 8s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 6s
review-verdict/h10 Review-verdict: MERGEABLE @ 4804aa9 (base: main)
The round-6 extraction changed the code and left three written references pointing at the old shape.
The record BODY was correct; the parts that get read in isolation were not.

The catalog `rule:` and the record frontmatter still said the default is attached "by
CreateChannelHandler" - and that line is the retrieval abstract, so a maintainer resolving this key,
or reading the MemPalace drawer mirrored from it, would have learned exactly the misconception that
caused the round-6 blocker: that the blank-channel path is where the default lives. `signals:` named
only that file too. Both now name ChannelGraphicsDefaults.Attach and both create paths.

The XML remarks on AttachOnNowNextByDefault had the same omission, in the file a reader lands on when
tracing the backfill. And mutation row 12 named AttachDefaultGraphicsElements, a method deleted in the
extraction - the table tells readers to reproduce a row by making the edit, which they cannot do by
grepping for a symbol that no longer exists.

Also dropped the pinned render md5. The invariant it was defending - the seeded template renders
identically with and without the per-style halo merge - holds on any host; the hash does not, because
the render depends on the host's fonts. A future reader checking the number on a different font set
would get a mismatch with no way to tell whether the invariant had actually broken. The doc now states
the invariant and how to re-derive it.

Decisions-Edit: yes
Refs: #732
2026-08-26 20:37:06 +02:00
timothy 7858ee6d2d test(732): re-measure all 32 rows after the shared create-time helper
Three rows moved, each a correct consequence of the round-6 fixes. Rows 1 and 4 gain the new
opacity-clamp test. Row 13 is the useful one: disarming the HLS-Direct exclusion now reddens the
tests for BOTH create paths, which is the evidence that the shared helper actually covers them rather
than just looking like it does.

Thirteen rows redden more than one test and two span two fixture classes - both figures taken from
the run, not from the previous version of the sentence.

Refs: #732
2026-08-26 20:37:06 +02:00
timothy 60e52cfd7c fix(732): attach the default overlay on the lineup create path too, via one shared helper
A functional gap, found by cold review and confirmed against the source: there are THREE places that
persist a Channel, and only one of them attached the built-in element.

CreateChannelFromLineupHandler is the SPA's primary "Add Channel" flow and the command Auto-Tune
bulk-creates through, and it attached nothing. Because the backfill writes its marker on the first
boot after upgrade, channels created there would never get the overlay - no log line, no UI
difference, no way back except toggling each one by hand. So the secondary "New blank channel" button
got the feature and the primary one did not.

The third site, DbInitializer's default channel, needs no call: it runs before
AttachOnNowNextByDefault in the same startup, so the backfill covers it. That one came from sweeping
`Channels.Add` rather than from the review, which is the point - the population is derivable from the
source and was not derived when the create-time default was first written.

Both create paths now call ChannelGraphicsDefaults.Attach, so they cannot drift apart again, and the
record says three sites with the grep that finds them rather than an enumeration that reads as
closed.

Also closes the round-6 follow-ups: the 0-100 opacity clamp now has a test (mutating Math.Clamp away
reddens it); the schema reference no longer claims an unparseable non-base halo_color leaves the halo
unset, when it inherits the base style's; and the rendered-bitmap md5 carries the command that
re-derives it.

Two tests were REMOVED rather than shipped: one for the cleanup-exception guard and one for the
no-inset legacy budget branch. Both were green with their clause disarmed - MockFileSystem does not
propagate an interceptor throw raised during a delete, and a MaxWidth of 0 and 1 render identically.
They are recorded as known-unreachable clauses with those reasons instead.

Decisions-Edit: yes
Refs: #732
2026-08-26 20:37:06 +02:00
timothy 12efaa8c41 test(732): re-measure the whole table after adding three clauses and their tests
Thirty rows, all red, eleven reddening more than one fixture. One row moved: dropping HaloColor from
FitTextBlock now also reddens the new blur test, because that test declares a halo colour too.

Added a note that rows are written per clause rather than per block. Block-level rows are what hid
the per-field gap a cold review found - a row naming the whole style-merge block read as covering it,
while HaloBlur inside that block had no reachable test.

Refs: #732
2026-08-26 20:37:06 +02:00
timothy 04ff11f854 test(732): cover the three clauses a cold review measured as having no red
Round 5 enumerated the guards independently and ran the full suite against each: `HaloBlur` and
`LineHeight` in FitTextBlock's rebuilt style, and the per-style `HaloBlur` override in
BuildTextStyles, could all be deleted with 2062 tests green. All three were added by the round-4 fix
commit - the same commit that rewrote the mutation-coverage paragraph and warned that adding a guard
without its row makes that paragraph false. It did exactly that, three times, in itself.

The blanket claim is already gone. These three now have differential tests and measured rows, so they
are covered rather than merely unclaimed. The existing halo rows were written at whole-block
granularity, which is what hid the per-field gap: HaloColor and HaloWidth were reachable, HaloBlur was
not.

Also disclosed: the per-style halo fix and the Scale path now carrying line_height are
operator-visible changes for custom templates, which belongs in the release notes rather than only in
a commit message. And a comment on the schema still said an unset background_color means no box at
all, which the border-only path and its own test contradict.

Refs: #732
2026-08-26 20:37:06 +02:00
timothy c3529ec706 fix(732): stop asserting mutation-coverage completeness, and keep cleanup from masking cancellation
The completeness sentence was wrong a third time - a different clause each round - so it is gone
rather than corrected again. "The only uncovered clause is X" silently becomes false the moment a
guard is added without its row, which is a property of the sentence, not of the reviewers who kept
falsifying it. The table now says what it IS (clauses with a measured proof) and explicitly makes no
claim about what is absent, with the known no-red clauses listed as examples rather than a closed set.

Cleanup could replace the exception that triggered it. A delete throwing while unwinding a
cancellation swapped the OperationCanceledException for an IOException, which the outer filter then
swallowed - downgrading a real shutdown to a warning, the one case that filter deliberately lets
through. The cleanup now catches its own failures and logs them.

The frame-cap test hardcoded 540 - one 1080p result rather than the documented rule - so changing the
test frame size would have failed correct production code. Derived from Math.Min(w, h) / 2 now.

Also removed a chronology clause from the doc that the narrative checker does not catch but the rule
forbids.

Decisions-Edit: yes
Refs: #732
2026-08-26 20:37:06 +02:00
timothy 8eab7baf58 docs(732): record that the per-style halo fix leaves the seeded template byte-identical
The halo fix changes a renderer that has already shipped, so the question is what it does to the one
template we ship. Measured rather than reasoned: the seeded on-now-next.yml renders to the same
bitmap with and without the fix (md5 0663AF1E13C558F4DB99F887318E275D, 1920x1080), because all three
of its styles declare the same halo - which is also why the bug was invisible. A third-party template
that varies halo per style will change, which is the point.

Refs: #732
2026-08-26 20:37:06 +02:00
timothy 37a2f5299d test(732): re-measure all 27 mutation rows after the round-4 fixes
Adding the frame-cap and per-style-halo clauses, renaming a test and tightening one assertion can all
move a red set, so the whole table was re-measured against the full project rather than patched.
Twenty-seven rows, all red, nine of them reddening more than one fixture. Only rows 5 and 14 actually
moved, and only by the test rename - the rest reproduced exactly, which is the first time the table
has been re-derived and found already correct.

Refs: #732
2026-08-26 20:37:06 +02:00
timothy 666d476417 fix(732): give the frame cap a proof, fix a per-style halo bug, and correct two false claims
Round-4 review, both reviewers BLOCKED. The blocker was the same shape this branch keeps producing:
a completeness claim stated in words rather than derived.

The frame cap on the inset, added one round earlier, had NO test and NO mutation row. Disarming the
clause left the whole 2064-test suite green. The nearest candidate could not see it: its bound was
`baseline + 25_000` while the clause prevents growth of 20_000 on a 1080p frame, i.e. the assertion
was looser than the defect. Worse, the mutation record written the following commit asserted that
exactly one clause was uncovered, naming a different one - a false enumeration in the doc that exists
to prevent false enumerations. Now: a test pinning the cap, a tightened bound on the sibling, two
mutation rows, the cap documented in the geometry notes, and the "not covered" paragraph rewritten as
a claim that decays when a guard is added without its row.

`Environment.ProcessId` is 1 in every container. The image's ENTRYPOINT is exec form, so each
container is PID 1 in its own namespace and they all compute the same temp name - the mitigation was
inert in exactly the deployment the record cited for it. Two containers on one config volume could
still truncate each other's temp file and rename a partial one over the live template, which is the
outcome write-then-move exists to prevent. Random name now, record corrected.

Per-style halo was documented as working and silently discarded. The merge loop rebuilt each style
from base and overrode only font and colour, so a non-base style's halo_* inherited the base style's.
The seeded template hid it by declaring identical halos on all three styles. Three lines, symmetric
with the existing overrides, plus a differential test.

Also: an assertion on `_target + ".upgrade.tmp"` was unfalsifiable once the temp name gained a
suffix - a path the code can never create, passing with the cleanup gutted; a test named
An_Unreadable_Template actually simulates an unwritable one, renamed; a comment described the wrong
channel as cleared.

Decisions-Edit: yes
Refs: #732
2026-08-26 20:37:06 +02:00
timothy 9dc0789767 test(732): re-measure the mutation table against the whole project, not a per-fixture filter
The table asserted its "Reddens" column was measured, and it was - through
`--filter FullyQualifiedName~<fixture>`, which structurally cannot observe a red in another fixture.
A measurement with a blind spot presented as a measurement is worse than none, and it was the table's
own documented reproduce command that carried the blind spot.

Re-measured by running the whole ErsatzTV.Tests project per mutation. Eight of the twenty-four rows
redden more than one fixture and were previously under-reported - including the row a cold review
caught by hand, which reddens `An_Already_Seeded_Install_Missing_Its_Element_Row_Gets_One` AND
`Repeated_Seeding_Does_Not_Accumulate_Element_Rows`, not one of them.

The reproduce instruction now says to run the project unfiltered, and the reason is stated so the
next person does not reintroduce the filter for speed.

The mutation harness also grew a guard: it restores with `git checkout --`, so an uncommitted change
to a file it mutates was silently reverted. It now refuses to run when a mutated file is dirty.

Decisions-Edit: yes
Refs: #732
2026-08-26 20:37:06 +02:00
timothy 7523fabbf3 test(732): re-derive the mutation record from a fresh measurement, and fix the two claims it broke
The table in docs/graphics-elements.md asserted 19 clause-level results carried over from notes. Two
were false: one named a test that had since been renamed, and one claimed a red for a clause whose
mutation reddened nothing. Every row is now generated from a fresh run against this tree, and the
"Reddens" column is the measured failure set rather than a prediction.

Re-measuring found two tests passing for the wrong reason.

The atomicity test could not see what it claimed. Testably raises its interception BEFORE truncating,
so a plain in-place WriteAllTextAsync leaves the original intact too and "the file survived" is true
either way - on a real filesystem it would not be. The test now captures which PATH the write targets
and requires it to be the temp file, which is what actually distinguishes the two, and reverting the
atomic write reddens it.

The non-finite width_percent test set no background fields, so the budget was never converted to an
int and the guard it was named for could be deleted with the test still green. It now carries a box.

The float.IsFinite guard on the width budget is recorded as NOT covered by any mutation: .NET
saturates float-to-int conversion, so removing it changes no observable behaviour. It stays as
explicit intent, said out loud rather than implied by omission.

Also recorded: warnings-as-error turn the obvious mutation shapes (if (true) return, self-assignment,
a constant-folded condition) into build failures that emit no test summary and read like a pass, and
detecting that needs `: error `, not `error CS`.

Decisions-Edit: yes
Refs: #732
2026-08-26 20:37:06 +02:00
timothy bef3f54798 fix(732): close the review findings on the background box and the default attach
Two independent cold reviews (Codex GPT-5.6 and a worktree-isolated Opus agent) converged on the
same three serious problems; both returned BLOCKED.

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

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

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

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

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

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

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

Decisions-Edit: yes
Refs: #732
2026-08-26 20:37:06 +02:00
timothy 0ab52ad71c feat(732): give the On Now / Next overlay a background box and turn it on by default
Part 1 - background box. TextGraphicsElement gains element-level background_color,
background_opacity_percent, background_padding, background_corner_radius, border_color and
border_width; TextElement draws a rounded rect behind the text block and insets the text into it.
Element level rather than per-style because the engine lays the whole element out as one
RichTextKit TextBlock and rasterises it into one bitmap, so one box per element is the only shape
the renderer can express. width_percent keeps bounding the visible element, so the insets are
subtracted from the text's wrap/scale budget.

The seeded on-now-next.yml adopts it. The halo drops from 2px to 1px rather than to zero, and the
box carries a low-alpha white border: rendered against real frames, a 65% black fill is legible on
bright and midtone content but vanishes entirely into dark content, which is why the issue asked
for an *outlined* box. The halo still matters because the fill is translucent.

Because #74's seeder writes the template only when absent, an already-seeded install would never
have seen any of this. GraphicsElementSeeder now keeps every default it has shipped as a verbatim
fingerprint and rewrites the file only when it still matches one (line-endings normalised), so an
untouched install upgrades and an operator-edited one is left alone. The V1 fingerprint was checked
byte-for-byte against the live install before being trusted - a fingerprint that matches nothing in
the field is a permanent silent no-op.

Part 2 - on by default. New channels get the built-in element from CreateChannelHandler (CreateChannel
carries 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 get a one-time AttachOnNowNextByDefault
backfill. The marker is written on the first run even when nothing was attached: the tempting
alternative - stay armed until the element row exists - would fire on a later boot and re-attach the
overlay to a channel the operator had cleared in between. HLS Direct is excluded at both sites,
where the overlay cannot render at all.

Resolves the issue's open question: [vge] in a filter graph does not imply a graphics element is
bound. Watermarks fall back onto the graphics engine whenever they cannot use ffmpeg's native
overlay shortcut, so a watermark alone produces that stage.

Tests assert rendered pixels, because every failure mode here is a silent no-op that a model-level
test cannot see. 13 clause mutations were executed against them; each reddened only its own clause.

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