Clock-align convenience: one-click per-channel/schedule pad-to-boundary toggle + 60-min increment (SPA) #392

Closed
opened 2026-07-17 01:14:32 +02:00 by timothy · 2 comments
Owner

Follow-up to #77 (the deferred, UI-gated residual).

Context

#77 established that clock-boundary schedule padding (snap to :00/:15/:30) already works — it's FillerMode.Pad + PadToNearestMinute on a FillerPreset for Classic playouts (Sequential has pad_to_next/pad_until; Block is inherently time-anchored). Verified end-to-end by PlayoutBuildGoldenTests.Classic_clock_padded + ChannelGuideProjectorClockPadTests. See docs/decisions.md 2026-07-17.

The one genuine gap is convenience: today, to clock-align a channel you must hand-create a Pad FillerPreset and wire it into a schedule item's PreRoll/MidRoll/PostRoll slot. There is no one-click "align this whole channel/schedule to :30" affordance.

Scope (when unblocked)

  • A per-schedule (ProgramSchedule) or per-channel option: pad to clock boundary + increment, that the Classic builder honours automatically without a hand-wired FillerPreset (backend column + API + builder wiring + SPA control).
  • Add the 60-minute option to the filler-preset editor's PAD_OPTIONS (currently 5/10/15/30; the backend already accepts any integer) — web/src/screens/FillerPresetsScreen.tsx.
  • Decide whether to model Tunarr's pad-per-slot vs pad-per-episode distinction, or leave the current per-item behaviour.

Blocked

Blocked on #388 (design-system sync epic) — all UI work is currently gated on it. The backend column could land first, but its value is mostly the SPA affordance, so keep it together.

Done-when

  • adversarial review passed
  • backend option + API + Classic builder wiring, with tests
  • SPA control added (per #388 design system) + 60-min increment option
  • docs updated (domain-model / decisions / spa-conventions as applicable)
Follow-up to #77 (the deferred, UI-gated residual). ## Context #77 established that clock-boundary schedule padding (snap to :00/:15/:30) **already works** — it's `FillerMode.Pad` + `PadToNearestMinute` on a `FillerPreset` for Classic playouts (Sequential has `pad_to_next`/`pad_until`; Block is inherently time-anchored). Verified end-to-end by `PlayoutBuildGoldenTests.Classic_clock_padded` + `ChannelGuideProjectorClockPadTests`. See `docs/decisions.md` 2026-07-17. The one genuine gap is **convenience**: today, to clock-align a channel you must hand-create a Pad `FillerPreset` and wire it into a schedule item's PreRoll/MidRoll/PostRoll slot. There is no one-click "align this whole channel/schedule to :30" affordance. ## Scope (when unblocked) - A per-schedule (`ProgramSchedule`) or per-channel option: **pad to clock boundary** + increment, that the Classic builder honours automatically without a hand-wired FillerPreset (backend column + API + builder wiring + SPA control). - Add the **60-minute** option to the filler-preset editor's `PAD_OPTIONS` (currently 5/10/15/30; the backend already accepts any integer) — `web/src/screens/FillerPresetsScreen.tsx`. - Decide whether to model Tunarr's **pad-per-slot vs pad-per-episode** distinction, or leave the current per-item behaviour. ## Blocked Blocked on **#388** (design-system sync epic) — all UI work is currently gated on it. The backend column could land first, but its value is mostly the SPA affordance, so keep it together. ## Done-when - [x] adversarial review passed - [x] backend option + API + Classic builder wiring, with tests - [x] SPA control added (per #388 design system) + 60-min increment option - [x] docs updated (domain-model / decisions / spa-conventions as applicable)
timothy added the enhancementpriority: lowfrontend labels 2026-07-17 01:14:32 +02:00
timothy added the in-progress label 2026-07-22 21:02:59 +02:00
Author
Owner

Claiming this — #388 (design-system epic) has closed, so the UI gate is lifted. Starting with a brainstorm on the per-schedule vs per-channel model and the pad-per-slot/episode question before implementing.

Claiming this — #388 (design-system epic) has closed, so the UI gate is lifted. Starting with a brainstorm on the per-schedule vs per-channel model and the pad-per-slot/episode question before implementing.
Author
Owner

Closing record

Outcome: Shipped in PR #573 (merged to main). A per-ProgramSchedule PadToNearestMinute (nullable int) makes the Classic playout builder pad every content item up to the next N-minute clock boundary without a hand-wired Pad FillerPreset — filling each gap with the schedule item's FallbackFiller, else an offline gap. Plus the 60-minute option on the filler-preset editor. Per-schedule (not per-channel); per-episode granularity; item's own Pad filler wins over the schedule pad.
Root cause: n/a (feature, not a bug).
Decisions/conventions changed: added sched.clock-padding-schedule-toggle (extends sched.clock-padding-existing).
Reusable knowledge:

  • FillerMode.Pad was already per-episode (AddFiller runs once per emitted content item), so "pad every episode to a boundary" needed no new per-item loop — just a synthetic content-less pad driven by a schedule-level column, reusing FallbackFillerForPad.
  • The offline advance (no fallback content) is carried by a transient PlayoutSchedulerResult.ClockPadOfflineTarget and the day-seam anchor clamp is exempted by exact equality with it (not a magnitude heuristic) — no persisted anchor schema.
  • Gotcha: Fill-With-Group schedule items are synthesized via Newtonsoft DeepCopy(), and ProgramScheduleItem.ProgramSchedule carries [JsonIgnore], so the reverse nav is lost — any feature reading a schedule-level field inside AddFiller must re-assign the nav on the copy (caught by the whole-branch review, fixed + regression-tested).
  • CI gotcha: the decisions lifecycle job is diff-based (decisions_validate.py --base origin/main --head HEAD) and flags editing an existing record's prose without a [decisions-edit] commit token; the plain local run doesn't catch it. A pure-append decisions diff avoids it.
    Verification: golden + invariant tests across One/Flood/Duration/Multiple and two midnight crossings; precedence test; existing Classic_clock_padded golden byte-identical; full suite green (Core 650/1-skip, ErsatzTV 1829); check:api + model-drift clean both providers; adversarial whole-branch review (1 defect found+fixed); live-E2E round-trip (create=30/update=15/null·0·-5→null); CI green on bb3e245b.
    Deferred: two non-blocking notes (documented in PR #573) — PlayoutModeSchedulerDuration offline-tail leaves clockPadOfflineTarget set-but-stale (harmless; optional = null reset); API accepts pad divisors that don't divide 60 (TZ-dependent guides, consistent with existing FillerPreset; SPA restricts to divisors of 60). No follow-up issue filed — both are minor/optional.
    Docs updated: docs/decisions.md (+ regenerated docs/decisions/README.md), docs/domain-model.md; design-system prototype (FillerPresets.jsx) mirrored + pushed to Claude Design.
## Closing record **Outcome:** Shipped in PR #573 (merged to `main`). A per-`ProgramSchedule` **`PadToNearestMinute`** (nullable int) makes the Classic playout builder pad every content item up to the next N-minute clock boundary without a hand-wired Pad `FillerPreset` — filling each gap with the schedule item's `FallbackFiller`, else an offline gap. Plus the 60-minute option on the filler-preset editor. Per-schedule (not per-channel); per-episode granularity; item's own Pad filler wins over the schedule pad. **Root cause:** n/a (feature, not a bug). **Decisions/conventions changed:** added `sched.clock-padding-schedule-toggle` (extends `sched.clock-padding-existing`). **Reusable knowledge:** - `FillerMode.Pad` was **already per-episode** (`AddFiller` runs once per emitted content item), so "pad every episode to a boundary" needed no new per-item loop — just a synthetic content-less pad driven by a schedule-level column, reusing `FallbackFillerForPad`. - The offline advance (no fallback content) is carried by a **transient** `PlayoutSchedulerResult.ClockPadOfflineTarget` and the day-seam anchor clamp is exempted by **exact equality** with it (not a magnitude heuristic) — no persisted anchor schema. - **Gotcha:** Fill-With-Group schedule items are synthesized via Newtonsoft `DeepCopy()`, and `ProgramScheduleItem.ProgramSchedule` carries `[JsonIgnore]`, so the reverse nav is lost — any feature reading a schedule-level field inside `AddFiller` must re-assign the nav on the copy (caught by the whole-branch review, fixed + regression-tested). - **CI gotcha:** the `decisions lifecycle` job is **diff-based** (`decisions_validate.py --base origin/main --head HEAD`) and flags editing an existing record's prose without a `[decisions-edit]` commit token; the plain local run doesn't catch it. A pure-append decisions diff avoids it. **Verification:** golden + invariant tests across One/Flood/Duration/Multiple and two midnight crossings; precedence test; existing `Classic_clock_padded` golden byte-identical; full suite green (Core 650/1-skip, ErsatzTV 1829); `check:api` + model-drift clean both providers; adversarial whole-branch review (1 defect found+fixed); **live-E2E** round-trip (create=30/update=15/null·0·-5→null); CI green on `bb3e245b`. **Deferred:** two non-blocking notes (documented in PR #573) — `PlayoutModeSchedulerDuration` offline-tail leaves `clockPadOfflineTarget` set-but-stale (harmless; optional `= null` reset); API accepts pad divisors that don't divide 60 (TZ-dependent guides, consistent with existing `FillerPreset`; SPA restricts to divisors of 60). No follow-up issue filed — both are minor/optional. **Docs updated:** `docs/decisions.md` (+ regenerated `docs/decisions/README.md`), `docs/domain-model.md`; design-system prototype (`FillerPresets.jsx`) mirrored + pushed to Claude Design.
timothy removed the in-progress label 2026-07-23 09:27:11 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: timothy/ersatztv#392