feat: Add support for Kairos layer effects

[nytamin]

About the Contributor

This pull request is posted on behalf of the NRK.

Type of Contribution

This is a: Feature

Current Behavior

TSR doesn't currently support controlling Kairos Scene-Layer-Effects.

New Behavior

Adds control of Kairos Scene-Layer-Effects.

Status

• PR is ready to be reviewed.
• The functionality has been tested by the author.
• Relevant unit tests has been added / updated.
• Relevant documentation (code comments, system documentation) has been added / updated.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Walkthrough

Adds end-to-end support for a new Kairos scene-layer-effect content type. This includes a new SCENE_LAYER_EFFECT enum value and TimelineContentKairosSceneLayerEffect type, a JSON mapping schema, state builder integration, a diffSceneLayerEffects helper, a KairosSceneLayerEffectCommand dispatch targeting 16 effect variants, application monitor awareness checks, and temporal priority graph wiring. A corresponding diffState test covers luminanceKey.

Changes

Kairos scene-layer-effect end-to-end support

Layer / File(s)	Summary
Public types and mapping schema packages/timeline-state-resolver-types/src/integrations/kairos/timeline.ts, packages/timeline-state-resolver/src/integrations/kairos/$schemas/mappings.json	Adds SCENE_LAYER_EFFECT enum entry, TimelineContentKairosSceneLayerEffect interface, TimelineContentKairosSceneAnySceneLayerEffect discriminated union with partial UpdateEffect*Object payloads per effect kind, and the scene-layer-effect JSON mapping schema with effectType, sceneName, layerName, effectName, and temporalPriority fields.
KairosDeviceState extension and state building packages/timeline-state-resolver/src/integrations/kairos/stateBuilder.ts	Adds sceneLayerEffects record to KairosDeviceState, exports KairosDeviceStateSceneLayerEffects type and getLayerEffectEffectName helper, implements _applySceneLayerEffect to validate names and merge effect content, and extends lookupMappingRef for scene-layer-effect refs.
Command interface and state diffing packages/timeline-state-resolver/src/integrations/kairos/commands.ts, packages/timeline-state-resolver/src/integrations/kairos/diffState.ts	Defines KairosSceneLayerEffectCommand, extends KairosCommandAny, adds a sendCommand dispatch for 'scene-layer-effect' routing to kairos.updateSceneLayerEffect* per effect type (with assertNever guard), and adds diffSceneLayerEffects wired into diffKairosStates.
Application monitor and temporal priority packages/timeline-state-resolver/src/integrations/kairos/kairos-application-monitor.ts, packages/timeline-state-resolver/src/integrations/kairos/temporal-priority.ts	Extends applyMappings() to register refSceneLayerEffect for SceneLayerEffect mappings and adds an existence check via kairos.listSceneLayerEffects; wires SceneLayerEffect into buildDependencyGraph and adds scene-layer-effect to the orderCommandsByTemporalPriority ref-based ordering set.
Tests packages/timeline-state-resolver/src/integrations/kairos/__tests__/diffState.spec.ts, packages/timeline-state-resolver/src/integrations/kairos/__tests__/lib.ts	Adds mainSceneBackgroundLayerLuminance to DEFAULT_MAPPINGS, introduces a Set LuminanceKey of SceneLayer test asserting the correct scene-layer-effect command and sourceKey payload, and extends EMPTY_STATE with sceneLayerEffects: {}.

Sequence Diagram(s)

sequenceDiagram
  participant Timeline
  participant KairosStateBuilder
  participant diffKairosStates
  participant sendCommand
  participant KairosAPI

  Timeline->>KairosStateBuilder: fromTimeline(MappingKairosType.SceneLayerEffect)
  KairosStateBuilder->>KairosStateBuilder: _applySceneLayerEffect → sceneLayerEffects[ref]
  KairosStateBuilder-->>diffKairosStates: KairosDeviceState (old, new)
  diffKairosStates->>diffKairosStates: diffSceneLayerEffects → KairosSceneLayerEffectCommand[]
  diffKairosStates->>sendCommand: scene-layer-effect command
  sendCommand->>KairosAPI: updateSceneLayerEffect*(ref, values)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Sofie-Automation/sofie-timeline-state-resolver#425: This PR extends KairosApplicationMonitor introduced in #425 by adding MappingKairosType.SceneLayerEffect tracking and an explicit scene-layer-effect realm existence check in the status loop.
• Sofie-Automation/sofie-timeline-state-resolver#441: This PR extends the Kairos temporal-priority framework from #441 by wiring scene-layer-effect into buildDependencyGraph and orderCommandsByTemporalPriority.
• Sofie-Automation/sofie-timeline-state-resolver#449: This PR extends the KairosTSRMappingRef/lookupMappingRef source-resolution machinery introduced in #449 to resolve scene-layer-effect mapping refs.

Suggested reviewers

• jstarpl

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main feature: adding support for Kairos layer effects, which aligns with all the changes across the codebase.
Description check	✅ Passed	The description accurately explains the current behavior (lack of Kairos Scene-Layer-Effects control), the new behavior (adding that control), and correctly identifies this as a feature contribution from NRK.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed. For unrecoverable errors, disable the tool in CodeRabbit configuration.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud