docs: add upstream tracking comments to plasma-bigscreen files

Flag the custom derivation and workarounds as temporary with TODO
markers and links to the relevant nixpkgs issue/PR. Makes it clear
what to remove once plasma-bigscreen lands in nixpkgs.

flake.nix

@@ -172,6 +172,7 @@
         ./machines/boxy/configuration.nix
         {
           home-manager.users.johno = import ./home/home-media-center.nix;
+          # kodi user: AVR volume control + minimal Plasma config for Bigscreen session
           home-manager.users.kodi = import ./home/home-kodi.nix;
           home-manager.extraSpecialArgs = { inherit system; };
         }

machines/boxy/configuration.nix

@@ -22,12 +22,11 @@ with lib;
       sddm = true;
       wayland = true;
     };
-    kodi = {
+    plasma-bigscreen = {
       enable = true;
       autologin = true;
-      wayland = true;
-      appLauncherServer.enable = true;
       jellyfinScaleFactor = 1.0;
+      appLauncherServer.enable = true;
     };
     nfs-mounts.enable = true;
     users.enable = true;
@@ -72,4 +71,3 @@ with lib;
   system.stateVersion = "24.05"; # Did you read the comment?
 
 }
-

roles/default.nix

@@ -12,6 +12,7 @@ with lib;
     ./k3s-node
     ./kodi
     ./nfs-mounts
+    ./plasma-bigscreen
     ./nvidia
     ./printing
     ./rclone-mount

roles/plasma-bigscreen/default.nix

@@ -0,0 +1,134 @@
+{ config, lib, pkgs, ... }:
+
+with lib;
+
+let
+  cfg = config.roles.plasma-bigscreen;
+
+  # Plasma Bigscreen package — not yet in nixpkgs, built from upstream master.
+  # TODO: Replace with pkgs.kdePackages.plasma-bigscreen once available.
+  plasma-bigscreen = pkgs.kdePackages.callPackage ./package.nix {};
+
+  jellyfinMediaPlayerPkg =
+    if cfg.jellyfinScaleFactor != null
+    then pkgs.symlinkJoin {
+      name = "jellyfin-media-player-scaled";
+      paths = [ pkgs.qt-pinned.jellyfin-media-player ];
+      nativeBuildInputs = [ pkgs.makeWrapper ];
+      postBuild = ''
+        mkdir -p $out/bin
+        rm -f $out/bin/jellyfin-desktop
+        makeWrapper ${pkgs.qt-pinned.jellyfin-media-player}/bin/jellyfin-desktop $out/bin/jellyfin-desktop \
+          --add-flags "--tv --scale-factor ${toString cfg.jellyfinScaleFactor}"
+
+        # Update .desktop file to include scale factor and TV mode arguments
+        mkdir -p $out/share/applications
+        rm -f $out/share/applications/org.jellyfin.JellyfinDesktop.desktop
+        substitute ${pkgs.qt-pinned.jellyfin-media-player}/share/applications/org.jellyfin.JellyfinDesktop.desktop \
+          $out/share/applications/org.jellyfin.JellyfinDesktop.desktop \
+          --replace-fail "Exec=jellyfin-desktop" "Exec=jellyfin-desktop --tv --scale-factor ${toString cfg.jellyfinScaleFactor}"
+      '';
+    }
+    else pkgs.qt-pinned.jellyfin-media-player;
+in
+{
+  options.roles.plasma-bigscreen = {
+    enable = mkEnableOption "Plasma Bigscreen TV interface";
+
+    autologin = mkOption {
+      type = types.bool;
+      default = false;
+      description = "Auto-login to Plasma Bigscreen session";
+    };
+
+    user = mkOption {
+      type = types.str;
+      default = "kodi";
+      description = "User account for the Bigscreen session";
+    };
+
+    jellyfinScaleFactor = mkOption {
+      type = types.nullOr types.float;
+      default = null;
+      description = "Scale factor for Jellyfin Media Player UI (e.g., 1.0 for 100% scaling)";
+    };
+
+    appLauncherServer = {
+      enable = mkOption {
+        type = types.bool;
+        default = false;
+        description = "Enable HTTP app launcher server for remote control";
+      };
+      port = mkOption {
+        type = types.int;
+        default = 8081;
+        description = "Port for the app launcher HTTP server";
+      };
+    };
+  };
+
+  config = mkIf cfg.enable {
+    # Create the bigscreen user
+    users.extraUsers.${cfg.user} = {
+      isNormalUser = true;
+      extraGroups = [ "wheel" "networkmanager" "audio" "video" ];
+    };
+
+    # Plasma Bigscreen is a Plasma 6 shell — needs Plasma 6 desktop manager
+    services.desktopManager.plasma6.enable = true;
+
+    # Register the bigscreen session with the display manager
+    services.displayManager = {
+      sessionPackages = [ plasma-bigscreen ];
+    } // optionalAttrs cfg.autologin {
+      autoLogin.enable = true;
+      autoLogin.user = cfg.user;
+      defaultSession = "plasma-bigscreen-wayland";
+    };
+    xdg.portal.configPackages = [ plasma-bigscreen ];
+
+    # Fix homescreen not being focused after quitting app or on boot
+    # xwaylandvideobridge can interfere with focus; exclude if present
+    environment.plasma6.excludePackages =
+      lib.optional (pkgs.kdePackages ? xwaylandvideobridge) pkgs.kdePackages.xwaylandvideobridge;
+
+    # Firewall for remote control
+    networking.firewall = {
+      allowedTCPPorts = optional cfg.appLauncherServer.enable cfg.appLauncherServer.port;
+    };
+
+    environment.systemPackages = with pkgs; [
+      plasma-bigscreen
+      firefox
+      jellyfinMediaPlayerPkg
+      qt-pinned.stremio
+      wget
+    ] ++ optional cfg.appLauncherServer.enable pkgs.custom.app-launcher-server;
+
+    nixpkgs.config.permittedInsecurePackages = lib.warn
+      "Allowing insecure package qtwebengine-5.15.19 as a jellyfin-media-player/stremio dependency."
+      [
+        "qtwebengine-5.15.19"
+      ];
+
+    programs.kdeconnect.enable = true;
+
+    systemd.user.services = mkIf cfg.appLauncherServer.enable {
+      app-launcher-server = {
+        description = "HTTP App Launcher Server";
+        wantedBy = [ "graphical-session.target" ];
+        after = [ "graphical-session.target" ];
+        serviceConfig = {
+          Type = "simple";
+          ExecStart = "${pkgs.custom.app-launcher-server}/bin/app-launcher-server ${toString cfg.appLauncherServer.port}";
+          Restart = "always";
+          RestartSec = "5s";
+          Environment = [
+            "PATH=${pkgs.firefox}/bin:/run/current-system/sw/bin"
+          ];
+        };
+      };
+    };
+
+  };
+}

roles/plasma-bigscreen/package.nix

@@ -0,0 +1,131 @@
+# Plasma Bigscreen — TV interface for Plasma 6
+# Not yet released or packaged in nixpkgs; built from upstream master.
+#
+# TODO: Remove this file once plasma-bigscreen lands in nixpkgs.
+#   Tracking issue: https://github.com/NixOS/nixpkgs/issues/428077
+#   Draft nixpkgs PR: https://github.com/NixOS/nixpkgs/pull/428353
+#   When available, switch to pkgs.kdePackages.plasma-bigscreen.
+#
+# Upstream: https://invent.kde.org/plasma/plasma-bigscreen
+{
+  mkKdeDerivation,
+  lib,
+  fetchFromGitLab,
+  pkg-config,
+  # KDE Frameworks 6
+  ki18n,
+  kdeclarative,
+  kcmutils,
+  knotifications,
+  kio,
+  kwayland,
+  kwindowsystem,
+  ksvg,
+  kiconthemes,
+  kglobalaccel,
+  kdbusaddons,
+  # KDE Plasma 6
+  plasma-workspace,
+  plasma-nano,
+  plasma-nm,
+  plasma-activities,
+  plasma-activities-stats,
+  milou,
+  libkscreen,
+  kdeconnect-kde,
+  # Qt 6
+  qtdeclarative, # needed for Qt6::QmlPrivate — see QCoro workaround in postPatch
+  qtmultimedia,
+  qtwebengine,
+  # Other
+  bluez-qt,
+  qcoro,
+  plasma-wayland-protocols,
+  wayland,
+  sdl3,
+}:
+
+mkKdeDerivation {
+  pname = "plasma-bigscreen";
+  version = "unstable-2026-03-07";
+
+  src = fetchFromGitLab {
+    domain = "invent.kde.org";
+    owner = "plasma";
+    repo = "plasma-bigscreen";
+    rev = "bd143fea7e386bac1652b8150a3ed3d5ef7cf93c";
+    hash = "sha256-y439IX7e0+XqxqFj/4+P5le0hA7DiwA+smDsD0UH/fI=";
+  };
+
+  extraNativeBuildInputs = [
+    pkg-config
+  ];
+
+  extraBuildInputs = [
+    # KDE Frameworks
+    ki18n
+    kdeclarative
+    kcmutils
+    knotifications
+    kio
+    kwayland
+    kwindowsystem
+    ksvg
+    kiconthemes
+    kglobalaccel
+    kdbusaddons
+    # Plasma
+    plasma-workspace
+    plasma-nano
+    plasma-nm
+    plasma-activities
+    plasma-activities-stats
+    milou
+    libkscreen
+    kdeconnect-kde
+    # Qt — qtdeclarative is needed for Qt6::QmlPrivate (see postPatch)
+    qtdeclarative
+    qtmultimedia
+    qtwebengine
+    # Other
+    bluez-qt
+    qcoro
+    plasma-wayland-protocols
+    wayland
+    sdl3
+  ];
+
+  postPatch = ''
+    substituteInPlace bin/plasma-bigscreen-wayland.in \
+      --replace @KDE_INSTALL_FULL_LIBEXECDIR@ "${plasma-workspace}/libexec"
+
+    # WORKAROUND: Plasma version numbers must match; we're building an
+    # unreleased package against a stable Plasma release. Remove once
+    # bigscreen is part of the Plasma release cycle.
+    substituteInPlace CMakeLists.txt \
+      --replace-fail 'set(PROJECT_VERSION "6.5.80")' 'set(PROJECT_VERSION "${plasma-workspace.version}")'
+
+    # WORKAROUND: QCoro6Qml's cmake config links against Qt6::QmlPrivate but
+    # doesn't call find_package to import the target. This is arguably a QCoro
+    # packaging bug in nixpkgs (it should propagate qtdeclarative). Remove
+    # once QCoro or the nixpkgs plasma-bigscreen package is fixed upstream.
+    substituteInPlace CMakeLists.txt \
+      --replace-fail 'find_package(QCoro6' 'find_package(Qt6 ''${QT_MIN_VERSION} CONFIG REQUIRED COMPONENTS QmlPrivate)
+find_package(QCoro6'
+  '';
+
+  preFixup = ''
+    wrapQtApp $out/bin/plasma-bigscreen-wayland
+  '';
+
+  passthru.providedSessions = [
+    "plasma-bigscreen-wayland"
+  ];
+
+  meta = {
+    description = "Plasma shell for TVs (Plasma Bigscreen)";
+    homepage = "https://plasma-bigscreen.org";
+    license = lib.licenses.gpl2Plus;
+    platforms = lib.platforms.linux;
+  };
+}