Bootstrap bundled plugins after legacy updates

.env.example

@@ -37,3 +37,15 @@ AUTO_UPDATE_ENABLED=false
 AUTO_UPDATE_INTERVAL_MINUTES=60
 GIT_REMOTE=origin
 GIT_BRANCH=main
+
+# Lumi host operator identity shown in generated Companion pairing packages.
+# Set these when distributing Companion from a self-hosted Lumi installation.
+LUMI_OPERATOR_NAME=
+LUMI_OPERATOR_CONTACT=
+LUMI_OPERATOR_PRIVACY_URL=
+
+# Runtime mode and bind host
+# Lumi auto-detects development mode from NODE_ENV, a loopback bind host, or a
+# source checkout. Explicit overrides always win.
+# LUMI_DEV_MODE=true
+# LUMI_HOST=127.0.0.1

.gitignore

@@ -31,3 +31,4 @@ Twitch.png
 twitch-credentials-lumi.png
 .secrets
 .secrets-*
+DEVNOTES.md

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Lumi changelog
 
+## 0.2.27
+
+- Completed bundled-plugin synchronization automatically on the first startup after a legacy core-only update, allowing production hosts on 0.2.25 to receive the Companion transcription and Song Overlay plugins in the same update flow.
+- Added a second snapshot-backed plugin synchronization boundary with automatic restoration, exact-release verification, preserved plugin data, and an idempotent completion marker.
+
+## 0.2.26
+
+- Added stable Lumi Companion distribution with a durable per-user installer, shared paired-device authentication, managed OBS integration, preserved identity, user-approved updates, complete legal notices, and matching application/tray branding.
+- Added server-hosted transcription with voice-free readiness checks, dedicated confidence and latency benchmarks, resilient worker recovery, detailed WebUI analysis, and no speech inference on the streaming computer.
+- Added Spotify-backed Song Overlay capture, transparent and live-updating OBS rendering, configurable announcements, and a shared-template `!music` command.
+- Made stable core updates snapshot, synchronize, verify, and restore bundled plugins as one transaction while preserving plugin data and local-only plugins, so hosts on `0.2.25` receive the full release in one update.
+- Stopped notification-area flicker by caching health icons, coalescing queued runtime state, and avoiding unchanged native icon/menu assignments.
+
 ## 0.2.25
 
 - Added verified, snapshot-backed production deployment switching between `main` and exact `experimental-*` branches, including bundled plugin code, preserved plugin data, automatic failed-apply restoration, and graceful wrapper restarts.

TODO.md

@@ -54,10 +54,28 @@ Experimental.8 makes the installed single-file build discover and verify its OBS
 payload deterministically, adds an executable-level package diagnostic, and shows
 OBS maintenance failures directly instead of leaving them only in diagnostics.
 
+Experimental.9 coalesces OBS callbacks into fixed 20 ms network frames and gives
+audio and initial OBS source inventory their own soft gateway budgets, so normal
+or pathological capture cadence cannot rate-limit and disconnect the Companion
+control connection.
+
+Experimental.10 deduplicates OBS source inventories and unchanged source-state
+notifications at both ends, removing the high-volume source-update feedback seen
+with large scene collections while retaining the non-disconnecting safety budget.
+
+Experimental.11 removes server-side inference backlog, filters whisper.cpp
+control tokens, preserves first-visible word latency while retaining finalized
+confidence, and makes manual test completion wait for the final worker result.
+The portable CUDA 12.4 worker targets RTX 3060 and newer NVIDIA GPUs, activates
+from the Lumi WebUI without a host SDK dependency, and retains a CPU
+compatibility package. On the RTX 3080 Ti acceptance phrase, `small.en` returned
+the exact 19-word transcript at 300 ms average, 106 ms median, and 1,007 ms maximum
+first-visible latency.
+
 Release-blocking work remains:
 
-- Package the native whisper.cpp worker as the Windows CUDA runtime, then benchmark
-  `small.en`, quantized `small.en`, and `base.en` on the RTX 3060.
+- Repeat the `small.en` latency gate and benchmark quantized `small.en` and
+  `base.en` on the production RTX 3060.
 - Sign the companion installer and add a rollback policy after the experimental
   updater has target-machine acceptance evidence.
 - Complete target-machine bridge acceptance and source rename/missing recovery.

companion/Lumi.Companion.sln

@@ -5,6 +5,8 @@ VisualStudioVersion = 17.0.31903.59
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{827E0CD3-B72D-47B6-A68D-7590B98EB39B}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Lumi.Companion.Abstractions", "src\Lumi.Companion.Abstractions\Lumi.Companion.Abstractions.csproj", "{0B3C2C62-2CCB-43C9-9AF9-769AC7F22285}"
+EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Lumi.Companion.Protocol", "src\Lumi.Companion.Protocol\Lumi.Companion.Protocol.csproj", "{3703AF57-828D-4E2F-BFBA-A95833555A5A}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Lumi.Companion.Core", "src\Lumi.Companion.Core\Lumi.Companion.Core.csproj", "{0BDAE25E-C487-456D-A465-41A0CA48AF30}"
@@ -17,6 +19,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "plugins", "plugins", "{07D5
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Lumi.Companion.Transcription", "plugins\Lumi.Companion.Transcription\Lumi.Companion.Transcription.csproj", "{49C19CA8-4669-4C33-B3A8-9CB934CD1171}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Lumi.Companion.SongOverlay", "plugins\Lumi.Companion.SongOverlay\Lumi.Companion.SongOverlay.csproj", "{F72BAFAD-17D3-4EF2-8690-B3B5646556C2}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -27,6 +31,30 @@ Global
 		Release|x86 = Release|x86
 	EndGlobalSection
 	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{0B3C2C62-2CCB-43C9-9AF9-769AC7F22285}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{0B3C2C62-2CCB-43C9-9AF9-769AC7F22285}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{0B3C2C62-2CCB-43C9-9AF9-769AC7F22285}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{0B3C2C62-2CCB-43C9-9AF9-769AC7F22285}.Debug|x64.Build.0 = Debug|Any CPU
+		{0B3C2C62-2CCB-43C9-9AF9-769AC7F22285}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{0B3C2C62-2CCB-43C9-9AF9-769AC7F22285}.Debug|x86.Build.0 = Debug|Any CPU
+		{0B3C2C62-2CCB-43C9-9AF9-769AC7F22285}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{0B3C2C62-2CCB-43C9-9AF9-769AC7F22285}.Release|Any CPU.Build.0 = Release|Any CPU
+		{0B3C2C62-2CCB-43C9-9AF9-769AC7F22285}.Release|x64.ActiveCfg = Release|Any CPU
+		{0B3C2C62-2CCB-43C9-9AF9-769AC7F22285}.Release|x64.Build.0 = Release|Any CPU
+		{0B3C2C62-2CCB-43C9-9AF9-769AC7F22285}.Release|x86.ActiveCfg = Release|Any CPU
+		{0B3C2C62-2CCB-43C9-9AF9-769AC7F22285}.Release|x86.Build.0 = Release|Any CPU
+		{F72BAFAD-17D3-4EF2-8690-B3B5646556C2}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{F72BAFAD-17D3-4EF2-8690-B3B5646556C2}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{F72BAFAD-17D3-4EF2-8690-B3B5646556C2}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{F72BAFAD-17D3-4EF2-8690-B3B5646556C2}.Debug|x64.Build.0 = Debug|Any CPU
+		{F72BAFAD-17D3-4EF2-8690-B3B5646556C2}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{F72BAFAD-17D3-4EF2-8690-B3B5646556C2}.Debug|x86.Build.0 = Debug|Any CPU
+		{F72BAFAD-17D3-4EF2-8690-B3B5646556C2}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{F72BAFAD-17D3-4EF2-8690-B3B5646556C2}.Release|Any CPU.Build.0 = Release|Any CPU
+		{F72BAFAD-17D3-4EF2-8690-B3B5646556C2}.Release|x64.ActiveCfg = Release|Any CPU
+		{F72BAFAD-17D3-4EF2-8690-B3B5646556C2}.Release|x64.Build.0 = Release|Any CPU
+		{F72BAFAD-17D3-4EF2-8690-B3B5646556C2}.Release|x86.ActiveCfg = Release|Any CPU
+		{F72BAFAD-17D3-4EF2-8690-B3B5646556C2}.Release|x86.Build.0 = Release|Any CPU
 		{3703AF57-828D-4E2F-BFBA-A95833555A5A}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{3703AF57-828D-4E2F-BFBA-A95833555A5A}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{3703AF57-828D-4E2F-BFBA-A95833555A5A}.Debug|x64.ActiveCfg = Debug|Any CPU
@@ -92,10 +120,12 @@ Global
 		HideSolutionNode = FALSE
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
+		{0B3C2C62-2CCB-43C9-9AF9-769AC7F22285} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 		{3703AF57-828D-4E2F-BFBA-A95833555A5A} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 		{0BDAE25E-C487-456D-A465-41A0CA48AF30} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 		{64C2B7E5-9356-457A-BAF8-F18F67DAE4CF} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 		{2F0041FD-FD06-4312-BF1E-180F0201EB97} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 		{49C19CA8-4669-4C33-B3A8-9CB934CD1171} = {07D57EEB-2F50-60C4-C011-FE4FA775C9A8}
+		{F72BAFAD-17D3-4EF2-8690-B3B5646556C2} = {07D57EEB-2F50-60C4-C011-FE4FA775C9A8}
 	EndGlobalSection
 EndGlobal

companion/README.md

@@ -1,27 +1,100 @@
-# Lumi Companion (experimental transcription milestone)
+# Lumi Companion
 
-This directory is the single Lumi Companion product boundary. The current milestone supplies the versioned protocol client, Windows credential protection, bounded outbound transport, plugin-process supervision, same-user OBS bridge IPC, native selected-source capture, and an Avalonia tray shell. The shell is single-instance, closes to the tray, confirms quit during OBS streaming/recording, supports explicit pairing, and reports real setup/test blockers without presenting simulated success.
+Lumi Companion is the Windows streaming-computer client for Lumi. It provides a
+single paired-device shell for Companion plugins, including server-hosted
+transcription and Song Overlay capture. The app is single-instance, installs per
+Windows user, closes to the notification area, and preserves pairing and settings
+across updates.
 
-Build prerequisites: the current .NET SDK with the .NET 8 targeting pack on Windows x64. The app targets .NET 8; .NET SDK 10 is recommended for Avalonia 12 source-generator compatibility. The native bridge additionally requires CMake, Visual Studio C++ tools, and the OBS 31+ SDK.
+## Install and pair
 
-The app accepts a `.lumi-pairing.json` bootstrap package. A paired ZIP downloaded from Lumi contains the per-user Windows setup executable and one bootstrap file. Setup installs Companion under `%LocalAppData%\Programs\Lumi Companion`, imports the adjacent package when this Windows user is not already paired, and launches the installed app. Existing portable installs retain the same current-user DPAPI credential instead of creating a duplicate device. Companion exchanges a newly imported token once and removes the pairing file after success. Do not commit bootstrap packages, credentials, generated installers, build output, or logs.
+From Lumi, open **Admin > Companion** and choose **Download Companion**. The
+private ZIP contains:
 
-The companion never performs ASR in this MVP. Audio is normalized to 16 kHz mono signed 16-bit PCM, held in bounded memory, and sent to the paired Lumi host over TLS WebSockets. HTTP/WS works only for a package generated from the exact matching loopback Lumi origin. The OBS bridge talks only to the companion over a same-user named pipe.
+- the checksum-pinned per-user Windows installer;
+- a one-time `.lumi-pairing.json` package;
+- a Host Operator notice and start instructions.
 
-Build all managed projects from the repository root:
+Extract the ZIP and run `Lumi.Companion-Setup.exe`. Setup installs to
+`%LocalAppData%\Programs\Lumi Companion`, displays the licence and privacy
+notices, identifies the paired Lumi host, imports the adjacent pairing package,
+and opens the installed copy. The extracted download can then be deleted.
+
+Existing portable or installed builds retain the current Windows user's
+DPAPI-protected device identity, so reinstalling does not create a duplicate
+paired device. Pairing packages expire after 15 minutes, work once, and must not
+be shared or committed.
+
+## Security boundaries
+
+- Companion plugins inherit the shell's paired-device authentication. Plugins do
+  not store or request separate Lumi credentials.
+- Production Companion traffic requires HTTPS. Plain HTTP/WebSocket traffic is
+  accepted only when the device was paired from the exact matching loopback Lumi
+  origin and the request remains on loopback.
+- The OBS integration communicates with Companion through a same-user named pipe.
+- Transcription audio is normalized to 16 kHz mono signed 16-bit PCM, kept in
+  bounded memory, and sent to the paired Lumi host. Companion does not perform
+  local speech recognition.
+- Installing or repairing the OBS integration requests elevation only while OBS
+  is closed and only to copy the verified managed component into OBS's shared
+  ProgramData plugin directory.
+
+## Updates
+
+Companion checks after connecting and every six hours. Updates are
+user-approved, size- and checksum-verified, and refused while OBS is streaming or
+recording. Applying an update replaces the installed executable, bundled
+components, and legal bundle, then restarts Companion. Pairing credentials,
+settings, and plugin state remain in the per-user data directory.
+
+Localhost development builds can also receive checksum-addressed same-version
+updates without publishing a release. See
+[Localhost development updates](../docs/local-development-updates.md).
+
+## Build and verify
+
+Requirements:
+
+- Windows x64;
+- a current .NET SDK with the .NET 8 targeting pack;
+- CMake and Visual Studio C++ tools for the native OBS bridge;
+- Inno Setup 6 for the installer.
+
+Build the managed solution:
 
 ```powershell
-dotnet build companion/Lumi.Companion.sln -p:EnableWindowsTargeting=true
+dotnet build companion/Lumi.Companion.sln -c Release -p:EnableWindowsTargeting=true
 ```
 
-Build the pinned OBS 31.1.1 bridge and a self-contained Windows package from PowerShell:
+Build the pinned OBS bridge, self-contained archive, legal bundle, and installer:
 
 ```powershell
 companion/scripts/publish-companion.ps1
 ```
 
-This verifies both official OBS archives by SHA-256, builds the native module with Visual Studio 2022/CMake, and places the bridge beside the published app as a managed component. In Companion, **Install/Repair** requests Windows administrator approval only to copy that verified component into OBS's shared ProgramData plugin directory. OBS must be closed; Companion refuses plugin maintenance while `obs64.exe` is running.
+The publish script generates the shared application/tray icon, verifies the OBS
+payload inside the published executable, collects NuGet notices, and packages the
+corresponding source for the GPL-licensed OBS bridge.
 
-Experimental.3 checks for updates after connecting and every six hours. Updates remain user-approved, are checksum-verified, refuse to run while OBS is streaming or recording, replace the installed app and bundled components, then restart Companion. Pairing credentials and settings remain in the per-user data directory. Experimental.7 adds the durable per-user installer; existing portable users install it once, after which updates stay in the stable install directory. Experimental.8 fixes packaged OBS integration discovery and exposes a standalone payload diagnostic. Code signing, rollback policy, and target-machine OBS/Twitch acceptance are still required.
+Run Song Overlay's focused verification with:
 
-The Admin **Download Companion** action distributes a private ZIP containing a checksum-pinned Windows x64 installer plus the one-time pairing package. It is intentionally marked experimental and is not code-signed yet.
+```powershell
+companion/scripts/verify-song-overlay.ps1
+```
+
+Generated installers, pairing packages, credentials, build output, and logs must
+not be committed.
+
+## Distribution and legal notices
+
+The release is currently unsigned, so Windows may show an unknown-publisher
+warning. The installer and installed `legal` directory include the Companion
+licence, default privacy notice, third-party notices, exact licence texts, and
+the corresponding OBS bridge source bundle.
+
+Self-hosters should set `LUMI_OPERATOR_NAME`, `LUMI_OPERATOR_CONTACT`, and
+`LUMI_OPERATOR_PRIVACY_URL`. Those values identify the Host Operator responsible
+for its hosted service and server-side processing; OokamiKunTV is the software
+developer and is not automatically the operator of an independently hosted Lumi
+installation.

companion/docs/song-overlay-companion.md

@@ -0,0 +1,38 @@
+# Song Overlay Companion integration
+
+This integration adds a provider-neutral media event source to Lumi Companion. Spotify is the only available provider in this release, but the Companion protocol and runtime isolate provider-specific behavior behind `IMediaProvider`.
+
+## Navigation contract
+
+Every Companion plugin implements `ICompanionPluginContribution` and receives one nested root in both navigation surfaces:
+
+- Tray menu: core actions, `Plugins`, one submenu per plugin, then health/update/log/settings controls and Quit.
+- App sidebar: Overview, `PLUGINS`, one expandable root per plugin, then Connection, Logs, and Settings at the bottom.
+
+Plugin actions are caught at the shell boundary so a routine plugin exception does not terminate Companion. The Song Overlay runtime also catches provider callbacks, transport failures, heartbeats, and initialization failures and reports an actionable plugin status.
+
+## Song Overlay flow
+
+1. Windows Global System Media Transport Controls exposes Spotify playback state.
+2. The provider raises media, playback, timeline, and session-availability events.
+3. The runtime sends only meaningful deltas to Lumi: track change, inferred next/previous, play, resume, pause, stop, seek, metadata enrichment, or a sparse recovery heartbeat.
+4. Playback progress is projected from the last event. Continuous progress messages are not sent.
+5. Cover art is resized and sent only with track metadata.
+6. The existing Lumi `plugins/now_playing` endpoint updates the Song Overlay source and optional chat announcement.
+
+## Build and verification
+
+From the repository root on Windows:
+
+```powershell
+dotnet build companion/Lumi.Companion.sln -c Release -p:EnableWindowsTargeting=true
+node plugins/now_playing/tests/verify.js
+```
+
+Or run:
+
+```powershell
+companion/scripts/verify-song-overlay.ps1
+```
+
+The optional Spotify Web API connection is used only for metadata enrichment such as exact links and release year. Core playback detection works through Windows without Spotify authorization.

companion/installer/Lumi.Companion.iss

@@ -1,5 +1,5 @@
 #ifndef AppVersion
-  #define AppVersion "0.1.0-experimental.8"
+  #define AppVersion "0.1.0"
 #endif
 #ifndef SourceRoot
   #error SourceRoot must point at the self-contained Companion publish directory.
@@ -13,7 +13,8 @@ AppId={{EDEB45E4-41CB-4D7A-A479-4073A1A08B93}
 AppName=Lumi Companion
 AppVersion={#AppVersion}
 AppVerName=Lumi Companion {#AppVersion}
-AppPublisher=Lumi
+AppPublisher=OokamiKunTV
+AppCopyright=Copyright (c) 2026 OokamiKunTV
 DefaultDirName={localappdata}\Programs\Lumi Companion
 DefaultGroupName=Lumi Companion
 DisableProgramGroupPage=yes
@@ -31,24 +32,184 @@ CloseApplicationsFilter=Lumi.Companion.App.exe
 RestartApplications=no
 UninstallDisplayName=Lumi Companion
 UninstallDisplayIcon={app}\Lumi.Companion.App.exe
+VersionInfoCompany=OokamiKunTV
+VersionInfoCopyright=Copyright (c) 2026 OokamiKunTV
 VersionInfoDescription=Lumi Companion installer
 VersionInfoProductName=Lumi Companion
 VersionInfoProductTextVersion={#AppVersion}
+LicenseFile={#SourceRoot}\legal\LUMI-COMPANION-LICENCE.txt
+InfoBeforeFile={#SourceRoot}\legal\PRIVACY-NOTICE.txt
+InfoAfterFile={#SourceRoot}\legal\THIRD-PARTY-NOTICES.txt
 
 [Files]
 Source: "{#SourceRoot}\Lumi.Companion.App.exe"; DestDir: "{app}"; Flags: ignoreversion
 Source: "{#SourceRoot}\components\*"; DestDir: "{app}\components"; Flags: ignoreversion recursesubdirs createallsubdirs
+Source: "{#SourceRoot}\legal\*"; DestDir: "{app}\legal"; Flags: ignoreversion recursesubdirs createallsubdirs
 
 [Icons]
 Name: "{autoprograms}\Lumi Companion"; Filename: "{app}\Lumi.Companion.App.exe"
+Name: "{autoprograms}\Lumi Companion - Legal and Privacy"; Filename: "{app}\legal\LEGAL-README.txt"
 
 [Run]
 Filename: "{app}\Lumi.Companion.App.exe"; Description: "Open Lumi Companion"; Flags: nowait postinstall skipifsilent
 
 [Code]
-procedure ImportPairingPackage;
+var
+  PairingPackagePath: String;
+  PairingHost: String;
+  PairingOperatorName: String;
+  PairingOperatorContact: String;
+  PairingPrivacyUrl: String;
+  HostAcknowledgementPage: TInputOptionWizardPage;
+
+function LocatePairingPackage: String;
 var
   FindRec: TFindRec;
+begin
+  Result := '';
+  if FindFirst(ExpandConstant('{src}\*.lumi-pairing.json'), FindRec) then
+  begin
+    try
+      Result := AddBackslash(ExpandConstant('{src}')) + FindRec.Name;
+    finally
+      FindClose(FindRec);
+    end;
+  end;
+end;
+
+function JsonStringValue(const Json: String; const Key: String): String;
+var
+  Marker: String;
+  Tail: String;
+  MarkerPos: Integer;
+  ColonPos: Integer;
+  EndQuotePos: Integer;
+begin
+  Result := '';
+  Marker := '"' + Key + '"';
+  MarkerPos := Pos(Marker, Json);
+  if MarkerPos = 0 then
+    Exit;
+
+  Tail := Copy(Json, MarkerPos + Length(Marker), Length(Json));
+  ColonPos := Pos(':', Tail);
+  if ColonPos = 0 then
+    Exit;
+
+  Tail := Trim(Copy(Tail, ColonPos + 1, Length(Tail)));
+  if (Length(Tail) < 2) or (Tail[1] <> '"') then
+    Exit;
+
+  Tail := Copy(Tail, 2, Length(Tail));
+  EndQuotePos := Pos('"', Tail);
+  if EndQuotePos = 0 then
+    Exit;
+
+  Result := Copy(Tail, 1, EndQuotePos - 1);
+end;
+
+function LoadPairingJson(const PackagePath: String; var Json: String): Boolean;
+var
+  Lines: TArrayOfString;
+  Index: Integer;
+begin
+  Result := False;
+  Json := '';
+  if (PackagePath = '') or not LoadStringsFromFile(PackagePath, Lines) then
+    Exit;
+
+  for Index := 0 to GetArrayLength(Lines) - 1 do
+  begin
+    if Index > 0 then
+      Json := Json + #10;
+    Json := Json + Lines[Index];
+  end;
+  Result := True;
+end;
+
+function ReadPairingHost(const Json: String): String;
+var
+  Candidate: String;
+  LowerCandidate: String;
+begin
+  Result := '';
+  Candidate := JsonStringValue(Json, 'host');
+  LowerCandidate := Lowercase(Candidate);
+  if ((Pos('https://', LowerCandidate) = 1) or (Pos('http://', LowerCandidate) = 1)) and
+     (Length(Candidate) <= 500) then
+    Result := Candidate;
+end;
+
+procedure InitializeWizard;
+var
+  HostDisplay: String;
+  Explanation: String;
+  OperatorDetails: String;
+  Json: String;
+begin
+  PairingPackagePath := LocatePairingPackage;
+  if LoadPairingJson(PairingPackagePath, Json) then
+  begin
+    PairingHost := ReadPairingHost(Json);
+    PairingOperatorName := Copy(JsonStringValue(Json, 'operator_name'), 1, 200);
+    PairingOperatorContact := Copy(JsonStringValue(Json, 'operator_contact'), 1, 300);
+    PairingPrivacyUrl := Copy(JsonStringValue(Json, 'privacy_url'), 1, 500);
+  end;
+
+  if PairingHost <> '' then
+    HostDisplay := PairingHost
+  else
+    HostDisplay := 'No paired Lumi host was identified beside this installer.';
+
+  OperatorDetails := '';
+  if PairingOperatorName <> '' then
+    OperatorDetails := OperatorDetails + #13#10 + 'Operator name: ' + PairingOperatorName;
+  if PairingOperatorContact <> '' then
+    OperatorDetails := OperatorDetails + #13#10 + 'Operator contact: ' + PairingOperatorContact;
+  if PairingPrivacyUrl <> '' then
+    OperatorDetails := OperatorDetails + #13#10 + 'Privacy information: ' + PairingPrivacyUrl;
+
+  Explanation :=
+    'This copy of Lumi Companion is intended to connect to:' + #13#10#13#10 +
+    HostDisplay + OperatorDetails + #13#10#13#10 +
+    'The person or organisation controlling that Lumi installation is the Host Operator. ' +
+    'The Host Operator is responsible for the Hosted Service it controls, including server configuration, ' +
+    'access, server-side data processing, retention, integrations, and required user notices. ' +
+    'OokamiKunTV is the software developer and is not automatically the operator of an independently hosted Lumi installation. ' +
+    'Responsibility always follows the actual facts and applicable law.';
+
+  HostAcknowledgementPage := CreateInputOptionPage(
+    wpInfoBefore,
+    'Lumi host and data responsibility',
+    'Review the host that will receive Companion data.',
+    Explanation,
+    False,
+    False);
+  HostAcknowledgementPage.Add(
+    'I understand which Lumi host this Companion will use and that the Host Operator controls its server-side service and processing.');
+end;
+
+function NextButtonClick(CurPageID: Integer): Boolean;
+begin
+  Result := True;
+  { A silent deployment is an administrator/operator action and has no wizard
+    UI in which an interactive acknowledgement can be collected. }
+  if WizardSilent then
+    Exit;
+
+  if (HostAcknowledgementPage <> nil) and (CurPageID = HostAcknowledgementPage.ID) and
+     not HostAcknowledgementPage.Values[0] then
+  begin
+    MsgBox(
+      'Confirm that you understand the host and operator responsibility before continuing.',
+      mbInformation,
+      MB_OK);
+    Result := False;
+  end;
+end;
+
+procedure ImportPairingPackage;
+var
   SourcePath: String;
   TargetPath: String;
 begin
@@ -57,17 +218,20 @@ begin
     the executable into its durable installed location. }
   if FileExists(ExpandConstant('{localappdata}\Lumi\Companion\device.credential')) then
     Exit;
-  if FindFirst(ExpandConstant('{src}\*.lumi-pairing.json'), FindRec) then
-  begin
-    try
-      SourcePath := AddBackslash(ExpandConstant('{src}')) + FindRec.Name;
-      TargetPath := AddBackslash(ExpandConstant('{app}')) + FindRec.Name;
-      if not CopyFile(SourcePath, TargetPath, False) then
-        MsgBox('Lumi Companion was installed, but its one-time pairing package could not be imported. Open Companion and choose the pairing file manually.', mbError, MB_OK);
-    finally
-      FindClose(FindRec);
-    end;
-  end;
+
+  SourcePath := PairingPackagePath;
+  if SourcePath = '' then
+    SourcePath := LocatePairingPackage;
+  if SourcePath = '' then
+    Exit;
+
+  TargetPath := AddBackslash(ExpandConstant('{app}')) + ExtractFileName(SourcePath);
+  if not CopyFile(SourcePath, TargetPath, False) then
+    MsgBox(
+      'Lumi Companion was installed, but its one-time pairing package could not be imported. ' +
+      'Open Companion and choose the pairing file manually.',
+      mbError,
+      MB_OK);
 end;
 
 procedure CurStepChanged(CurStep: TSetupStep);

companion/legal/HOST-OPERATOR-NOTICE.template.txt

@@ -0,0 +1,10 @@
+LUMI COMPANION — HOST OPERATOR NOTICE
+
+Paired Lumi host: {{HOST_URL}}
+Operator name: {{OPERATOR_NAME}}
+Operator contact: {{OPERATOR_CONTACT}}
+Privacy information: {{PRIVACY_URL}}
+
+This package connects Companion to the Lumi installation at the host shown above. The person or organisation controlling that installation is responsible for its Hosted Service, including server configuration, user access, server-side processing, retention, integrations, notices, and compliance obligations.
+
+OokamiKunTV is the developer of Lumi Companion and is not automatically the operator of an independently hosted Lumi installation. Responsibility follows the actual facts and applicable law. The host URL is a technical identifier and may not by itself identify the operator’s legal name.

companion/legal/LEGAL-MAINTAINER-NOTES.md

@@ -0,0 +1,12 @@
+# Legal maintainer notes
+
+This bundle is a practical baseline, not a substitute for review by a qualified lawyer familiar with the actual distribution, business model, and jurisdictions.
+
+Before a public or paid release:
+
+- publish a stable developer contact channel and, if applicable, the legal person/business name and address;
+- let self-hosters configure an operator name, contact address, and privacy URL in generated pairing packages;
+- confirm the project-wide licence strategy, especially the GPL-2.0-or-later OBS bridge boundary;
+- retain the generated `third-party/nuget/NuGet-LICENCE-INVENTORY.txt` and copied package notices from the exact resolved .NET/NuGet dependency set for each release;
+- preserve the corresponding-source archive for every distributed OBS bridge binary for as long as the relevant GPL obligations require; and
+- review consumer terms, data-processing roles, and any paid-service terms before charging users.

companion/legal/LEGAL-README.txt

@@ -0,0 +1,10 @@
+LUMI COMPANION — LEGAL AND PRIVACY DOCUMENTS
+
+- LUMI-COMPANION-LICENCE.txt: licence terms for developer-authored proprietary portions.
+- PRIVACY-NOTICE.txt: default client-side data behaviour and Host Operator responsibility.
+- THIRD-PARTY-NOTICES.txt: third-party components and licence locations.
+- third-party directory: full third-party licence and notice files supplied with this build.
+- third-party\nuget\NuGet-LICENCE-INVENTORY.txt: generated inventory and package-supplied notices for the exact restored NuGet graph.
+- Lumi-OBS-Bridge-Source.zip: corresponding source and build materials for the GPL-licensed OBS bridge.
+
+The installer also displays the paired Lumi host URL when a pairing package is present. The person or organisation controlling that host is responsible for its own Hosted Service and server-side processing, subject to the actual facts and applicable law.

companion/legal/LUMI-COMPANION-LICENCE.txt

@@ -0,0 +1,102 @@
+LUMI COMPANION SOFTWARE LICENCE AND TERMS OF USE
+Effective date: 23 July 2026
+
+PLEASE READ THESE TERMS BEFORE INSTALLING OR USING LUMI COMPANION.
+
+These terms govern the Lumi Companion desktop application and installer, except for components that are supplied under separate open-source or third-party licences. By installing, copying, pairing, updating, or using Lumi Companion, you accept these terms. If you do not accept them, do not install or use the software.
+
+1. PARTIES AND DEFINITIONS
+
+“Developer” means OokamiKunTV, the developer and copyright holder of Lumi Companion and the Lumi project components authored by OokamiKunTV.
+
+“Companion” means the Lumi Companion application, installer, updates, documentation, and developer-authored components supplied with it.
+
+“Host Operator” means the person or organisation that controls the Lumi installation to which Companion is paired. The paired host URL shown by the installer identifies the technical endpoint, but may not by itself identify the Host Operator’s legal name.
+
+“Hosted Service” means the Lumi installation, its configuration, accounts, models, storage, integrations, moderation, transcription, and other server-side functions operated by the Host Operator.
+
+2. SEPARATE RESPONSIBILITIES
+
+Companion is client software. It connects to a separately operated Lumi host selected through a pairing package or by the user.
+
+The Host Operator is responsible for the Hosted Service it controls, including its configuration, availability, security, access management, user notices, legal basis for processing, retention, integrations, and compliance with laws applicable to that operation. The Developer is not automatically the Host Operator merely because the Host Operator uses Lumi software.
+
+Where the Developer also operates the paired Lumi host, the Developer may additionally have responsibilities in that separate role. Legal responsibility always follows the actual facts and applicable law; these terms do not reassign a statutory responsibility that cannot lawfully be reassigned.
+
+3. LICENCE GRANT
+
+Subject to these terms, the Developer grants you a limited, non-exclusive, non-transferable, revocable licence to install and use Companion on devices you own or control for personal or internal organisational use with a Lumi installation you are authorised to access.
+
+A Host Operator may redistribute an unmodified official Companion installer together with a pairing package to users authorised to access that Host Operator’s Lumi installation. No right is granted to sell, rebrand, misrepresent, or distribute modified proprietary Companion binaries without the Developer’s permission.
+
+You may make reasonable backup copies. You may not remove proprietary notices, bypass access controls, use Companion to gain unauthorised access, or reverse engineer proprietary portions except to the extent that applicable law expressly permits this despite this restriction.
+
+Open-source components are governed only by their respective licences. Nothing in these terms limits rights granted under those licences.
+
+4. EXPERIMENTAL SOFTWARE AND USER RESPONSIBILITY
+
+Companion may be identified as experimental, preview, beta, or pre-release software. It may contain defects, change without notice, fail to interoperate with OBS, Windows, hardware, networks, third-party services, or a particular Lumi host, and may be discontinued.
+
+You are responsible for deciding whether Companion is suitable for your use, maintaining backups, testing changes before relying on them, protecting your accounts and devices, reviewing the Host Operator’s policies, and obtaining any permissions required before capturing or transmitting audio, captions, account information, or other data.
+
+Companion is not designed for emergency, medical, safety-critical, legal-compliance, life-support, or other use where failure could foreseeably cause death, personal injury, or substantial physical damage.
+
+5. DATA AND NETWORK FUNCTIONS
+
+Companion stores local settings, an installation identifier, diagnostic logs, and a Windows user-protected device credential. When paired, it communicates with the paired Lumi host and may transmit selected OBS audio, device and component status, configuration information, test data, captions, and diagnostics needed for enabled functions.
+
+The Privacy Notice supplied with Companion explains the default client-side behaviour. The Host Operator must provide information about server-side processing for the Hosted Service. You must not assume that the Developer receives or controls data sent to an independently operated Lumi host.
+
+6. UPDATES, CHANGES, AND THIRD-PARTY SERVICES
+
+Companion may check the paired Lumi host for updates. Installation of an update remains subject to the behaviour presented by the application. Updates may add, remove, or change features and may be required for compatibility or security.
+
+Companion may interoperate with third-party software and services, including OBS Studio and Windows. Those products are controlled by their respective providers and may be subject to separate terms. The Developer does not control and is not responsible for their continued availability, behaviour, policies, or changes.
+
+7. SUPPORT
+
+Unless the Developer or Host Operator separately agrees in writing, no support, maintenance, service level, response time, continued hosting, compatibility period, or update schedule is promised.
+
+8. NO WARRANTY
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, COMPANION IS PROVIDED “AS IS” AND “AS AVAILABLE”, WITH ALL FAULTS AND WITHOUT WARRANTIES, REPRESENTATIONS, CONDITIONS, OR GUARANTEES OF ANY KIND, WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE.
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE DEVELOPER DISCLAIMS IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, ACCURACY, SECURITY, AVAILABILITY, COMPATIBILITY, AND ERROR-FREE OR UNINTERRUPTED OPERATION.
+
+No statement, documentation, test result, roadmap, or assistance creates a warranty unless the Developer expressly agrees to it in a signed written agreement.
+
+9. LIMITATION OF LIABILITY
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE DEVELOPER WILL NOT BE LIABLE FOR INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL LOSS; LOSS OF DATA, CONTENT, PRIVACY, REVENUE, PROFITS, GOODWILL, BUSINESS, OPPORTUNITY, OR USE; SERVICE INTERRUPTION; DEVICE OR SOFTWARE DAMAGE; THIRD-PARTY CLAIMS; OR THE CONDUCT, SECURITY, AVAILABILITY, OR DATA PROCESSING OF AN INDEPENDENT HOST OPERATOR OR THIRD-PARTY SERVICE.
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE DEVELOPER’S TOTAL AGGREGATE LIABILITY ARISING FROM OR RELATING TO COMPANION WILL NOT EXCEED THE AMOUNT YOU PAID DIRECTLY TO THE DEVELOPER FOR COMPANION DURING THE TWELVE MONTHS BEFORE THE EVENT GIVING RISE TO THE CLAIM.
+
+These exclusions and limits do not apply where liability cannot lawfully be excluded or limited, including mandatory consumer rights and, where applicable, liability for fraud, intentional misconduct, gross negligence, or death or personal injury caused by negligence.
+
+10. BUSINESS-USER INDEMNITY
+
+If you use Companion on behalf of a business or organisation, that business or organisation will, to the extent permitted by law, defend and indemnify the Developer against third-party claims, losses, and reasonable costs arising from its unlawful use of Companion, infringement of third-party rights, failure to obtain required permissions, or operation of a Lumi host in breach of law. This section does not apply to consumers acting wholly outside a trade or profession.
+
+11. TERMINATION
+
+This licence ends automatically if you materially breach these terms. On termination, you must stop using proprietary portions of Companion and remove copies under your control, except where retention is required by law or permitted by an applicable open-source licence. Sections intended by their nature to survive termination remain effective.
+
+12. GOVERNING LAW AND MANDATORY RIGHTS
+
+These terms are governed by the laws of Norway, excluding conflict-of-law rules, unless mandatory law requires otherwise. Norwegian courts have non-exclusive jurisdiction where legally permitted.
+
+If you are a consumer, you retain all mandatory protections and rights available under the law of your country of residence. Nothing in these terms waives a right or remedy that cannot legally be waived, restricts your right to bring proceedings in a court available under mandatory law, or requires you to accept a lower level of protection than mandatory consumer law provides.
+
+13. GENERAL
+
+If any provision is invalid or unenforceable, it will be limited or removed only to the minimum extent necessary, and the remaining provisions will continue in effect. Failure to enforce a provision is not a waiver. These terms, the Privacy Notice, and applicable third-party licences form the agreement for Companion unless a separate written agreement expressly replaces them.
+
+The English version controls to the extent permitted by law. A translation may be provided for convenience.
+
+14. CONTACT AND OPERATOR INFORMATION
+
+Developer: OokamiKunTV
+Project: Lumi / Lumi Companion
+Developer contact: use the official Lumi project support or contact channel from which the software was obtained.
+
+For Hosted Service, account, server-side data, moderation, retention, or access questions, contact the Host Operator identified through the paired Lumi host. The installer displays the host endpoint when a pairing package is present.

companion/legal/PRIVACY-NOTICE.txt

@@ -0,0 +1,79 @@
+LUMI COMPANION PRIVACY NOTICE
+Effective date: 23 July 2026
+
+This notice describes the default data behaviour of the Lumi Companion Windows application. It does not replace the privacy notice of the person or organisation operating the Lumi host to which Companion is paired.
+
+1. WHO IS RESPONSIBLE
+
+Companion is client software developed by OokamiKunTV. It can connect to Lumi installations operated by different people or organisations.
+
+The person or organisation operating the paired Lumi installation is normally responsible for deciding why and how server-side personal data is processed through that installation. That operator is referred to here as the “Host Operator”. The installer shows the paired host URL when it can read one from the adjacent pairing package.
+
+The host URL identifies a technical endpoint, not necessarily the Host Operator’s full legal identity. Obtain the operator’s identity, contact details, purposes, legal bases, recipients, retention periods, and rights information from the operator or the paired Lumi WebUI.
+
+OokamiKunTV is not automatically responsible for processing performed by an independently operated Lumi host. If OokamiKunTV also operates the paired host or receives information for support, security, or another stated purpose, responsibility for that processing follows the actual arrangement and applicable law. This notice does not override statutory controller or processor roles.
+
+2. DATA STORED ON THE WINDOWS COMPUTER
+
+Companion may store the following under the current Windows user profile:
+
+- settings, selected source identifiers, and feature preferences;
+- a random installation identifier;
+- a device credential containing the paired host address, device identifier, secret, capabilities, and protocol version;
+- short-lived diagnostic log files containing timestamps, connection and component events, error messages, host addresses, device names, and potentially caption or test text;
+- staged update files while an update is being prepared; and
+- a copied one-time pairing package until it is successfully used, found redundant, manually removed, or expires.
+
+The device credential is protected with Windows Data Protection API for the current Windows user. This reduces casual disclosure but does not protect against every compromise of the Windows account or device.
+
+Diagnostic logs are pruned after seven days and capped at a combined 256 MiB by default. Uninstalling Companion may leave the per-user settings, credential, installation identifier, logs, and update directory in %LocalAppData%\Lumi\Companion so that reinstalling does not silently create a new authorised device. Use “Forget this device” before uninstalling when available, revoke the device from the Lumi host, and delete that folder manually if you want the remaining local data removed.
+
+3. DATA SENT TO THE PAIRED LUMI HOST
+
+Depending on the features you enable, Companion may send:
+
+- the computer or device name, installation identifier, Companion version, protocol version, capabilities, and component status;
+- OBS state and selected-source information;
+- audio from the OBS source you select, converted to 16 kHz mono signed 16-bit PCM and transmitted in bounded frames;
+- readiness, test, benchmark, connection, and diagnostic information; and
+- settings or control messages required for enabled Companion features.
+
+Raw audio is held in bounded memory and is not written to disk by Companion by default. Audio is transmitted to the paired Lumi host for server-side processing. The Host Operator controls the server-side speech model, storage, logs, caption delivery, integrations, and retention. Review the Host Operator’s notice before enabling capture.
+
+You are responsible for having authority to capture and transmit audio or other information, including informing participants and obtaining consent where required.
+
+4. NETWORK CONNECTIONS
+
+Companion connects to:
+
+- the host and exchange URL contained in the pairing package;
+- the paired Lumi host over secure HTTP and WebSocket connections, except for an exact matching loopback host where local unencrypted transport is permitted; and
+- an update artifact URL supplied by the paired Lumi host when you approve or initiate an update.
+
+Companion does not include advertising or general-purpose analytics telemetry in the inspected release. It does not send data directly to OokamiKunTV merely because OokamiKunTV wrote the software. An independently operated host may add integrations or server-side logging outside Companion’s control.
+
+5. PURPOSES AND LEGAL BASES
+
+Local processing is performed to pair the device, remember settings, operate enabled features, diagnose failures, verify components, and apply approved updates.
+
+The Host Operator determines the purposes and legal bases for server-side processing. Depending on the context, those bases may include performance of a contract, legitimate interests, consent, legal obligations, or another basis available under applicable law. Contact the Host Operator for the basis that applies to your use.
+
+6. RETENTION AND DELETION
+
+Local diagnostic logs follow the default limits described above. Credentials and settings remain until removed by the user, the application, or the operating system. Pairing tokens are designed to be single-use and expire after the period stated in the pairing package.
+
+Server-side retention is controlled by the Host Operator and may differ from local retention. Deleting local data does not automatically delete data already sent to the host. Revoking a device on the host does not necessarily delete prior server-side logs or content.
+
+7. SECURITY
+
+Companion validates the pairing origin, normally requires HTTPS, protects the device credential with Windows user-scoped encryption, verifies update checksums, and keeps raw audio in bounded memory by default. No security measure is perfect. Keep Windows, OBS, Companion, and the Lumi host updated; protect the Windows account; and revoke devices that are lost, shared, or no longer trusted.
+
+8. YOUR RIGHTS
+
+Depending on applicable law, you may have rights to information, access, correction, deletion, restriction, objection, portability, withdrawal of consent, and complaint to a supervisory authority.
+
+For data held by the paired Lumi host, direct requests to the Host Operator. For local data, use Companion controls where available, revoke the device from the host, and remove the local Companion data directory. For information actually received and controlled by OokamiKunTV, use the official Lumi project contact channel through which that processing occurred.
+
+9. CHANGES
+
+This notice may be updated when Companion’s data behaviour changes. The effective date identifies the version of the notice supplied with the installer. Material changes should be presented with a new release or through the relevant Host Operator.

companion/legal/THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,42 @@
+LUMI COMPANION THIRD-PARTY AND OPEN-SOURCE NOTICES
+Effective date: 23 July 2026
+
+Lumi Companion contains or interoperates with software supplied under separate licences. Those licences govern the relevant components and take priority over the Lumi Companion Software Licence for those components.
+
+1. Avalonia UI
+Copyright (c) AvaloniaUI OÜ. Licensed under the MIT License.
+Licence file: third-party\Avalonia-MIT.txt
+Project: https://github.com/AvaloniaUI/Avalonia
+
+2. Microsoft .NET Runtime and libraries
+Copyright (c) .NET Foundation and Contributors. Licensed primarily under the MIT License and incorporating additional third-party material.
+Licence files: third-party\dotnet-MIT.txt and third-party\dotnet-THIRD-PARTY-NOTICES.txt
+Project: https://github.com/dotnet/runtime
+
+The release build also generates third-party\nuget\NuGet-LICENCE-INVENTORY.txt from the exact restored package graph and copies package-supplied licence, notice, copying, and copyright files into adjacent package directories. This covers transitive packages and native assets, including Avalonia rendering dependencies, that are present in the actual build.
+
+3. Inter font family
+Copyright (c) The Inter Project Authors. Licensed under the SIL Open Font License, Version 1.1.
+Licence file: third-party\Inter-OFL-1.1.txt
+Project: https://github.com/rsms/inter
+
+4. nlohmann/json 3.12.0
+Copyright (c) 2013-2025 Niels Lohmann. Licensed primarily under the MIT License. The upstream project also identifies incorporated material under compatible licences, including Apache-2.0 and public-domain/CC0 material.
+Licence files: third-party\nlohmann-json-MIT.txt and third-party\Apache-2.0.txt
+Project: https://github.com/nlohmann/json
+
+5. OBS Studio / libobs and Lumi OBS Bridge
+OBS Studio is distributed under the GNU General Public License, version 2 or any later version. Lumi Companion does not distribute OBS Studio itself, but the bundled Lumi OBS Bridge links with OBS/libobs and is distributed under GPL-2.0-or-later.
+Licence file: third-party\GPL-2.0-or-later.txt
+Corresponding source: Lumi-OBS-Bridge-Source.zip installed in the legal directory.
+OBS project: https://github.com/obsproject/obs-studio
+
+6. Inno Setup
+The Windows installer was created with Inno Setup by Jordan Russell and Martijn Laan. Inno Setup is supplied under its own licence.
+Licence file: third-party\Inno-Setup-License.txt
+Project: https://jrsoftware.org/isinfo.php
+
+7. Windows and third-party products
+Microsoft Windows, Windows Data Protection API, OBS Studio, and other named products are trademarks or products of their respective owners. Their inclusion or mention does not imply sponsorship or endorsement.
+
+The source archive and licence files are provided to preserve the rights granted by the applicable open-source licences. If a required notice is believed to be missing, report it through the official Lumi project contact channel so it can be corrected.

companion/legal/third-party/Apache-2.0.txt

@@ -0,0 +1,73 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+     (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+     (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+     (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+     (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+     You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

companion/legal/third-party/Avalonia-MIT.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) AvaloniaUI OÜ
+All Rights Reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

companion/legal/third-party/GPL-2.0-or-later.txt

@@ -0,0 +1,339 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                            NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, write to the Free Software Foundation, Inc.,
+    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.

companion/legal/third-party/Inno-Setup-License.txt

@@ -0,0 +1,32 @@
+Inno Setup License
+==================
+
+Except where otherwise noted, all of the documentation and software included in the Inno
+Setup package is copyrighted by Jordan Russell.
+
+Copyright (C) 1997-2026 Jordan Russell. All rights reserved.
+Portions Copyright (C) 2000-2026 Martijn Laan. All rights reserved.
+
+This software is provided "as-is," without any express or implied warranty. In no event shall
+the author be held liable for any damages arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose, including commercial
+applications, and to alter and redistribute it, provided that the following conditions are met:
+
+1. All redistributions of source code files must retain all copyright notices that are currently
+   in place, and this list of conditions without modification.
+
+2. All redistributions in binary form must retain all occurrences of the above copyright notice
+   and web site addresses that are currently in place (for example, in the About boxes).
+
+3. The origin of this software must not be misrepresented; you must not claim that you wrote
+   the original software. If you use this software to distribute a product, an acknowledgment
+   in the product documentation would be appreciated but is not required.
+
+4. Modified versions in source or binary form must be plainly marked as such, and must not
+   be misrepresented as being the original software.
+
+
+Jordan Russell
+jr-2020 AT jrsoftware.org
+https://jrsoftware.org/

companion/legal/third-party/Inter-OFL-1.1.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

companion/legal/third-party/dotnet-MIT.txt

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) .NET Foundation and Contributors
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

companion/legal/third-party/nlohmann-json-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2013-2025 Niels Lohmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

companion/native/obs-bridge/CMakeLists.txt

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+# Copyright (c) 2026 OokamiKunTV
+
 cmake_minimum_required(VERSION 3.28)
 project(lumi-obs-bridge VERSION 0.1.0 LANGUAGES CXX)
 set(LUMI_BRIDGE_VERSION "0.1.0-development" CACHE STRING "Lumi Companion bridge release version")

companion/native/obs-bridge/COPYING

@@ -0,0 +1,339 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                            NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, write to the Free Software Foundation, Inc.,
+    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.

companion/native/obs-bridge/README.md

@@ -0,0 +1,9 @@
+# Lumi OBS Bridge
+
+The Lumi OBS Bridge is the native OBS module bundled with Lumi Companion.
+
+Copyright (c) 2026 OokamiKunTV.
+
+This component is free software licensed under the GNU General Public License, version 2 or (at your option) any later version (`GPL-2.0-or-later`). See `COPYING` for the complete licence.
+
+The release build includes a corresponding-source archive containing this directory and the build script used to produce the distributed binary. OBS Studio and nlohmann/json remain available from their upstream projects under their respective licences.

companion/native/obs-bridge/include/bounded_spsc_queue.hpp

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+// Copyright (c) 2026 OokamiKunTV
+
 #pragma once
 #include <array>
 #include <atomic>

companion/native/obs-bridge/src/plugin.cpp

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+// Copyright (c) 2026 OokamiKunTV
+
 #include <obs-module.h>
 #include <obs-frontend-api.h>
 #include <nlohmann/json.hpp>

companion/plugins/Lumi.Companion.SongOverlay/Lumi.Companion.SongOverlay.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <UseSystemDrawing>true</UseSystemDrawing>
+    <AssemblyName>Lumi.Companion.SongOverlay</AssemblyName>
+    <RootNamespace>Lumi.Companion.SongOverlay</RootNamespace>
+  </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="../../src/Lumi.Companion.Abstractions/Lumi.Companion.Abstractions.csproj" />
+    <PackageReference Include="System.Drawing.Common" Version="8.0.0" />
+    <PackageReference Include="System.Security.Cryptography.ProtectedData" Version="8.0.0" />
+  </ItemGroup>
+</Project>

companion/plugins/Lumi.Companion.SongOverlay/MediaModels.cs

@@ -0,0 +1,53 @@
+using System.Text.Json.Serialization;
+
+namespace Lumi.Companion.SongOverlay;
+
+internal sealed record MediaTrack(
+    string Key,
+    string Title,
+    string Artist,
+    string Album,
+    string ReleaseYear,
+    string Link,
+    long DurationMilliseconds,
+    CoverPayload? Cover);
+
+internal sealed record MediaSnapshot(
+    string Provider,
+    string Status,
+    long PositionMilliseconds,
+    long DurationMilliseconds,
+    double PlaybackRate,
+    MediaTrack? Track,
+    DateTimeOffset CapturedAt);
+
+internal sealed record CoverPayload(
+    [property: JsonPropertyName("mime")] string Mime,
+    [property: JsonPropertyName("base64")] string Base64,
+    [property: JsonPropertyName("primary")] string Primary,
+    [property: JsonPropertyName("secondary")] string Secondary);
+
+internal sealed record TrackPayload(
+    [property: JsonPropertyName("key")] string Key,
+    [property: JsonPropertyName("title")] string Title,
+    [property: JsonPropertyName("artist")] string Artist,
+    [property: JsonPropertyName("album")] string Album,
+    [property: JsonPropertyName("release_year")] string ReleaseYear,
+    [property: JsonPropertyName("link")] string Link,
+    [property: JsonPropertyName("cover")] CoverPayload? Cover);
+
+internal sealed record PlaybackPayload(
+    [property: JsonPropertyName("status")] string Status,
+    [property: JsonPropertyName("position_ms")] long PositionMilliseconds,
+    [property: JsonPropertyName("duration_ms")] long DurationMilliseconds,
+    [property: JsonPropertyName("rate")] double Rate);
+
+internal sealed record NowPlayingEventPayload(
+    [property: JsonPropertyName("protocol_version")] int ProtocolVersion,
+    [property: JsonPropertyName("provider")] string Provider,
+    [property: JsonPropertyName("session_id")] string SessionId,
+    [property: JsonPropertyName("sequence")] long Sequence,
+    [property: JsonPropertyName("event")] string Event,
+    [property: JsonPropertyName("occurred_at")] long OccurredAt,
+    [property: JsonPropertyName("playback")] PlaybackPayload Playback,
+    [property: JsonPropertyName("track")] TrackPayload? Track);

companion/plugins/Lumi.Companion.SongOverlay/Providers/IMediaProvider.cs

@@ -0,0 +1,24 @@
+namespace Lumi.Companion.SongOverlay.Providers;
+
+internal interface IMediaProvider : IAsyncDisposable
+{
+    string Id { get; }
+    string DisplayName { get; }
+    event EventHandler<ProviderStateChangedEventArgs>? StateChanged;
+    event EventHandler<string>? AvailabilityChanged;
+    Task StartAsync(CancellationToken cancellationToken);
+    Task StopAsync(CancellationToken cancellationToken);
+    Task<MediaSnapshot?> GetSnapshotAsync(CancellationToken cancellationToken);
+}
+
+internal sealed class ProviderStateChangedEventArgs : EventArgs
+{
+    public ProviderStateChangedEventArgs(string reason, MediaSnapshot? snapshot)
+    {
+        Reason = reason;
+        Snapshot = snapshot;
+    }
+
+    public string Reason { get; }
+    public MediaSnapshot? Snapshot { get; }
+}

companion/plugins/Lumi.Companion.SongOverlay/Providers/SpotifyWindowsMediaProvider.cs

@@ -0,0 +1,322 @@
+using System.Drawing;
+using System.Drawing.Imaging;
+using System.Security.Cryptography;
+using System.Text;
+using Windows.Media.Control;
+using Windows.Storage.Streams;
+
+namespace Lumi.Companion.SongOverlay.Providers;
+
+internal sealed class SpotifyWindowsMediaProvider : IMediaProvider
+{
+    private const int MaxCoverInputBytes = 3 * 1024 * 1024;
+    private const int MaxCoverOutputBytes = 500 * 1024;
+    private readonly Func<SongOverlaySettings> _settings;
+    private readonly Func<MediaTrack, CancellationToken, Task<MediaTrack>> _enrich;
+    private readonly Action<string, Exception?> _log;
+    private GlobalSystemMediaTransportControlsSessionManager? _manager;
+    private GlobalSystemMediaTransportControlsSession? _session;
+    private MediaSnapshot? _last;
+    private MediaTrack? _trackCache;
+    private bool _started;
+    private readonly SemaphoreSlim _refreshLock = new(1, 1);
+
+    public SpotifyWindowsMediaProvider(Func<SongOverlaySettings> settings, Func<MediaTrack, CancellationToken, Task<MediaTrack>> enrich, Action<string, Exception?> log)
+    {
+        _settings = settings;
+        _enrich = enrich;
+        _log = log;
+    }
+
+    public string Id => "spotify";
+    public string DisplayName => "Spotify";
+    public event EventHandler<ProviderStateChangedEventArgs>? StateChanged;
+    public event EventHandler<string>? AvailabilityChanged;
+
+    public async Task StartAsync(CancellationToken cancellationToken)
+    {
+        if (_started) return;
+        _manager = await GlobalSystemMediaTransportControlsSessionManager.RequestAsync();
+        _manager.CurrentSessionChanged += OnSessionCollectionChanged;
+        _manager.SessionsChanged += OnSessionCollectionChanged;
+        _started = true;
+        await SelectSessionAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    public async Task StopAsync(CancellationToken cancellationToken)
+    {
+        if (!_started) return;
+        if (_manager is not null)
+        {
+            _manager.CurrentSessionChanged -= OnSessionCollectionChanged;
+            _manager.SessionsChanged -= OnSessionCollectionChanged;
+        }
+        DetachSession();
+        _manager = null;
+        _started = false;
+        await Task.CompletedTask;
+    }
+
+    public Task<MediaSnapshot?> GetSnapshotAsync(CancellationToken cancellationToken) => RefreshAsync("snapshot", true, cancellationToken);
+
+    private async void OnSessionCollectionChanged(GlobalSystemMediaTransportControlsSessionManager sender, object args)
+    {
+        try { await SelectSessionAsync(CancellationToken.None).ConfigureAwait(false); }
+        catch (Exception error) { _log("Could not refresh Spotify media sessions", error); }
+    }
+
+    private async Task SelectSessionAsync(CancellationToken cancellationToken)
+    {
+        var selected = _manager?.GetSessions().FirstOrDefault(IsSpotifySession);
+        if (ReferenceEquals(selected, _session))
+        {
+            if (_session is not null) await RefreshAndPublishAsync("snapshot", false, cancellationToken).ConfigureAwait(false);
+            return;
+        }
+        DetachSession();
+        _session = selected;
+        if (_session is null)
+        {
+            AvailabilityChanged?.Invoke(this, "Spotify is not exposing a Windows media session.");
+            if (_last is not null)
+            {
+                _last = null;
+                StateChanged?.Invoke(this, new ProviderStateChangedEventArgs("stop", null));
+            }
+            return;
+        }
+        _session.MediaPropertiesChanged += OnMediaPropertiesChanged;
+        _session.PlaybackInfoChanged += OnPlaybackInfoChanged;
+        _session.TimelinePropertiesChanged += OnTimelinePropertiesChanged;
+        AvailabilityChanged?.Invoke(this, "Spotify media session connected.");
+        await RefreshAndPublishAsync("snapshot", true, cancellationToken).ConfigureAwait(false);
+    }
+
+    private void DetachSession()
+    {
+        if (_session is null) return;
+        _session.MediaPropertiesChanged -= OnMediaPropertiesChanged;
+        _session.PlaybackInfoChanged -= OnPlaybackInfoChanged;
+        _session.TimelinePropertiesChanged -= OnTimelinePropertiesChanged;
+        _session = null;
+        _trackCache = null;
+    }
+
+    private async void OnMediaPropertiesChanged(GlobalSystemMediaTransportControlsSession sender, MediaPropertiesChangedEventArgs args)
+    {
+        try { await RefreshAndPublishAsync("media", true, CancellationToken.None).ConfigureAwait(false); }
+        catch (Exception error) { _log("Spotify media-property update failed", error); }
+    }
+
+    private async void OnPlaybackInfoChanged(GlobalSystemMediaTransportControlsSession sender, PlaybackInfoChangedEventArgs args)
+    {
+        try { await RefreshAndPublishAsync("playback", false, CancellationToken.None).ConfigureAwait(false); }
+        catch (Exception error) { _log("Spotify playback update failed", error); }
+    }
+
+    private async void OnTimelinePropertiesChanged(GlobalSystemMediaTransportControlsSession sender, TimelinePropertiesChangedEventArgs args)
+    {
+        try { await RefreshAndPublishAsync("timeline", false, CancellationToken.None).ConfigureAwait(false); }
+        catch (Exception error) { _log("Spotify timeline update failed", error); }
+    }
+
+    private async Task RefreshAndPublishAsync(string reason, bool enrichTrack, CancellationToken cancellationToken)
+    {
+        var snapshot = await RefreshAsync(reason, enrichTrack, cancellationToken).ConfigureAwait(false);
+        if (snapshot is null) return;
+        StateChanged?.Invoke(this, new ProviderStateChangedEventArgs(reason, snapshot));
+    }
+
+    private async Task<MediaSnapshot?> RefreshAsync(string reason, bool enrichTrack, CancellationToken cancellationToken)
+    {
+        if (_session is null) return null;
+        await _refreshLock.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            var playback = _session.GetPlaybackInfo();
+            var timeline = _session.GetTimelineProperties();
+            var duration = Math.Max(0, (long)timeline.EndTime.TotalMilliseconds);
+            var position = Math.Max(0, (long)timeline.Position.TotalMilliseconds);
+            var status = playback.PlaybackStatus switch
+            {
+                GlobalSystemMediaTransportControlsSessionPlaybackStatus.Playing => "playing",
+                GlobalSystemMediaTransportControlsSessionPlaybackStatus.Paused => "paused",
+                GlobalSystemMediaTransportControlsSessionPlaybackStatus.Stopped => "stopped",
+                GlobalSystemMediaTransportControlsSessionPlaybackStatus.Closed => "closed",
+                _ => "unknown"
+            };
+            var capturedAt = DateTimeOffset.UtcNow;
+            var rate = playback.PlaybackRate ?? 1d;
+            if (rate <= 0) rate = 1d;
+            if (status == "playing" && timeline.LastUpdatedTime != default)
+            {
+                var elapsed = Math.Max(0, (capturedAt - timeline.LastUpdatedTime).TotalMilliseconds);
+                position += (long)(elapsed * rate);
+                if (duration > 0) position = Math.Min(duration, position);
+            }
+
+            var needsMediaRefresh = _trackCache is null || reason is "media" or "snapshot";
+            if (needsMediaRefresh)
+            {
+                var media = await _session.TryGetMediaPropertiesAsync();
+                var title = Clean(media.Title);
+                var artist = Clean(media.Artist);
+                var album = Clean(media.AlbumTitle);
+                if (!string.IsNullOrWhiteSpace(title) || !string.IsNullOrWhiteSpace(artist))
+                {
+                    var key = Fingerprint(title, artist, album, duration);
+                    var cover = _settings().SendCoverArt ? await ReadCoverAsync(media.Thumbnail, cancellationToken).ConfigureAwait(false) : null;
+                    var fallbackLink = _settings().UseSearchLinkFallback
+                        ? "https://open.spotify.com/search/" + Uri.EscapeDataString(string.Join(" ", new[] { title, artist }.Where(value => value.Length > 0)))
+                        : "";
+                    var track = new MediaTrack(key, title, artist, album, "", fallbackLink, duration, cover);
+                    _trackCache = track;
+                    if (enrichTrack) _ = EnrichAndPublishAsync(track);
+                }
+                else
+                {
+                    _trackCache = null;
+                }
+            }
+            else if (_trackCache is not null && _trackCache.DurationMilliseconds != duration)
+            {
+                _trackCache = _trackCache with { DurationMilliseconds = duration };
+            }
+
+            var snapshot = new MediaSnapshot(Id, status, position, duration, rate, _trackCache, capturedAt);
+            _last = snapshot;
+            return snapshot;
+        }
+        finally { _refreshLock.Release(); }
+    }
+
+
+    private async Task EnrichAndPublishAsync(MediaTrack track)
+    {
+        try
+        {
+            var enriched = await _enrich(track, CancellationToken.None).ConfigureAwait(false);
+            if (enriched == track) return;
+            await _refreshLock.WaitAsync().ConfigureAwait(false);
+            try
+            {
+                if (_trackCache?.Key != track.Key) return;
+                _trackCache = enriched;
+            }
+            finally { _refreshLock.Release(); }
+            await RefreshAndPublishAsync("metadata", false, CancellationToken.None).ConfigureAwait(false);
+        }
+        catch (Exception error) { _log("Spotify metadata enrichment update failed", error); }
+    }
+
+    private static bool IsSpotifySession(GlobalSystemMediaTransportControlsSession session)
+    {
+        var source = session.SourceAppUserModelId ?? "";
+        return source.Contains("spotify", StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static async Task<CoverPayload?> ReadCoverAsync(IRandomAccessStreamReference? reference, CancellationToken cancellationToken)
+    {
+        if (reference is null) return null;
+        try
+        {
+            using var stream = await reference.OpenReadAsync();
+            var length = checked((uint)Math.Min(stream.Size, MaxCoverInputBytes));
+            if (length == 0) return null;
+            using var reader = new DataReader(stream.GetInputStreamAt(0));
+            var loaded = await reader.LoadAsync(length);
+            cancellationToken.ThrowIfCancellationRequested();
+            if (loaded == 0) return null;
+            var bytes = new byte[checked((int)loaded)];
+            reader.ReadBytes(bytes);
+            var mime = string.IsNullOrWhiteSpace(stream.ContentType) ? "image/jpeg" : stream.ContentType;
+            return CreateCoverPayload(bytes, mime);
+        }
+        catch { return null; }
+    }
+
+
+    internal static CoverPayload? CreateCoverPayload(byte[] bytes, string sourceMime)
+    {
+        if (bytes.Length == 0 || bytes.Length > MaxCoverInputBytes) return null;
+        try
+        {
+            var encoded = ResizeJpeg(bytes, 512, 82L);
+            if (encoded.Length > MaxCoverOutputBytes) encoded = ResizeJpeg(bytes, 320, 68L);
+            if (encoded.Length == 0 || encoded.Length > MaxCoverOutputBytes) return null;
+            var colors = ExtractColors(encoded);
+            return new CoverPayload("image/jpeg", Convert.ToBase64String(encoded), colors.Primary, colors.Secondary);
+        }
+        catch { return null; }
+    }
+
+    private static byte[] ResizeJpeg(byte[] bytes, int maximumDimension, long quality)
+    {
+        using var input = new MemoryStream(bytes);
+        using var original = new Bitmap(input);
+        var ratio = Math.Min(1d, Math.Min((double)maximumDimension / original.Width, (double)maximumDimension / original.Height));
+        var width = Math.Max(1, (int)Math.Round(original.Width * ratio));
+        var height = Math.Max(1, (int)Math.Round(original.Height * ratio));
+        using var resized = new Bitmap(width, height, PixelFormat.Format24bppRgb);
+        using (var graphics = Graphics.FromImage(resized))
+        {
+            graphics.Clear(Color.Black);
+            graphics.CompositingQuality = System.Drawing.Drawing2D.CompositingQuality.HighQuality;
+            graphics.InterpolationMode = System.Drawing.Drawing2D.InterpolationMode.HighQualityBicubic;
+            graphics.SmoothingMode = System.Drawing.Drawing2D.SmoothingMode.HighQuality;
+            graphics.PixelOffsetMode = System.Drawing.Drawing2D.PixelOffsetMode.HighQuality;
+            graphics.DrawImage(original, 0, 0, width, height);
+        }
+        using var output = new MemoryStream();
+        var codec = ImageCodecInfo.GetImageEncoders().First(item => item.FormatID == ImageFormat.Jpeg.Guid);
+        using var parameters = new EncoderParameters(1);
+        parameters.Param[0] = new EncoderParameter(System.Drawing.Imaging.Encoder.Quality, quality);
+        resized.Save(output, codec, parameters);
+        return output.ToArray();
+    }
+
+    internal static (string Primary, string Secondary) ExtractColors(byte[] bytes)
+    {
+        try
+        {
+            using var memory = new MemoryStream(bytes);
+            using var bitmap = new Bitmap(memory);
+            var samples = new List<Color>();
+            var stepX = Math.Max(1, bitmap.Width / 12);
+            var stepY = Math.Max(1, bitmap.Height / 12);
+            for (var y = stepY / 2; y < bitmap.Height; y += stepY)
+            for (var x = stepX / 2; x < bitmap.Width; x += stepX)
+            {
+                var color = bitmap.GetPixel(x, y);
+                if (color.A > 100) samples.Add(color);
+            }
+            if (samples.Count == 0) return ("#1f2937", "#111827");
+            var primary = Average(samples.OrderByDescending(c => Saturation(c)).Take(Math.Max(1, samples.Count / 3)));
+            var secondary = Average(samples.OrderBy(c => Brightness(c)).Take(Math.Max(1, samples.Count / 3)));
+            return (Hex(primary), Hex(secondary));
+        }
+        catch { return ("#1f2937", "#111827"); }
+    }
+
+    private static Color Average(IEnumerable<Color> colors)
+    {
+        var list = colors.ToList();
+        return list.Count == 0 ? Color.FromArgb(31, 41, 55) : Color.FromArgb(
+            (int)list.Average(c => c.R), (int)list.Average(c => c.G), (int)list.Average(c => c.B));
+    }
+    private static double Saturation(Color c) => c.GetSaturation();
+    private static double Brightness(Color c) => c.GetBrightness();
+    private static string Hex(Color c) => $"#{c.R:X2}{c.G:X2}{c.B:X2}";
+    private static string Clean(string? value) => string.Join(" ", (value ?? "").Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries)).Trim();
+    private static string Fingerprint(string title, string artist, string album, long duration)
+    {
+        var input = Encoding.UTF8.GetBytes($"{title}\u001f{artist}\u001f{album}\u001f{duration}");
+        return Convert.ToHexString(SHA256.HashData(input)).ToLowerInvariant();
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        await StopAsync(CancellationToken.None).ConfigureAwait(false);
+        _refreshLock.Dispose();
+    }
+}

companion/plugins/Lumi.Companion.SongOverlay/SongOverlayRuntime.cs

@@ -0,0 +1,383 @@
+using Lumi.Companion.Abstractions;
+using Lumi.Companion.SongOverlay.Providers;
+using Lumi.Companion.SongOverlay.Spotify;
+
+namespace Lumi.Companion.SongOverlay;
+
+public sealed class SongOverlayRuntime : ICompanionPluginContribution, IAsyncDisposable
+{
+    private const string PluginId = "now_playing";
+    private readonly SongOverlaySettingsStore _settingsStore;
+    private readonly SongOverlaySecretProtector _secrets = new();
+    private readonly SongOverlayTransport _transport;
+    private readonly string _logDirectory;
+    private IMediaProvider? _provider;
+    private SpotifyWebApiEnricher? _spotify;
+    private CancellationTokenSource? _lifetime;
+    private PeriodicTimer? _heartbeat;
+    private Task? _heartbeatTask;
+    private readonly SemaphoreSlim _eventLock = new(1, 1);
+    private MediaSnapshot? _lastObserved;
+    private MediaSnapshot? _lastDelivered;
+    private readonly List<string> _trackHistory = [];
+    private int _historyIndex = -1;
+    private long _sequence;
+    private readonly string _sessionId = Guid.NewGuid().ToString("N");
+    private bool _initialized;
+
+    public SongOverlayRuntime(
+        string pluginDataDirectory,
+        string logDirectory,
+        ICompanionPluginTransport hostTransport)
+    {
+        Directory.CreateDirectory(pluginDataDirectory);
+        _logDirectory = logDirectory;
+        _settingsStore = new SongOverlaySettingsStore(Path.Combine(pluginDataDirectory, "settings.json"));
+        _transport = new SongOverlayTransport(hostTransport);
+        Actions =
+        [
+            new CompanionPluginAction("send", () => "Send current song now", SendSnapshotAsync, () => _initialized && Settings.Enabled, 10),
+            new CompanionPluginAction("toggle", () => Settings.Enabled ? "Disable monitoring" : "Enable monitoring", ToggleEnabledAsync, () => _initialized, 20)
+        ];
+    }
+
+    public CompanionPluginDescriptor Descriptor { get; } = new(
+        PluginId,
+        "Song Overlay",
+        new Version(0, 1, 1),
+        "Reads provider-neutral Windows media-session events and sends minimal playback changes to Lumi.",
+        200);
+
+    public IReadOnlyList<CompanionPluginPage> Pages { get; } =
+    [
+        new CompanionPluginPage("SongOverlay", "Overview & settings", 10)
+    ];
+
+    public IReadOnlyList<CompanionPluginAction> Actions { get; }
+    public CompanionPluginStatus Status { get; private set; } = new(CompanionPluginHealth.Ready, "Starting", "Waiting for initialization.");
+    public SongOverlaySettings Settings => _settingsStore.Current;
+    public bool IsInitialized => _initialized;
+    public bool IsSpotifyEnrichmentConnected => _spotify?.IsConfigured == true;
+    public bool UsesCompanionAuthentication => _transport.IsConfigured;
+    public string ProviderStatus => Status.Detail ?? Status.Summary;
+    public string? CurrentTrack => _lastObserved?.Track is null ? null : $"{_lastObserved.Track.Title} — {_lastObserved.Track.Artist}";
+    public Uri? EffectiveLumiBaseUri => _transport.BaseUri;
+    public event Action? Changed;
+
+    public async Task InitializeAsync(CancellationToken cancellationToken = default)
+    {
+        await _settingsStore.LoadAsync(cancellationToken).ConfigureAwait(false);
+        if (string.IsNullOrWhiteSpace(Settings.ProviderId)) Settings.ProviderId = "spotify";
+        // Re-save through the current schema so legacy plugin-specific Lumi host
+        // and connection-key fields are removed after the shared transport upgrade.
+        await _settingsStore.SaveAsync(Settings, cancellationToken).ConfigureAwait(false);
+        _spotify = new SpotifyWebApiEnricher(Settings, _secrets, SaveSettingsSync, Log);
+        _initialized = true;
+        await RestartProviderAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    public async Task SaveSettingsAsync(bool restartProvider, CancellationToken cancellationToken = default)
+    {
+        Settings.HeartbeatSeconds = Math.Clamp(Settings.HeartbeatSeconds, 15, 300);
+        Settings.SeekThresholdMilliseconds = Math.Clamp(Settings.SeekThresholdMilliseconds, 500, 10000);
+        Settings.ProviderId = string.IsNullOrWhiteSpace(Settings.ProviderId) ? "spotify" : Settings.ProviderId.Trim().ToLowerInvariant();
+        await _settingsStore.SaveAsync(Settings, cancellationToken).ConfigureAwait(false);
+        if (restartProvider) await RestartProviderAsync(cancellationToken).ConfigureAwait(false);
+        RaiseChanged();
+    }
+
+    public async Task ToggleEnabledAsync(CancellationToken cancellationToken = default)
+    {
+        Settings.Enabled = !Settings.Enabled;
+        await SaveSettingsAsync(restartProvider: true, cancellationToken).ConfigureAwait(false);
+    }
+
+    public async Task ConnectSpotifyAsync(CancellationToken cancellationToken = default)
+    {
+        EnsureInitialized();
+        await _spotify!.AuthorizeAsync(cancellationToken).ConfigureAwait(false);
+        SaveSettingsSync();
+        RaiseChanged();
+        if (_transport.IsConfigured)
+            await SendSnapshotAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    public void DisconnectSpotify()
+    {
+        _spotify?.Disconnect();
+        RaiseChanged();
+    }
+
+    public async Task SendSnapshotAsync(CancellationToken cancellationToken = default)
+    {
+        EnsureInitialized();
+        if (!_transport.IsConfigured) throw new InvalidOperationException("Pair Companion with Lumi before sending song updates.");
+        if (_provider is null) throw new InvalidOperationException("No media provider is running.");
+        var snapshot = await _provider.GetSnapshotAsync(cancellationToken).ConfigureAwait(false);
+        if (snapshot is null) throw new InvalidOperationException("Spotify is not currently exposing playback information.");
+        await SendAsync("snapshot", snapshot, includeTrack: true, cancellationToken).ConfigureAwait(false);
+    }
+
+    private async Task RestartProviderAsync(CancellationToken cancellationToken)
+    {
+        await StopProviderAsync().ConfigureAwait(false);
+        if (!Settings.Enabled)
+        {
+            SetStatus(CompanionPluginHealth.Ready, "Disabled", "Song Overlay monitoring is disabled.");
+            return;
+        }
+        _lastObserved = null;
+        _lastDelivered = null;
+        _lifetime = new CancellationTokenSource();
+        _provider = Settings.ProviderId switch
+        {
+            "spotify" => new SpotifyWindowsMediaProvider(() => Settings, EnrichTrackAsync, Log),
+            _ => throw new InvalidOperationException($"Provider '{Settings.ProviderId}' is not installed.")
+        };
+        _provider.StateChanged += OnProviderStateChanged;
+        _provider.AvailabilityChanged += OnAvailabilityChanged;
+        try
+        {
+            await _provider.StartAsync(cancellationToken).ConfigureAwait(false);
+            StartHeartbeat();
+            var initial = await _provider.GetSnapshotAsync(cancellationToken).ConfigureAwait(false);
+            if (!_transport.IsConfigured)
+                SetStatus(CompanionPluginHealth.Warning, "Pairing required", "Spotify monitoring is ready, but Companion must be paired before Lumi can receive updates.");
+            else if (initial is null)
+                SetStatus(CompanionPluginHealth.Warning, "Waiting for Spotify", "Spotify is not currently exposing a Windows media session.");
+            else
+                SetStatus(CompanionPluginHealth.Healthy, "Monitoring", Describe(initial));
+        }
+        catch (Exception error)
+        {
+            SetStatus(CompanionPluginHealth.Error, "Provider failed", "Could not start the Spotify media provider: " + error.Message);
+            throw;
+        }
+    }
+
+    private async Task StopProviderAsync()
+    {
+        _lifetime?.Cancel();
+        _heartbeat?.Dispose();
+        if (_heartbeatTask is not null)
+        {
+            try { await _heartbeatTask.ConfigureAwait(false); } catch { }
+        }
+        _heartbeat = null;
+        _heartbeatTask = null;
+        if (_provider is not null)
+        {
+            _provider.StateChanged -= OnProviderStateChanged;
+            _provider.AvailabilityChanged -= OnAvailabilityChanged;
+            await _provider.DisposeAsync().ConfigureAwait(false);
+        }
+        _provider = null;
+        _lifetime?.Dispose();
+        _lifetime = null;
+    }
+
+    private void StartHeartbeat()
+    {
+        _heartbeat = new PeriodicTimer(TimeSpan.FromSeconds(Math.Clamp(Settings.HeartbeatSeconds, 15, 300)));
+        var token = _lifetime?.Token ?? CancellationToken.None;
+        _heartbeatTask = Task.Run(async () =>
+        {
+            try
+            {
+                while (_heartbeat is not null && await _heartbeat.WaitForNextTickAsync(token).ConfigureAwait(false))
+                {
+                    var current = _lastObserved;
+                    if (current is null || !_transport.IsConfigured) continue;
+                    await SendAsync("heartbeat", current, includeTrack: _lastDelivered?.Track?.Key != current.Track?.Key, token).ConfigureAwait(false);
+                }
+            }
+            catch (OperationCanceledException) { }
+            catch (Exception error) { Log("Song Overlay heartbeat failed", error); }
+        }, token);
+    }
+
+    private void OnAvailabilityChanged(object? sender, string message)
+    {
+        if (!_transport.IsConfigured)
+        {
+            SetStatus(CompanionPluginHealth.Warning, "Pairing required", message);
+            return;
+        }
+        var waiting = message.Contains("not exposing", StringComparison.OrdinalIgnoreCase);
+        SetStatus(waiting ? CompanionPluginHealth.Warning : CompanionPluginHealth.Healthy,
+            waiting ? "Waiting for Spotify" : "Monitoring", message);
+    }
+
+    private void OnProviderStateChanged(object? sender, ProviderStateChangedEventArgs args) =>
+        _ = HandleStateChangeAsync(args.Reason, args.Snapshot, _lifetime?.Token ?? CancellationToken.None);
+
+    private async Task HandleStateChangeAsync(string reason, MediaSnapshot? snapshot, CancellationToken cancellationToken)
+    {
+        await _eventLock.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            if (snapshot is null)
+            {
+                if (_lastObserved is null) return;
+                var stopped = _lastObserved with { Status = "stopped", PositionMilliseconds = 0, Track = null, CapturedAt = DateTimeOffset.UtcNow };
+                _lastObserved = null;
+                if (_transport.IsConfigured) await SendAsync("stop", stopped, false, cancellationToken).ConfigureAwait(false);
+                else RaiseChanged();
+                return;
+            }
+            var previous = _lastObserved;
+            _lastObserved = snapshot;
+            RaiseChanged();
+            if (!_transport.IsConfigured)
+            {
+                SetStatus(CompanionPluginHealth.Warning, "Pairing required", Describe(snapshot));
+                return;
+            }
+            var currentTrackKey = snapshot.Track?.Key;
+            var trackChanged = !string.IsNullOrWhiteSpace(currentTrackKey)
+                && !string.Equals(currentTrackKey, previous?.Track?.Key, StringComparison.Ordinal);
+            if (trackChanged)
+            {
+                await SendAsync(ClassifyTrackDirection(currentTrackKey!), snapshot, true, cancellationToken).ConfigureAwait(false);
+                return;
+            }
+            if (previous is null)
+            {
+                await SendAsync("snapshot", snapshot, true, cancellationToken).ConfigureAwait(false);
+                return;
+            }
+            if (reason == "metadata")
+            {
+                await SendAsync("snapshot", snapshot, true, cancellationToken).ConfigureAwait(false);
+                return;
+            }
+            if (!string.Equals(previous.Status, snapshot.Status, StringComparison.Ordinal))
+            {
+                var playbackEvent = snapshot.Status switch
+                {
+                    "paused" => "pause",
+                    "stopped" or "closed" => "stop",
+                    "playing" when previous.Status == "paused" => "resume",
+                    "playing" => "play",
+                    _ => "snapshot"
+                };
+                await SendAsync(playbackEvent, snapshot, false, cancellationToken).ConfigureAwait(false);
+                return;
+            }
+            if (reason == "timeline")
+            {
+                var expected = ProjectPosition(previous, snapshot.CapturedAt);
+                if (Math.Abs(snapshot.PositionMilliseconds - expected) >= Math.Clamp(Settings.SeekThresholdMilliseconds, 500, 10000))
+                    await SendAsync("seek", snapshot, false, cancellationToken).ConfigureAwait(false);
+            }
+        }
+        catch (OperationCanceledException) { }
+        catch (Exception error)
+        {
+            Log("Could not process a Song Overlay event", error);
+            SetStatus(CompanionPluginHealth.Warning, "Delivery delayed", "Playback was detected, but Lumi could not be updated: " + error.Message);
+        }
+        finally { _eventLock.Release(); }
+    }
+
+    private async Task SendAsync(string eventName, MediaSnapshot snapshot, bool includeTrack, CancellationToken cancellationToken)
+    {
+        var track = includeTrack && snapshot.Track is not null
+            ? new TrackPayload(snapshot.Track.Key, snapshot.Track.Title, snapshot.Track.Artist, snapshot.Track.Album,
+                snapshot.Track.ReleaseYear, snapshot.Track.Link, snapshot.Track.Cover)
+            : null;
+        var payload = new NowPlayingEventPayload(
+            1,
+            snapshot.Provider,
+            _sessionId,
+            Interlocked.Increment(ref _sequence),
+            eventName,
+            snapshot.CapturedAt.ToUnixTimeMilliseconds(),
+            new PlaybackPayload(snapshot.Status, snapshot.PositionMilliseconds, snapshot.DurationMilliseconds, snapshot.PlaybackRate),
+            track);
+        var response = await _transport.SendJsonAsync("/plugins/now_playing/api/companion/state", payload, cancellationToken).ConfigureAwait(false);
+        if (!response.IsSuccessStatusCode)
+        {
+            throw new InvalidOperationException($"Lumi rejected the update with HTTP {response.StatusCode}: {Trim(response.Body, 240)}");
+        }
+        _lastDelivered = snapshot;
+        SetStatus(CompanionPluginHealth.Healthy, snapshot.Status == "playing" ? "Playing" : "Connected", Describe(snapshot));
+    }
+
+    private async Task<MediaTrack> EnrichTrackAsync(MediaTrack track, CancellationToken cancellationToken)
+    {
+        if (_spotify?.IsConfigured != true) return track;
+        SpotifyEnrichment? enriched = null;
+        foreach (var delay in new[] { 0, 500, 1000 })
+        {
+            if (delay > 0) await Task.Delay(delay, cancellationToken).ConfigureAwait(false);
+            enriched = await _spotify.EnrichAsync(track, cancellationToken).ConfigureAwait(false);
+            if (enriched is not null) break;
+        }
+        if (enriched is null) return track;
+        CoverPayload? cover = track.Cover;
+        if (enriched.CoverBytes is { Length: > 0 } bytes && Settings.SendCoverArt)
+            cover = SpotifyWindowsMediaProvider.CreateCoverPayload(bytes, enriched.CoverMime) ?? cover;
+        return track with
+        {
+            Link = string.IsNullOrWhiteSpace(enriched.Link) ? track.Link : enriched.Link,
+            ReleaseYear = string.IsNullOrWhiteSpace(enriched.ReleaseYear) ? track.ReleaseYear : enriched.ReleaseYear,
+            Cover = cover
+        };
+    }
+
+    private string ClassifyTrackDirection(string key)
+    {
+        if (_historyIndex > 0 && _trackHistory[_historyIndex - 1] == key) { _historyIndex--; return "previous"; }
+        if (_historyIndex >= 0 && _historyIndex + 1 < _trackHistory.Count && _trackHistory[_historyIndex + 1] == key) { _historyIndex++; return "next"; }
+        if (_historyIndex + 1 < _trackHistory.Count) _trackHistory.RemoveRange(_historyIndex + 1, _trackHistory.Count - _historyIndex - 1);
+        _trackHistory.Add(key);
+        if (_trackHistory.Count > 50) _trackHistory.RemoveAt(0);
+        _historyIndex = _trackHistory.Count - 1;
+        return "track_changed";
+    }
+
+    private static long ProjectPosition(MediaSnapshot snapshot, DateTimeOffset at)
+    {
+        if (snapshot.Status != "playing") return snapshot.PositionMilliseconds;
+        var elapsed = Math.Max(0, (at - snapshot.CapturedAt).TotalMilliseconds);
+        return Math.Min(snapshot.DurationMilliseconds > 0 ? snapshot.DurationMilliseconds : long.MaxValue,
+            snapshot.PositionMilliseconds + (long)(elapsed * snapshot.PlaybackRate));
+    }
+
+    private void SaveSettingsSync() => _settingsStore.Save(Settings);
+    private void EnsureInitialized()
+    {
+        if (!_initialized) throw new InvalidOperationException("The Song Overlay companion plugin has not initialized yet.");
+    }
+
+    private void SetStatus(CompanionPluginHealth health, string summary, string detail)
+    {
+        Status = new CompanionPluginStatus(health, summary, detail);
+        RaiseChanged();
+    }
+
+    private void RaiseChanged() => Changed?.Invoke();
+    private void Log(string message, Exception? error = null)
+    {
+        try
+        {
+            Directory.CreateDirectory(_logDirectory);
+            File.AppendAllText(Path.Combine(_logDirectory, $"song-overlay-{DateTime.UtcNow:yyyyMMdd}.log"),
+                $"{DateTimeOffset.Now:O}\t{message}{(error is null ? "" : "\t" + error)}{Environment.NewLine}");
+        }
+        catch { }
+    }
+
+    private static string Describe(MediaSnapshot snapshot) => snapshot.Track is null
+        ? "Connected; no active song."
+        : $"{snapshot.Status}: {snapshot.Track.Title} — {snapshot.Track.Artist}";
+    private static string Trim(string value, int max) => value.Length <= max ? value : value[..max];
+
+    public async ValueTask DisposeAsync()
+    {
+        await StopProviderAsync().ConfigureAwait(false);
+        _spotify?.Dispose();
+        _eventLock.Dispose();
+    }
+}

companion/plugins/Lumi.Companion.SongOverlay/SongOverlaySecretProtector.cs

@@ -0,0 +1,28 @@
+using System.Security.Cryptography;
+using System.Text;
+
+namespace Lumi.Companion.SongOverlay;
+
+internal sealed class SongOverlaySecretProtector
+{
+    private static readonly byte[] Entropy = "Lumi.Companion.SongOverlay.v1"u8.ToArray();
+
+    public string Protect(string value)
+    {
+        if (string.IsNullOrWhiteSpace(value)) return "";
+        return Convert.ToBase64String(ProtectedData.Protect(Encoding.UTF8.GetBytes(value), Entropy, DataProtectionScope.CurrentUser));
+    }
+
+    public string Unprotect(string value)
+    {
+        if (string.IsNullOrWhiteSpace(value)) return "";
+        try
+        {
+            return Encoding.UTF8.GetString(ProtectedData.Unprotect(Convert.FromBase64String(value), Entropy, DataProtectionScope.CurrentUser));
+        }
+        catch (CryptographicException)
+        {
+            return "";
+        }
+    }
+}

companion/plugins/Lumi.Companion.SongOverlay/SongOverlaySettings.cs

@@ -0,0 +1,13 @@
+namespace Lumi.Companion.SongOverlay;
+
+public sealed class SongOverlaySettings
+{
+    public bool Enabled { get; set; } = true;
+    public string ProviderId { get; set; } = "spotify";
+    public int HeartbeatSeconds { get; set; } = 30;
+    public int SeekThresholdMilliseconds { get; set; } = 1500;
+    public bool SendCoverArt { get; set; } = true;
+    public bool UseSearchLinkFallback { get; set; } = true;
+    public string SpotifyClientId { get; set; } = "";
+    public string ProtectedSpotifyRefreshToken { get; set; } = "";
+}

companion/plugins/Lumi.Companion.SongOverlay/SongOverlaySettingsStore.cs

@@ -0,0 +1,68 @@
+using System.Text.Json;
+
+namespace Lumi.Companion.SongOverlay;
+
+internal sealed class SongOverlaySettingsStore(string path)
+{
+    private readonly SemaphoreSlim _gate = new(1, 1);
+    public SongOverlaySettings Current { get; private set; } = new();
+
+    public async Task LoadAsync(CancellationToken cancellationToken = default)
+    {
+        if (!File.Exists(path)) return;
+        try
+        {
+            Current = JsonSerializer.Deserialize<SongOverlaySettings>(
+                await File.ReadAllBytesAsync(path, cancellationToken),
+                SongOverlayJson.Options) ?? new();
+        }
+        catch (JsonException)
+        {
+            Current = new();
+        }
+    }
+
+    public void Save(SongOverlaySettings settings)
+    {
+        _gate.Wait();
+        try
+        {
+            Directory.CreateDirectory(Path.GetDirectoryName(path)!);
+            var temporary = $"{path}.{Environment.ProcessId}.tmp";
+            try
+            {
+                File.WriteAllBytes(temporary, JsonSerializer.SerializeToUtf8Bytes(settings, SongOverlayJson.Options));
+                File.Move(temporary, path, true);
+            }
+            finally { File.Delete(temporary); }
+            Current = settings;
+        }
+        finally { _gate.Release(); }
+    }
+
+    public async Task SaveAsync(SongOverlaySettings settings, CancellationToken cancellationToken = default)
+    {
+        await _gate.WaitAsync(cancellationToken);
+        try
+        {
+            Directory.CreateDirectory(Path.GetDirectoryName(path)!);
+            var temporary = $"{path}.{Environment.ProcessId}.tmp";
+            try
+            {
+                await File.WriteAllBytesAsync(temporary, JsonSerializer.SerializeToUtf8Bytes(settings, SongOverlayJson.Options), cancellationToken);
+                File.Move(temporary, path, true);
+            }
+            finally { File.Delete(temporary); }
+            Current = settings;
+        }
+        finally { _gate.Release(); }
+    }
+}
+
+internal static class SongOverlayJson
+{
+    public static readonly JsonSerializerOptions Options = new(JsonSerializerDefaults.Web)
+    {
+        DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull
+    };
+}

companion/plugins/Lumi.Companion.SongOverlay/SongOverlayTransport.cs

@@ -0,0 +1,16 @@
+using Lumi.Companion.Abstractions;
+
+namespace Lumi.Companion.SongOverlay;
+
+internal sealed class SongOverlayTransport(ICompanionPluginTransport host)
+{
+    public Uri? BaseUri => host.LumiBaseUri;
+
+    public bool IsConfigured => host.IsAuthenticated;
+
+    public Task<CompanionPluginHttpResponse> SendJsonAsync(
+        string relativePath,
+        object payload,
+        CancellationToken cancellationToken = default) =>
+        host.PostJsonAsync(relativePath, payload, cancellationToken);
+}

companion/plugins/Lumi.Companion.SongOverlay/Spotify/SpotifyWebApiEnricher.cs

@@ -0,0 +1,256 @@
+using System.Diagnostics;
+using System.Net;
+using System.Net.Http.Headers;
+using System.Net.Sockets;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+
+namespace Lumi.Companion.SongOverlay.Spotify;
+
+internal sealed record SpotifyEnrichment(string Link, string ReleaseYear, byte[]? CoverBytes, string CoverMime);
+
+internal sealed class SpotifyWebApiEnricher : IDisposable
+{
+    private const string Scope = "user-read-currently-playing";
+    private readonly HttpClient _http = new() { Timeout = TimeSpan.FromSeconds(15) };
+    private readonly SongOverlaySecretProtector _secrets;
+    private readonly Action _save;
+    private readonly Action<string, Exception?> _log;
+    private readonly SongOverlaySettings _settings;
+    private string _accessToken = "";
+    private DateTimeOffset _accessTokenExpiresAt = DateTimeOffset.MinValue;
+
+    public SpotifyWebApiEnricher(SongOverlaySettings settings, SongOverlaySecretProtector secrets, Action save, Action<string, Exception?> log)
+    {
+        _settings = settings;
+        _secrets = secrets;
+        _save = save;
+        _log = log;
+        _http.DefaultRequestHeaders.UserAgent.ParseAdd("Lumi-Companion-NowPlaying/0.1.0");
+    }
+
+    public bool IsConfigured => !string.IsNullOrWhiteSpace(_settings.SpotifyClientId) && !string.IsNullOrWhiteSpace(_settings.ProtectedSpotifyRefreshToken);
+
+    public async Task AuthorizeAsync(CancellationToken cancellationToken)
+    {
+        var clientId = _settings.SpotifyClientId.Trim();
+        if (string.IsNullOrWhiteSpace(clientId)) throw new InvalidOperationException("Enter your Spotify application Client ID first.");
+
+        var verifier = Base64Url(RandomNumberGenerator.GetBytes(64));
+        var challenge = Base64Url(SHA256.HashData(Encoding.ASCII.GetBytes(verifier)));
+        var state = Base64Url(RandomNumberGenerator.GetBytes(24));
+        var port = FindFreePort();
+        var redirectUri = $"http://127.0.0.1:{port}/callback/";
+        using var listener = new HttpListener();
+        listener.Prefixes.Add(redirectUri);
+        listener.Start();
+
+        var authorizationUrl = "https://accounts.spotify.com/authorize?" + BuildQuery(new Dictionary<string, string>
+        {
+            ["client_id"] = clientId,
+            ["response_type"] = "code",
+            ["redirect_uri"] = redirectUri,
+            ["scope"] = Scope,
+            ["code_challenge_method"] = "S256",
+            ["code_challenge"] = challenge,
+            ["state"] = state
+        });
+        Process.Start(new ProcessStartInfo(authorizationUrl) { UseShellExecute = true });
+
+        using var timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+        timeout.CancelAfter(TimeSpan.FromMinutes(3));
+        var contextTask = listener.GetContextAsync();
+        var completed = await Task.WhenAny(contextTask, Task.Delay(Timeout.InfiniteTimeSpan, timeout.Token)).ConfigureAwait(false);
+        if (completed != contextTask) throw new TimeoutException("Spotify authorization timed out.");
+        var context = await contextTask.ConfigureAwait(false);
+        var query = context.Request.QueryString;
+        var responseText = "Spotify is connected to Lumi Companion. You can close this page.";
+        try
+        {
+            if (!string.Equals(query["state"], state, StringComparison.Ordinal)) throw new InvalidOperationException("Spotify returned an invalid authorization state.");
+            if (!string.IsNullOrWhiteSpace(query["error"])) throw new InvalidOperationException("Spotify authorization was declined: " + query["error"]);
+            var code = query["code"] ?? throw new InvalidOperationException("Spotify did not return an authorization code.");
+            var token = await ExchangeAsync(new Dictionary<string, string>
+            {
+                ["client_id"] = clientId,
+                ["grant_type"] = "authorization_code",
+                ["code"] = code,
+                ["redirect_uri"] = redirectUri,
+                ["code_verifier"] = verifier
+            }, cancellationToken).ConfigureAwait(false);
+            ApplyToken(token);
+            if (string.IsNullOrWhiteSpace(token.RefreshToken)) throw new InvalidOperationException("Spotify did not provide a refresh token.");
+            _settings.ProtectedSpotifyRefreshToken = _secrets.Protect(token.RefreshToken);
+            _save();
+        }
+        catch
+        {
+            responseText = "Spotify could not be connected to Lumi Companion. Return to the app for details.";
+            throw;
+        }
+        finally
+        {
+            var bytes = Encoding.UTF8.GetBytes($"<!doctype html><meta charset=\"utf-8\"><title>Lumi Companion</title><style>body{{font:18px system-ui;max-width:720px;margin:15vh auto;padding:24px;background:#111827;color:#f9fafb}}</style><h1>Lumi Companion</h1><p>{WebUtility.HtmlEncode(responseText)}</p>");
+            context.Response.ContentType = "text/html; charset=utf-8";
+            context.Response.ContentLength64 = bytes.Length;
+            await context.Response.OutputStream.WriteAsync(bytes, cancellationToken).ConfigureAwait(false);
+            context.Response.Close();
+        }
+    }
+
+    public void Disconnect()
+    {
+        _accessToken = "";
+        _accessTokenExpiresAt = DateTimeOffset.MinValue;
+        _settings.ProtectedSpotifyRefreshToken = "";
+        _save();
+    }
+
+    public async Task<SpotifyEnrichment?> EnrichAsync(MediaTrack track, CancellationToken cancellationToken)
+    {
+        if (!IsConfigured) return null;
+        try
+        {
+            var token = await GetAccessTokenAsync(cancellationToken).ConfigureAwait(false);
+            if (string.IsNullOrWhiteSpace(token)) return null;
+            using var response = await SendCurrentlyPlayingAsync(token, cancellationToken).ConfigureAwait(false);
+            if (response.StatusCode == HttpStatusCode.NoContent) return null;
+            if (response.StatusCode == HttpStatusCode.Unauthorized)
+            {
+                _accessToken = "";
+                token = await GetAccessTokenAsync(cancellationToken).ConfigureAwait(false);
+                if (string.IsNullOrWhiteSpace(token)) return null;
+                using var retry = await SendCurrentlyPlayingAsync(token, cancellationToken).ConfigureAwait(false);
+                if (retry.StatusCode == HttpStatusCode.NoContent || !retry.IsSuccessStatusCode) return null;
+                return await ParseEnrichmentAsync(retry, track, cancellationToken).ConfigureAwait(false);
+            }
+            if (!response.IsSuccessStatusCode) return null;
+            return await ParseEnrichmentAsync(response, track, cancellationToken).ConfigureAwait(false);
+        }
+        catch (Exception error)
+        {
+            _log("Spotify metadata enrichment failed", error);
+            return null;
+        }
+    }
+
+
+    private async Task<HttpResponseMessage> SendCurrentlyPlayingAsync(string token, CancellationToken cancellationToken)
+    {
+        using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.spotify.com/v1/me/player/currently-playing?additional_types=track");
+        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
+        return await _http.SendAsync(request, cancellationToken).ConfigureAwait(false);
+    }
+
+    private async Task<SpotifyEnrichment?> ParseEnrichmentAsync(HttpResponseMessage response, MediaTrack track, CancellationToken cancellationToken)
+    {
+        using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false));
+        if (!document.RootElement.TryGetProperty("item", out var item) || item.ValueKind != JsonValueKind.Object) return null;
+        var title = String(item, "name");
+        var artists = item.TryGetProperty("artists", out var artistArray) && artistArray.ValueKind == JsonValueKind.Array
+            ? string.Join(", ", artistArray.EnumerateArray().Select(value => String(value, "name")).Where(value => value.Length > 0))
+            : "";
+        if (!LooseMatch(track.Title, title) || (!string.IsNullOrWhiteSpace(track.Artist) && !LooseMatch(track.Artist, artists))) return null;
+        var link = item.TryGetProperty("external_urls", out var urls) ? String(urls, "spotify") : "";
+        var releaseYear = "";
+        string imageUrl = "";
+        if (item.TryGetProperty("album", out var album))
+        {
+            var releaseDate = String(album, "release_date");
+            if (releaseDate.Length >= 4) releaseYear = releaseDate[..4];
+            if (album.TryGetProperty("images", out var images) && images.ValueKind == JsonValueKind.Array)
+                imageUrl = images.EnumerateArray().Select(value => String(value, "url")).FirstOrDefault(value => value.Length > 0) ?? "";
+        }
+        byte[]? cover = null;
+        var mime = "image/jpeg";
+        if (!string.IsNullOrWhiteSpace(imageUrl))
+        {
+            using var imageResponse = await _http.GetAsync(imageUrl, cancellationToken).ConfigureAwait(false);
+            if (imageResponse.IsSuccessStatusCode)
+            {
+                cover = await imageResponse.Content.ReadAsByteArrayAsync(cancellationToken).ConfigureAwait(false);
+                if (cover.Length > 3 * 1024 * 1024) cover = null;
+                mime = imageResponse.Content.Headers.ContentType?.MediaType ?? mime;
+            }
+        }
+        return new SpotifyEnrichment(link, releaseYear, cover, mime);
+    }
+
+    private async Task<string> GetAccessTokenAsync(CancellationToken cancellationToken)
+    {
+        if (!string.IsNullOrWhiteSpace(_accessToken) && _accessTokenExpiresAt > DateTimeOffset.UtcNow.AddMinutes(1)) return _accessToken;
+        var refreshToken = _secrets.Unprotect(_settings.ProtectedSpotifyRefreshToken);
+        if (string.IsNullOrWhiteSpace(refreshToken)) return "";
+        try
+        {
+            var token = await ExchangeAsync(new Dictionary<string, string>
+            {
+                ["client_id"] = _settings.SpotifyClientId.Trim(),
+                ["grant_type"] = "refresh_token",
+                ["refresh_token"] = refreshToken
+            }, cancellationToken).ConfigureAwait(false);
+            ApplyToken(token);
+            if (!string.IsNullOrWhiteSpace(token.RefreshToken))
+            {
+                _settings.ProtectedSpotifyRefreshToken = _secrets.Protect(token.RefreshToken);
+                _save();
+            }
+            return _accessToken;
+        }
+        catch (SpotifyInvalidGrantException)
+        {
+            Disconnect();
+            return "";
+        }
+    }
+
+    private async Task<TokenResponse> ExchangeAsync(Dictionary<string, string> values, CancellationToken cancellationToken)
+    {
+        using var response = await _http.PostAsync("https://accounts.spotify.com/api/token", new FormUrlEncodedContent(values), cancellationToken).ConfigureAwait(false);
+        var body = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+        if (!response.IsSuccessStatusCode)
+        {
+            if (body.Contains("invalid_grant", StringComparison.OrdinalIgnoreCase)) throw new SpotifyInvalidGrantException();
+            throw new InvalidOperationException($"Spotify token exchange failed with HTTP {(int)response.StatusCode}.");
+        }
+        using var document = JsonDocument.Parse(body);
+        return new TokenResponse(
+            String(document.RootElement, "access_token"),
+            String(document.RootElement, "refresh_token"),
+            document.RootElement.TryGetProperty("expires_in", out var expires) ? expires.GetInt32() : 3600);
+    }
+
+    private void ApplyToken(TokenResponse token)
+    {
+        _accessToken = token.AccessToken;
+        _accessTokenExpiresAt = DateTimeOffset.UtcNow.AddSeconds(Math.Max(60, token.ExpiresIn));
+    }
+
+    private static string String(JsonElement element, string property) =>
+        element.TryGetProperty(property, out var value) && value.ValueKind == JsonValueKind.String ? value.GetString() ?? "" : "";
+
+    private static bool LooseMatch(string left, string right)
+    {
+        static string Normalize(string value) => new(value.ToLowerInvariant().Where(char.IsLetterOrDigit).ToArray());
+        var a = Normalize(left); var b = Normalize(right);
+        return a.Length > 0 && b.Length > 0 && (a == b || a.Contains(b, StringComparison.Ordinal) || b.Contains(a, StringComparison.Ordinal));
+    }
+
+    private static int FindFreePort()
+    {
+        var listener = new TcpListener(IPAddress.Loopback, 0);
+        listener.Start();
+        var port = ((IPEndPoint)listener.LocalEndpoint).Port;
+        listener.Stop();
+        return port;
+    }
+
+    private static string BuildQuery(IEnumerable<KeyValuePair<string, string>> values) =>
+        string.Join("&", values.Select(pair => $"{Uri.EscapeDataString(pair.Key)}={Uri.EscapeDataString(pair.Value)}"));
+    private static string Base64Url(byte[] bytes) => Convert.ToBase64String(bytes).TrimEnd('=').Replace('+', '-').Replace('/', '_');
+
+    public void Dispose() => _http.Dispose();
+    private sealed record TokenResponse(string AccessToken, string RefreshToken, int ExpiresIn);
+    private sealed class SpotifyInvalidGrantException : Exception { }
+}

companion/plugins/Lumi.Companion.SongOverlay/plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "now_playing",
+  "name": "Song Overlay",
+  "version": "0.1.2",
+  "provider_api": 1,
+  "providers": ["spotify"],
+  "capabilities": [
+    "windows.media-session.read",
+    "network.lumi",
+    "network.spotify.optional"
+  ],
+  "navigation": {
+    "root": "Song Overlay",
+    "pages": ["SongOverlay"]
+  }
+}

companion/scripts/build-obs-bridge.ps1

@@ -1,6 +1,6 @@
 param(
   [string]$ObsVersion = "31.1.1",
-  [string]$BridgeVersion = "0.1.0-experimental.5",
+  [string]$BridgeVersion = "0.1.0",
   [string]$CacheRoot = "$env:LOCALAPPDATA\LumiCompanionBuild"
 )
 
@@ -79,11 +79,19 @@ New-Item -ItemType Directory -Force -Path $importRoot | Out-Null
 New-ImportLibrary (Join-Path $runtimeRoot "bin\64bit\obs.dll") "obs" $dumpbin $lib
 New-ImportLibrary (Join-Path $runtimeRoot "bin\64bit\obs-frontend-api.dll") "obs-frontend-api" $dumpbin $lib
 
-$configureArguments = @("-S", "`"$nativeRoot`"", "-B", "`"$buildRoot`"", "-G", "`"Visual Studio 17 2022`"", "-A", "x64", "`"-DOBS_SOURCE_DIR=$sourceRoot`"", "`"-DOBS_IMPORT_DIR=$importRoot`"", "`"-DLUMI_BRIDGE_VERSION=$BridgeVersion`"")
-$configured = Start-Process -FilePath $cmake -ArgumentList $configureArguments -NoNewWindow -Wait -PassThru
-if ($configured.ExitCode) { throw "OBS bridge configuration failed." }
-$built = Start-Process -FilePath $cmake -ArgumentList @("--build", "`"$buildRoot`"", "--config", "Release") -NoNewWindow -Wait -PassThru
-if ($built.ExitCode) { throw "OBS bridge build failed." }
+$configureArguments = @(
+  "-S", $nativeRoot,
+  "-B", $buildRoot,
+  "-G", "Visual Studio 17 2022",
+  "-A", "x64",
+  "-DOBS_SOURCE_DIR=$sourceRoot",
+  "-DOBS_IMPORT_DIR=$importRoot",
+  "-DLUMI_BRIDGE_VERSION=$BridgeVersion"
+)
+& $cmake @configureArguments
+if ($LASTEXITCODE) { throw "OBS bridge configuration failed." }
+& $cmake --build $buildRoot --config Release
+if ($LASTEXITCODE) { throw "OBS bridge build failed." }
 
 New-Item -ItemType Directory -Force -Path $componentRoot | Out-Null
 $bridgeDll = Join-Path $buildRoot "Release\lumi-obs-bridge.dll"

companion/scripts/collect-nuget-notices.ps1

@@ -0,0 +1,98 @@
+param(
+  [Parameter(Mandatory = $true)][string]$RepoRoot,
+  [Parameter(Mandatory = $true)][string]$OutputRoot
+)
+
+$ErrorActionPreference = "Stop"
+$repo = (Resolve-Path $RepoRoot).Path
+$assetFiles = @(Get-ChildItem (Join-Path $repo "companion") -Filter project.assets.json -File -Recurse -ErrorAction SilentlyContinue |
+  Where-Object { $_.FullName -notmatch '[\\/]installer[\\/]output[\\/]' })
+if ($assetFiles.Count -eq 0) { throw "No restored NuGet project.assets.json files were found after publish." }
+
+Remove-Item $OutputRoot -Recurse -Force -ErrorAction SilentlyContinue
+New-Item -ItemType Directory -Force -Path $OutputRoot | Out-Null
+
+
+function Get-ChildText([System.Xml.XmlNode]$Node, [string]$Name) {
+  if (!$Node) { return $null }
+  $child = $Node.SelectSingleNode("*[local-name()='$Name']")
+  if (!$child) { return $null }
+  return $child.InnerText.Trim()
+}
+
+$packages = @{}
+foreach ($assetFile in $assetFiles) {
+  $assets = Get-Content $assetFile.FullName -Raw | ConvertFrom-Json
+  $packageFolders = @($assets.packageFolders.PSObject.Properties.Name)
+  foreach ($libraryProperty in $assets.libraries.PSObject.Properties) {
+    if ($libraryProperty.Value.type -ne "package") { continue }
+    $parts = $libraryProperty.Name -split '/', 2
+    if ($parts.Count -ne 2) { continue }
+    $id = $parts[0]
+    $version = $parts[1]
+    $key = "$($id.ToLowerInvariant())/$($version.ToLowerInvariant())"
+    if ($packages.ContainsKey($key)) { continue }
+
+    $packageRoot = $null
+    foreach ($folder in $packageFolders) {
+      $candidate = Join-Path $folder ($key -replace '/', [IO.Path]::DirectorySeparatorChar)
+      if (Test-Path $candidate) { $packageRoot = (Resolve-Path $candidate).Path; break }
+    }
+    if (!$packageRoot) { throw "Restored package files are missing for $id $version." }
+    $packages[$key] = [ordered]@{ Id = $id; Version = $version; Root = $packageRoot }
+  }
+}
+
+$inventory = [Collections.Generic.List[string]]::new()
+$inventory.Add("LUMI COMPANION - EXACT NUGET PACKAGE LICENCE INVENTORY")
+$inventory.Add("Generated: $([DateTime]::UtcNow.ToString('yyyy-MM-dd HH:mm:ss')) UTC")
+$inventory.Add("")
+$inventory.Add("This file is generated from the restored project.assets.json files used by the Companion build. Package-specific licence, notice, copying, and copyright files found in the restored packages are copied into the adjacent package directories.")
+$inventory.Add("")
+
+foreach ($package in @($packages.Values | Sort-Object Id, Version)) {
+  $safeName = ("$($package.Id)-$($package.Version)" -replace '[^A-Za-z0-9._-]', '_')
+  $packageOutput = Join-Path $OutputRoot $safeName
+  New-Item -ItemType Directory -Force -Path $packageOutput | Out-Null
+
+  $nuspec = Get-ChildItem $package.Root -Filter *.nuspec -File | Select-Object -First 1
+  $metadata = $null
+  if ($nuspec) {
+    [xml]$nuspecXml = Get-Content $nuspec.FullName -Raw
+    $metadata = $nuspecXml.SelectSingleNode("/*[local-name()='package']/*[local-name()='metadata']")
+  }
+  $licenseText = Get-ChildText $metadata "license"
+  if (!$licenseText) { $licenseText = Get-ChildText $metadata "licenseUrl" }
+  $authorsText = Get-ChildText $metadata "authors"
+  $copyrightText = Get-ChildText $metadata "copyright"
+  $projectUrlText = Get-ChildText $metadata "projectUrl"
+  $license = if ($licenseText) { $licenseText } else { "Not declared in package metadata" }
+  $authors = if ($authorsText) { $authorsText } else { "Not declared" }
+  $copyright = if ($copyrightText) { $copyrightText } else { "Not declared" }
+  $projectUrl = if ($projectUrlText) { $projectUrlText } else { "Not declared" }
+
+  $copied = [Collections.Generic.List[string]]::new()
+  $noticeFiles = @(Get-ChildItem $package.Root -File -Recurse -ErrorAction SilentlyContinue | Where-Object {
+    $_.Length -le 5MB -and $_.Name -match '^(license|licence|notice|third[-_. ]?party|thirdparty|copying|copyright)([._ -].*)?$'
+  })
+  foreach ($notice in $noticeFiles) {
+    $rootPrefix = $package.Root.TrimEnd([char[]]"\/")
+    $relative = $notice.FullName.Substring($rootPrefix.Length).TrimStart([char[]]"\/")
+    $targetName = ($relative -replace '[\\/:*?"<>|]', '__')
+    $target = Join-Path $packageOutput $targetName
+    Copy-Item $notice.FullName $target -Force
+    $copied.Add($targetName)
+  }
+  if ($copied.Count -eq 0) { Remove-Item $packageOutput -Force }
+
+  $inventory.Add("Package: $($package.Id) $($package.Version)")
+  $inventory.Add("Authors: $authors")
+  $inventory.Add("Copyright: $copyright")
+  $inventory.Add("Licence declaration: $license")
+  $inventory.Add("Project: $projectUrl")
+  $inventory.Add("Copied notice files: $(if ($copied.Count) { $copied -join ', ' } else { 'none found in restored package' })")
+  $inventory.Add("")
+}
+
+[IO.File]::WriteAllLines((Join-Path $OutputRoot "NuGet-LICENCE-INVENTORY.txt"), $inventory, [Text.UTF8Encoding]::new($false))
+Write-Host "Collected legal metadata for $($packages.Count) restored NuGet packages."

companion/scripts/generate-companion-icon.ps1

@@ -0,0 +1,94 @@
+param(
+  [string]$OutputPath = ""
+)
+
+$ErrorActionPreference = "Stop"
+$repoRoot = (Resolve-Path (Join-Path $PSScriptRoot "..\..")).Path
+if ([string]::IsNullOrWhiteSpace($OutputPath)) {
+  $OutputPath = Join-Path $repoRoot "companion\src\Lumi.Companion.App\Assets\Lumi.Companion.ico"
+}
+$OutputPath = [System.IO.Path]::GetFullPath($OutputPath)
+$sizes = @(16, 32, 48, 256)
+
+function New-LumiIconFrame {
+  param([int]$Size)
+
+  $radius = [Math]::Max(3, [Math]::Round($Size * 0.22))
+  $center = ($Size - 1) / 2.0
+  $diamondRadius = $Size * 0.36
+  $maskStride = [Math]::Ceiling($Size / 32.0) * 4
+  $pixels = New-Object byte[] ($Size * $Size * 4)
+
+  for ($y = 0; $y -lt $Size; $y++) {
+    for ($x = 0; $x -lt $Size; $x++) {
+      $inside = $true
+      if (!(($x -ge $radius -and $x -lt $Size - $radius) -or ($y -ge $radius -and $y -lt $Size - $radius))) {
+        $cornerX = if ($x -lt $radius) { $radius } else { $Size - $radius - 1 }
+        $cornerY = if ($y -lt $radius) { $radius } else { $Size - $radius - 1 }
+        $dx = $x - $cornerX
+        $dy = $y - $cornerY
+        $inside = (($dx * $dx) + ($dy * $dy)) -le ($radius * $radius)
+      }
+      $diamond = (([Math]::Abs($x - $center) / $diamondRadius) + ([Math]::Abs($y - $center) / $diamondRadius)) -le 1
+      $target = ((($Size - 1 - $y) * $Size) + $x) * 4
+      $pixels[$target] = if ($diamond -and $inside) { 255 } else { 200 }
+      $pixels[$target + 1] = if ($diamond -and $inside) { 255 } else { 183 }
+      $pixels[$target + 2] = if ($diamond -and $inside) { 255 } else { 40 }
+      $pixels[$target + 3] = if ($inside) { 255 } else { 0 }
+    }
+  }
+
+  $stream = [System.IO.MemoryStream]::new()
+  $writer = [System.IO.BinaryWriter]::new($stream)
+  $writer.Write([int]40)
+  $writer.Write([int]$Size)
+  $writer.Write([int]($Size * 2))
+  $writer.Write([uint16]1)
+  $writer.Write([uint16]32)
+  $writer.Write([int]0)
+  $writer.Write([int]$pixels.Length)
+  $writer.Write([int]0)
+  $writer.Write([int]0)
+  $writer.Write([int]0)
+  $writer.Write([int]0)
+  $writer.Write($pixels)
+  $writer.Write((New-Object byte[] ($maskStride * $Size)))
+  $writer.Flush()
+  $result = $stream.ToArray()
+  $writer.Dispose()
+  $stream.Dispose()
+  return ,$result
+}
+
+[byte[][]]$frames = @($sizes | ForEach-Object { ,(New-LumiIconFrame -Size $_) })
+$directorySize = 6 + ($frames.Count * 16)
+$offset = $directorySize
+$output = [System.IO.MemoryStream]::new()
+$binary = [System.IO.BinaryWriter]::new($output)
+$binary.Write([uint16]0)
+$binary.Write([uint16]1)
+$binary.Write([uint16]$frames.Count)
+
+for ($index = 0; $index -lt $frames.Count; $index++) {
+  $size = $sizes[$index]
+  $frame = $frames[$index]
+  $encodedSize = if ($size -eq 256) { 0 } else { $size }
+  $binary.Write([byte]$encodedSize)
+  $binary.Write([byte]$encodedSize)
+  $binary.Write([byte]0)
+  $binary.Write([byte]0)
+  $binary.Write([uint16]1)
+  $binary.Write([uint16]32)
+  $binary.Write([int]$frame.Length)
+  $binary.Write([int]$offset)
+  $offset += $frame.Length
+}
+foreach ($frame in $frames) { $binary.Write($frame) }
+$binary.Flush()
+
+$directory = Split-Path -Parent $OutputPath
+[System.IO.Directory]::CreateDirectory($directory) | Out-Null
+[System.IO.File]::WriteAllBytes($OutputPath, $output.ToArray())
+$binary.Dispose()
+$output.Dispose()
+Write-Host "Generated Lumi Companion icon: $OutputPath"

companion/scripts/publish-companion.ps1

@@ -1,6 +1,7 @@
 param(
-  [string]$Version = "0.1.0-experimental.8",
-  [string]$BridgeVersion = "0.1.0-experimental.5"
+  [string]$Version = "0.1.0",
+  [string]$BridgeVersion = "0.1.0",
+  [string]$ObsVersion = "31.1.1"
 )
 
 $ErrorActionPreference = "Stop"
@@ -9,32 +10,104 @@ $project = Join-Path $repoRoot "companion\src\Lumi.Companion.App\Lumi.Companion.
 $outputRoot = Join-Path $repoRoot "companion\installer\output"
 $publishRoot = Join-Path $outputRoot "publish"
 $stageRoot = Join-Path $outputRoot "package"
+$sourceStageRoot = Join-Path $outputRoot "obs-bridge-source"
 $archive = Join-Path $outputRoot "Lumi.Companion-win-x64.zip"
 $installer = Join-Path $outputRoot "Lumi.Companion-Setup.exe"
+$legalSourceRoot = Join-Path $repoRoot "companion\legal"
+$publishLegalRoot = Join-Path $publishRoot "legal"
 
-& (Join-Path $PSScriptRoot "build-obs-bridge.ps1") -BridgeVersion $BridgeVersion
-Remove-Item $publishRoot, $stageRoot -Recurse -Force -ErrorAction SilentlyContinue
+function Compress-ArchiveWithRetry {
+  param(
+    [Parameter(Mandatory = $true)][string]$Path,
+    [Parameter(Mandatory = $true)][string]$DestinationPath,
+    [int]$Attempts = 8
+  )
+
+  for ($attempt = 1; $attempt -le $Attempts; $attempt++) {
+    try {
+      Remove-Item $DestinationPath -Force -ErrorAction SilentlyContinue
+      Compress-Archive -Path $Path -DestinationPath $DestinationPath -CompressionLevel Optimal -ErrorAction Stop
+      return
+    } catch {
+      if ($attempt -eq $Attempts) { throw }
+      Start-Sleep -Seconds 2
+    }
+  }
+}
+
+& (Join-Path $PSScriptRoot "generate-companion-icon.ps1")
+& (Join-Path $PSScriptRoot "build-obs-bridge.ps1") -BridgeVersion $BridgeVersion -ObsVersion $ObsVersion
+Remove-Item $publishRoot, $stageRoot, $sourceStageRoot -Recurse -Force -ErrorAction SilentlyContinue
 New-Item -ItemType Directory -Force -Path $publishRoot, $stageRoot | Out-Null
 $localDotnet = Join-Path $HOME ".dotnet-sdk\dotnet.exe"
 $dotnet = if (Test-Path $localDotnet) { $localDotnet } else { (Get-Command dotnet.exe -ErrorAction Stop).Source }
-$publishArguments = @("publish", "`"$project`"", "-c", "Release", "-r", "win-x64", "--self-contained", "true", "--disable-build-servers", "-o", "`"$publishRoot`"",
+$publishArguments = @("publish", $project, "-c", "Release", "-r", "win-x64", "--self-contained", "true", "--disable-build-servers", "-o", $publishRoot,
   "-p:PublishSingleFile=true", "-p:IncludeNativeLibrariesForSelfExtract=true", "-p:DebugType=None", "-p:Version=$Version")
-$published = Start-Process -FilePath $dotnet -ArgumentList $publishArguments -NoNewWindow -Wait -PassThru
-if ($published.ExitCode) { throw "Companion publish failed." }
+& $dotnet @publishArguments
+if ($LASTEXITCODE) { throw "Companion publish failed." }
 
 $bridgeDiagnostic = Join-Path $outputRoot "obs-bridge-package-diagnostic.json"
 Remove-Item $bridgeDiagnostic -Force -ErrorAction SilentlyContinue
-$diagnosed = Start-Process -FilePath (Join-Path $publishRoot "Lumi.Companion.App.exe") -ArgumentList @("--diagnose-obs-bridge", "`"$bridgeDiagnostic`"") -Wait -PassThru
-if ($diagnosed.ExitCode -ne 0) {
+& (Join-Path $publishRoot "Lumi.Companion.App.exe") --diagnose-obs-bridge $bridgeDiagnostic
+if ($LASTEXITCODE -ne 0) {
   $detail = if (Test-Path $bridgeDiagnostic) { Get-Content $bridgeDiagnostic -Raw } else { "No diagnostic result was written." }
   throw "Published OBS integration payload failed its executable-level check: $detail"
 }
 Remove-Item $bridgeDiagnostic -Force -ErrorAction SilentlyContinue
 
+# Copy the release legal bundle beside the application so installed and portable
+# builds carry the same terms, privacy notice, and third-party attributions.
+New-Item -ItemType Directory -Force -Path $publishLegalRoot | Out-Null
+foreach ($name in @(
+  "LUMI-COMPANION-LICENCE.txt",
+  "PRIVACY-NOTICE.txt",
+  "THIRD-PARTY-NOTICES.txt",
+  "LEGAL-README.txt"
+)) {
+  Copy-Item (Join-Path $legalSourceRoot $name) (Join-Path $publishLegalRoot $name) -Force
+}
+Copy-Item (Join-Path $legalSourceRoot "third-party") (Join-Path $publishLegalRoot "third-party") -Recurse -Force
+& (Join-Path $PSScriptRoot "collect-nuget-notices.ps1") -RepoRoot $repoRoot -OutputRoot (Join-Path $publishLegalRoot "third-party\nuget")
+
+# The bundled OBS module links with GPL-licensed OBS/libobs. Ship the exact Lumi
+# bridge source and build materials with every binary distribution.
+$sourceCompanionRoot = Join-Path $sourceStageRoot "companion"
+$sourceNativeParent = Join-Path $sourceCompanionRoot "native"
+$sourceScriptsRoot = Join-Path $sourceCompanionRoot "scripts"
+New-Item -ItemType Directory -Force -Path $sourceNativeParent, $sourceScriptsRoot | Out-Null
+Copy-Item (Join-Path $repoRoot "companion\native\obs-bridge") (Join-Path $sourceNativeParent "obs-bridge") -Recurse -Force
+Copy-Item (Join-Path $repoRoot "companion\scripts\build-obs-bridge.ps1") (Join-Path $sourceScriptsRoot "build-obs-bridge.ps1") -Force
+$upstreamSourceRoot = Join-Path $sourceStageRoot "upstream-source"
+New-Item -ItemType Directory -Force -Path $upstreamSourceRoot | Out-Null
+$bridgeCacheRoot = Join-Path $env:LOCALAPPDATA "LumiCompanionBuild\obs-$ObsVersion"
+$obsSourceArchive = Join-Path $bridgeCacheRoot "obs-source.zip"
+$jsonSourceRoot = Join-Path $bridgeCacheRoot "bridge-build\_deps\json-src"
+if (!(Test-Path $obsSourceArchive)) { throw "The exact OBS source archive used for the bridge build is missing." }
+if (!(Test-Path $jsonSourceRoot)) { throw "The exact nlohmann/json source used for the bridge build is missing." }
+Copy-Item $obsSourceArchive (Join-Path $upstreamSourceRoot "OBS-Studio-$ObsVersion-source.zip") -Force
+Copy-Item $jsonSourceRoot (Join-Path $upstreamSourceRoot "nlohmann-json-3.12.0") -Recurse -Force
+@"
+Lumi OBS Bridge corresponding source
+Release version: $BridgeVersion
+
+This archive contains the Lumi-authored source and build script used for the
+GPL-2.0-or-later OBS bridge distributed with Lumi Companion.
+
+The archive includes the Lumi bridge source, its build script, the exact OBS Studio
+$ObsVersion source archive used for its interfaces, and the exact nlohmann/json
+3.12.0 source used in the binary. Checksums and upstream locations remain recorded
+in the build script. OBS Studio binaries are not distributed by Companion.
+
+Licence: companion/native/obs-bridge/COPYING
+"@ | Set-Content -Encoding UTF8 (Join-Path $sourceStageRoot "SOURCE-README.txt")
+$bridgeSourceArchive = Join-Path $publishLegalRoot "Lumi-OBS-Bridge-Source.zip"
+Compress-ArchiveWithRetry -Path (Join-Path $sourceStageRoot "*") -DestinationPath $bridgeSourceArchive
+
 Copy-Item (Join-Path $publishRoot "Lumi.Companion.App.exe") $stageRoot
 Copy-Item (Join-Path $publishRoot "components") $stageRoot -Recurse
+Copy-Item (Join-Path $publishRoot "legal") $stageRoot -Recurse
 Remove-Item $archive -Force -ErrorAction SilentlyContinue
-Compress-Archive -Path (Join-Path $stageRoot "*") -DestinationPath $archive -CompressionLevel Optimal
+Compress-ArchiveWithRetry -Path (Join-Path $stageRoot "*") -DestinationPath $archive
 
 $isccCandidates = @(
   (Join-Path $env:LOCALAPPDATA "Programs\Inno Setup 6\ISCC.exe"),
@@ -45,13 +118,13 @@ $iscc = $isccCandidates | Where-Object { $_ -and (Test-Path $_) } | Select-Objec
 if (-not $iscc) { throw "Inno Setup 6 is required to build the durable per-user Companion installer." }
 Remove-Item $installer -Force -ErrorAction SilentlyContinue
 $compileArguments = @(
-  "`"/DAppVersion=$Version`"",
-  "`"/DSourceRoot=$publishRoot`"",
-  "`"/DOutputRoot=$outputRoot`"",
-  "`"$(Join-Path $repoRoot "companion\installer\Lumi.Companion.iss")`""
+  "/DAppVersion=$Version",
+  "/DSourceRoot=$publishRoot",
+  "/DOutputRoot=$outputRoot",
+  (Join-Path $repoRoot "companion\installer\Lumi.Companion.iss")
 )
-$compiled = Start-Process -FilePath $iscc -ArgumentList $compileArguments -NoNewWindow -Wait -PassThru
-if ($compiled.ExitCode -ne 0 -or -not (Test-Path $installer)) { throw "Companion installer compilation failed." }
+& $iscc @compileArguments
+if ($LASTEXITCODE -ne 0 -or -not (Test-Path $installer)) { throw "Companion installer compilation failed." }
 
 $file = Get-Item $archive
 $sha = (Get-FileHash $archive -Algorithm SHA256).Hash.ToLowerInvariant()

companion/scripts/publish-dev-update.ps1

@@ -0,0 +1,72 @@
+param(
+  [Parameter(Mandatory = $true)][string]$OutputArchive,
+  [Parameter(Mandatory = $true)][string]$ManifestPath
+)
+
+$ErrorActionPreference = "Stop"
+$repoRoot = (Resolve-Path (Join-Path $PSScriptRoot "..\..")).Path
+$project = Join-Path $repoRoot "companion\src\Lumi.Companion.App\Lumi.Companion.App.csproj"
+$outputArchive = [System.IO.Path]::GetFullPath($OutputArchive)
+$manifest = [System.IO.Path]::GetFullPath($ManifestPath)
+$workRoot = Join-Path ([System.IO.Path]::GetDirectoryName($outputArchive)) "work"
+$publishRoot = Join-Path $workRoot "publish"
+$stageRoot = Join-Path $workRoot "package"
+
+if (!(Test-Path $manifest)) { throw "The development build manifest is missing." }
+& (Join-Path $PSScriptRoot "generate-companion-icon.ps1")
+Remove-Item $workRoot -Recurse -Force -ErrorAction SilentlyContinue
+New-Item -ItemType Directory -Force -Path $publishRoot, $stageRoot | Out-Null
+New-Item -ItemType Directory -Force -Path ([System.IO.Path]::GetDirectoryName($outputArchive)) | Out-Null
+
+$localDotnet = Join-Path $HOME ".dotnet-sdk\dotnet.exe"
+$dotnet = if (Test-Path $localDotnet) { $localDotnet } else { (Get-Command dotnet.exe -ErrorAction Stop).Source }
+$arguments = @(
+  "publish", "`"$project`"",
+  "-c", "Release",
+  "-r", "win-x64",
+  "--self-contained", "true",
+  "--disable-build-servers",
+  "-o", "`"$publishRoot`"",
+  "-p:PublishSingleFile=true",
+  "-p:IncludeNativeLibrariesForSelfExtract=true",
+  "-p:DebugType=None"
+)
+$published = Start-Process -FilePath $dotnet -ArgumentList $arguments -NoNewWindow -Wait -PassThru
+if ($published.ExitCode -ne 0) { throw "Companion development publish failed." }
+
+$app = Join-Path $publishRoot "Lumi.Companion.App.exe"
+if (!(Test-Path $app)) { throw "The Companion development publish did not create Lumi.Companion.App.exe." }
+Copy-Item $app $stageRoot -Force
+$componentsSource = Join-Path $publishRoot "components"
+if (Test-Path $componentsSource) { Copy-Item $componentsSource (Join-Path $stageRoot "components") -Recurse -Force }
+
+$legalSource = Join-Path $repoRoot "companion\legal"
+$legalTarget = Join-Path $stageRoot "legal"
+if (Test-Path $legalSource) {
+  New-Item -ItemType Directory -Force -Path $legalTarget | Out-Null
+  foreach ($name in @("LUMI-COMPANION-LICENCE.txt", "PRIVACY-NOTICE.txt", "THIRD-PARTY-NOTICES.txt", "LEGAL-README.txt")) {
+    $source = Join-Path $legalSource $name
+    if (Test-Path $source) { Copy-Item $source (Join-Path $legalTarget $name) -Force }
+  }
+  $thirdParty = Join-Path $legalSource "third-party"
+  if (Test-Path $thirdParty) { Copy-Item $thirdParty (Join-Path $legalTarget "third-party") -Recurse -Force }
+}
+Copy-Item $manifest (Join-Path $stageRoot ".lumi-dev-build.json") -Force
+Remove-Item $outputArchive -Force -ErrorAction SilentlyContinue
+$archiveItems = Get-ChildItem $stageRoot -Force | Select-Object -ExpandProperty FullName
+$archiveCreated = $false
+for ($attempt = 1; $attempt -le 20; $attempt++) {
+  try {
+    Compress-Archive -Path $archiveItems -DestinationPath $outputArchive -CompressionLevel Optimal -ErrorAction Stop
+    $archiveCreated = $true
+    break
+  }
+  catch {
+    Remove-Item $outputArchive -Force -ErrorAction SilentlyContinue
+    if ($attempt -eq 20) { throw }
+    Start-Sleep -Milliseconds 250
+  }
+}
+if (-not $archiveCreated) { throw "The Companion development archive could not be created." }
+Remove-Item $workRoot -Recurse -Force -ErrorAction SilentlyContinue
+Write-Host "Created localhost development update: $outputArchive"

companion/scripts/verify-song-overlay.ps1

@@ -0,0 +1,15 @@
+$ErrorActionPreference = 'Stop'
+$repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
+Push-Location $repoRoot
+try {
+    Write-Host 'Building Lumi Companion and all registered Companion plugins...'
+    dotnet build 'companion/Lumi.Companion.sln' -c Release -p:EnableWindowsTargeting=true
+
+    Write-Host 'Verifying the existing Lumi Song Overlay server plugin...'
+    node 'plugins/now_playing/tests/verify.js'
+
+    Write-Host 'Song Overlay Companion verification passed.' -ForegroundColor Green
+}
+finally {
+    Pop-Location
+}

companion/src/Lumi.Companion.Abstractions/CompanionPluginTransport.cs

@@ -0,0 +1,22 @@
+namespace Lumi.Companion.Abstractions;
+
+public sealed record CompanionPluginHttpResponse(
+    int StatusCode,
+    string Body)
+{
+    public bool IsSuccessStatusCode => StatusCode is >= 200 and <= 299;
+}
+
+/// <summary>
+/// A plugin-scoped view of the Companion shell's authenticated Lumi transport.
+/// Plugins never receive, store, or refresh the paired device credential.
+/// </summary>
+public interface ICompanionPluginTransport
+{
+    Uri? LumiBaseUri { get; }
+    bool IsAuthenticated { get; }
+    Task<CompanionPluginHttpResponse> PostJsonAsync(
+        string relativePath,
+        object payload,
+        CancellationToken cancellationToken = default);
+}

companion/src/Lumi.Companion.Abstractions/Lumi.Companion.Abstractions.csproj

@@ -0,0 +1,7 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+</Project>

companion/src/Lumi.Companion.Abstractions/PluginContributions.cs

@@ -0,0 +1,47 @@
+namespace Lumi.Companion.Abstractions;
+
+public enum CompanionPluginHealth
+{
+    Ready,
+    Healthy,
+    Warning,
+    Error
+}
+
+public sealed record CompanionPluginDescriptor(
+    string Id,
+    string Name,
+    Version Version,
+    string Description,
+    int Order = 100);
+
+public sealed record CompanionPluginPage(
+    string Key,
+    string Label,
+    int Order = 100);
+
+public sealed record CompanionPluginStatus(
+    CompanionPluginHealth Health,
+    string Summary,
+    string? Detail = null);
+
+public sealed record CompanionPluginAction(
+    string Id,
+    Func<string> Label,
+    Func<CancellationToken, Task> Execute,
+    Func<bool>? CanExecute = null,
+    int Order = 100);
+
+/// <summary>
+/// A UI-neutral contribution contract. The Avalonia shell owns rendering and
+/// guarantees that each plugin receives one nested root in both the sidebar and
+/// tray menu instead of leaking loose actions into the global navigation.
+/// </summary>
+public interface ICompanionPluginContribution
+{
+    CompanionPluginDescriptor Descriptor { get; }
+    IReadOnlyList<CompanionPluginPage> Pages { get; }
+    IReadOnlyList<CompanionPluginAction> Actions { get; }
+    CompanionPluginStatus Status { get; }
+    event Action? Changed;
+}

companion/src/Lumi.Companion.App/App.axaml

@@ -73,6 +73,10 @@
       <Setter Property="CornerRadius" Value="9" />
       <Setter Property="Padding" Value="16,9" />
     </Style>
+    <Style Selector="Expander.pluginRoot">
+      <Setter Property="HorizontalAlignment" Value="Stretch" />
+      <Setter Property="Margin" Value="0,1" />
+    </Style>
     <Style Selector="Button.nav">
       <Setter Property="HorizontalContentAlignment" Value="Left" />
       <Setter Property="Background" Value="Transparent" />

companion/src/Lumi.Companion.App/App.axaml.cs

@@ -3,6 +3,8 @@ using Avalonia.Controls;
 using Avalonia.Controls.ApplicationLifetimes;
 using Avalonia.Markup.Xaml;
 using Avalonia.Threading;
+using Lumi.Companion.Abstractions;
+using Lumi.Companion.SongOverlay;
 
 namespace Lumi.Companion.App;
 
@@ -10,6 +12,8 @@ public partial class App : Application
 {
     private TrayIcon? _trayIcon;
     private MainWindow? _mainWindow;
+    private SongOverlayRuntime? _songOverlay;
+    private IReadOnlyList<ICompanionPluginContribution> _plugins = [];
 
     public override void Initialize() => AvaloniaXamlLoader.Load(this);
 
@@ -21,39 +25,89 @@ public partial class App : Application
             var paths = CompanionPaths.ForCurrentUser();
             var settings = new CompanionSettingsStore(paths.SettingsPath);
             var runtime = new CompanionRuntime(paths, settings);
-            _mainWindow = new MainWindow(runtime, settings);
+            _songOverlay = new SongOverlayRuntime(
+                Path.Combine(paths.Root, "plugins", "now_playing"),
+                paths.LogsDirectory,
+                runtime.CreatePluginTransport("now_playing"));
+            _plugins = [new TranscriptionPluginContribution(runtime), _songOverlay];
+            _mainWindow = new MainWindow(runtime, settings, _songOverlay, _plugins);
             desktop.MainWindow = _mainWindow;
-            ConfigureTray(desktop, runtime);
+            ConfigureTray(desktop, runtime, _plugins);
             runtime.UpdateRestartRequested += async () =>
             {
                 _mainWindow.AllowExit();
                 _trayIcon?.Dispose();
+                if (_songOverlay is not null) await _songOverlay.DisposeAsync();
                 await runtime.DisposeAsync();
                 desktop.Shutdown();
             };
             Program.InstanceCoordinator!.ActivationRequested += () => Dispatcher.UIThread.Post(ShowMainWindow);
             if (!Program.LaunchInBackground) _mainWindow.Show();
-            _ = runtime.InitializeAsync();
+            _ = InitializeRuntimesAsync(runtime, _songOverlay);
         }
         base.OnFrameworkInitializationCompleted();
     }
 
-    private void ConfigureTray(IClassicDesktopStyleApplicationLifetime desktop, CompanionRuntime runtime)
+    private static async Task InitializeRuntimesAsync(CompanionRuntime runtime, SongOverlayRuntime songOverlay)
+    {
+        await runtime.InitializeAsync();
+        try { await songOverlay.InitializeAsync(); }
+        catch { /* The plugin publishes its own actionable status without taking down the shell. */ }
+    }
+
+    private void ConfigureTray(IClassicDesktopStyleApplicationLifetime desktop, CompanionRuntime runtime, IReadOnlyList<ICompanionPluginContribution> plugins)
     {
         var open = new NativeMenuItem("Open Lumi Companion");
-        var test = new NativeMenuItem("Run transcription test");
+        var web = new NativeMenuItem("Open Lumi WebUI");
+        open.Click += (_, _) => ShowMainWindow();
+        web.Click += (_, _) => runtime.OpenLumiWebUi();
+
+        var menu = new NativeMenu();
+        menu.Items.Add(open);
+        menu.Items.Add(web);
+        menu.Items.Add(new NativeMenuItemSeparator());
+        menu.Items.Add(new NativeMenuItem("Plugins") { IsEnabled = false });
+
+        var pluginViews = new List<PluginTrayView>();
+        foreach (var plugin in plugins.OrderBy(item => item.Descriptor.Order).ThenBy(item => item.Descriptor.Name, StringComparer.OrdinalIgnoreCase))
+        {
+            var submenu = new NativeMenu();
+            var firstPage = plugin.Pages.OrderBy(item => item.Order).FirstOrDefault();
+            if (firstPage is not null)
+            {
+                var openPlugin = new NativeMenuItem($"Open {plugin.Descriptor.Name}");
+                openPlugin.Click += (_, _) => ShowPluginPage(firstPage.Key);
+                submenu.Items.Add(openPlugin);
+                if (plugin.Actions.Count > 0) submenu.Items.Add(new NativeMenuItemSeparator());
+            }
+
+            var actionViews = new List<(CompanionPluginAction Action, NativeMenuItem Item)>();
+            foreach (var action in plugin.Actions.OrderBy(item => item.Order))
+            {
+                var actionItem = new NativeMenuItem(action.Label());
+                actionItem.Click += async (_, _) => await RunPluginActionAsync(plugin, action);
+                submenu.Items.Add(actionItem);
+                actionViews.Add((action, actionItem));
+            }
+
+            if (submenu.Items.Count > 0) submenu.Items.Add(new NativeMenuItemSeparator());
+            var status = new NativeMenuItem($"Status: {plugin.Status.Summary}") { IsEnabled = false };
+            submenu.Items.Add(status);
+            var root = new NativeMenuItem(plugin.Descriptor.Name) { Menu = submenu };
+            menu.Items.Add(root);
+            var view = new PluginTrayView(plugin, root, status, actionViews);
+            pluginViews.Add(view);
+            plugin.Changed += () => Dispatcher.UIThread.Post(() => RefreshPluginTray(view));
+        }
+
+        menu.Items.Add(new NativeMenuItemSeparator());
         var health = new NativeMenuItem("Health: Starting") { IsEnabled = false };
         var update = new NativeMenuItem("Updates: Checking…") { IsEnabled = false };
-        var web = new NativeMenuItem("Open Lumi WebUI");
+        var logs = new NativeMenuItem("Logs & diagnostics");
+        var settings = new NativeMenuItem("Settings");
         var quit = new NativeMenuItem("Quit");
-        open.Click += (_, _) => ShowMainWindow();
-        test.Click += async (_, _) =>
-        {
-            ShowMainWindow();
-            _mainWindow?.ShowPage(CompanionPage.Test);
-            await runtime.RunTestAsync();
-        };
-        web.Click += (_, _) => runtime.OpenLumiWebUi();
+        logs.Click += (_, _) => { runtime.OpenLogsDirectory(); };
+        settings.Click += (_, _) => { ShowMainWindow(); _mainWindow?.ShowPage(CompanionPage.Settings); };
         update.Click += (_, _) => { ShowMainWindow(); _mainWindow?.ShowPage(CompanionPage.Overview); };
         quit.Click += async (_, _) =>
         {
@@ -61,30 +115,137 @@ public partial class App : Application
             if (_mainWindow is null || !await _mainWindow.ConfirmQuitAsync()) return;
             _mainWindow.AllowExit();
             _trayIcon?.Dispose();
+            if (_songOverlay is not null) await _songOverlay.DisposeAsync();
             await runtime.DisposeAsync();
             desktop.Shutdown();
         };
+        menu.Items.Add(health);
+        menu.Items.Add(update);
+        menu.Items.Add(logs);
+        menu.Items.Add(settings);
+        menu.Items.Add(new NativeMenuItemSeparator());
+        menu.Items.Add(quit);
 
         _trayIcon = new TrayIcon
         {
             Icon = LumiIconFactory.Create(TrayHealth.Ready),
             ToolTipText = "Lumi Companion — starting",
             IsVisible = true,
-            Menu = new NativeMenu { Items = { open, test, web, health, update, new NativeMenuItemSeparator(), quit } }
+            Menu = menu
         };
         _trayIcon.Clicked += (_, _) => ShowMainWindow();
         TrayIcon.SetIcons(this, new TrayIcons { _trayIcon });
-        runtime.StateChanged += state => Dispatcher.UIThread.Post(() =>
+        var renderedHealth = TrayHealth.Ready;
+        var renderedToolTip = _trayIcon.ToolTipText;
+        var renderedHealthHeader = health.Header?.ToString();
+        var renderedUpdateHeader = update.Header?.ToString();
+        var renderedUpdateEnabled = update.IsEnabled;
+        var refreshGate = new object();
+        CompanionState? pendingState = null;
+        var refreshQueued = false;
+
+        void ApplyTrayState(CompanionState state)
         {
             if (_trayIcon is null) return;
-            _trayIcon.Icon = LumiIconFactory.Create(state.Health);
-            _trayIcon.ToolTipText = state.UpdateAvailable ? $"Lumi Companion — update {state.AvailableVersion} available" : $"Lumi Companion — {state.Summary}";
-            health.Header = $"Health: {state.Summary}";
-            update.Header = state.UpdateAvailable ? $"Update available: {state.AvailableVersion}" : "Updates: Current";
-            update.IsEnabled = state.UpdateAvailable;
-            test.Header = state.TestRunning || state.BenchmarkRunning ? "Transcription test running…" : "Run transcription test";
-            test.IsEnabled = !state.TestRunning && !state.BenchmarkRunning;
-        });
+            if (state.Health != renderedHealth)
+            {
+                _trayIcon.Icon = LumiIconFactory.Create(state.Health);
+                renderedHealth = state.Health;
+            }
+
+            var nextToolTip = state.UpdateAvailable
+                ? $"Lumi Companion — update {state.AvailableVersion} available"
+                : $"Lumi Companion — {state.Summary}";
+            if (!string.Equals(nextToolTip, renderedToolTip, StringComparison.Ordinal))
+            {
+                _trayIcon.ToolTipText = nextToolTip;
+                renderedToolTip = nextToolTip;
+            }
+
+            var nextHealthHeader = $"Health: {state.Summary}";
+            if (!string.Equals(nextHealthHeader, renderedHealthHeader, StringComparison.Ordinal))
+            {
+                health.Header = nextHealthHeader;
+                renderedHealthHeader = nextHealthHeader;
+            }
+
+            var nextUpdateHeader = state.UpdateAvailable
+                ? $"Update available: {state.AvailableVersion}"
+                : "Updates: Current";
+            if (!string.Equals(nextUpdateHeader, renderedUpdateHeader, StringComparison.Ordinal))
+            {
+                update.Header = nextUpdateHeader;
+                renderedUpdateHeader = nextUpdateHeader;
+            }
+            if (state.UpdateAvailable != renderedUpdateEnabled)
+            {
+                update.IsEnabled = state.UpdateAvailable;
+                renderedUpdateEnabled = state.UpdateAvailable;
+            }
+        }
+
+        void DrainTrayRefresh()
+        {
+            CompanionState? latest;
+            lock (refreshGate)
+            {
+                latest = pendingState;
+                pendingState = null;
+            }
+            if (latest is not null) ApplyTrayState(latest);
+
+            lock (refreshGate)
+            {
+                if (pendingState is null)
+                {
+                    refreshQueued = false;
+                    return;
+                }
+            }
+            Dispatcher.UIThread.Post(DrainTrayRefresh, DispatcherPriority.Background);
+        }
+
+        runtime.StateChanged += state =>
+        {
+            lock (refreshGate)
+            {
+                pendingState = state;
+                if (refreshQueued) return;
+                refreshQueued = true;
+            }
+            Dispatcher.UIThread.Post(DrainTrayRefresh, DispatcherPriority.Background);
+        };
+        foreach (var view in pluginViews) RefreshPluginTray(view);
+    }
+
+    private async Task RunPluginActionAsync(ICompanionPluginContribution plugin, CompanionPluginAction action)
+    {
+        try
+        {
+            await action.Execute(CancellationToken.None);
+        }
+        catch
+        {
+            var page = plugin.Pages.OrderBy(item => item.Order).FirstOrDefault();
+            if (page is not null) ShowPluginPage(page.Key);
+        }
+    }
+
+    private static void RefreshPluginTray(PluginTrayView view)
+    {
+        view.Root.Header = view.Plugin.Descriptor.Name;
+        view.Status.Header = $"Status: {view.Plugin.Status.Summary}";
+        foreach (var (action, item) in view.Actions)
+        {
+            item.Header = action.Label();
+            item.IsEnabled = action.CanExecute?.Invoke() ?? true;
+        }
+    }
+
+    private void ShowPluginPage(string pageKey)
+    {
+        ShowMainWindow();
+        if (Enum.TryParse<CompanionPage>(pageKey, out var page)) _mainWindow?.ShowPage(page);
     }
 
     private void ShowMainWindow()
@@ -94,4 +255,10 @@ public partial class App : Application
         _mainWindow.WindowState = WindowState.Normal;
         _mainWindow.Activate();
     }
+
+    private sealed record PluginTrayView(
+        ICompanionPluginContribution Plugin,
+        NativeMenuItem Root,
+        NativeMenuItem Status,
+        IReadOnlyList<(CompanionPluginAction Action, NativeMenuItem Item)> Actions);
 }

companion/src/Lumi.Companion.App/CompanionRuntime.cs

@@ -4,6 +4,7 @@ using System.Reflection;
 using System.Security.Cryptography;
 using System.Text;
 using System.Text.Json;
+using Lumi.Companion.Abstractions;
 using Lumi.Companion.Core;
 using Lumi.Companion.Protocol;
 using Lumi.Companion.Transcription;
@@ -68,6 +69,9 @@ public sealed class CompanionRuntime : IAsyncDisposable
     public event Action<string>? LogAdded;
     public event Func<Task>? UpdateRestartRequested;
 
+    public ICompanionPluginTransport CreatePluginTransport(string pluginId) =>
+        new CompanionPluginTransport(_http, () => _credentials.Load(), pluginId);
+
     public async Task InitializeAsync()
     {
         try { await InitializeCoreAsync(); }
@@ -303,18 +307,29 @@ public sealed class CompanionRuntime : IAsyncDisposable
         if (!State.BenchmarkRunning || _socket is null || Interlocked.Exchange(ref _benchmarkStopping, 1) != 0) return;
         _benchmarkLifetime?.Cancel();
         SetState(State with { BenchmarkDetail = reason == "silence_timeout" ? "Ten seconds of silence detected. Finalizing the test…" : "Finalizing the test…" });
+        var finalized = false;
         try
         {
             await _socket.SendAsync("stop", new { reason }, _socket.SessionId, cancellationToken);
             if (_benchmarkCompleteSignal is not null)
-                await Task.WhenAny(_benchmarkCompleteSignal.Task, Task.Delay(TimeSpan.FromSeconds(7), cancellationToken));
+            {
+                var completed = await Task.WhenAny(_benchmarkCompleteSignal.Task, Task.Delay(TimeSpan.FromSeconds(20), cancellationToken));
+                if (completed != _benchmarkCompleteSignal.Task)
+                    throw new TimeoutException("Lumi did not finalize the transcription test in time. The test was ended safely, but its final confidence result is unavailable.");
+                finalized = Benchmark.Words.Count == 0 || Benchmark.Confidence.Count > 0;
+                if (!finalized)
+                    throw new InvalidOperationException("Lumi returned the test transcript without finalized confidence. The incomplete result was kept for troubleshooting.");
+            }
         }
         finally
         {
             VoiceLevelChanged?.Invoke(-60);
-            SetState(State with { BenchmarkRunning = false, BenchmarkDetail = Benchmark.Words.Count > 0 ? $"Test complete with {Benchmark.Words.Count} measured words or phrases." : "The test ended without a finalized transcript." });
+            SetState(State with { BenchmarkRunning = false, BenchmarkDetail = finalized
+                ? (Benchmark.Words.Count > 0 ? $"Test complete with {Benchmark.Words.Count} measured words or phrases." : "The test ended without recognized speech.")
+                : "The test ended, but Lumi did not return finalized confidence results." });
             _sessionStartSignal = null;
             _testFailure = null;
+            _benchmarkCompleteSignal = null;
             Interlocked.Exchange(ref _benchmarkStopping, 0);
         }
     }
@@ -364,13 +379,20 @@ public sealed class CompanionRuntime : IAsyncDisposable
         if (credential is null) { SetState(State with { UpdateDetail = "Pair this computer before checking for updates." }); return; }
         try
         {
+            SetState(State with { UpdateDetail = "Checking for Companion updates…" });
             _availableUpdate = await _updates.CheckAsync(credential, Version, cancellationToken);
+            var updateDetail = _availableUpdate is null
+                ? $"Lumi Companion {Version} is current."
+                : _availableUpdate.Development
+                    ? $"Local development update ready: {string.Join(", ", _availableUpdate.ChangedComponents?.Select(item => item.Id) ?? new[] { "Companion source" })}."
+                    : $"Lumi Companion {_availableUpdate.Version} is ready to install when OBS is idle.";
             SetState(State with
             {
                 UpdateAvailable = _availableUpdate is not null,
                 AvailableVersion = _availableUpdate?.Version,
-                UpdateDetail = _availableUpdate is null ? $"Lumi Companion {Version} is current." : $"Lumi Companion {_availableUpdate.Version} is ready to install when OBS is idle."
+                UpdateDetail = updateDetail
             });
+            await WriteLogAsync(_availableUpdate is null ? "update_current" : "update_available", updateDetail);
         }
         catch (Exception error)
         {
@@ -385,8 +407,9 @@ public sealed class CompanionRuntime : IAsyncDisposable
         var update = _availableUpdate ?? throw new InvalidOperationException("No Companion update is ready to install.");
         try
         {
-            SetState(State with { UpdateDetail = $"Downloading and verifying {update.Version}…" });
-            var staged = await _updates.StageAsync(update, cancellationToken);
+            var credential = _credentials.Load() ?? throw new InvalidOperationException("The paired Companion credential is unavailable.");
+            SetState(State with { UpdateDetail = update.Development ? "Building, downloading, and verifying the localhost development update…" : $"Downloading and verifying {update.Version}…" });
+            var staged = await _updates.StageAsync(update, credential, cancellationToken);
             if (State.ObsStreaming || State.ObsRecording) throw new InvalidOperationException("OBS started output while the update was downloading. Stop streaming and recording, then try again.");
             _updates.LaunchApplier(staged);
             SetState(State with { UpdateDetail = "Update verified. Restarting Lumi Companion…" });
@@ -564,7 +587,10 @@ public sealed class CompanionRuntime : IAsyncDisposable
                 ReadString(source, "display_name") ?? ReadString(source, "name") ?? "OBS source",
                 ReadBoolean(source, "program_active") || ReadBoolean(source, "active"),
                 ReadBoolean(source, "source_missing") || ReadBoolean(source, "missing")))
-                .Where(source => Guid.TryParse(source.Uuid, out _)).ToArray();
+                .Where(source => Guid.TryParse(source.Uuid, out _))
+                .GroupBy(source => source.Uuid)
+                .Select(group => group.Last())
+                .ToArray();
             _bridgeSelectionAttached = null;
             ObsSourcesChanged?.Invoke(ObsSources);
             foreach (var source in ObsSources) await SendSourceUpdateAsync(source);
@@ -576,6 +602,8 @@ public sealed class CompanionRuntime : IAsyncDisposable
             var source = new ObsSource(ReadString(message, "source_uuid") ?? string.Empty, ReadString(message, "display_name") ?? "OBS source", ReadBoolean(message, "program_active"), ReadBoolean(message, "source_missing"));
             if (Guid.TryParse(source.Uuid, out _))
             {
+                var previous = ObsSources.FirstOrDefault(item => item.Uuid == source.Uuid);
+                if (previous == source) return;
                 ObsSources = ObsSources.Where(item => item.Uuid != source.Uuid).Append(source).OrderBy(item => item.Name).ToArray();
                 ObsSourcesChanged?.Invoke(ObsSources);
                 await SendSourceUpdateAsync(source);
@@ -600,7 +628,10 @@ public sealed class CompanionRuntime : IAsyncDisposable
         {
             if (State.BenchmarkRunning) _benchmarkLastVoiceAt = DateTimeOffset.UtcNow;
         }
-        if (_socket is not null && State.Connected && !_socket.QueueBridgeAudio(frame))
+        var audioNeeded = State.TestRunning || (State.BenchmarkRunning
+            ? Volatile.Read(ref _benchmarkStopping) == 0
+            : State.ObsStreaming);
+        if (audioNeeded && _socket is not null && State.Connected && !_socket.QueueBridgeAudio(frame))
             _ = WriteLogAsync("audio_dropped", "An obsolete audio frame was dropped before network delivery.");
         return Task.CompletedTask;
     }
@@ -903,6 +934,9 @@ public sealed class CompanionRuntime : IAsyncDisposable
         new("Simulated output", "Nothing is sent to Twitch during this test.", TestStageState.Waiting)
     ];
     public static string Version => (Assembly.GetExecutingAssembly().GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion ?? "0.1.0").Split('+')[0];
+    public static string DisplayVersion => DevelopmentBuildManifest.Load() is { BuildChecksum.Length: >= 8 } build
+        ? $"{Version} · Local development {build.BuildChecksum[..8]}"
+        : Version;
 
     public async ValueTask DisposeAsync()
     {

companion/src/Lumi.Companion.App/CompanionState.cs

@@ -1,7 +1,7 @@
 namespace Lumi.Companion.App;
 
 public enum TrayHealth { Ready, Operating, Degraded, Failed }
-public enum CompanionPage { Overview, Transcription, Test, Connection, Logs, Settings }
+public enum CompanionPage { Overview, Transcription, Test, SongOverlay, Connection, Logs, Settings }
 public enum TestStageState { Waiting, Running, Passed, Blocked, Failed }
 
 public sealed record CompanionState(

companion/src/Lumi.Companion.App/DevelopmentBuildManifest.cs

@@ -0,0 +1,37 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Lumi.Companion.Protocol;
+
+namespace Lumi.Companion.App;
+
+public sealed record DevelopmentBuildManifest(
+    [property: JsonPropertyName("schema_version")] int SchemaVersion,
+    [property: JsonPropertyName("mode")] string Mode,
+    [property: JsonPropertyName("build_checksum")] string BuildChecksum,
+    [property: JsonPropertyName("generated_at")] string GeneratedAt,
+    [property: JsonPropertyName("components")] IReadOnlyDictionary<string, string> Components)
+{
+    public static DevelopmentBuildManifest? Load()
+    {
+        var path = Path.Combine(AppContext.BaseDirectory, ".lumi-dev-build.json");
+        if (!File.Exists(path)) return null;
+        try
+        {
+            var manifest = JsonSerializer.Deserialize<DevelopmentBuildManifest>(File.ReadAllText(path), ProtocolV1.JsonOptions);
+            return manifest is { SchemaVersion: 1 } && IsSha256(manifest.BuildChecksum)
+                ? manifest with { Components = Sanitize(manifest.Components) }
+                : null;
+        }
+        catch { return null; }
+    }
+
+    private static IReadOnlyDictionary<string, string> Sanitize(IReadOnlyDictionary<string, string>? input)
+    {
+        if (input is null) return new Dictionary<string, string>();
+        return input
+            .Where(entry => entry.Key.Length is > 0 and <= 160 && IsSha256(entry.Value))
+            .ToDictionary(entry => entry.Key, entry => entry.Value.ToLowerInvariant(), StringComparer.OrdinalIgnoreCase);
+    }
+
+    private static bool IsSha256(string? value) => value is { Length: 64 } && value.All(Uri.IsHexDigit);
+}

companion/src/Lumi.Companion.App/Lumi.Companion.App.csproj

@@ -1,17 +1,21 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
     <OutputType>WinExe</OutputType>
-    <TargetFramework>net8.0-windows</TargetFramework>
+    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
     <ApplicationManifest>app.manifest</ApplicationManifest>
-    <Version>0.1.0-experimental.8</Version>
+    <ApplicationIcon>Assets\Lumi.Companion.ico</ApplicationIcon>
+    <Version>0.1.0</Version>
     <AssemblyVersion>0.1.0.0</AssemblyVersion>
   </PropertyGroup>
   <ItemGroup>
+    <AvaloniaResource Include="Assets\Lumi.Companion.ico" />
     <ProjectReference Include="../Lumi.Companion.Core/Lumi.Companion.Core.csproj" />
     <ProjectReference Include="../Lumi.Companion.Protocol/Lumi.Companion.Protocol.csproj" />
+    <ProjectReference Include="../Lumi.Companion.Abstractions/Lumi.Companion.Abstractions.csproj" />
     <ProjectReference Include="../../plugins/Lumi.Companion.Transcription/Lumi.Companion.Transcription.csproj" />
+    <ProjectReference Include="../../plugins/Lumi.Companion.SongOverlay/Lumi.Companion.SongOverlay.csproj" />
     <PackageReference Include="Avalonia" Version="12.1.0" />
     <PackageReference Include="Avalonia.Desktop" Version="12.1.0" />
     <PackageReference Include="Avalonia.Fonts.Inter" Version="12.1.0" />

companion/src/Lumi.Companion.App/LumiIconFactory.cs

@@ -4,7 +4,21 @@ namespace Lumi.Companion.App;
 
 internal static class LumiIconFactory
 {
+    private static readonly Dictionary<TrayHealth, WindowIcon> Icons = new();
+    private static readonly object IconGate = new();
+
     public static WindowIcon Create(TrayHealth health)
+    {
+        lock (IconGate)
+        {
+            if (Icons.TryGetValue(health, out var icon)) return icon;
+            icon = CreateUncached(health);
+            Icons[health] = icon;
+            return icon;
+        }
+    }
+
+    private static WindowIcon CreateUncached(TrayHealth health)
     {
         const int size = 32;
         var color = health switch
@@ -12,7 +26,7 @@ internal static class LumiIconFactory
             TrayHealth.Operating => (R: (byte)35, G: (byte)132, B: (byte)91),
             TrayHealth.Degraded => (R: (byte)169, G: (byte)102, B: (byte)18),
             TrayHealth.Failed => (R: (byte)189, G: (byte)77, B: (byte)77),
-            _ => (R: (byte)79, G: (byte)182, B: (byte)194)
+            _ => (R: (byte)40, G: (byte)183, B: (byte)200)
         };
         var pixels = new byte[size * size * 4];
         for (var y = 0; y < size; y++)

companion/src/Lumi.Companion.App/MainWindow.axaml

@@ -2,6 +2,7 @@
         xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
         x:Class="Lumi.Companion.App.MainWindow"
         Title="Lumi Companion"
+        Icon="/Assets/Lumi.Companion.ico"
         Width="1120" Height="760" MinWidth="900" MinHeight="620"
         WindowStartupLocation="CenterScreen">
   <Grid ColumnDefinitions="248,*">
@@ -27,14 +28,23 @@
           </Grid>
         </Border>
 
-        <StackPanel Grid.Row="2" x:Name="Navigation">
+        <Grid Grid.Row="2" RowDefinitions="Auto,*,Auto">
           <Button x:Name="OverviewNav" Classes="nav selected" Content="Overview" Tag="Overview" />
-          <Button x:Name="TranscriptionNav" Classes="nav" Content="Transcription" Tag="Transcription" />
-          <Button x:Name="TestNav" Classes="nav" Content="Test" Tag="Test" />
-          <Button x:Name="ConnectionNav" Classes="nav" Content="Connection &amp; device" Tag="Connection" />
-          <Button x:Name="LogsNav" Classes="nav" Content="Logs &amp; diagnostics" Tag="Logs" />
-          <Button x:Name="SettingsNav" Classes="nav" Content="Settings" Tag="Settings" />
-        </StackPanel>
+
+          <ScrollViewer Grid.Row="1" Margin="0,14,0,14" VerticalScrollBarVisibility="Auto">
+            <StackPanel Spacing="6">
+              <TextBlock Text="PLUGINS" Classes="eyebrow" Margin="12,0,0,4" />
+              <StackPanel x:Name="PluginNavigation" Spacing="4" />
+            </StackPanel>
+          </ScrollViewer>
+
+          <StackPanel Grid.Row="2" x:Name="TechnicalNavigation">
+            <Border Height="1" Background="{DynamicResource LumiBorderBrush}" Margin="0,0,0,8" />
+            <Button x:Name="ConnectionNav" Classes="nav" Content="Connection &amp; device" Tag="Connection" />
+            <Button x:Name="LogsNav" Classes="nav" Content="Logs &amp; diagnostics" Tag="Logs" />
+            <Button x:Name="SettingsNav" Classes="nav" Content="Settings" Tag="Settings" />
+          </StackPanel>
+        </Grid>
 
         <TextBlock Grid.Row="3" Text="Runs quietly in the notification area" Classes="muted" FontSize="11" />
       </Grid>
@@ -173,6 +183,76 @@
         </StackPanel>
       </ScrollViewer>
 
+
+      <ScrollViewer x:Name="SongOverlayPage" IsVisible="False">
+        <StackPanel Margin="44,38,52,48" MaxWidth="760" HorizontalAlignment="Left" Spacing="24">
+          <StackPanel Spacing="6">
+            <TextBlock Text="MEDIA" Classes="eyebrow" />
+            <TextBlock Text="Song Overlay" Classes="pageTitle" />
+            <TextBlock Text="Spotify is the first media provider. The provider contract remains generic so later services can use the same event and overlay pipeline." Classes="muted" FontSize="15" />
+          </StackPanel>
+
+          <Border Classes="soft">
+            <Grid ColumnDefinitions="*,Auto" ColumnSpacing="20">
+              <StackPanel Spacing="4">
+                <TextBlock x:Name="SongOverlayStatusTitle" Text="Starting" FontWeight="SemiBold" />
+                <TextBlock x:Name="SongOverlayStatusDetail" Text="Waiting for the media provider…" Classes="muted" />
+                <TextBlock x:Name="SongOverlayCurrentTrack" Text="No active song" Classes="muted" FontSize="12" />
+              </StackPanel>
+              <ToggleSwitch Grid.Column="1" x:Name="SongOverlayEnabledToggle" OffContent="Off" OnContent="On" VerticalAlignment="Center" />
+            </Grid>
+          </Border>
+
+          <StackPanel Spacing="10">
+            <TextBlock Text="Lumi authentication" Classes="sectionTitle" />
+            <Border Classes="soft">
+              <StackPanel Spacing="4">
+                <TextBlock x:Name="SongOverlayLumiAuthenticationText" Text="Uses the Companion device pairing" FontWeight="SemiBold" />
+                <TextBlock Text="Song Overlay inherits the protected Companion credential automatically. Revoking or forgetting this Companion also revokes plugin access; no separate plugin key is needed." Classes="muted" />
+              </StackPanel>
+            </Border>
+          </StackPanel>
+
+          <StackPanel Spacing="12">
+            <TextBlock Text="Playback provider" Classes="sectionTitle" />
+            <Grid ColumnDefinitions="150,*" RowDefinitions="Auto,Auto,Auto" RowSpacing="10" ColumnSpacing="12">
+              <TextBlock Text="Provider" Classes="muted" VerticalAlignment="Center" />
+              <ComboBox Grid.Column="1" x:Name="SongOverlayProviderPicker" SelectedIndex="0" IsEnabled="False">
+                <ComboBoxItem Content="Spotify" Tag="spotify" />
+              </ComboBox>
+              <TextBlock Grid.Row="1" Text="Recovery heartbeat" Classes="muted" VerticalAlignment="Center" />
+              <NumericUpDown Grid.Row="1" Grid.Column="1" x:Name="SongOverlayHeartbeatBox" Minimum="15" Maximum="300" Increment="5" FormatString="0 seconds" HorizontalAlignment="Left" Width="160" />
+              <TextBlock Grid.Row="2" Text="Seek sensitivity" Classes="muted" VerticalAlignment="Center" />
+              <NumericUpDown Grid.Row="2" Grid.Column="1" x:Name="SongOverlaySeekBox" Minimum="500" Maximum="10000" Increment="250" FormatString="0 ms" HorizontalAlignment="Left" Width="160" />
+            </Grid>
+            <CheckBox x:Name="SongOverlayCoverToggle" Content="Send cover art only with track metadata" />
+            <CheckBox x:Name="SongOverlaySearchLinkToggle" Content="Use a Spotify search link when an exact song link is unavailable" />
+          </StackPanel>
+
+          <Border Classes="card">
+            <StackPanel Spacing="12">
+              <StackPanel Spacing="4">
+                <TextBlock Text="SPOTIFY-SPECIFIC" Classes="eyebrow" />
+                <TextBlock Text="Optional metadata enrichment" Classes="sectionTitle" />
+                <TextBlock Text="Windows normally supplies title, artist, album, timeline and artwork. Connecting your own Spotify application adds an exact link, release year and official artwork when available. Spotify is contacted only when track metadata changes or needs recovery." Classes="muted" />
+              </StackPanel>
+              <TextBox x:Name="SongOverlaySpotifyClientIdBox" PlaceholderText="Spotify application Client ID" />
+              <StackPanel Orientation="Horizontal" Spacing="10">
+                <Button x:Name="ConnectSongOverlaySpotifyButton" Classes="secondary" Content="Connect Spotify metadata" />
+                <Button x:Name="DisconnectSongOverlaySpotifyButton" Classes="secondary" Content="Disconnect" />
+              </StackPanel>
+              <TextBlock x:Name="SongOverlaySpotifyStatus" Text="Not connected. Core playback detection still works through Windows." Classes="muted" />
+            </StackPanel>
+          </Border>
+
+          <StackPanel Orientation="Horizontal" Spacing="10">
+            <Button x:Name="SaveSongOverlayButton" Classes="primary" Content="Save Song Overlay" />
+            <Button x:Name="SendSongOverlayStateButton" Classes="secondary" Content="Send current song now" />
+          </StackPanel>
+          <TextBlock x:Name="SongOverlayFeedback" Classes="muted" />
+        </StackPanel>
+      </ScrollViewer>
+
       <ScrollViewer x:Name="ConnectionPage" IsVisible="False">
         <StackPanel Margin="44,38,52,48" MaxWidth="760" HorizontalAlignment="Left" Spacing="24">
           <StackPanel Spacing="6">

companion/src/Lumi.Companion.App/MainWindow.axaml.cs

@@ -4,6 +4,8 @@ using Avalonia.Interactivity;
 using Avalonia.Media;
 using Avalonia.Platform.Storage;
 using Avalonia.Threading;
+using Lumi.Companion.Abstractions;
+using Lumi.Companion.SongOverlay;
 
 namespace Lumi.Companion.App;
 
@@ -11,25 +13,33 @@ public partial class MainWindow : Window
 {
     private readonly CompanionRuntime _runtime;
     private readonly CompanionSettingsStore _settings;
+    private readonly SongOverlayRuntime _songOverlay;
+    private readonly IReadOnlyList<ICompanionPluginContribution> _plugins;
+    private readonly Dictionary<CompanionPage, Button> _navigationButtons = [];
     private bool _allowExit;
     private bool _renderingSources;
+    private bool _renderingSongOverlay;
 
     public MainWindow() : this(CreateDefaultServices()) { }
 
-    private MainWindow((CompanionRuntime Runtime, CompanionSettingsStore Settings) services)
-        : this(services.Runtime, services.Settings) { }
+    private MainWindow((CompanionRuntime Runtime, CompanionSettingsStore Settings, SongOverlayRuntime SongOverlay, IReadOnlyList<ICompanionPluginContribution> Plugins) services)
+        : this(services.Runtime, services.Settings, services.SongOverlay, services.Plugins) { }
 
-    public MainWindow(CompanionRuntime runtime, CompanionSettingsStore settings)
+    public MainWindow(CompanionRuntime runtime, CompanionSettingsStore settings, SongOverlayRuntime songOverlay, IReadOnlyList<ICompanionPluginContribution> plugins)
     {
         _runtime = runtime;
         _settings = settings;
+        _songOverlay = songOverlay;
+        _plugins = plugins;
         InitializeComponent();
+        BuildPluginNavigation();
         WireActions();
         RenderState(runtime.State);
         RenderTestStages(runtime.TestStages);
         RenderBenchmark(runtime.Benchmark);
+        RenderSongOverlay();
         Closing += OnClosing;
-        runtime.StateChanged += state => Dispatcher.UIThread.Post(() => RenderState(state));
+        runtime.StateChanged += state => Dispatcher.UIThread.Post(() => { RenderState(state); RenderSongOverlay(); });
         runtime.TestStagesChanged += stages => Dispatcher.UIThread.Post(() => RenderTestStages(stages));
         runtime.ObsSourcesChanged += sources => Dispatcher.UIThread.Post(() => RenderSources(sources));
         runtime.BenchmarkChanged += benchmark => Dispatcher.UIThread.Post(() => RenderBenchmark(benchmark));
@@ -40,11 +50,44 @@ public partial class MainWindow : Window
         });
         runtime.LogAdded += line => Dispatcher.UIThread.Post(() => AddLog(line));
         settings.Changed += value => Dispatcher.UIThread.Post(() => RenderSettings(value));
+        songOverlay.Changed += () => Dispatcher.UIThread.Post(RenderSongOverlay);
+    }
+
+    private void BuildPluginNavigation()
+    {
+        PluginNavigation.Children.Clear();
+        foreach (var plugin in _plugins.OrderBy(item => item.Descriptor.Order).ThenBy(item => item.Descriptor.Name, StringComparer.OrdinalIgnoreCase))
+        {
+            var children = new StackPanel { Spacing = 2, Margin = new Thickness(8, 3, 0, 6) };
+            foreach (var page in plugin.Pages.OrderBy(item => item.Order))
+            {
+                if (!Enum.TryParse<CompanionPage>(page.Key, out var parsed)) continue;
+                var button = new Button { Content = page.Label, Tag = page.Key, HorizontalContentAlignment = Avalonia.Layout.HorizontalAlignment.Left };
+                button.Classes.Add("nav");
+                button.Click += OnNavigate;
+                children.Children.Add(button);
+                _navigationButtons[parsed] = button;
+            }
+            var expander = new Expander
+            {
+                Header = new TextBlock { Text = plugin.Descriptor.Name, FontWeight = FontWeight.SemiBold },
+                IsExpanded = true,
+                Content = children,
+                HorizontalAlignment = Avalonia.Layout.HorizontalAlignment.Stretch
+            };
+            expander.Classes.Add("pluginRoot");
+            PluginNavigation.Children.Add(expander);
+        }
+        _navigationButtons[CompanionPage.Overview] = OverviewNav;
+        _navigationButtons[CompanionPage.Connection] = ConnectionNav;
+        _navigationButtons[CompanionPage.Logs] = LogsNav;
+        _navigationButtons[CompanionPage.Settings] = SettingsNav;
     }
 
     private void WireActions()
     {
-        foreach (var button in Navigation.Children.OfType<Button>()) button.Click += OnNavigate;
+        OverviewNav.Click += OnNavigate;
+        foreach (var button in TechnicalNavigation.Children.OfType<Button>()) button.Click += OnNavigate;
         NextActionButton.Click += OnNextAction;
         PairButton.Click += async (_, _) => await ChoosePairingPackageAsync();
         ReconnectButton.Click += async (_, _) => await RunUiActionAsync(() => _runtime.RetryConnectionAsync(), ReconnectButton);
@@ -60,6 +103,14 @@ public partial class MainWindow : Window
         InstallBridgeButton.Click += async (_, _) => await InstallBridgeAsync();
         RemoveBridgeButton.Click += async (_, _) => await RemoveBridgeAsync();
         AdvancedToggle.IsCheckedChanged += (_, _) => AdvancedPanel.IsVisible = AdvancedToggle.IsChecked == true;
+        SaveSongOverlayButton.Click += async (_, _) => await SaveSongOverlayAsync();
+        SendSongOverlayStateButton.Click += async (_, _) => await RunSongOverlayActionAsync(() => _songOverlay.SendSnapshotAsync(), SendSongOverlayStateButton);
+        ConnectSongOverlaySpotifyButton.Click += async (_, _) =>
+        {
+            await SaveSongOverlayAsync(restartProvider: false);
+            await RunSongOverlayActionAsync(() => _songOverlay.ConnectSpotifyAsync(), ConnectSongOverlaySpotifyButton);
+        };
+        DisconnectSongOverlaySpotifyButton.Click += (_, _) => { _songOverlay.DisconnectSpotify(); RenderSongOverlay(); };
         SourcePicker.SelectionChanged += async (_, _) =>
         {
             if (!_renderingSources && SourcePicker.SelectedItem is ObsSource source) await _runtime.SelectSourceAsync(source);
@@ -75,15 +126,17 @@ public partial class MainWindow : Window
     {
         var pages = new Dictionary<CompanionPage, Control>
         {
-            [CompanionPage.Overview] = OverviewPage, [CompanionPage.Transcription] = TranscriptionPage,
-            [CompanionPage.Test] = TestPage, [CompanionPage.Connection] = ConnectionPage,
-            [CompanionPage.Logs] = LogsPage, [CompanionPage.Settings] = SettingsPage
+            [CompanionPage.Overview] = OverviewPage,
+            [CompanionPage.Transcription] = TranscriptionPage,
+            [CompanionPage.Test] = TestPage,
+            [CompanionPage.SongOverlay] = SongOverlayPage,
+            [CompanionPage.Connection] = ConnectionPage,
+            [CompanionPage.Logs] = LogsPage,
+            [CompanionPage.Settings] = SettingsPage
         };
         foreach (var item in pages) item.Value.IsVisible = item.Key == page;
-        foreach (var button in Navigation.Children.OfType<Button>())
-        {
-            button.Classes.Set("selected", string.Equals(button.Tag as string, page.ToString(), StringComparison.Ordinal));
-        }
+        foreach (var item in _navigationButtons)
+            item.Value.Classes.Set("selected", item.Key == page);
     }
 
     private async void OnNextAction(object? sender, RoutedEventArgs args)
@@ -130,6 +183,55 @@ public partial class MainWindow : Window
         finally { RenderState(_runtime.State); }
     }
 
+    private async Task SaveSongOverlayAsync(bool restartProvider = true)
+    {
+        if (_renderingSongOverlay) return;
+        SaveSongOverlayButton.IsEnabled = false;
+        SongOverlayFeedback.Text = "Saving…";
+        try
+        {
+            var settings = _songOverlay.Settings;
+            settings.Enabled = SongOverlayEnabledToggle.IsChecked == true;
+            settings.ProviderId = "spotify";
+            settings.HeartbeatSeconds = Decimal.ToInt32(SongOverlayHeartbeatBox.Value ?? 30);
+            settings.SeekThresholdMilliseconds = Decimal.ToInt32(SongOverlaySeekBox.Value ?? 1500);
+            settings.SendCoverArt = SongOverlayCoverToggle.IsChecked == true;
+            settings.UseSearchLinkFallback = SongOverlaySearchLinkToggle.IsChecked == true;
+            settings.SpotifyClientId = SongOverlaySpotifyClientIdBox.Text?.Trim() ?? "";
+            await _songOverlay.SaveSettingsAsync(restartProvider);
+            SongOverlayFeedback.Text = "Song Overlay settings saved.";
+        }
+        catch (Exception error)
+        {
+            SongOverlayFeedback.Text = $"Could not save Song Overlay: {error.Message}";
+            AddLog($"{DateTime.Now:HH:mm:ss}  Song Overlay: {error.Message}");
+        }
+        finally
+        {
+            SaveSongOverlayButton.IsEnabled = true;
+            RenderSongOverlay();
+        }
+    }
+
+    private async Task RunSongOverlayActionAsync(Func<Task> action, Button button)
+    {
+        button.IsEnabled = false;
+        try
+        {
+            await action();
+            SongOverlayFeedback.Text = "Song Overlay action completed.";
+        }
+        catch (Exception error)
+        {
+            SongOverlayFeedback.Text = error.Message;
+            AddLog($"{DateTime.Now:HH:mm:ss}  Song Overlay: {error.Message}");
+        }
+        finally
+        {
+            RenderSongOverlay();
+        }
+    }
+
     private async Task SaveSettingsAsync()
     {
         SaveSettingsButton.IsEnabled = false;
@@ -202,7 +304,7 @@ public partial class MainWindow : Window
         UpdateTitle.Text = state.UpdateAvailable ? $"Lumi Companion {state.AvailableVersion} is available" : "Lumi Companion is current";
         UpdateDetail.Text = state.UpdateDetail;
         ApplyUpdateButton.IsEnabled = state.UpdateAvailable && !state.ObsStreaming && !state.ObsRecording;
-        CurrentVersionText.Text = CompanionRuntime.Version;
+        CurrentVersionText.Text = CompanionRuntime.DisplayVersion;
         UpdateStatusText.Text = state.UpdateDetail;
         BridgeStatusText.Text = state.ObsBridgeDetail;
         InstallBridgeButton.Content = state.ObsBridgeRepairNeeded ? "Repair integration" : state.ObsBridgeInstalled ? "Reinstall integration" : "Install integration";
@@ -248,6 +350,33 @@ public partial class MainWindow : Window
     }
 
 
+    private void RenderSongOverlay()
+    {
+        _renderingSongOverlay = true;
+        try
+        {
+            var settings = _songOverlay.Settings;
+            SongOverlayStatusTitle.Text = _songOverlay.Status.Summary;
+            SongOverlayStatusDetail.Text = _songOverlay.ProviderStatus;
+            SongOverlayCurrentTrack.Text = _songOverlay.CurrentTrack is { Length: > 0 } current ? $"Current: {current}" : "No active song";
+            SongOverlayEnabledToggle.IsChecked = settings.Enabled;
+            SongOverlayLumiAuthenticationText.Text = _songOverlay.UsesCompanionAuthentication
+                ? $"Authenticated through Companion · {_songOverlay.EffectiveLumiBaseUri}"
+                : "Pair Companion to enable Song Overlay delivery";
+            SongOverlayHeartbeatBox.Value = Math.Clamp(settings.HeartbeatSeconds, 15, 300);
+            SongOverlaySeekBox.Value = Math.Clamp(settings.SeekThresholdMilliseconds, 500, 10000);
+            SongOverlayCoverToggle.IsChecked = settings.SendCoverArt;
+            SongOverlaySearchLinkToggle.IsChecked = settings.UseSearchLinkFallback;
+            if (!SongOverlaySpotifyClientIdBox.IsFocused) SongOverlaySpotifyClientIdBox.Text = settings.SpotifyClientId;
+            SongOverlaySpotifyStatus.Text = _songOverlay.IsSpotifyEnrichmentConnected
+                ? "Connected. Exact links, release year and official artwork can be enriched on song changes."
+                : "Not connected. Core playback detection still works through Windows.";
+            DisconnectSongOverlaySpotifyButton.IsEnabled = _songOverlay.IsSpotifyEnrichmentConnected;
+            SendSongOverlayStateButton.IsEnabled = _songOverlay.IsInitialized && settings.Enabled && _songOverlay.UsesCompanionAuthentication;
+        }
+        finally { _renderingSongOverlay = false; }
+    }
+
     private void RenderSources(IReadOnlyList<ObsSource> sources)
     {
         _renderingSources = true;
@@ -338,10 +467,16 @@ public partial class MainWindow : Window
 
     public void AllowExit() => _allowExit = true;
 
-    private static (CompanionRuntime, CompanionSettingsStore) CreateDefaultServices()
+    private static (CompanionRuntime, CompanionSettingsStore, SongOverlayRuntime, IReadOnlyList<ICompanionPluginContribution>) CreateDefaultServices()
     {
         var paths = CompanionPaths.ForCurrentUser();
         var settings = new CompanionSettingsStore(paths.SettingsPath);
-        return (new CompanionRuntime(paths, settings), settings);
+        var runtime = new CompanionRuntime(paths, settings);
+        var songOverlay = new SongOverlayRuntime(
+            Path.Combine(paths.Root, "plugins", "now_playing"),
+            paths.LogsDirectory,
+            runtime.CreatePluginTransport("now_playing"));
+        ICompanionPluginContribution[] plugins = [new TranscriptionPluginContribution(runtime), songOverlay];
+        return (runtime, settings, songOverlay, plugins);
     }
 }

companion/src/Lumi.Companion.App/TranscriptionPluginContribution.cs

@@ -0,0 +1,51 @@
+using Lumi.Companion.Abstractions;
+
+namespace Lumi.Companion.App;
+
+internal sealed class TranscriptionPluginContribution : ICompanionPluginContribution
+{
+    private readonly CompanionRuntime _runtime;
+
+    public TranscriptionPluginContribution(CompanionRuntime runtime)
+    {
+        _runtime = runtime;
+        Actions =
+        [
+            new CompanionPluginAction(
+                "test",
+                () => _runtime.State.TestRunning || _runtime.State.BenchmarkRunning ? "Transcription test running…" : "Run transcription test",
+                cancellationToken => _runtime.RunTestAsync(cancellationToken),
+                () => !_runtime.State.TestRunning && !_runtime.State.BenchmarkRunning,
+                10)
+        ];
+        _runtime.StateChanged += _ => Changed?.Invoke();
+    }
+
+    public CompanionPluginDescriptor Descriptor { get; } = new(
+        "transcription",
+        "Transcription",
+        new Version(0, 1, 0),
+        "Captures selected OBS sources and delivers closed captions through Lumi.",
+        100);
+
+    public IReadOnlyList<CompanionPluginPage> Pages { get; } =
+    [
+        new CompanionPluginPage("Transcription", "Capture", 10),
+        new CompanionPluginPage("Test", "Test & benchmark", 20)
+    ];
+
+    public IReadOnlyList<CompanionPluginAction> Actions { get; }
+
+    public CompanionPluginStatus Status => new(
+        _runtime.State.Health switch
+        {
+            TrayHealth.Ready => CompanionPluginHealth.Healthy,
+            TrayHealth.Operating => CompanionPluginHealth.Healthy,
+            TrayHealth.Failed => CompanionPluginHealth.Error,
+            _ => CompanionPluginHealth.Warning
+        },
+        _runtime.State.Summary,
+        _runtime.State.Detail);
+
+    public event Action? Changed;
+}

companion/src/Lumi.Companion.App/UpdateApplier.cs

@@ -22,6 +22,12 @@ internal static class UpdateApplier
             var targetRoot = Path.GetDirectoryName(target)!;
             var stagedComponents = Path.Combine(stageRoot, "components");
             if (Directory.Exists(stagedComponents)) ReplaceDirectory(stagedComponents, Path.Combine(targetRoot, "components"));
+            var stagedLegal = Path.Combine(stageRoot, "legal");
+            if (Directory.Exists(stagedLegal)) ReplaceDirectory(stagedLegal, Path.Combine(targetRoot, "legal"));
+            var stagedDevelopmentManifest = Path.Combine(stageRoot, ".lumi-dev-build.json");
+            var targetDevelopmentManifest = Path.Combine(targetRoot, ".lumi-dev-build.json");
+            if (File.Exists(stagedDevelopmentManifest)) File.Copy(stagedDevelopmentManifest, targetDevelopmentManifest, true);
+            else try { File.Delete(targetDevelopmentManifest); } catch { }
             var temporary = $"{target}.{Environment.ProcessId}.update";
             var backup = $"{target}.previous";
             File.Copy(staged, temporary, true);

companion/src/Lumi.Companion.App/UpdateService.cs

@@ -1,9 +1,11 @@
 using System.Diagnostics;
 using System.IO.Compression;
 using System.Net.Http.Headers;
+using System.Net.Http.Json;
 using System.Security.Cryptography;
 using System.Text.Json;
 using System.Text.Json.Serialization;
+using Lumi.Companion.Core;
 using Lumi.Companion.Protocol;
 
 namespace Lumi.Companion.App;
@@ -13,27 +15,69 @@ public sealed class UpdateService(HttpClient http, CompanionPaths paths)
     public async Task<CompanionUpdate?> CheckAsync(DeviceCredential credential, string currentVersion, CancellationToken cancellationToken = default)
     {
         var host = new Uri(credential.Host);
+        var endpoint = new Uri(host, "/plugins/lumi_transcription/api/companion/update");
+        var localBuild = DevelopmentBuildManifest.Load();
+        var deadline = DateTimeOffset.UtcNow.AddMinutes(10);
+        while (true)
+        {
+            using var request = new HttpRequestMessage(HttpMethod.Post, endpoint);
+            request.Headers.Authorization = new AuthenticationHeaderValue("LumiDevice", $"{credential.DeviceId}.{credential.DeviceSecret}");
+            request.Content = JsonContent.Create(new CompanionUpdateCheck(
+                currentVersion,
+                localBuild?.BuildChecksum,
+                localBuild?.Components ?? new Dictionary<string, string>(),
+                true), options: ProtocolV1.JsonOptions);
+            using var response = await http.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, cancellationToken);
+            if (response.StatusCode is System.Net.HttpStatusCode.NotFound or System.Net.HttpStatusCode.MethodNotAllowed)
+                return await CheckLegacyAsync(credential, currentVersion, host, cancellationToken);
+            response.EnsureSuccessStatusCode();
+            var update = await JsonSerializer.DeserializeAsync<CompanionUpdate>(
+                await response.Content.ReadAsStreamAsync(cancellationToken),
+                ProtocolV1.JsonOptions,
+                cancellationToken);
+            if (update is not { Ok: true, UpdateAvailable: true }) return null;
+            if (update.Artifact is not null) return update;
+            if (!update.Development || !update.BuildPending)
+                throw new InvalidDataException("Lumi announced a Companion update without a downloadable artifact.");
+            if (DateTimeOffset.UtcNow >= deadline)
+                throw new TimeoutException("Lumi did not finish preparing the local Companion update within 10 minutes.");
+            await Task.Delay(TimeSpan.FromMilliseconds(Math.Clamp(update.RetryAfterMilliseconds ?? 2000, 500, 10000)), cancellationToken);
+        }
+    }
+
+    private async Task<CompanionUpdate?> CheckLegacyAsync(DeviceCredential credential, string currentVersion, Uri host, CancellationToken cancellationToken)
+    {
         var endpoint = new Uri(host, $"/plugins/lumi_transcription/api/companion/update?current_version={Uri.EscapeDataString(currentVersion)}");
         using var request = new HttpRequestMessage(HttpMethod.Get, endpoint);
         request.Headers.Authorization = new AuthenticationHeaderValue("LumiDevice", $"{credential.DeviceId}.{credential.DeviceSecret}");
         using var response = await http.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, cancellationToken);
         response.EnsureSuccessStatusCode();
-        var update = await JsonSerializer.DeserializeAsync<CompanionUpdate>(await response.Content.ReadAsStreamAsync(cancellationToken), ProtocolV1.JsonOptions, cancellationToken);
-        return update is { Ok: true, UpdateAvailable: true } ? update : null;
+        var legacy = await JsonSerializer.DeserializeAsync<LegacyCompanionUpdate>(await response.Content.ReadAsStreamAsync(cancellationToken), ProtocolV1.JsonOptions, cancellationToken);
+        if (legacy is not { Ok: true, UpdateAvailable: true }) return null;
+        return new CompanionUpdate(legacy.Ok, legacy.Version, legacy.UpdateAvailable, legacy.Artifact, legacy.Signed, legacy.ReleaseNotes,
+            false, null, null, null, false, null);
     }
 
-    public async Task<StagedUpdate> StageAsync(CompanionUpdate update, CancellationToken cancellationToken = default)
+    public async Task<StagedUpdate> StageAsync(CompanionUpdate update, DeviceCredential? credential = null, CancellationToken cancellationToken = default)
     {
-        if (update.Artifact.Bytes is <= 0 or > 300 * 1024 * 1024 || !IsSha256(update.Artifact.Sha256)) throw new InvalidDataException("The update manifest is invalid.");
-        if (!Uri.TryCreate(update.Artifact.Url, UriKind.Absolute, out var artifactUri) || artifactUri.Scheme != Uri.UriSchemeHttps) throw new InvalidDataException("The update manifest does not use a secure artifact URL.");
+        var artifact = update.Artifact ?? throw new InvalidDataException("The update manifest does not contain an artifact.");
+        if (artifact.Bytes is <= 0 or > 300 * 1024 * 1024 || !IsSha256(artifact.Sha256)) throw new InvalidDataException("The update manifest is invalid.");
+        var pairedHost = credential is null ? null : new Uri(credential.Host);
+        if (!Uri.TryCreate(artifact.Url, UriKind.Absolute, out var artifactUri) ||
+            !IsAllowedArtifactUri(artifactUri, update.Development, pairedHost))
+            throw new InvalidDataException("The update manifest does not use an allowed artifact URL.");
         var safeVersion = SafeVersion(update.Version);
         if (string.IsNullOrWhiteSpace(safeVersion)) throw new InvalidDataException("The update manifest has an invalid version.");
         Directory.CreateDirectory(paths.UpdatesDirectory);
-        var archivePath = Path.Combine(paths.UpdatesDirectory, $"companion-{safeVersion}.zip.partial");
-        var stageRoot = Path.Combine(paths.UpdatesDirectory, safeVersion);
+        var buildSuffix = update.Development && IsSha256(update.BuildChecksum ?? string.Empty) ? $"-{update.BuildChecksum![..12]}" : string.Empty;
+        var archivePath = Path.Combine(paths.UpdatesDirectory, $"companion-{safeVersion}{buildSuffix}.zip.partial");
+        var stageRoot = Path.Combine(paths.UpdatesDirectory, $"{safeVersion}{buildSuffix}");
         try
         {
-            using var response = await http.GetAsync(update.Artifact.Url, HttpCompletionOption.ResponseHeadersRead, cancellationToken);
+            using var download = new HttpRequestMessage(HttpMethod.Get, artifactUri);
+            if (update.Development && credential is not null && CompanionTransportPolicy.IsSameOrigin(artifactUri, pairedHost!))
+                download.Headers.Authorization = new AuthenticationHeaderValue("LumiDevice", $"{credential.DeviceId}.{credential.DeviceSecret}");
+            using var response = await http.SendAsync(download, HttpCompletionOption.ResponseHeadersRead, cancellationToken);
             response.EnsureSuccessStatusCode();
             await using (var source = await response.Content.ReadAsStreamAsync(cancellationToken))
             await using (var target = new FileStream(archivePath, FileMode.Create, FileAccess.Write, FileShare.None, 81920, true))
@@ -45,11 +89,11 @@ public sealed class UpdateService(HttpClient http, CompanionPaths paths)
                     var read = await source.ReadAsync(buffer, cancellationToken);
                     if (read == 0) break;
                     total = checked(total + read);
-                    if (total > update.Artifact.Bytes) throw new InvalidDataException("The Companion update download exceeded its declared size.");
+                    if (total > artifact.Bytes) throw new InvalidDataException("The Companion update download exceeded its declared size.");
                     await target.WriteAsync(buffer.AsMemory(0, read), cancellationToken);
                 }
             }
-            if (new FileInfo(archivePath).Length != update.Artifact.Bytes || !HashFile(archivePath).Equals(update.Artifact.Sha256, StringComparison.OrdinalIgnoreCase))
+            if (new FileInfo(archivePath).Length != artifact.Bytes || !HashFile(archivePath).Equals(artifact.Sha256, StringComparison.OrdinalIgnoreCase))
                 throw new InvalidDataException("The downloaded Companion update did not match its trusted checksum.");
             if (Directory.Exists(stageRoot)) Directory.Delete(stageRoot, true);
             Directory.CreateDirectory(stageRoot);
@@ -68,7 +112,7 @@ public sealed class UpdateService(HttpClient http, CompanionPaths paths)
                 Directory.CreateDirectory(Path.GetDirectoryName(destination)!);
                 entry.ExtractToFile(destination, true);
             }
-            var staged = Path.GetFullPath(Path.Combine(stageRoot, update.Artifact.Entrypoint.Replace('/', Path.DirectorySeparatorChar)));
+            var staged = Path.GetFullPath(Path.Combine(stageRoot, artifact.Entrypoint.Replace('/', Path.DirectorySeparatorChar)));
             if (!File.Exists(staged) || !staged.StartsWith(stageRoot + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase))
                 throw new InvalidDataException("The Companion update is missing its application entrypoint.");
             return new StagedUpdate(stageRoot, staged, HashFile(staged));
@@ -87,18 +131,48 @@ public sealed class UpdateService(HttpClient http, CompanionPaths paths)
         Process.Start(start)?.Dispose();
     }
 
+    private static bool IsAllowedArtifactUri(Uri uri, bool development, Uri? pairedHost)
+    {
+        if (CompanionTransportPolicy.IsSecureOrigin(uri)) return true;
+        return development && CompanionTransportPolicy.IsEndpointAllowed(uri, pairedHost);
+    }
+
     internal static string HashFile(string path) { using var stream = File.OpenRead(path); return Convert.ToHexString(SHA256.HashData(stream)).ToLowerInvariant(); }
     private static bool IsSha256(string value) => value.Length == 64 && value.All(Uri.IsHexDigit);
     private static string SafeVersion(string value) => string.Concat(value.Where(character => char.IsLetterOrDigit(character) || character is '.' or '-')).Trim('.');
 }
 
-public sealed record CompanionUpdate(
+public sealed record LegacyCompanionUpdate(
     [property: JsonPropertyName("ok")] bool Ok,
     [property: JsonPropertyName("version")] string Version,
     [property: JsonPropertyName("update_available")] bool UpdateAvailable,
     [property: JsonPropertyName("artifact")] CompanionUpdateArtifact Artifact,
     [property: JsonPropertyName("signed")] bool Signed,
     [property: JsonPropertyName("release_notes")] string ReleaseNotes);
+
+public sealed record CompanionUpdateCheck(
+    [property: JsonPropertyName("current_version")] string CurrentVersion,
+    [property: JsonPropertyName("build_checksum")] string? BuildChecksum,
+    [property: JsonPropertyName("component_checksums")] IReadOnlyDictionary<string, string> ComponentChecksums,
+    [property: JsonPropertyName("supports_pending_build")] bool SupportsPendingBuild);
+
+public sealed record CompanionUpdate(
+    [property: JsonPropertyName("ok")] bool Ok,
+    [property: JsonPropertyName("version")] string Version,
+    [property: JsonPropertyName("update_available")] bool UpdateAvailable,
+    [property: JsonPropertyName("artifact")] CompanionUpdateArtifact? Artifact,
+    [property: JsonPropertyName("signed")] bool Signed,
+    [property: JsonPropertyName("release_notes")] string ReleaseNotes,
+    [property: JsonPropertyName("development")] bool Development,
+    [property: JsonPropertyName("build_checksum")] string? BuildChecksum,
+    [property: JsonPropertyName("component_checksums")] IReadOnlyDictionary<string, string>? ComponentChecksums,
+    [property: JsonPropertyName("changed_components")] IReadOnlyList<CompanionUpdateComponent>? ChangedComponents,
+    [property: JsonPropertyName("build_pending")] bool BuildPending,
+    [property: JsonPropertyName("retry_after_ms")] int? RetryAfterMilliseconds);
+public sealed record CompanionUpdateComponent(
+    [property: JsonPropertyName("id")] string Id,
+    [property: JsonPropertyName("kind")] string Kind,
+    [property: JsonPropertyName("checksum")] string Checksum);
 public sealed record CompanionUpdateArtifact(
     [property: JsonPropertyName("url")] string Url,
     [property: JsonPropertyName("sha256")] string Sha256,

companion/src/Lumi.Companion.Core/CompanionPluginTransport.cs

@@ -0,0 +1,76 @@
+using System.Net.Http.Headers;
+using System.Net.Http.Json;
+using Lumi.Companion.Abstractions;
+using Lumi.Companion.Protocol;
+
+namespace Lumi.Companion.Core;
+
+public sealed class CompanionPluginTransport(
+    HttpClient http,
+    Func<DeviceCredential?> credentialProvider,
+    string pluginId) : ICompanionPluginTransport
+{
+    private readonly string _pluginId = ValidatePluginId(pluginId);
+
+    public Uri? LumiBaseUri
+    {
+        get
+        {
+            try
+            {
+                var credential = credentialProvider();
+                return credential is null ? null : new Uri(credential.Host);
+            }
+            catch
+            {
+                return null;
+            }
+        }
+    }
+
+    public bool IsAuthenticated => LumiBaseUri is not null;
+
+    public async Task<CompanionPluginHttpResponse> PostJsonAsync(
+        string relativePath,
+        object payload,
+        CancellationToken cancellationToken = default)
+    {
+        var credential = credentialProvider()
+            ?? throw new InvalidOperationException("Pair Companion with Lumi before using this plugin.");
+        var host = new Uri(credential.Host);
+        if (!CompanionTransportPolicy.IsPairedHostAllowed(host))
+            throw new InvalidDataException("Companion transport requires HTTPS unless this device was paired with localhost.");
+
+        var expectedPrefix = $"/plugins/{_pluginId}/";
+        if (!relativePath.StartsWith(expectedPrefix, StringComparison.Ordinal) ||
+            !Uri.TryCreate(relativePath, UriKind.Relative, out var relative))
+            throw new InvalidDataException($"Plugin '{_pluginId}' attempted to use an endpoint outside its Lumi plugin scope.");
+
+        var endpoint = new Uri(host, relative);
+        if (!CompanionTransportPolicy.IsEndpointAllowed(endpoint, host))
+            throw new InvalidDataException("The plugin endpoint does not match the paired Lumi host.");
+
+        using var request = new HttpRequestMessage(HttpMethod.Post, endpoint)
+        {
+            Content = JsonContent.Create(payload, options: ProtocolV1.JsonOptions)
+        };
+        request.Headers.Authorization = new AuthenticationHeaderValue(
+            "LumiDevice",
+            $"{credential.DeviceId}.{credential.DeviceSecret}");
+        request.Headers.UserAgent.ParseAdd("Lumi-Companion/1.0");
+        request.Headers.Add("X-Lumi-Companion-Plugin", _pluginId);
+
+        using var response = await http.SendAsync(request, cancellationToken).ConfigureAwait(false);
+        var body = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+        return new CompanionPluginHttpResponse((int)response.StatusCode, body);
+    }
+
+    private static string ValidatePluginId(string value)
+    {
+        var clean = (value ?? string.Empty).Trim();
+        if (clean.Length is < 1 or > 100 ||
+            clean.Any(character => !char.IsAsciiLetterOrDigit(character) && character is not '_' and not '-' and not '.'))
+            throw new ArgumentException("A valid Companion plugin identifier is required.", nameof(value));
+        return clean;
+    }
+}

companion/src/Lumi.Companion.Core/CompanionSocket.cs

@@ -7,7 +7,13 @@ namespace Lumi.Companion.Core;
 
 public sealed class CompanionSocket : IAsyncDisposable
 {
+    private const int NetworkAudioPayloadBytes = 640; // 20 ms of 16 kHz mono PCM16.
     private readonly Channel<ReadOnlyMemory<byte>> _audio = Channel.CreateBounded<ReadOnlyMemory<byte>>(new BoundedChannelOptions(250) { FullMode = BoundedChannelFullMode.Wait, SingleReader = true });
+    private readonly object _bridgeAudioGate = new();
+    private readonly byte[] _bridgeAudioBuffer = new byte[ProtocolV1.MaxAudioPayloadBytes + NetworkAudioPayloadBytes];
+    private readonly byte[] _bridgeAudioHeader = new byte[ProtocolV1.AudioHeaderBytes];
+    private int _bridgeAudioBuffered;
+    private uint _bridgeAudioSequence;
     private ClientWebSocket? _socket;
     private CancellationTokenSource? _lifetime;
     private readonly SemaphoreSlim _sendLock = new(1, 1);
@@ -25,7 +31,7 @@ public sealed class CompanionSocket : IAsyncDisposable
         _socket = new ClientWebSocket();
         _socket.Options.SetRequestHeader("Authorization", $"LumiDevice {credential.DeviceId}.{credential.DeviceSecret}");
         var host = new Uri(credential.Host);
-        if (host.Scheme != "https" && !(host.Scheme == "http" && host.IsLoopback))
+        if (!CompanionTransportPolicy.IsPairedHostAllowed(host))
             throw new InvalidDataException("Companion transport requires HTTPS unless this credential was issued for localhost.");
         var uri = new UriBuilder(host) { Scheme = host.Scheme == "https" ? "wss" : "ws", Path = "/plugins/lumi_transcription/live" }.Uri;
         await _socket.ConnectAsync(uri, cancellationToken);
@@ -56,11 +62,36 @@ public sealed class CompanionSocket : IAsyncDisposable
     }
     public bool QueueBridgeAudio(ReadOnlyMemory<byte> encoded)
     {
-        if (encoded.Length < ProtocolV1.AudioHeaderBytes || !encoded.Span[..4].SequenceEqual("LACP"u8)) return false;
-        var normalized = encoded.ToArray();
-        SessionId.TryWriteBytes(normalized.AsSpan(20, 16), bigEndian: true, out _);
-        BinaryPrimitives.WriteUInt64LittleEndian(normalized.AsSpan(12, 8), (ulong)DateTimeOffset.UtcNow.ToUnixTimeMilliseconds() * 1000UL);
-        return QueueEncodedAudio(normalized);
+        var input = encoded.Span;
+        if (input.Length < ProtocolV1.AudioHeaderBytes || input.Length > ProtocolV1.AudioHeaderBytes + ProtocolV1.MaxAudioPayloadBytes ||
+            !input[..4].SequenceEqual("LACP"u8) || BinaryPrimitives.ReadUInt16LittleEndian(input[6..8]) != ProtocolV1.AudioHeaderBytes) return false;
+        var payloadBytes = (int)BinaryPrimitives.ReadUInt32LittleEndian(input[60..64]);
+        if (payloadBytes < 0 || payloadBytes % 2 != 0 || input.Length != ProtocolV1.AudioHeaderBytes + payloadBytes) return false;
+        lock (_bridgeAudioGate)
+        {
+            var sourceChanged = !_bridgeAudioHeader.AsSpan(36, 16).SequenceEqual(input[36..52]);
+            var stateChanged = _bridgeAudioHeader[5] != input[5];
+            if (_bridgeAudioBuffered > 0 && (sourceChanged || stateChanged)) _bridgeAudioBuffered = 0;
+            input[..ProtocolV1.AudioHeaderBytes].CopyTo(_bridgeAudioHeader);
+            input[ProtocolV1.AudioHeaderBytes..].CopyTo(_bridgeAudioBuffer.AsSpan(_bridgeAudioBuffered));
+            _bridgeAudioBuffered += payloadBytes;
+            var accepted = true;
+            while (_bridgeAudioBuffered >= NetworkAudioPayloadBytes)
+            {
+                var normalized = new byte[ProtocolV1.AudioHeaderBytes + NetworkAudioPayloadBytes];
+                _bridgeAudioHeader.CopyTo(normalized, 0);
+                BinaryPrimitives.WriteUInt32LittleEndian(normalized.AsSpan(8, 4), _bridgeAudioSequence++);
+                BinaryPrimitives.WriteUInt64LittleEndian(normalized.AsSpan(12, 8), (ulong)DateTimeOffset.UtcNow.ToUnixTimeMilliseconds() * 1000UL);
+                SessionId.TryWriteBytes(normalized.AsSpan(20, 16), bigEndian: true, out _);
+                BinaryPrimitives.WriteUInt32LittleEndian(normalized.AsSpan(60, 4), NetworkAudioPayloadBytes);
+                _bridgeAudioBuffer.AsSpan(0, NetworkAudioPayloadBytes).CopyTo(normalized.AsSpan(ProtocolV1.AudioHeaderBytes));
+                _bridgeAudioBuffered -= NetworkAudioPayloadBytes;
+                if (_bridgeAudioBuffered > 0)
+                    _bridgeAudioBuffer.AsSpan(NetworkAudioPayloadBytes, _bridgeAudioBuffered).CopyTo(_bridgeAudioBuffer);
+                accepted &= QueueEncodedAudio(normalized);
+            }
+            return accepted;
+        }
     }
     public async Task SendAsync(string type, object payload, Guid? sessionId, CancellationToken cancellationToken)
     {

companion/src/Lumi.Companion.Core/CompanionTransportPolicy.cs

@@ -0,0 +1,37 @@
+namespace Lumi.Companion.Core;
+
+/// <summary>
+/// Canonical transport boundary for every Companion feature that sends
+/// credentials or private stream data to Lumi.
+/// </summary>
+public static class CompanionTransportPolicy
+{
+    public static bool IsSecureOrigin(Uri uri) =>
+        uri.Scheme.Equals(Uri.UriSchemeHttps, StringComparison.OrdinalIgnoreCase);
+
+    public static bool IsLoopbackHttpOrigin(Uri uri) =>
+        uri.Scheme.Equals(Uri.UriSchemeHttp, StringComparison.OrdinalIgnoreCase) &&
+        uri.IsLoopback;
+
+    public static bool IsSameOrigin(Uri left, Uri right) =>
+        left.Scheme.Equals(right.Scheme, StringComparison.OrdinalIgnoreCase) &&
+        left.Host.Equals(right.Host, StringComparison.OrdinalIgnoreCase) &&
+        left.Port == right.Port;
+
+    public static bool IsPairingExchangeAllowed(Uri exchangeUri, Uri hostUri) =>
+        IsSameOrigin(exchangeUri, hostUri) &&
+        ((IsSecureOrigin(exchangeUri) && IsSecureOrigin(hostUri)) ||
+         (IsLoopbackHttpOrigin(exchangeUri) && IsLoopbackHttpOrigin(hostUri)));
+
+    public static bool IsPairedHostAllowed(Uri hostUri) =>
+        IsSecureOrigin(hostUri) || IsLoopbackHttpOrigin(hostUri);
+
+    public static bool IsEndpointAllowed(Uri endpoint, Uri? pairedHost)
+    {
+        if (IsSecureOrigin(endpoint)) return true;
+        return pairedHost is not null &&
+               IsLoopbackHttpOrigin(endpoint) &&
+               IsLoopbackHttpOrigin(pairedHost) &&
+               IsSameOrigin(endpoint, pairedHost);
+    }
+}

companion/src/Lumi.Companion.Core/Lumi.Companion.Core.csproj

@@ -1 +1 @@
-<Project Sdk="Microsoft.NET.Sdk"><PropertyGroup><TargetFramework>net8.0-windows</TargetFramework><Nullable>enable</Nullable><ImplicitUsings>enable</ImplicitUsings></PropertyGroup><ItemGroup><ProjectReference Include="../Lumi.Companion.Protocol/Lumi.Companion.Protocol.csproj" /><PackageReference Include="System.Security.Cryptography.ProtectedData" Version="8.0.0" /></ItemGroup></Project>
+<Project Sdk="Microsoft.NET.Sdk"><PropertyGroup><TargetFramework>net8.0-windows</TargetFramework><Nullable>enable</Nullable><ImplicitUsings>enable</ImplicitUsings></PropertyGroup><ItemGroup><ProjectReference Include="../Lumi.Companion.Abstractions/Lumi.Companion.Abstractions.csproj" /><ProjectReference Include="../Lumi.Companion.Protocol/Lumi.Companion.Protocol.csproj" /><PackageReference Include="System.Security.Cryptography.ProtectedData" Version="8.0.0" /></ItemGroup></Project>

companion/src/Lumi.Companion.Core/PairingClient.cs

@@ -16,9 +16,7 @@ public sealed class PairingClient(HttpClient http)
             throw new InvalidDataException("Pairing package has expired. Download a new package from Lumi.");
         var exchangeUri = new Uri(bootstrap.ExchangeUrl);
         var hostUri = new Uri(bootstrap.Host);
-        var secure = exchangeUri.Scheme.Equals("https", StringComparison.OrdinalIgnoreCase) && hostUri.Scheme.Equals("https", StringComparison.OrdinalIgnoreCase);
-        var localHttp = exchangeUri.Scheme.Equals("http", StringComparison.OrdinalIgnoreCase) && hostUri.Scheme.Equals("http", StringComparison.OrdinalIgnoreCase) && exchangeUri.IsLoopback && hostUri.IsLoopback;
-        if ((!secure && !localHttp) || exchangeUri.GetLeftPart(UriPartial.Authority) != hostUri.GetLeftPart(UriPartial.Authority))
+        if (!CompanionTransportPolicy.IsPairingExchangeAllowed(exchangeUri, hostUri))
             throw new InvalidDataException("Pairing requires HTTPS unless the package explicitly uses one matching localhost origin.");
         using var response = await http.PostAsJsonAsync(bootstrap.ExchangeUrl, new { token = bootstrap.Token, device }, ProtocolV1.JsonOptions, cancellationToken);
         var body = await response.Content.ReadAsStringAsync(cancellationToken);

docs/adr/0001-companion-transcription-boundaries.md

@@ -1,6 +1,6 @@
 # ADR 0001: Companion transcription boundaries
 
-Status: accepted for the experimental MVP branch.
+Status: accepted for the first stable Companion release.
 
 The MVP uses server-hosted whisper.cpp behind `TranscriptionProvider` and returns captions through `CaptionDeliveryAdapter`. The first concrete boundaries are `WhisperCppServerProvider` and companion-managed OBS native delivery. Session and UI code depend on those interfaces rather than engine, location, or platform details.
 

docs/branch-deployments.md

@@ -29,9 +29,13 @@ new branch.
 
 ## Test an experimental branch
 
-First update production on `main` to stable `0.2.25` through the existing
-**Update from repository** action. This installs the exact-branch controls on
-stable, so future switches in either direction use the same verified workflow.
+First update production on `main` to the latest stable release through
+**Update from repository**. Stable `0.2.27` and newer synchronize core and
+bundled plugins in one snapshot-backed transaction. When the update begins on
+`0.2.25`, the newly started core automatically completes the exact-release
+bundled-plugin phase under a second rollback snapshot before plugins load, with
+no repair action required. Future switches in either direction then use the same
+verified workflow.
 If a `0.2.24` host enters Experimental before taking the stable update, the
 guarded compatibility bootstrap completes bundled-plugin synchronization after
 the older updater installs the newest `experimental-*` branch; expect a second

docs/local-development-updates.md

@@ -0,0 +1,107 @@
+# Localhost development updates
+
+Lumi exposes one reusable runtime environment object:
+
+```js
+global.lumiRuntime
+global.lumiEnvironment
+global.lumiFrameworks.runtime
+global.lumiFrameworks.environment
+```
+
+Useful fields include:
+
+```js
+{
+  mode: "development" | "production",
+  isDevelopment: boolean,
+  isProduction: boolean,
+  devMode: boolean,
+  reason: string,
+  allowsLocalDevelopmentUpdates(req): boolean
+}
+```
+
+Runtime detection uses explicit `LUMI_DEV_MODE` first, followed by `NODE_ENV`, an explicitly loopback-bound `LUMI_HOST`, and whether Lumi is running from a source checkout. Production operators can always force production mode with `LUMI_DEV_MODE=false` or `NODE_ENV=production`.
+
+The development update endpoint has a stricter boundary than the global mode flag. It is active only when all of the following are true:
+
+1. Lumi is in development mode.
+2. The request hostname is `localhost`, `127.0.0.1`, or `::1`.
+3. The request originates from a loopback address.
+4. The Companion device was paired from that exact localhost origin.
+
+A source checkout exposed on a LAN therefore does not expose development artifacts to LAN clients.
+
+## Checksum flow
+
+The update service hashes source contents directly and never calls Git. Generated and mutable directories such as `bin`, `obj`, `node_modules`, `data`, logs, tests, documentation folders, build output, and update caches are excluded. README and changelog edits do not trigger binary updates.
+
+Checksums are tracked independently for:
+
+- Companion core;
+- every directory under `companion/plugins`;
+- Lumi server plugins related to Companion functionality.
+
+Related server plugins are discovered through a matching Companion `plugin.json` ID or a server-side `companion_manifest.json`. This currently links Song Overlay and Lumi Transcription to their Companion components.
+
+The aggregate build checksum combines the individual tracked component checksums. The installed Companion stores the checksums from its last localhost development update in `.lumi-dev-build.json` beside the executable.
+
+When Companion checks for updates it sends only:
+
+- its normal version;
+- the aggregate development checksum;
+- the per-component checksums.
+
+Lumi responds with the changed component IDs. No source code or file inventory crosses the connection.
+
+## Same-version update flow
+
+When checksums differ on localhost, Lumi:
+
+1. builds a self-contained Windows x64 Companion package from the current local source;
+2. adds `.lumi-dev-build.json` to that package;
+3. computes the package SHA-256 and exact size;
+4. exposes the package through an authenticated localhost-only route;
+5. returns a normal Companion update response even when the semantic version is unchanged.
+
+Companion then uses its existing confirmation, download, checksum verification, staging, OBS-idle safety check, replacement, and restart flow. The build checksum is appended to the local staging directory so repeated same-version builds do not collide.
+
+After restart, the installed checksum manifest prevents the same source state from being offered again.
+
+## Requirements
+
+The machine running Lumi must have a usable Windows .NET 8 SDK when a localhost development package needs to be built. The build runs lazily only after Companion asks for updates and its checksums differ.
+
+The build cache is stored under:
+
+```text
+data/development-updates/companion/
+```
+
+Only the five newest checksum-addressed builds are retained by default.
+
+## Configuration
+
+Example local-only development setup:
+
+```dotenv
+LUMI_DEV_MODE=true
+LUMI_HOST=127.0.0.1
+```
+
+`LUMI_HOST` is optional, but explicitly binding to `127.0.0.1` is recommended for a development instance that should never be reachable from the LAN.
+
+Run the focused verification with:
+
+```bash
+npm run verify:dev-updates
+```
+
+## First adoption
+
+An already installed Companion that predates this feature still uses the legacy
+GET-only update check and cannot apply a localhost HTTP development artifact.
+Build or install the patched Companion once through the normal development
+workflow. After that first adoption, later same-version source changes use the
+checksum update path automatically.

docs/lumi-companion-transcription.md

@@ -1,56 +1,88 @@
-# Lumi Companion transcription (experimental)
+# Lumi Companion transcription
 
-## Delivered foundation
+`lumi_transcription` is a separately disableable Lumi plugin. It owns paired
+devices, session state, model/runtime artifacts, worker supervision, caption
+stabilization, delivery, diagnostics, tests, and WebUI routes. Core supplies the
+shared Companion authentication and versioned WebSocket boundary.
 
-`lumi_transcription` is an independently disableable Lumi plugin. Core contains only a generic HTTP upgrade registry so plugins can attach versioned WebSocket transports. The plugin owns pairing/devices, session state, settings revisions, model/runtime manifests, worker supervision, caption stabilization, delivery, logs, routes, and shutdown.
-
-The implemented transport path is:
+## Runtime path
 
 ```text
-OBS bridge boundary -> same-user companion IPC -> bounded companion queue
--> authenticated TLS WebSocket -> bounded per-source Lumi buffer
--> supervised TranscriptionProvider -> stabilized revision-aware caption
--> WebSocket -> companion delivery adapter -> OBS native caption boundary
+selected OBS source -> same-user Companion IPC -> bounded audio queue
+-> authenticated TLS WebSocket -> bounded Lumi session
+-> supervised server-hosted whisper.cpp worker -> stabilized caption revisions
+-> Companion -> OBS native caption boundary
 ```
 
-The repository contains a pinned native whisper.cpp rolling-window worker and a CPU build/protocol smoke test. It has not yet been benchmarked with a model on the target RTX 3060, packaged as the Windows CUDA runtime, or validated end to end. The repository also does not contain a complete signed OBS bridge installer. Accordingly, this branch does not claim live Twitch acceptance.
+Speech recognition never runs on the streaming computer. Raw audio is kept in
+bounded memory and is not logged or written to disk. Lumi prefers the published
+CUDA worker on an NVIDIA RTX 3060 or newer and retains the CPU worker as a
+portable fallback.
 
-## Trust and privacy
+## Install and pair
 
-- Pairing packages contain a cryptographically random credential that expires after 15 minutes and can be activated once. Lumi stores only its SHA-256 digest.
-- Activation returns a revocable device secret once. The Windows companion stores it with current-user DPAPI.
-- Device HTTP and WebSocket credentials require HTTPS/WSS. HTTP/WS is accepted only when an administrator downloads the package through an explicit loopback URL and Companion returns to that exact loopback origin, including its port. There is no environment-variable bypass.
-- The OBS bridge never receives the Lumi credential and never connects to Lumi directly.
-- Audio frames are capped at 200 ms and recovery buffers at five seconds. Old or excess frames are dropped; capture paths never block for inference.
-- Raw audio is never logged or written to disk. JSON Lines diagnostics default to seven days and 256 MiB. Caption text can be disabled in diagnostics.
+1. Enable **Lumi Transcription** under **Admin > Plugins**.
+2. Use **Download Companion** from the Admin dashboard or Transcription page.
+3. Extract the private ZIP and run `Lumi.Companion-Setup.exe` within 15 minutes.
+4. Complete the per-user setup and install or repair the managed OBS integration
+   while OBS is closed.
+5. Select the OBS microphone in Companion.
+6. Run the short voice-free full-path check. A successful result remains valid
+   until a relevant source, integration, model, or host setting changes.
+7. Use the dedicated transcription test when measuring real speech accuracy,
+   confidence, latency, and input level.
 
-## Pairing and installation milestone
+Production device HTTP and WebSocket traffic requires HTTPS/WSS. Plain
+HTTP/WebSocket is allowed only for a device paired from the exact matching
+loopback Lumi origin and only while both sides remain on loopback.
 
-1. Serve Lumi through HTTPS and enable `lumi_transcription` under Admin > Plugins. Local development may use HTTP only from the exact `localhost` or loopback URL used to download Companion.
-2. Use **Download Companion** in Admin or Plugins > Transcription. Lumi downloads and checksum-verifies the pinned Windows artifact, adds a short-lived single-use pairing file, and returns a private ZIP.
-3. On the Windows streaming computer, extract the complete ZIP and start `Lumi.Companion-Setup.exe` within 15 minutes. Setup installs the app under the current user's Local AppData, imports the adjacent pairing file, and launches Companion. Companion exchanges the pairing token once, stores the credential with current-user DPAPI, and removes the imported pairing file after success.
-4. Install a pinned runtime/model only after explicit confirmation. `small.en` is recommended; `small.en-q5_1` and `base.en` are fallbacks. Every artifact is checksum-verified before install.
-5. Build the supervised worker with `plugins/lumi_transcription/scripts/build-worker.ps1`. Lumi discovers the installed CUDA worker first and the CPU worker second. `LUMI_TRANSCRIPTION_WORKER` remains an explicit override for nonstandard installations.
+## Models and workers
 
-The Avalonia tray UI, per-user Windows installer, shared Lumi settings shell, Admin summary, host-side model controls, managed OBS bridge install/repair, live source enumeration, and measured benchmark UI now exist. The installer is not code-signed yet, so Windows may warn.
+The Admin page installs checksum-pinned model and worker artifacts only after
+explicit confirmation. `small.en` is the recommended model;
+`small.en-q5_1` and `base.en` remain available as lower-resource alternatives.
+The worker is supervised, restarts are bounded, and an explicit
+`LUMI_TRANSCRIPTION_WORKER` override remains available for nonstandard
+installations.
+
+The native worker source is under
+`plugins/lumi_transcription/backend/transcription/worker-native`. Release
+workers are built with `plugins/lumi_transcription/scripts/build-worker.ps1`.
 
 ## Operation and recovery
 
-Live start is rejected unless OBS reports an active stream. Test mode is allowed without streaming and sends captions only to the simulated delivery output. If a live stream or connection ends, delivery pauses and the session/model receive a 30-second grace period. Reconnection can resume that session; expiry finalizes and stops it. Recording without streaming does not create third-party delivery.
+- Live sessions require an active OBS stream. Tests use simulated delivery and
+  never publish captions to Twitch.
+- Disconnects pause delivery and retain the session/model for a bounded grace
+  period so a short reconnect can resume safely.
+- Manual benchmark completion waits for the final confidence-bearing caption;
+  silence ends a test after ten seconds.
+- Device revocation takes effect on the next authenticated request or
+  connection.
+- Disabling the plugin unregisters routes, closes clients and sessions, stops
+  the worker, and leaves unrelated plugins running.
 
-Device and capability revocation take effect on the next authenticated request/connection. Worker crashes are bounded to three restart attempts per minute. Disabling the plugin unregisters the WebSocket route, closes clients/sessions, stops the worker, clears timers, and leaves unrelated plugins operational.
+The Admin summary reports Companion, device, inference, and session health.
+Detailed benchmark records remain inspectable for one hour and include
+word/phrase latency and confidence views.
 
-## Diagnostics
+## Verification
 
-Use the compact Lumi Companion section on Admin for connection, device, inference, session, and package health. Open the shared-shell Transcription settings page for provider, model, device, and log details. Recovery errors distinguish missing setup, unavailable inference, source inactivity, protocol incompatibility, and revoked access. The target-machine test must additionally record latency, resource, OBS missed-frame, audio-dropout, queue-drop, and network metrics using the acceptance template in `companion/docs/performance-acceptance-template.md`.
+```powershell
+npm run verify:transcription
+dotnet build companion/Lumi.Companion.sln -c Release -p:EnableWindowsTargeting=true
+```
 
-## Known limitations
+Target-machine acceptance can be recorded with
+`companion/docs/performance-acceptance-template.md`.
 
-- The managed .NET solution and self-contained Windows x64 application have been compiled in the development environment; the OBS SDK integration still requires its target toolchain and acceptance host.
-- No real whisper.cpp streaming worker has been integrated or benchmarked.
-- The bridge skeleton does not yet run its named-pipe worker or selected-source audio callback.
-- Twitch toggleable caption behavior has not been tested; native API presence is not acceptance evidence.
-- The downloadable bundle contains an unsigned experimental per-user installer; production code signing is still required.
-- Bridge repair, source discovery/nested Program-scene evaluation, benchmark UX, and conflict-resolution UI remain pending.
+## Remaining release limitation
 
-See `docs/adr/0001-companion-transcription-boundaries.md`, `protocol/companion-protocol-v1.md`, and `companion/docs/obs-native-caption-compatibility-spike.md`.
+The Windows installer is checksum-pinned but not yet code-signed, so Windows may
+show an unknown-publisher warning. The release includes its licence, privacy
+notice, third-party notices, and corresponding source for the GPL-licensed OBS
+bridge.
+
+See `docs/adr/0001-companion-transcription-boundaries.md`,
+`protocol/companion-protocol-v1.md`, and
+`companion/docs/obs-native-caption-compatibility-spike.md`.

docs/updates.md

@@ -137,18 +137,29 @@ in place:
 - `knowledge/community/` and `knowledge/corrections/`;
 - files under generated knowledge folders unless they explicitly declare both
   `generated: true` and `editable: false`;
-- local configuration, storage, uploads, logs, secrets, environment files, and
-  the plugin directory during core-only updates.
+- local configuration, storage, uploads, logs, secrets, and environment files;
+- plugin data and local-only plugin code. Bundled plugin code follows the exact
+  stable release or managed branch being installed.
 
 Full core updates remove stale replaceable code before copying the new version.
 Plugin code is prepared in a staging directory and swapped only after the new
 files are ready; plugin data is moved into the replacement as part of that
 transaction.
 
-Core updates intentionally do not copy or delete the `plugins/` directory.
-Core code therefore accesses optional plugin capabilities through the registered
-framework API instead of importing files from a plugin directory. Plugins can
-be installed or changed independently from their version picker.
+Stable core updates and managed branch deployments synchronize the bundled
+plugins from the exact selected release. Existing plugin data directories remain
+in place, locally installed plugins absent from that release are retained, and
+new bundled plugins are registered automatically after the restart. The same
+snapshot contains both core and bundled-plugin code so an automatic restore
+cannot leave those layers on different releases. Core code still accesses
+optional plugin capabilities through registered framework APIs, and plugins can
+be repaired, upgraded, or downgraded independently from their version picker.
+
+Hosts updating from a legacy core-only updater complete the bundled-plugin phase
+at the start of the new core, before plugins are loaded. Lumi verifies the same
+immutable release ref, takes a second core-and-plugin snapshot, preserves plugin
+data and local-only plugins, restores automatically if synchronization fails,
+and records an idempotent per-version completion marker.
 
 ## Runtime Dependencies
 
@@ -199,3 +210,10 @@ When a problem occurs only on production, the optional **Admin > Diagnostics**
 page can expose the redacted `update_state`, `system_health`, and
 `recent_errors` checks to a trusted maintainer without shell or write access.
 See [Production diagnostics](production-diagnostics.md).
+
+## Localhost Companion development updates
+
+A source checkout can also offer checksum-addressed, same-version Companion
+updates without publishing a Git tag. This path is strictly limited to a
+localhost-paired Companion and never replaces the production repository update
+flow. See [Localhost development updates](local-development-updates.md).

knowledge/core/lumi-core.md

@@ -14,7 +14,7 @@ editable: false
 Lumi is the core web UI and bot runtime.
 ## Runtime
 Package: lumi-bot
-Version: 0.2.25
+Version: 0.2.27
 ## Routes
 - POST /api/diagnostics/v1/run
 - GET /api/events

knowledge/plugins/lumi-transcription.md

@@ -14,7 +14,7 @@ editable: false
 Server-hosted whisper.cpp transcription for Lumi Companion and OBS closed captions.
 ## Metadata
 Plugin ID: lumi_transcription
-Version: 0.1.0-experimental.8
+Version: 0.1.0
 Default state: enabled
 ## Web Routes
 - /plugins/lumi_transcription
@@ -23,6 +23,8 @@ Default state: enabled
 - POST /plugins/lumi_transcription/api/pairing-package
 - POST /plugins/lumi_transcription/api/companion/download
 - GET /plugins/lumi_transcription/api/companion/update
+- POST /plugins/lumi_transcription/api/companion/update
+- GET /plugins/lumi_transcription/api/companion/dev-artifact/:buildId
 - POST /plugins/lumi_transcription/api/pair
 - GET /plugins/lumi_transcription/api/devices
 - POST /plugins/lumi_transcription/api/devices/:id/revoke
@@ -84,11 +86,29 @@ Default state: enabled
 ### GET /plugins/lumi_transcription/api/companion/update
 
 - Purpose: Renders or serves the lumi_transcription plugin page for api companion update.
-- Inputs: query: `current_version`
-- Response format: JSON response
+- Inputs: No request parameters detected by static analysis.
+- Response format: HTML or data response; exact format was not detected statically.
 - Access: No explicit access guard detected in the route handler; check surrounding router/mount middleware.
-- Side effects: writes or mutates server-side state
-- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations. Input length or numeric bounds are enforced by helper functions in the handler. API consumers should expect JSON unless the response format says otherwise.
+- Side effects: Usually read-only.
+- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations. API consumers should expect JSON unless the response format says otherwise.
+
+### POST /plugins/lumi_transcription/api/companion/update
+
+- Purpose: Processes the lumi_transcription plugin action for api companion update.
+- Inputs: No request parameters detected by static analysis.
+- Response format: Form/action response; exact format was not detected statically.
+- Access: No explicit access guard detected in the route handler; check surrounding router/mount middleware.
+- Side effects: Action route; side effects were not detected statically.
+- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations. Most non-API POST routes are browser form submissions and usually redirect after completion. API consumers should expect JSON unless the response format says otherwise.
+
+### GET /plugins/lumi_transcription/api/companion/dev-artifact/:buildId
+
+- Purpose: Renders or serves the lumi_transcription plugin page for api companion dev artifact buildId.
+- Inputs: path params: `buildId`
+- Response format: file download
+- Access: No explicit access guard detected in the route handler; check surrounding router/mount middleware.
+- Side effects: Usually read-only.
+- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations. API consumers should expect JSON unless the response format says otherwise.
 
 ### POST /plugins/lumi_transcription/api/pair
 

knowledge/plugins/now-playing.md

@@ -0,0 +1,143 @@
+---
+id: plugin.now_playing
+title: Song Overlay
+scope: plugins
+status: active
+priority: 10
+visibility: user
+category: Plugin
+tags: plugin, now_playing
+generated: true
+editable: false
+---
+# Song Overlay
+Provider-neutral song state, chat announcements, and a customizable Lumi Overlay source.
+## Metadata
+Plugin ID: now_playing
+Version: 0.1.2
+Default state: enabled
+## Web Routes
+- /plugins/now_playing
+- GET /plugins/now_playing
+- POST /plugins/now_playing/settings
+- POST /plugins/now_playing/overlay/install
+- POST /plugins/now_playing/overlay/remove
+- POST /plugins/now_playing/test-announcement
+- GET /plugins/now_playing/api/companion/ping
+- POST /plugins/now_playing/api/companion/state
+- GET /plugins/now_playing/render/:token
+- GET /plugins/now_playing/render/:token/state
+- GET /plugins/now_playing/render/:token/events
+- GET /plugins/now_playing/render/:token/cover/:hash
+## Route Reference
+### MOUNT /plugins/now_playing
+
+- Purpose: Mounts the plugin router at this base WebUI path.
+- Inputs: No request parameters detected by static analysis.
+- Response format: Plugin router mount point.
+- Access: Access is controlled by the mount options and individual plugin routes.
+- Side effects: No direct route action; child routes handle requests.
+- Limits/notes: Mount metadata is inferred from static source scanning.
+
+### GET /plugins/now_playing
+
+- Purpose: Renders or serves the now_playing plugin page.
+- Inputs: No request parameters detected by static analysis.
+- Response format: HTML page rendered from an EJS view
+- Access: No explicit access guard detected in the route handler; check surrounding router/mount middleware.
+- Side effects: Usually read-only.
+- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations.
+
+### POST /plugins/now_playing/settings
+
+- Purpose: Processes the now_playing plugin action for settings.
+- Inputs: body: full submitted body is passed to a helper; exact fields are defined by the matching form/service
+- Response format: HTTP redirect after handling the request
+- Access: No explicit access guard detected in the route handler; check surrounding router/mount middleware.
+- Side effects: writes or mutates server-side state
+- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations. Errors are caught and usually returned as a flash message, JSON error, or error page. Most non-API POST routes are browser form submissions and usually redirect after completion.
+
+### POST /plugins/now_playing/overlay/install
+
+- Purpose: Processes the now_playing plugin action for overlay install.
+- Inputs: body: `scene_id`
+- Response format: HTTP redirect after handling the request
+- Access: No explicit access guard detected in the route handler; check surrounding router/mount middleware.
+- Side effects: writes or mutates server-side state
+- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations. Errors are caught and usually returned as a flash message, JSON error, or error page. Most non-API POST routes are browser form submissions and usually redirect after completion.
+
+### POST /plugins/now_playing/overlay/remove
+
+- Purpose: Processes the now_playing plugin action for overlay remove.
+- Inputs: No request parameters detected by static analysis.
+- Response format: HTTP redirect after handling the request
+- Access: No explicit access guard detected in the route handler; check surrounding router/mount middleware.
+- Side effects: writes or mutates server-side state
+- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations. Errors are caught and usually returned as a flash message, JSON error, or error page. Most non-API POST routes are browser form submissions and usually redirect after completion.
+
+### POST /plugins/now_playing/test-announcement
+
+- Purpose: Processes the now_playing plugin action for test announcement.
+- Inputs: No request parameters detected by static analysis.
+- Response format: HTTP redirect after handling the request
+- Access: logged-in session required or used
+- Side effects: Action route; side effects were not detected statically.
+- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations. Errors are caught and usually returned as a flash message, JSON error, or error page. Most non-API POST routes are browser form submissions and usually redirect after completion.
+
+### GET /plugins/now_playing/api/companion/ping
+
+- Purpose: Renders or serves the now_playing plugin page for api companion ping.
+- Inputs: No request parameters detected by static analysis.
+- Response format: JSON response
+- Access: No explicit access guard detected in the route handler; check surrounding router/mount middleware.
+- Side effects: Usually read-only.
+- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations. API consumers should expect JSON unless the response format says otherwise.
+
+### POST /plugins/now_playing/api/companion/state
+
+- Purpose: Processes the now_playing plugin action for api companion state.
+- Inputs: body: full submitted body is passed to a helper; exact fields are defined by the matching form/service
+- Response format: JSON response
+- Access: No explicit access guard detected in the route handler; check surrounding router/mount middleware.
+- Side effects: writes or mutates server-side state
+- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations. Errors are caught and usually returned as a flash message, JSON error, or error page. Most non-API POST routes are browser form submissions and usually redirect after completion. API consumers should expect JSON unless the response format says otherwise.
+
+### GET /plugins/now_playing/render/:token
+
+- Purpose: Renders or serves the now_playing plugin page for render token.
+- Inputs: path params: `token`
+- Response format: HTML page rendered from an EJS view
+- Access: No explicit access guard detected in the route handler; check surrounding router/mount middleware.
+- Side effects: Usually read-only.
+- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations.
+
+### GET /plugins/now_playing/render/:token/state
+
+- Purpose: Renders or serves the now_playing plugin page for render token state.
+- Inputs: path params: `token`
+- Response format: JSON response
+- Access: No explicit access guard detected in the route handler; check surrounding router/mount middleware.
+- Side effects: Usually read-only.
+- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations.
+
+### GET /plugins/now_playing/render/:token/events
+
+- Purpose: Renders or serves the now_playing plugin page for render token events.
+- Inputs: path params: `token`
+- Response format: streaming event response
+- Access: No explicit access guard detected in the route handler; check surrounding router/mount middleware.
+- Side effects: writes or mutates server-side state
+- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations.
+
+### GET /plugins/now_playing/render/:token/cover/:hash
+
+- Purpose: Renders or serves the now_playing plugin page for render token cover hash.
+- Inputs: path params: `hash`, `token`
+- Response format: static file response
+- Access: No explicit access guard detected in the route handler; check surrounding router/mount middleware.
+- Side effects: Usually read-only.
+- Limits/notes: Generated from static route source analysis; confirm exact behavior in the handler before changing integrations.
+## Commands
+- No plugin command triggers detected.
+## Source
+Plugin folder: plugins/now_playing

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "lumi-bot",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "lumi-bot",
-      "version": "0.2.25",
+      "version": "0.2.27",
       "dependencies": {
         "adm-zip": "^0.6.0",
         "better-sqlite3": "^11.5.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumi-bot",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "private": true,
   "type": "commonjs",
   "scripts": {
@@ -22,7 +22,8 @@
     "verify:webui": "node scripts/verify-webui.js && node scripts/verify-destructive-actions.js",
     "benchmark:okf": "node scripts/benchmark-okf-search.js",
     "verify:content": "node scripts/verify-content-library.js",
-    "verify:transcription": "node plugins/lumi_transcription/tests/verify.js"
+    "verify:transcription": "node plugins/lumi_transcription/tests/verify.js",
+    "verify:dev-updates": "node scripts/verify-local-development-updates.js"
   },
   "engines": {
     "node": ">=18"

plugins/lumi_transcription/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Lumi Transcription changelog
+
+## 0.1.0
+
+- Added server-hosted whisper.cpp transcription with bounded Companion audio transport and no local speech inference.
+- Added paired-device authentication, localhost-only development packages, revocation, diagnostics, model management, and recoverable worker supervision.
+- Added voice-free full-path readiness checks and dedicated accuracy, confidence, latency, and live audio-level testing.
+- Added a durable per-user Companion installer, managed OBS integration, user-approved updates, and preserved device identity.

plugins/lumi_transcription/backend/companion/device_store.js

@@ -109,7 +109,9 @@ function digest(value) { return crypto.createHash("sha256").update(String(value
 function safeEqual(left, right) { const a = Buffer.from(String(left)); const b = Buffer.from(String(right)); return a.length === b.length && crypto.timingSafeEqual(a, b); }
 function tokenValue(buffer) { return Buffer.from(buffer).toString("base64url"); }
 function normalizeHost(value) { const url = new URL(String(value)); if (url.protocol !== "https:" && !isLoopbackHttpOrigin(url)) throw new Error("Lumi Companion requires HTTPS. HTTP is allowed only when the pairing URL explicitly uses localhost or a loopback address."); return url.origin; }
-function isLoopbackHttpOrigin(value) { try { const url = value instanceof URL ? value : new URL(String(value)); return url.protocol === "http:" && ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname); } catch { return false; } }
+function isLoopbackOrigin(value) { try { const url = value instanceof URL ? value : new URL(String(value)); return ["http:", "https:"].includes(url.protocol) && ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname); } catch { return false; } }
+function isLoopbackHttpOrigin(value) { try { const url = value instanceof URL ? value : new URL(String(value)); return url.protocol === "http:" && isLoopbackOrigin(url); } catch { return false; } }
+function sameLocalhostOrigin(left, right) { try { const a = new URL(String(left)); const b = new URL(String(right)); return isLoopbackOrigin(a) && isLoopbackOrigin(b) && a.origin === b.origin; } catch { return false; } }
 function sameLoopbackOrigin(left, right) { try { const a = new URL(String(left)); const b = new URL(String(right)); return isLoopbackHttpOrigin(a) && isLoopbackHttpOrigin(b) && a.origin === b.origin; } catch { return false; } }
 function insecureDeviceAllowed(device, requestOrigin, remoteAddress) { return ["127.0.0.1", "::1", "::ffff:127.0.0.1"].includes(String(remoteAddress || "")) && sameLoopbackOrigin(device?.pairing_host, requestOrigin); }
 function ensureColumn(db, table, column, type) { if (!db.prepare(`PRAGMA table_info(${table})`).all().some((entry) => entry.name === column)) db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`); }
@@ -118,4 +120,4 @@ function parseArray(value) { try { const parsed = JSON.parse(value); return Arra
 function safeMetadata(device) { return { companion_version: clean(device.companion_version, 32), obs_version: clean(device.obs_version, 32), os: clean(device.os, 120), architecture: clean(device.architecture, 32), hardware: clean(device.hardware, 500) }; }
 function serialize(row, capabilities) { return { id: row.id, install_id: row.install_id, name: row.name, lumi_user_id: row.lumi_user_id, capabilities, metadata: JSON.parse(row.metadata_json || "{}"), first_connected_at: row.first_connected_at, last_connected_at: row.last_connected_at, revoked_at: row.revoked_at, pairing_host: row.pairing_host || null }; }
 
-module.exports = { DeviceStore, DEFAULT_CAPABILITIES, digest, normalizeHost, isLoopbackHttpOrigin, sameLoopbackOrigin, insecureDeviceAllowed };
+module.exports = { DeviceStore, DEFAULT_CAPABILITIES, digest, normalizeHost, isLoopbackOrigin, isLoopbackHttpOrigin, sameLocalhostOrigin, sameLoopbackOrigin, insecureDeviceAllowed };

plugins/lumi_transcription/backend/companion/gateway.js

@@ -2,6 +2,10 @@ const { WebSocketServer, WebSocket } = require("ws");
 const { MAX_JSON_BYTES, MAX_AUDIO_PAYLOAD_BYTES, AUDIO_HEADER_BYTES, parseEnvelope, validateHello, parseAudioFrame, envelope } = require("./protocol");
 const { insecureDeviceAllowed } = require("./device_store");
 
+const MAX_CONTROL_MESSAGES_PER_SECOND = 120;
+const MAX_AUDIO_MESSAGES_PER_SECOND = 200;
+const MAX_SOURCE_MESSAGES_PER_SECOND = 1000;
+
 class CompanionGateway {
   constructor(options) {
     this.devices = options.devices;
@@ -27,7 +31,12 @@ class CompanionGateway {
     let helloComplete = false;
     let lastPong = Date.now();
     let windowStarted = Date.now();
-    let messagesInWindow = 0;
+    let controlMessagesInWindow = 0;
+    let audioMessagesInWindow = 0;
+    let sourceMessagesInWindow = 0;
+    let audioMessagesDropped = 0;
+    let sourceMessagesDropped = 0;
+    const sourceStates = new Map();
     let messageChain = Promise.resolve();
     const send = (type, payload, sessionId = session?.id || null) => {
       if (socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify(envelope(type, payload, sessionId)));
@@ -42,16 +51,34 @@ class CompanionGateway {
       const body = Buffer.from(data);
       messageChain = messageChain.then(async () => {
       try {
-        if (Date.now() - windowStarted >= 1000) { windowStarted = Date.now(); messagesInWindow = 0; }
-        messagesInWindow += 1;
-        if (messagesInWindow > 300) throw coded("RATE_LIMIT", "Companion message rate exceeded its limit.");
+        if (Date.now() - windowStarted >= 1000) {
+          if (audioMessagesDropped) this.log.append({ kind: "audio_rate_limited", device_id: device.id, session_id: session?.id, dropped_frames: audioMessagesDropped });
+          if (sourceMessagesDropped) this.log.append({ kind: "source_rate_limited", device_id: device.id, session_id: session?.id, dropped_updates: sourceMessagesDropped });
+          windowStarted = Date.now(); controlMessagesInWindow = 0; audioMessagesInWindow = 0; sourceMessagesInWindow = 0; audioMessagesDropped = 0; sourceMessagesDropped = 0;
+        }
         if (isBinary) {
           if (!helloComplete || !session) throw coded("HELLO_REQUIRED", "Complete the handshake before sending audio.");
+          audioMessagesInWindow += 1;
+          if (audioMessagesInWindow > MAX_AUDIO_MESSAGES_PER_SECOND) { audioMessagesDropped += 1; return; }
           const result = await this.sessions.audio(session.id, parseAudioFrame(body));
           if (result.gap) send("metric", { kind: "sequence_gap", missing_frames: result.gap });
           return;
         }
         const message = parseEnvelope(body);
+        if (helloComplete && message.type === "source_update") {
+          const sourceId = String(message.payload?.source_uuid || "");
+          const signature = JSON.stringify(message.payload || {});
+          if (sourceId && sourceStates.get(sourceId) === signature) return;
+          if (sourceId) {
+            sourceStates.set(sourceId, signature);
+            if (sourceStates.size > 2048) sourceStates.delete(sourceStates.keys().next().value);
+          }
+          sourceMessagesInWindow += 1;
+          if (sourceMessagesInWindow > MAX_SOURCE_MESSAGES_PER_SECOND) { sourceMessagesDropped += 1; return; }
+        } else {
+          controlMessagesInWindow += 1;
+          if (controlMessagesInWindow > MAX_CONTROL_MESSAGES_PER_SECOND) throw coded("RATE_LIMIT", "Companion control message rate exceeded its limit.");
+        }
         if (!helloComplete) {
           const hello = validateHello(message);
           this.devices.updateRuntime(device.id, { companion_version: hello.companion_version, companion_plugin_version: hello.plugin_version });
@@ -121,4 +148,4 @@ function sameHostOrigin(origin, host) { try { return new URL(origin).host === ho
 function coded(code, message) { return Object.assign(new Error(message), { code }); }
 function cleanReason(value) { return ["requested", "test_complete", "benchmark_complete", "silence_timeout", "disconnect"].includes(String(value)) ? String(value) : "requested"; }
 
-module.exports = { CompanionGateway, sameHostOrigin };
+module.exports = { CompanionGateway, sameHostOrigin, MAX_CONTROL_MESSAGES_PER_SECOND, MAX_AUDIO_MESSAGES_PER_SECOND, MAX_SOURCE_MESSAGES_PER_SECOND };

plugins/lumi_transcription/backend/companion/package_service.js

@@ -54,19 +54,45 @@ class CompanionPackageService {
     }
     const pairingName = `lumi-companion-${pairing.pairing_id}.lumi-pairing.json`;
     output.addFile(pairingName, Buffer.from(`${JSON.stringify(pairing.bootstrap, null, 2)}\n`, "utf8"));
+    output.addFile("HOST-OPERATOR-NOTICE.txt", Buffer.from(hostOperatorNotice(pairing.bootstrap), "utf8"));
+    const host = safeNoticeValue(pairing.bootstrap?.host, "the Lumi host identified by the pairing package", 500);
     output.addFile("START-HERE.txt", Buffer.from([
-      "Lumi Companion — experimental transcription MVP", "",
-      "1. Extract both files in this ZIP to a temporary folder on the Windows streaming computer.",
-      `2. Start ${installer?.filename || entry.entrypoint} within 15 minutes.`,
-      "3. Setup installs Companion in your Windows account, imports the adjacent one-time pairing package, and launches the durable installed copy.",
-      "4. After setup completes, this extracted folder can be deleted. Use the Start menu to open Lumi Companion.", "",
+      "Lumi Companion", "",
+      "1. Extract all files in this ZIP to a temporary folder on the Windows streaming computer.",
+      "2. Read HOST-OPERATOR-NOTICE.txt. The installer will also display the paired host and legal notices.",
+      `3. Start ${installer?.filename || entry.entrypoint} within 15 minutes.`,
+      "4. Setup installs Companion in your Windows account, imports the adjacent one-time pairing package, and launches the durable installed copy.",
+      "5. After setup completes, this extracted folder can be deleted. Use the Start menu to open Lumi Companion.", "",
+      `Paired Lumi host: ${host}`,
       "Do not share this ZIP. Its pairing package works once and expires after 15 minutes.",
-      "Windows may warn because this experimental build is not code-signed yet.", ""
+      "Windows may warn because this release is not code-signed yet.", ""
     ].join("\r\n"), "utf8"));
     return { buffer: output.toBuffer(), filename: `Lumi-Companion-${manifest.version}-paired.zip`, pairingName };
   }
 }
 
+
+function safeNoticeValue(value, fallback, maxLength = 300) {
+  const clean = String(value || "").replace(/[\r\n\0]/g, " ").trim().slice(0, maxLength);
+  return clean || fallback;
+}
+
+function hostOperatorNotice(bootstrap = {}) {
+  const host = safeNoticeValue(bootstrap.host, "Not identified", 500);
+  const operatorName = safeNoticeValue(bootstrap.operator_name, "Not supplied by this host", 200);
+  const operatorContact = safeNoticeValue(bootstrap.operator_contact, `Use the Lumi WebUI or administrator at ${host}`, 300);
+  const privacyUrl = safeNoticeValue(bootstrap.privacy_url, "Not supplied by this host", 500);
+  return [
+    "LUMI COMPANION — HOST OPERATOR NOTICE", "",
+    `Paired Lumi host: ${host}`,
+    `Operator name: ${operatorName}`,
+    `Operator contact: ${operatorContact}`,
+    `Privacy information: ${privacyUrl}`, "",
+    "This package connects Companion to the Lumi installation at the host shown above. The person or organisation controlling that installation is responsible for its Hosted Service, including server configuration, user access, server-side processing, retention, integrations, notices, and compliance obligations.", "",
+    "OokamiKunTV is the developer of Lumi Companion and is not automatically the operator of an independently hosted Lumi installation. Responsibility follows the actual facts and applicable law. The host URL is a technical identifier and may not by itself identify the operator's legal name.", ""
+  ].join("\r\n");
+}
+
 function safeArchivePath(value) {
   const portable = String(value || "").replace(/\\/g, "/");
   const normalized = path.posix.normalize(portable).replace(/^\/+/, "");

plugins/lumi_transcription/backend/models/artifact_manager.js

@@ -47,8 +47,7 @@ class ArtifactManager {
     }
     zip.extractAllTo(staged, true);
     for (const expected of entry.expected_paths || []) if (!findBasename(staged, expected)) throw new Error(`Runtime is missing ${expected}.`);
-    fs.rmSync(target, { recursive: true, force: true });
-    fs.renameSync(staged, target);
+    replaceDirectory(staged, target);
     return { installed: true, path: target, backend: entry.backend, version: entry.id };
   }
 }
@@ -56,5 +55,36 @@ class ArtifactManager {
 function validateManifestEntry(entry) { if (!entry?.id || !/^https:\/\//.test(entry.url || "") || !/^[a-f0-9]{64}$/.test(entry.sha256 || "")) throw new Error("Artifact manifest entry is invalid."); }
 function sha256File(target) { const hash = crypto.createHash("sha256"); const fd = fs.openSync(target, "r"); const buffer = Buffer.alloc(1024 * 1024); try { let read; while ((read = fs.readSync(fd, buffer, 0, buffer.length, null)) > 0) hash.update(buffer.subarray(0, read)); } finally { fs.closeSync(fd); } return hash.digest("hex"); }
 function findBasename(root, basename) { const pending = [root]; while (pending.length) { const current = pending.pop(); for (const entry of fs.readdirSync(current, { withFileTypes: true })) { const target = path.join(current, entry.name); if (entry.isDirectory()) pending.push(target); else if (entry.name === basename) return target; } } return null; }
+function replaceDirectory(staged, target) {
+  const backup = `${target}.${process.pid}.backup`;
+  fs.rmSync(backup, { recursive: true, force: true });
+  const hadTarget = fs.existsSync(target);
+  let backupDisposable = false;
+  try {
+    if (hadTarget) moveDirectory(target, backup);
+    moveDirectory(staged, target);
+    backupDisposable = true;
+    fs.rmSync(backup, { recursive: true, force: true });
+  } catch (error) {
+    fs.rmSync(target, { recursive: true, force: true });
+    if (hadTarget && fs.existsSync(backup)) {
+      moveDirectory(backup, target);
+      backupDisposable = true;
+    } else if (!hadTarget) backupDisposable = true;
+    throw error;
+  } finally {
+    fs.rmSync(staged, { recursive: true, force: true });
+    if (backupDisposable) fs.rmSync(backup, { recursive: true, force: true });
+  }
+}
+function moveDirectory(source, target) {
+  try { fs.renameSync(source, target); }
+  catch (error) {
+    if (!["EPERM", "EACCES", "EXDEV"].includes(error.code)) throw error;
+    fs.mkdirSync(target, { recursive: true });
+    fs.cpSync(source, target, { recursive: true, force: true });
+    fs.rmSync(source, { recursive: true, force: true });
+  }
+}
 
 module.exports = { ArtifactManager, sha256File, validateManifestEntry };

plugins/lumi_transcription/backend/paths.js

@@ -4,15 +4,33 @@ const ROOT = path.resolve(__dirname, "..");
 const DATA = path.join(ROOT, "data");
 function ensureDataDirs() { for (const name of ["logs", "models", "runtime", "tmp"]) fs.mkdirSync(path.join(DATA, name), { recursive: true }); }
 function dataPath(...parts) { const target = path.resolve(DATA, ...parts); if (target !== DATA && !target.startsWith(`${DATA}${path.sep}`)) throw new Error("Path escapes transcription plugin data."); return target; }
+function activeWorkerExecutable() {
+  try {
+    const requested = fs.readFileSync(dataPath("runtime", "active-worker.txt"), "utf8").trim();
+    const target = path.resolve(requested);
+    const runtimeRoot = dataPath("runtime");
+    return target.startsWith(`${runtimeRoot}${path.sep}`) && fs.statSync(target).isFile() ? target : "";
+  } catch { return ""; }
+}
+function setActiveWorkerExecutable(target) {
+  const executable = path.resolve(String(target || ""));
+  const runtimeRoot = dataPath("runtime");
+  if (!executable.startsWith(`${runtimeRoot}${path.sep}`) || !fs.existsSync(executable) || !fs.statSync(executable).isFile())
+    throw new Error("Active transcription worker must be an installed runtime file.");
+  fs.writeFileSync(dataPath("runtime", "active-worker.txt"), `${executable}\n`, { encoding: "utf8", mode: 0o600 });
+}
 function resolveWorkerExecutable(override = "") {
   const requested = String(override || "").trim();
   if (requested) return fs.existsSync(requested) ? path.resolve(requested) : requested;
   const executable = process.platform === "win32" ? "lumi-whisper-worker.exe" : "lumi-whisper-worker";
   const candidates = [
+    activeWorkerExecutable(),
+    dataPath("runtime", process.platform === "win32" ? "windows-x64-cuda-12.4" : `${process.platform}-${process.arch}-cuda`, "bin", executable),
     dataPath("runtime", "worker", process.platform === "win32" ? "windows-x64-cuda" : `${process.platform}-${process.arch}-cuda`, "bin", executable),
+    dataPath("runtime", process.platform === "win32" ? "windows-x64-cpu" : `${process.platform}-${process.arch}`, "bin", executable),
     dataPath("runtime", "worker", process.platform === "win32" ? "windows-x64-cpu" : `${process.platform}-${process.arch}`, "bin", executable),
     path.join(ROOT, "backend", "transcription", "worker-native", "build", executable)
   ];
   return candidates.find((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile()) || "";
 }
-module.exports = { ROOT, DATA, ensureDataDirs, dataPath, resolveWorkerExecutable };
+module.exports = { ROOT, DATA, ensureDataDirs, dataPath, resolveWorkerExecutable, setActiveWorkerExecutable };

plugins/lumi_transcription/backend/sessions/session_coordinator.js

@@ -115,8 +115,8 @@ class SessionCoordinator {
     const session = this.require(sessionId);
     clearTimeout(session.graceTimer);
     session.graceTimer = null;
-    await session.delivery.stop();
     if (session.providerActive) await this.provider.stopSession(session.id);
+    await session.delivery.stop();
     if (session.benchmarkId && this.benchmarks) {
       const benchmarkStatus = reason === "silence_timeout" ? "silence_timeout" : reason === "provider_failed" ? "failed" : reason === "disconnect" || reason === "plugin_shutdown" ? "aborted" : "completed";
       const result = this.benchmarks.finish(session.id, benchmarkStatus);
@@ -196,10 +196,12 @@ class SessionCoordinator {
     const session = this.sessions.get(raw.session_id);
     const track = session?.tracks.get(raw.track_id || raw.source_uuid);
     if (!session || !track || session.state !== "running") return;
+    const hypothesisText = cleanAnalysisText(raw.text);
+    if (!hypothesisText) return;
     track.lastSpeechAt = this.now();
     const primary = Array.from(session.tracks.values()).find((candidate) => candidate.primary);
     if (primary && track !== primary && this.now() - primary.lastSpeechAt < 800) return;
-    const stable = this.stabilizer.update(track.source_uuid, raw.text, { final: raw.final, newUtterance: raw.new_utterance, trailingIncomplete: raw.incomplete_word });
+    const stable = this.stabilizer.update(track.source_uuid, hypothesisText, { final: raw.final, newUtterance: raw.new_utterance, trailingIncomplete: raw.incomplete_word });
     const event = {
       session_id: session.id, source_uuid: track.source_uuid,
       speaker_label: speakerLabel(session, track), ...stable,
@@ -207,7 +209,13 @@ class SessionCoordinator {
       latency: { capture_ms: raw.capture_ms || 0, network_ms: raw.network_ms || 0, queue_ms: raw.queue_ms || 0, inference_ms: raw.inference_ms || 0, stabilization_ms: stable.stabilization_ms, total_ms: raw.total_ms || 0 },
       model: { id: raw.model_id || "unknown", provider: "whisper.cpp", backend: raw.backend || "unknown" }
     };
-    event.analysis = { transcript: String(raw.text || "").slice(0, 8000), words: Array.isArray(raw.words) ? raw.words.slice(0, 500) : [], emitted_at_ms: raw.emitted_at_ms || this.now() };
+    event.analysis = {
+      transcript: hypothesisText.slice(0, 8000),
+      words: Array.isArray(raw.words) ? raw.words.slice(0, 500)
+        .map((word) => ({ ...word, text: cleanAnalysisText(word?.text) }))
+        .filter((word) => word.text) : [],
+      emitted_at_ms: raw.emitted_at_ms || this.now()
+    };
     if (session.mode === "benchmark") this.benchmarks?.record(session.id, event);
     const result = await session.delivery.deliver(event);
     this.log.append({ kind: "caption", session_id: session.id, source_uuid: track.source_uuid, caption_text: session.mode === "benchmark" ? undefined : event.stable_text, uncertain_text: session.mode === "benchmark" ? undefined : event.uncertain_text, revision: event.revision, final: event.final, delivery: result.disposition, latency: event.latency, model: event.model, benchmark_id: session.benchmarkId });
@@ -241,6 +249,9 @@ class SessionCoordinator {
 function speakerLabel(session, track) { const enabled = Array.from(session.tracks.values()).filter((candidate) => candidate.enabled); return enabled.length === 1 && track.single_speaker ? null : track.speaker_label || track.display_name; }
 function serializeTrack(track) { return { source_uuid: track.source_uuid, display_name: track.display_name, speaker_label: track.speaker_label, enabled: track.enabled, primary: track.primary, single_speaker: track.single_speaker, delivery_enabled: track.delivery_enabled, program_active: track.program_active, source_missing: track.source_missing, last_activity_at: track.last_activity_at, sequence: track.sequence?.metrics?.() }; }
 function text(value, max) { return String(value || "").trim().slice(0, max); }
+function cleanAnalysisText(value) {
+  return String(value || "").replace(/\[_(?:BEG_|TT_\d+)\]/gi, "").replace(/\[BLANK_AUDIO\]/gi, "").trim();
+}
 function isUuid(value) { return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(String(value || "")); }
 function pathTestCaption(session, track, health, now) {
   return {

plugins/lumi_transcription/backend/tests/benchmark_store.js

@@ -110,7 +110,8 @@ class BenchmarkStore {
     const selected = Array.from(captions.values()).sort((a, b) => a.received_at - b.received_at);
     const words = [];
     for (const revision of selected) {
-      for (const word of parseWords(revision.words_json)) words.push({ ...word, confidence: revision.final ? word.confidence : null, final: Boolean(revision.final) });
+      const history = revisions.filter((candidate) => candidate.caption_id === revision.caption_id);
+      for (const word of mergeRevisionWords(revision, history)) words.push({ ...word, confidence: revision.final ? word.confidence : null, final: Boolean(revision.final) });
     }
     const latency = metricStats(words.map((word) => word.latency_ms));
     const confidence = metricStats(words.map((word) => word.confidence).filter(Number.isFinite));
@@ -119,7 +120,7 @@ class BenchmarkStore {
       source_uuid: row.source_uuid, source_name: row.source_name, started_at: row.started_at,
       ended_at: row.ended_at, duration_ms: Math.max(0, (row.ended_at || this.now()) - row.started_at),
       status: row.status, model_id: row.model_id, backend: row.backend,
-      transcript: selected.map((revision) => revision.text).filter(Boolean).join(" "), words,
+      transcript: selected.map((revision) => cleanTranscript(revision.text)).filter(Boolean).join(" "), words,
       stats: { latency, confidence }, revisions: revisions.length
     };
   }
@@ -136,13 +137,42 @@ class BenchmarkStore {
 
 function safeWord(word) {
   return {
-    text: String(word?.text || "").slice(0, 120),
+    text: cleanWordText(word?.text).slice(0, 120),
     latency_ms: finite(word?.latency_ms), confidence: clamp(word?.confidence, 0, 1),
     audio_start_ms: finite(word?.audio_start_ms), audio_end_ms: finite(word?.audio_end_ms),
     captured_at_ms: finite(word?.captured_at_ms)
   };
 }
 function parseWords(value) { try { const parsed = JSON.parse(value); return Array.isArray(parsed) ? parsed.map(safeWord).filter((word) => word.text) : []; } catch { return []; } }
+function mergeRevisionWords(selected, revisions) {
+  const words = withOccurrences(parseWords(selected.words_json));
+  const candidates = revisions.flatMap((revision) => withOccurrences(parseWords(revision.words_json)));
+  return words.map((word) => {
+    const matches = candidates.filter((candidate) => candidate.key === word.key && candidate.occurrence === word.occurrence &&
+      Math.abs(candidate.captured_at_ms - word.captured_at_ms) <= 1500);
+    const { key: _key, occurrence: _occurrence, ...plain } = word;
+    return matches.length ? { ...plain, latency_ms: Math.min(...matches.map((candidate) => candidate.latency_ms)) } : plain;
+  });
+}
+function withOccurrences(words) {
+  const seen = new Map();
+  return words.map((word) => {
+    const key = comparableWord(word.text);
+    const occurrence = seen.get(key) || 0;
+    seen.set(key, occurrence + 1);
+    return { ...word, key, occurrence };
+  });
+}
+function cleanWordText(value) {
+  return String(value || "")
+    .replace(/\[_(?:BEG_|TT_\d+)\]/gi, "")
+    .replace(/\[BLANK_AUDIO\]/gi, "")
+    .trim();
+}
+function cleanTranscript(value) {
+  return cleanWordText(value).replace(/\s+/g, " ").trim();
+}
+function comparableWord(value) { return cleanWordText(value).toLocaleLowerCase().replace(/[^\p{L}\p{N}]+/gu, ""); }
 function finite(value) { const number = Number(value); return Number.isFinite(number) ? Math.max(0, number) : 0; }
 function clamp(value, min, max) { return Math.min(max, Math.max(min, finite(value))); }
 function metricStats(input) {

plugins/lumi_transcription/backend/transcription/provider.js

@@ -191,7 +191,7 @@ class WhisperCppServerProvider extends TranscriptionProvider {
   async stopSession(sessionId) {
     this.sessions.delete(sessionId);
     const stopped = new Promise((resolve) => {
-      const timer = setTimeout(() => { cleanup(); resolve(false); }, 5000);
+      const timer = setTimeout(() => { cleanup(); resolve(false); }, 15000);
       const onStopped = (event) => { if (event.session_id !== sessionId) return; cleanup(); resolve(true); };
       const cleanup = () => { clearTimeout(timer); this.off("session_stopped", onStopped); };
       this.on("session_stopped", onStopped);

plugins/lumi_transcription/backend/transcription/worker-native/CMakeLists.txt

@@ -9,6 +9,18 @@ set(WHISPER_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
 set(WHISPER_BUILD_TESTS OFF CACHE BOOL "" FORCE)
 set(WHISPER_BUILD_SERVER OFF CACHE BOOL "" FORCE)
 set(GGML_CUDA ${LUMI_WHISPER_CUDA} CACHE BOOL "" FORCE)
+# Build a portable AVX2 host path instead of inheriting the build machine's
+# AVX-512 features. The GPU package must run on ordinary RTX 3060-era hosts.
+set(GGML_NATIVE OFF CACHE BOOL "" FORCE)
+set(GGML_AVX ON CACHE BOOL "" FORCE)
+set(GGML_AVX2 ON CACHE BOOL "" FORCE)
+set(GGML_AVX512 OFF CACHE BOOL "" FORCE)
+if(LUMI_WHISPER_CUDA)
+  # The RTX 3060 production baseline and RTX 3080 Ti development host are
+  # both Ampere (SM 8.6). Include PTX for forward compatibility as well.
+  set(LUMI_CUDA_ARCHITECTURES "86-real;86-virtual" CACHE STRING "CUDA architectures included in the portable worker")
+  set(CMAKE_CUDA_ARCHITECTURES "${LUMI_CUDA_ARCHITECTURES}" CACHE STRING "" FORCE)
+endif()
 
 FetchContent_Declare(
   whisper

plugins/lumi_transcription/backend/transcription/worker-native/src/main.cpp

@@ -23,7 +23,8 @@ using clock_type = std::chrono::steady_clock;
 
 namespace {
 constexpr std::size_t sample_rate = 16000;
-constexpr std::size_t max_samples = sample_rate * 6;
+constexpr std::size_t max_samples = sample_rate * 15;
+constexpr std::size_t preroll_samples = sample_rate * 2 / 5;
 constexpr std::size_t min_decode_samples = sample_rate / 2;
 constexpr auto decode_interval = std::chrono::milliseconds(600);
 constexpr std::uint64_t finalize_silence_us = 750000;
@@ -37,7 +38,7 @@ struct track_state {
     std::uint64_t audio_end_us = 0;
     std::uint64_t captured_at_ms = 0;
     std::uint64_t last_voice_us = 0;
-    std::uint64_t last_decode_us = 0;
+    clock_type::time_point last_decode_at{};
     bool voiced = false;
     bool new_utterance = true;
 };
@@ -138,6 +139,9 @@ transcription_result transcribe(const std::vector<float> & samples, double & inf
     parameters.single_segment = true;
     parameters.token_timestamps = true;
     parameters.split_on_word = true;
+    parameters.max_tokens = 96;
+    parameters.suppress_blank = true;
+    parameters.suppress_nst = true;
     parameters.language = "en";
     parameters.n_threads = std::max(1U, std::min(4U, std::thread::hardware_concurrency()));
     const auto started = clock_type::now();
@@ -152,13 +156,14 @@ transcription_result transcribe(const std::vector<float> & samples, double & inf
         for (int index = 0; index < tokens; ++index) {
             const char * value = whisper_full_get_token_text(context.get(), segment, index);
             if (!value || !*value) continue;
+            const auto data = whisper_full_get_token_data(context.get(), segment, index);
+            if (data.id >= whisper_token_eot(context.get())) continue;
             std::string raw(value);
             if (raw.starts_with("<|")) continue;
             const auto first = raw.find_first_not_of(" \t\r\n");
             if (first == std::string::npos) continue;
             const auto last = raw.find_last_not_of(" \t\r\n");
             const bool begins_word = first > 0 || output.words.empty();
-            const auto data = whisper_full_get_token_data(context.get(), segment, index);
             if (begins_word) output.words.push_back({});
             auto & word = output.words.back();
             word.text += raw.substr(first, last - first + 1);
@@ -203,13 +208,14 @@ void decode_track(const std::string & session_id, const std::string & track_id,
         });
         track.new_utterance = false;
     }
-    track.last_decode_us = track.audio_end_us;
+    track.last_decode_at = clock_type::now();
     if (final) {
         track.samples.clear();
         track.voiced = false;
         track.new_utterance = true;
         track.audio_start_us = 0;
         track.captured_at_ms = 0;
+        track.last_decode_at = {};
     }
 }
 
@@ -236,10 +242,20 @@ void audio(const json & packet, const std::vector<std::uint8_t> & pcm) {
     const auto duration_us = static_cast<std::uint64_t>(count * 1000000ULL / sample_rate);
     track.audio_end_us = captured_us + duration_us;
     const auto rms = std::sqrt(squares / static_cast<double>(std::max<std::size_t>(1, count)));
-    if (rms >= 0.012) { track.voiced = true; track.last_voice_us = track.audio_end_us; }
+    if (rms >= 0.012) {
+        track.voiced = true;
+        track.last_voice_us = track.audio_end_us;
+    } else if (!track.voiced && track.samples.size() > preroll_samples) {
+        const auto removed = track.samples.size() - preroll_samples;
+        track.samples.erase(track.samples.begin(), track.samples.begin() + static_cast<std::ptrdiff_t>(removed));
+        const auto removed_us = static_cast<std::uint64_t>(removed * 1000000ULL / sample_rate);
+        track.audio_start_us += removed_us;
+        track.captured_at_ms += removed_us / 1000ULL;
+    }
     const bool final = track.voiced && (track.samples.size() >= max_samples ||
         (track.audio_end_us > track.last_voice_us && track.audio_end_us - track.last_voice_us >= finalize_silence_us));
-    const bool decode_due = track.last_decode_us == 0 || track.audio_end_us - track.last_decode_us >= static_cast<std::uint64_t>(decode_interval.count()) * 1000ULL;
+    const auto now = clock_type::now();
+    const bool decode_due = track.last_decode_at == clock_type::time_point{} || now - track.last_decode_at >= decode_interval;
     if (final || (track.voiced && decode_due)) decode_track(session_id, track_id, track, final);
 }
 

plugins/lumi_transcription/companion_manifest.json

@@ -1,17 +1,17 @@
 {
   "schema_version": 1,
-  "version": "0.1.0-experimental.8",
+  "version": "0.1.0",
   "signed": false,
-  "release_notes": "Fixes OBS integration package discovery in the installed single-file app, validates the packaged payload directly, and displays actionable installation errors.",
+  "release_notes": "First stable Companion release with shared plugin authentication, server-hosted transcription, Song Overlay, matching Windows branding, and a steady non-flickering tray status.",
   "installer": {
     "id": "windows-x64-installer",
     "platform": "win32",
     "architecture": "x64",
     "label": "Windows x64 per-user installer",
     "filename": "Lumi.Companion-Setup.exe",
-    "url": "https://git.rolfsvaag.no/Rolfsvaag_Datateknikk/Lumi/releases/download/companion-v0.1.0-experimental.8/Lumi.Companion-Setup.exe",
-    "sha256": "075fb4dd9a84ab10655d75899a6b4944269c9fe6371573778740d80b16ca19d0",
-    "bytes": 32041200
+    "url": "https://git.rolfsvaag.no/Rolfsvaag_Datateknikk/Lumi/releases/download/companion-v0.1.0/Lumi.Companion-Setup.exe",
+    "sha256": "71ee091971a8e246d9b991a16fc28bd73495351c82b44839ae34ca36fb5784ff",
+    "bytes": 51849287
   },
   "artifacts": [
     {
@@ -20,9 +20,9 @@
       "architecture": "x64",
       "label": "Windows x64 self-contained",
       "filename": "Lumi.Companion-win-x64.zip",
-      "url": "https://git.rolfsvaag.no/Rolfsvaag_Datateknikk/Lumi/releases/download/companion-v0.1.0-experimental.8/Lumi.Companion-win-x64.zip",
-      "sha256": "46c58b044a213e328fa96fe86e48b9ea0b67e327439fed14fc485c711f03eb3e",
-      "bytes": 41757425,
+      "url": "https://git.rolfsvaag.no/Rolfsvaag_Datateknikk/Lumi/releases/download/companion-v0.1.0/Lumi.Companion-win-x64.zip",
+      "sha256": "1194475b2a6acdeb6ef9429726cb5de31a5c93f1dc53a3faa29bb54eaef0368a",
+      "bytes": 66731197,
       "entrypoint": "Lumi.Companion.App.exe"
     }
   ]

plugins/lumi_transcription/index.js

@@ -3,7 +3,7 @@ const ejs = require("ejs");
 const fs = require("fs");
 const path = require("path");
 const { DeviceStore } = require("./backend/companion/device_store");
-const { insecureDeviceAllowed } = require("./backend/companion/device_store");
+const { insecureDeviceAllowed, sameLocalhostOrigin } = require("./backend/companion/device_store");
 const { CompanionGateway } = require("./backend/companion/gateway");
 const { CompanionPackageService } = require("./backend/companion/package_service");
 const { RevisionStore } = require("./backend/config/revision_store");
@@ -13,7 +13,7 @@ const { ArtifactManager } = require("./backend/models/artifact_manager");
 const { SessionCoordinator } = require("./backend/sessions/session_coordinator");
 const { WhisperWorkerSupervisor, WhisperCppServerProvider } = require("./backend/transcription/provider");
 const { BenchmarkStore } = require("./backend/tests/benchmark_store");
-const { ensureDataDirs, dataPath, resolveWorkerExecutable } = require("./backend/paths");
+const { ensureDataDirs, dataPath, resolveWorkerExecutable, setActiveWorkerExecutable } = require("./backend/paths");
 const modelManifest = require("./models_manifest.json");
 const runtimeManifest = require("./runtime_manifest.json");
 const manifest = require("./plugin.json");
@@ -101,7 +101,7 @@ module.exports = {
       try {
         const host = requestHost(req);
         const pairing = devices.issuePairing({ userId: req.session.user.id, host });
-        const bootstrap = { format: "lumi-companion-bootstrap-v1", ...pairing, exchange_url: `${host}/plugins/${PLUGIN_ID}/api/pair` };
+        const bootstrap = { format: "lumi-companion-bootstrap-v1", ...pairing, exchange_url: `${host}/plugins/${PLUGIN_ID}/api/pair`, ...companionOperatorMetadata(host) };
         res.set("Cache-Control", "no-store");
         res.attachment(`lumi-companion-${pairing.pairing_id}.lumi-pairing.json`);
         res.send(`${JSON.stringify(bootstrap, null, 2)}\n`);
@@ -111,27 +111,109 @@ module.exports = {
       try {
         const host = requestHost(req);
         const pairing = devices.issuePairing({ userId: req.session.user.id, host });
-        const bootstrap = { format: "lumi-companion-bootstrap-v1", ...pairing, exchange_url: `${host}/plugins/${PLUGIN_ID}/api/pair` };
+        const bootstrap = { format: "lumi-companion-bootstrap-v1", ...pairing, exchange_url: `${host}/plugins/${PLUGIN_ID}/api/pair`, ...companionOperatorMetadata(host) };
         const bundle = await companionPackages.build({ ...pairing, bootstrap });
         res.set("Cache-Control", "no-store");
         res.attachment(bundle.filename);
         res.send(bundle.buffer);
       } catch (error) { res.status(503).json({ ok: false, error: error.message }); }
     });
-    router.get("/api/companion/update", requireDeviceAccess(devices), (req, res) => {
-      const updateManifest = companionPackages.currentManifest();
-      const entry = companionPackages.entry(updateManifest);
-      if (!entry) return res.status(503).json({ ok: false, error: "No Windows Companion update is configured." });
+    const companionUpdateHandler = async (req, res) => {
+      try {
+        const updateManifest = companionPackages.currentManifest();
+        const currentVersion = String(req.body?.current_version || req.query.current_version || "").slice(0, 40);
+        const developmentUpdates = global.lumiFrameworks?.developmentUpdates;
+        const localDevelopment = Boolean(
+          req.method === "POST" &&
+          developmentUpdates?.enabled?.() &&
+          global.lumiRuntime?.allowsLocalDevelopmentUpdates?.(req) &&
+          sameLocalhostOrigin(req.lumiDevice?.pairing_host, requestHost(req))
+        );
+        res.set("Cache-Control", "no-store");
+        if (localDevelopment) {
+          const comparison = developmentUpdates.compare({
+            build_checksum: req.body?.build_checksum || req.query.build_checksum,
+            component_checksums: req.body?.component_checksums || {}
+          });
+          let artifact = null;
+          let buildPending = false;
+          if (comparison.update_available) {
+            let built = developmentUpdates.readArtifact(comparison.aggregate_checksum);
+            if (!built && req.body?.supports_pending_build === true) {
+              buildPending = true;
+              developmentUpdates.buildCompanionArtifact(comparison).catch((error) => {
+                diagnosticLog.append({ kind: "companion_development_build", state: "failed", message: error.message });
+              });
+            } else if (!built) {
+              // Compatibility for the first development-update adoption. Older
+              // Companion builds do not understand build_pending and require a
+              // complete artifact response.
+              built = await developmentUpdates.buildCompanionArtifact(comparison);
+            }
+            if (built) {
+              artifact = {
+                url: `${requestHost(req)}/plugins/${PLUGIN_ID}/api/companion/dev-artifact/${built.build_id}`,
+                sha256: built.sha256,
+                bytes: built.bytes,
+                entrypoint: built.entrypoint
+              };
+            }
+          }
+          return res.json({
+            ok: true,
+            version: updateManifest.version,
+            current_version: currentVersion,
+            update_available: comparison.update_available,
+            development: true,
+            build_checksum: comparison.aggregate_checksum,
+            component_checksums: Object.fromEntries(comparison.updatable_components.map((item) => [item.id, item.checksum])),
+            changed_components: comparison.changed_components,
+            server_components: comparison.server_components,
+            artifact,
+            build_pending: buildPending,
+            retry_after_ms: buildPending ? 2000 : null,
+            signed: false,
+            release_notes: comparison.update_available
+              ? `Local development changes detected: ${comparison.changed_components.map((item) => item.id).join(", ") || "Companion source"}.`
+              : "The localhost Companion build matches the current Lumi source checksums."
+          });
+        }
+        const entry = companionPackages.entry(updateManifest);
+        if (!entry) return res.status(503).json({ ok: false, error: "No Windows Companion update is configured." });
+        return res.json({
+          ok: true,
+          version: updateManifest.version,
+          current_version: currentVersion,
+          update_available: compareVersions(updateManifest.version, currentVersion) > 0,
+          development: false,
+          build_checksum: null,
+          component_checksums: {},
+          changed_components: [],
+          server_components: [],
+          artifact: { url: entry.url, sha256: entry.sha256, bytes: entry.bytes, entrypoint: entry.entrypoint },
+          signed: updateManifest.signed === true,
+          release_notes: String(updateManifest.release_notes || "Companion reliability and integration improvements.").slice(0, 500)
+        });
+      } catch (error) {
+        diagnosticLog.append({ kind: "companion_update", state: "failed", message: error.message });
+        return res.status(503).json({ ok: false, error: error.message });
+      }
+    };
+    router.get("/api/companion/update", requireDeviceAccess(devices), companionUpdateHandler);
+    router.post("/api/companion/update", requireDeviceAccess(devices), companionUpdateHandler);
+    router.get("/api/companion/dev-artifact/:buildId", requireDeviceAccess(devices), (req, res) => {
+      const developmentUpdates = global.lumiFrameworks?.developmentUpdates;
+      const allowed = Boolean(
+        developmentUpdates?.enabled?.() &&
+        global.lumiRuntime?.allowsLocalDevelopmentUpdates?.(req) &&
+        sameLocalhostOrigin(req.lumiDevice?.pairing_host, requestHost(req))
+      );
+      if (!allowed) return res.status(404).json({ ok: false, error: "Local development artifacts are available only through the paired localhost origin." });
+      const artifact = developmentUpdates.readArtifact(req.params.buildId);
+      if (!artifact) return res.status(404).json({ ok: false, error: "The requested local development artifact is unavailable or stale." });
       res.set("Cache-Control", "no-store");
-      res.json({
-        ok: true,
-        version: updateManifest.version,
-        current_version: String(req.query.current_version || "").slice(0, 40),
-        update_available: compareVersions(updateManifest.version, req.query.current_version) > 0,
-        artifact: { url: entry.url, sha256: entry.sha256, bytes: entry.bytes, entrypoint: entry.entrypoint },
-        signed: updateManifest.signed === true,
-        release_notes: String(updateManifest.release_notes || "Companion reliability and integration improvements.").slice(0, 500)
-      });
+      res.set("X-Lumi-Development-Build", artifact.build_id);
+      res.download(artifact.path, "Lumi.Companion-win-x64.zip");
     });
     router.post("/api/pair", requirePairingTransport(devices), (req, res) => {
       try { res.set("Cache-Control", "no-store"); res.status(201).json({ ok: true, ...devices.exchange(req.body || {}) }); }
@@ -185,15 +267,43 @@ module.exports = {
       const entry = runtimeManifest.artifacts.find((candidate) => candidate.id === req.params.id);
       if (!entry) return res.status(404).json({ ok: false, error: "Runtime was not found." });
       try {
+        if ((await provider.health()).sessions > 0) return res.status(409).json({ ok: false, error: "End active transcription sessions before changing the inference runtime." });
         const filename = `${entry.id}.zip`;
         const archive = await runtimeArchives.download({ ...entry, filename }, { confirmed: req.body.confirmed === true });
-        res.status(201).json({ ok: true, status: runtimes.installZip(entry, archive.path) });
+        const selected = modelManifest.models.find((candidate) => candidate.id === revisions.list().selected_model_id?.value);
+        const selectedStatus = selected ? models.status(selected) : null;
+        const previousExecutable = supervisor.executable;
+        let activated;
+        try {
+          await provider.stop();
+          const installed = runtimes.installZip(entry, archive.path);
+          const executable = path.join(installed.path, "bin", process.platform === "win32" ? "lumi-whisper-worker.exe" : "lumi-whisper-worker");
+          if (!fs.existsSync(executable)) throw new Error("Installed runtime did not contain the Lumi transcription worker.");
+          supervisor.executable = executable;
+          activated = selected && selectedStatus?.valid
+            ? await provider.loadModel({ ...selected, path: selectedStatus.path })
+            : await provider.health();
+          setActiveWorkerExecutable(executable);
+          res.status(201).json({ ok: true, status: installed, activated });
+        } catch (activationError) {
+          await provider.stop().catch(() => {});
+          supervisor.executable = previousExecutable;
+          if (previousExecutable && selected && selectedStatus?.valid)
+            await provider.loadModel({ ...selected, path: selectedStatus.path }).catch(() => {});
+          throw activationError;
+        }
       } catch (error) { res.status(400).json({ ok: false, error: error.message }); }
     });
     router.get("/api/logs", requireAdmin, (_req, res) => res.json({ files: diagnosticLog.files().map(({ path: _path, ...entry }) => entry) }));
 
     web.mount(`/plugins/${PLUGIN_ID}`, router, { label: "Transcription", role: "admin", section: "plugins" });
     global.lumiFrameworks = global.lumiFrameworks || {};
+    const companionFramework = {
+      version: 1,
+      requireDevice: requireDeviceAccess(devices),
+      authenticate: (header, requiredCapability = null) => devices.authenticate(header, requiredCapability)
+    };
+    global.lumiFrameworks.companion = companionFramework;
     global.lumiFrameworks.transcription = {
       version: manifest.version,
       protocol_version: 1,
@@ -207,6 +317,7 @@ module.exports = {
       await gateway.close();
       await sessions.close();
       await provider.stop();
+      if (global.lumiFrameworks?.companion === companionFramework) delete global.lumiFrameworks.companion;
       if (global.lumiFrameworks?.transcription?.version === manifest.version) delete global.lumiFrameworks.transcription;
       logger?.info?.("Lumi transcription stopped", {}, { event: "transcription_stopped" });
     };
@@ -214,7 +325,24 @@ module.exports = {
 };
 
 function requireAdmin(req, res, next) { if (req.session?.user?.isAdmin) return next(); return res.status(403).json({ error: "Administrator access is required." }); }
-function requireDeviceAccess(devices) { return (req, res, next) => { const auth = devices.authenticate(req.headers.authorization); if (!auth.allowed) return res.status(401).json({ error: "A paired device credential is required." }); if (!req.secure && !insecureDeviceAllowed(auth.device, requestHost(req), req.socket.remoteAddress)) return res.status(426).json({ error: "Companion update checks require HTTPS unless this device was paired from the same localhost origin." }); req.lumiDevice = auth.device; next(); }; }
+function companionOperatorMetadata(host) {
+  const value = (name, max) => String(process.env[name] || "").replace(/[\r\n\0"\\]/g, " ").trim().slice(0, max) || undefined;
+  const privacyCandidate = value("LUMI_OPERATOR_PRIVACY_URL", 500);
+  let privacyUrl;
+  if (privacyCandidate) {
+    try {
+      const parsed = new URL(privacyCandidate, host);
+      if (["http:", "https:"].includes(parsed.protocol)) privacyUrl = parsed.toString();
+    } catch { }
+  }
+  return {
+    operator_name: value("LUMI_OPERATOR_NAME", 200),
+    operator_contact: value("LUMI_OPERATOR_CONTACT", 300),
+    privacy_url: privacyUrl
+  };
+}
+
+function requireDeviceAccess(devices) { return (req, res, next) => { const auth = devices.authenticate(req.headers.authorization); if (!auth.allowed) return res.status(401).json({ error: "A paired device credential is required." }); if (!req.secure && !insecureDeviceAllowed(auth.device, requestHost(req), req.socket.remoteAddress)) return res.status(426).json({ error: "Companion requests require HTTPS unless this device was paired from the same localhost origin." }); req.lumiDevice = auth.device; next(); }; }
 function compareVersions(left, right) {
   const parse = (value) => {
     const [version] = String(value || "0").split("+", 1);

plugins/lumi_transcription/plugin.json

@@ -1,10 +1,10 @@
 {
   "id": "lumi_transcription",
   "name": "Lumi Transcription",
-  "version": "0.1.0-experimental.8",
+  "version": "0.1.0",
   "description": "Server-hosted whisper.cpp transcription for Lumi Companion and OBS closed captions.",
   "main": "index.js",
-  "channel": "experimental",
-  "compatible_from": "0.1.0-experimental.1",
+  "channel": "stable",
+  "compatible_from": "0.1.0",
   "rollback_safe": true
 }

plugins/lumi_transcription/public/transcription.js

@@ -90,6 +90,25 @@
     }
   });
 
+  root.addEventListener("click", async (event) => {
+    const runtime = event.target.closest("[data-install-runtime]");
+    if (!runtime) return;
+    const size = Number(runtime.dataset.runtimeSize) || 0;
+    if (!window.confirm(`Download and activate ${runtime.dataset.runtimeLabel}${size ? ` (${size} MiB)` : ""} on the Lumi host? Active transcription tests must be stopped first.`)) return;
+    runtime.disabled = true;
+    status.textContent = "Downloading, verifying, and activating the inference runtime…";
+    try {
+      const response = await fetch(`/plugins/lumi_transcription/api/runtime/${encodeURIComponent(runtime.dataset.installRuntime)}/install`, {
+        method: "POST", headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({ confirmed: true })
+      });
+      const result = await response.json();
+      if (!response.ok) throw new Error(result.error || "The inference runtime could not be installed.");
+      status.textContent = "Inference runtime verified and activated.";
+      setTimeout(() => window.location.reload(), 700);
+    } catch (error) { status.textContent = error.message; runtime.disabled = false; }
+  });
+
   root.addEventListener("click", async (event) => {
     const download = event.target.closest("[data-download-model]");
     const load = event.target.closest("[data-load-model]");

plugins/lumi_transcription/runtime_manifest.json

@@ -17,9 +17,12 @@
       "architecture": "x64",
       "backend": "cuda",
       "cuda": "12.4",
-      "url": "https://github.com/ggml-org/whisper.cpp/releases/download/v1.9.1/whisper-cublas-12.4.0-bin-x64.zip",
-      "sha256": "106a2030eff8998e4ef320fe72e263a78449e9040386ee27c41ea80b001b601b",
-      "expected_paths": ["whisper-cli.exe"],
+      "label": "NVIDIA GPU runtime (RTX 3060 and newer)",
+      "url": "https://git.rolfsvaag.no/Rolfsvaag_Datateknikk/Lumi/releases/download/companion-v0.1.0/lumi-whisper-worker-windows-x64-cuda.zip",
+      "sha256": "ab8f5e7ac1d8cfc6453574d69a4b61e5ab2f892d27707486c614b13c3a5debef",
+      "bytes": 469478354,
+      "expected_paths": ["lumi-whisper-worker.exe", "cudart64_12.dll", "cublas64_12.dll", "cublasLt64_12.dll"],
+      "minimum_gpu": "NVIDIA RTX 3060",
       "tested": true
     },
     {
@@ -27,11 +30,13 @@
       "platform": "win32",
       "architecture": "x64",
       "backend": "cpu",
-      "url": "https://github.com/ggml-org/whisper.cpp/releases/download/v1.9.1/whisper-bin-x64.zip",
-      "sha256": "7d8be46ecd31828e1eb7a2ecdd0d6b314feafd82163038ab6092594b0a063539",
-      "expected_paths": ["whisper-cli.exe"],
-      "tested": false,
-      "note": "CPU fallback remains disabled until the host benchmark meets the latency target."
+      "label": "CPU compatibility fallback",
+      "url": "https://git.rolfsvaag.no/Rolfsvaag_Datateknikk/Lumi/releases/download/companion-v0.1.0/lumi-whisper-worker-windows-x64-cpu.zip",
+      "sha256": "044f06396765ce64a32c4fb3701def8f1c27ebab71dde95f0e4c1b7d32134c6b",
+      "bytes": 631098,
+      "expected_paths": ["lumi-whisper-worker.exe"],
+      "tested": true,
+      "note": "Compatibility fallback only; the NVIDIA runtime is required for Lumi's low-latency target."
     }
   ]
 }

plugins/lumi_transcription/scripts/benchmark-worker.js

@@ -0,0 +1,189 @@
+const fs = require("fs");
+const path = require("path");
+const { spawn } = require("child_process");
+
+const options = parseArguments(process.argv.slice(2));
+if (!options.worker || !options.audio || !options.model) {
+  console.error("Usage: node benchmark-worker.js --worker <exe> --audio <16-kHz-mono.wav> --model <ggml.bin> [--max-latency-ms 2160] [--expect-transcript \"...\"]");
+  process.exit(2);
+}
+
+run().catch((error) => {
+  console.error(error.stack || error.message);
+  process.exit(1);
+});
+
+async function run() {
+  const pcm = readPcmWave(options.audio);
+  const child = spawn(options.worker, [], {
+    stdio: ["pipe", "pipe", "pipe"],
+    windowsHide: true,
+    env: process.env
+  });
+  const messages = [];
+  let stdout = "";
+  let stderr = "";
+  child.stderr.on("data", (chunk) => { stderr = `${stderr}${chunk}`.slice(-8000); });
+  child.stdout.on("data", (chunk) => {
+    stdout += chunk;
+    let newline;
+    while ((newline = stdout.indexOf("\n")) >= 0) {
+      const line = stdout.slice(0, newline).trim();
+      stdout = stdout.slice(newline + 1);
+      if (!line) continue;
+      try { messages.push(JSON.parse(line)); } catch { }
+    }
+  });
+  const exited = new Promise((resolve) => child.once("exit", (code) => resolve(code)));
+  await waitFor(messages, (message) => message.type === "ready", 20000, exited, stderr);
+  send(child, { type: "load_model", model: { id: "benchmark-model", path: path.resolve(options.model) } });
+  const loaded = await waitFor(messages, (message) => ["model_loaded", "model_error"].includes(message.type), 30000, exited, stderr);
+  if (loaded.type !== "model_loaded") throw new Error(loaded.message || "Model loading failed.");
+
+  const sessionId = "benchmark-session";
+  const trackId = "benchmark-track";
+  send(child, { type: "start_session", session: { id: sessionId, mode: "benchmark" } });
+  send(child, { type: "add_track", session_id: sessionId, track: { source_uuid: trackId } });
+  const frameBytes = 640;
+  const started = Date.now();
+  let sequence = 0;
+  for (let offset = 0; offset < pcm.length; offset += frameBytes) {
+    const dueAt = started + sequence * 20;
+    const wait = dueAt - Date.now();
+    if (wait > 0) await delay(wait);
+    const frame = Buffer.alloc(frameBytes);
+    pcm.copy(frame, 0, offset, Math.min(pcm.length, offset + frameBytes));
+    const capturedAt = Date.now();
+    send(child, {
+      type: "audio", session_id: sessionId, track_id: trackId, sequence,
+      capture_timestamp_us: capturedAt * 1000, captured_at: capturedAt
+    }, frame);
+    sequence += 1;
+  }
+  for (let index = 0; index < 50; index += 1) {
+    const dueAt = started + sequence * 20;
+    const wait = dueAt - Date.now();
+    if (wait > 0) await delay(wait);
+    const capturedAt = Date.now();
+    send(child, {
+      type: "audio", session_id: sessionId, track_id: trackId, sequence,
+      capture_timestamp_us: capturedAt * 1000, captured_at: capturedAt
+    }, Buffer.alloc(frameBytes));
+    sequence += 1;
+  }
+  await waitFor(messages, (message) => message.type === "hypothesis" && message.final, 15000, exited, stderr);
+  send(child, { type: "stop_session", session_id: sessionId });
+  await waitFor(messages, (message) => message.type === "session_stopped" && message.session_id === sessionId, 5000, exited, stderr);
+  send(child, { type: "shutdown" });
+  await Promise.race([exited, delay(3000)]);
+
+  const hypotheses = messages.filter((message) => message.type === "hypothesis");
+  const selected = hypotheses.findLast((message) => message.final) || hypotheses.at(-1);
+  if (!selected) throw new Error("The worker did not produce a hypothesis.");
+  const words = mergeFirstSeen(selected.words || [], hypotheses);
+  const latencies = words.map((word) => word.latency_ms).filter(Number.isFinite);
+  const inference = hypotheses.map((message) => message.inference_ms).filter(Number.isFinite);
+  const result = {
+    backend: loaded.backend,
+    audio_ms: Math.round(pcm.length / 32),
+    revisions: hypotheses.length,
+    transcript: selected.text,
+    word_count: words.length,
+    latency_ms: statistics(latencies),
+    inference_ms: statistics(inference),
+    control_tokens_present: words.some((word) => /\[_(?:BEG_|TT_\d+)\]/i.test(word.text)),
+    transcript_matches_expected: options.expectTranscript === undefined ? null
+      : comparableTranscript(selected.text) === comparableTranscript(options.expectTranscript)
+  };
+  console.log(JSON.stringify(result, null, 2));
+  if (result.control_tokens_present) throw new Error("Whisper control tokens leaked into word analysis.");
+  if (result.transcript_matches_expected === false)
+    throw new Error(`Transcript did not match the expected acceptance phrase: ${selected.text}`);
+  if (Number.isFinite(options.maxLatencyMs) && result.latency_ms.max > options.maxLatencyMs)
+    throw new Error(`Maximum first-seen word latency ${result.latency_ms.max} ms exceeds ${options.maxLatencyMs} ms.`);
+}
+
+function mergeFirstSeen(selected, hypotheses) {
+  const chosen = withOccurrences(selected);
+  const candidates = hypotheses.flatMap((hypothesis) => withOccurrences(Array.isArray(hypothesis.words) ? hypothesis.words : []));
+  return chosen.map((word) => {
+    const matches = candidates.filter((candidate) => candidate.key === word.key && candidate.occurrence === word.occurrence &&
+      Math.abs(Number(candidate.captured_at_ms) - Number(word.captured_at_ms)) <= 1500);
+    const { key: _key, occurrence: _occurrence, ...plain } = word;
+    return matches.length ? { ...plain, latency_ms: Math.min(...matches.map((candidate) => Number(candidate.latency_ms))) } : plain;
+  }).filter((word) => comparable(word.text));
+}
+function withOccurrences(words) {
+  const seen = new Map();
+  return words.map((word) => {
+    const key = comparable(word.text);
+    const occurrence = seen.get(key) || 0;
+    seen.set(key, occurrence + 1);
+    return { ...word, key, occurrence };
+  });
+}
+
+function comparable(value) { return String(value || "").toLocaleLowerCase().replace(/[^\p{L}\p{N}]+/gu, ""); }
+function comparableTranscript(value) { return String(value || "").toLocaleLowerCase().match(/[\p{L}\p{N}]+/gu)?.join(" ") || ""; }
+function statistics(values) {
+  if (!values.length) return { count: 0, min: null, average: null, median: null, p99: null, max: null };
+  const sorted = [...values].sort((left, right) => left - right);
+  return {
+    count: sorted.length, min: sorted[0],
+    average: sorted.reduce((sum, value) => sum + value, 0) / sorted.length,
+    median: percentile(sorted, .5), p99: percentile(sorted, .99), max: sorted.at(-1)
+  };
+}
+function percentile(values, ratio) {
+  const position = (values.length - 1) * ratio;
+  const lower = Math.floor(position); const upper = Math.ceil(position);
+  return values[lower] + (values[upper] - values[lower]) * (position - lower);
+}
+function send(child, metadata, pcm = Buffer.alloc(0)) {
+  const json = Buffer.from(JSON.stringify(metadata));
+  const header = Buffer.alloc(8);
+  header.writeUInt32LE(json.length, 0);
+  header.writeUInt32LE(pcm.length, 4);
+  child.stdin.write(Buffer.concat([header, json, pcm]));
+}
+async function waitFor(messages, predicate, timeoutMs, exited, stderr) {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    const match = messages.find(predicate);
+    if (match) return match;
+    const exit = await Promise.race([exited, delay(20).then(() => null)]);
+    if (exit !== null) throw new Error(`Worker exited with code ${exit}.${stderr ? ` ${stderr.trim()}` : ""}`);
+  }
+  throw new Error(`Worker response timed out after ${timeoutMs} ms.${stderr ? ` ${stderr.trim()}` : ""}`);
+}
+function readPcmWave(filename) {
+  const body = fs.readFileSync(filename);
+  if (body.toString("ascii", 0, 4) !== "RIFF" || body.toString("ascii", 8, 12) !== "WAVE") throw new Error("Audio input is not a WAV file.");
+  let offset = 12;
+  let format = null;
+  let pcm = null;
+  while (offset + 8 <= body.length) {
+    const type = body.toString("ascii", offset, offset + 4);
+    const size = body.readUInt32LE(offset + 4);
+    const start = offset + 8;
+    if (type === "fmt ") format = {
+      codec: body.readUInt16LE(start), channels: body.readUInt16LE(start + 2),
+      sampleRate: body.readUInt32LE(start + 4), bits: body.readUInt16LE(start + 14)
+    };
+    if (type === "data") pcm = body.subarray(start, start + size);
+    offset = start + size + (size % 2);
+  }
+  if (!format || format.codec !== 1 || format.channels !== 1 || format.sampleRate !== 16000 || format.bits !== 16 || !pcm)
+    throw new Error("Audio input must be 16-kHz mono PCM16.");
+  return pcm;
+}
+function parseArguments(args) {
+  const result = {};
+  for (let index = 0; index < args.length; index += 2) {
+    const key = args[index]?.replace(/^--/, "").replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
+    if (key) result[key] = args[index + 1];
+  }
+  result.maxLatencyMs = result.maxLatencyMs === undefined ? null : Number(result.maxLatencyMs);
+  return result;
+}
+function delay(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }

plugins/lumi_transcription/scripts/build-worker.ps1

@@ -1,5 +1,8 @@
 param(
-  [switch]$Cuda
+  [switch]$Cuda,
+  [string]$CudaToolkitRoot = "",
+  [switch]$Clean,
+  [switch]$Package
 )
 
 $ErrorActionPreference = "Stop"
@@ -21,17 +24,55 @@ function Find-Tool([string]$name) {
 
 $cmake = Find-Tool "cmake.exe"
 $ninja = Find-Tool "ninja.exe"
+$cudaRoot = if ($Cuda -and $CudaToolkitRoot) {
+  Get-Item -LiteralPath $CudaToolkitRoot -ErrorAction Stop
+} elseif ($Cuda) {
+  Get-ChildItem "$env:ProgramFiles\NVIDIA GPU Computing Toolkit\CUDA\v*" -Directory -ErrorAction SilentlyContinue |
+    Where-Object { Test-Path (Join-Path $_.FullName "bin\nvcc.exe") } |
+    Sort-Object FullName -Descending |
+    Select-Object -First 1
+} else { $null }
+if ($Cuda -and !$cudaRoot) { throw "The CUDA Toolkit was not found. Install it before building the CUDA worker." }
+if ($Cuda -and !(Test-Path (Join-Path $cudaRoot.FullName "bin\nvcc.exe"))) {
+  throw "The selected CUDA Toolkit does not contain bin\\nvcc.exe."
+}
+$cudaToolRoot = $null
+if ($cudaRoot) {
+  $cudaToolRoot = Join-Path $env:TEMP "lumi-cuda-sdk"
+  if (Test-Path $cudaToolRoot) { Remove-Item $cudaToolRoot -Force -Recurse }
+  New-Item -ItemType Junction -Path $cudaToolRoot -Target $cudaRoot.FullName | Out-Null
+}
 $vcvars = Get-ChildItem "${env:ProgramFiles(x86)}\Microsoft Visual Studio\2022\*\VC\Auxiliary\Build\vcvars64.bat" -ErrorAction SilentlyContinue |
   Select-Object -First 1
 if (!$vcvars) { throw "Visual Studio 2022 C++ Build Tools were not found." }
+$windowsSdkBin = Get-ChildItem "${env:ProgramFiles(x86)}\Windows Kits\10\bin\*\x64" -Directory -ErrorAction SilentlyContinue |
+  Where-Object { (Test-Path (Join-Path $_.FullName "rc.exe")) -and (Test-Path (Join-Path $_.FullName "mt.exe")) } |
+  Sort-Object FullName -Descending |
+  Select-Object -First 1
+if (!$windowsSdkBin) { throw "The Windows SDK resource and manifest tools were not found." }
+$resourceCompiler = (Join-Path $windowsSdkBin.FullName "rc.exe").Replace("\", "/")
+$manifestTool = (Join-Path $windowsSdkBin.FullName "mt.exe").Replace("\", "/")
+$windowsSdkVersion = $windowsSdkBin.Parent.Name
+$windowsSdkRoot = Join-Path "${env:ProgramFiles(x86)}" "Windows Kits\10"
+$windowsSdkInclude = Join-Path $windowsSdkRoot "Include\$windowsSdkVersion"
+$windowsSdkLib = Join-Path $windowsSdkRoot "Lib\$windowsSdkVersion"
 
+if ($Clean -and (Test-Path $buildRoot)) { Remove-Item $buildRoot -Force -Recurse }
 New-Item -ItemType Directory -Force -Path $buildRoot, $targetRoot | Out-Null
 $cudaValue = if ($Cuda) { "ON" } else { "OFF" }
+$cudaArgument = if ($cudaRoot) {
+  '-DCUDAToolkit_ROOT="{0}" -DCMAKE_CUDA_COMPILER="{1}"' -f $cudaToolRoot.Replace("\", "/"), (Join-Path $cudaToolRoot "bin\nvcc.exe").Replace("\", "/")
+} else { "" }
 $buildScript = Join-Path $buildRoot "build-worker.cmd"
 @(
   "@echo off",
   ('call "{0}" >nul' -f $vcvars.FullName),
-  ('"{0}" -S "{1}" -B "{2}" -G Ninja -DLUMI_WHISPER_CUDA={3} -DCMAKE_BUILD_TYPE=Release -DCMAKE_MAKE_PROGRAM="{4}"' -f $cmake, $sourceRoot, $buildRoot, $cudaValue, $ninja),
+  'set "PATHEXT=.COM;.EXE;.BAT;.CMD"',
+  ('set "PATH={0};%PATH%"' -f $windowsSdkBin.FullName),
+  $(if ($cudaRoot) { 'set "PATH={0};%PATH%"' -f (Join-Path $cudaToolRoot "bin") } else { "rem CUDA is disabled" }),
+  ('set "INCLUDE=%INCLUDE%;{0};{1};{2};{3}"' -f (Join-Path $windowsSdkInclude "ucrt"), (Join-Path $windowsSdkInclude "shared"), (Join-Path $windowsSdkInclude "um"), (Join-Path $windowsSdkInclude "winrt")),
+  ('set "LIB=%LIB%;{0};{1}"' -f (Join-Path $windowsSdkLib "ucrt\x64"), (Join-Path $windowsSdkLib "um\x64")),
+  ('"{0}" -S "{1}" -B "{2}" -G Ninja -DLUMI_WHISPER_CUDA={3} -DCMAKE_BUILD_TYPE=Release -DCMAKE_MAKE_PROGRAM="{4}" -DCMAKE_RC_COMPILER="{5}" -DCMAKE_MT="{6}" {7}' -f $cmake, $sourceRoot, $buildRoot, $cudaValue, $ninja, $resourceCompiler, $manifestTool, $cudaArgument),
   "if errorlevel 1 exit /b %errorlevel%",
   ('"{0}" --build "{1}" --config Release' -f $cmake, $buildRoot),
   "exit /b %errorlevel%"
@@ -43,4 +84,25 @@ if ($process.ExitCode -ne 0) { throw "Worker build failed with exit code $($proc
 $worker = Join-Path $buildRoot "lumi-whisper-worker.exe"
 if (!(Test-Path $worker)) { throw "The build completed without producing lumi-whisper-worker.exe." }
 Copy-Item -Force $worker (Join-Path $targetRoot "lumi-whisper-worker.exe")
+if ($Cuda) {
+  Get-ChildItem $targetRoot -Filter "*.dll" -ErrorAction SilentlyContinue | Remove-Item -Force
+  foreach ($pattern in @("cudart64_*.dll", "cublas64_*.dll", "cublasLt64_*.dll")) {
+    $dependency = Get-ChildItem (Join-Path $cudaRoot.FullName "bin") -Filter $pattern -File |
+      Sort-Object Name |
+      Select-Object -First 1
+    if (!$dependency) { throw "The selected CUDA Toolkit is missing $pattern." }
+    Copy-Item -Force $dependency.FullName $targetRoot
+  }
+}
 Write-Host "Installed Lumi whisper worker ($backend) in $targetRoot"
+if ($Package) {
+  $archive = Join-Path $pluginRoot "data\tmp\lumi-whisper-worker-windows-x64-$backend.zip"
+  New-Item -ItemType Directory -Force -Path (Split-Path -Parent $archive) | Out-Null
+  Remove-Item $archive -Force -ErrorAction SilentlyContinue
+  Compress-Archive -Path $targetRoot -DestinationPath $archive -CompressionLevel Optimal
+  $file = Get-Item $archive
+  $sha = (Get-FileHash $archive -Algorithm SHA256).Hash.ToLowerInvariant()
+  Write-Host "Runtime package: $archive"
+  Write-Host "Runtime bytes: $($file.Length)"
+  Write-Host "Runtime SHA256: $sha"
+}

plugins/lumi_transcription/tests/verify.js

@@ -40,6 +40,7 @@ async function run() {
     verifyBenchmarkRetention();
     verifyAdminDeviceRevocationUx();
     await verifyBenchmarkStartRollback();
+    await verifyManualBenchmarkFinalization();
     await verifySessionLifecycle();
     await verifyProviderFailureFeedback();
     await verifyWorkerRestart();
@@ -117,6 +118,8 @@ function verifyLocalhostTransportPolicy() {
 }
 
 function verifyCompanionVersionOrdering() {
+  assert.equal(plugin.compareVersions("0.1.0-experimental.10", "0.1.0-experimental.9"), 1);
+  assert.equal(plugin.compareVersions("0.1.0-experimental.9", "0.1.0-experimental.8"), 1);
   assert.equal(plugin.compareVersions("0.1.0-experimental.8", "0.1.0-experimental.7"), 1);
   assert.equal(plugin.compareVersions("0.1.0-experimental.7", "0.1.0-experimental.6"), 1);
   assert.equal(plugin.compareVersions("0.1.0-experimental.6", "0.1.0-experimental.5"), 1);
@@ -190,16 +193,26 @@ function verifyBenchmarkRetention() {
   const source = crypto.randomUUID();
   const id = store.start({ sessionId: "benchmark-session", deviceId: "device", source: { source_uuid: source, display_name: "Mic" } });
   store.record("benchmark-session", {
-    caption_id: "caption", revision: 1, final: true, stable_text: "hello world",
+    caption_id: "caption", revision: 1, final: false, stable_text: "hello world",
     analysis: { transcript: "hello world", words: [
-      { text: "hello", latency_ms: 700, confidence: .96, audio_start_ms: 0, audio_end_ms: 300 },
-      { text: "world", latency_ms: 1400, confidence: .82, audio_start_ms: 300, audio_end_ms: 700 }
+      { text: "[_BEG_]", latency_ms: 400, confidence: .2, captured_at_ms: 1000 },
+      { text: "hello", latency_ms: 500, confidence: .7, audio_start_ms: 0, audio_end_ms: 300, captured_at_ms: 1000 },
+      { text: "world[_TT_300]", latency_ms: 900, confidence: .6, audio_start_ms: 300, audio_end_ms: 700, captured_at_ms: 1300 }
+    ] }, latency: { inference_ms: 400 }, model: { id: "small.en", backend: "cpu" }
+  });
+  store.record("benchmark-session", {
+    caption_id: "caption", revision: 2, final: true, stable_text: "hello world",
+    analysis: { transcript: "hello world", words: [
+      { text: "hello", latency_ms: 700, confidence: .96, audio_start_ms: 0, audio_end_ms: 300, captured_at_ms: 1000 },
+      { text: "world", latency_ms: 1400, confidence: .82, audio_start_ms: 300, audio_end_ms: 700, captured_at_ms: 1300 }
     ] }, latency: { inference_ms: 500 }, model: { id: "small.en", backend: "cpu" }
   });
   const result = store.finish("benchmark-session", "completed");
   assert.equal(result.id, id);
   assert.equal(result.words.length, 2);
-  assert.equal(result.stats.latency.average, 1050);
+  assert.deepEqual(result.words.map((word) => word.text), ["hello", "world"]);
+  assert.equal(result.stats.latency.average, 700);
+  assert.ok(Math.abs(result.stats.confidence.average - .89) < 1e-9);
   assert.equal(metricStats([1, 2, 3]).median, 2);
   const secondId = store.start({ sessionId: "benchmark-session", deviceId: "device", source: { source_uuid: source, display_name: "Mic" } });
   assert.notEqual(secondId, id);
@@ -225,6 +238,47 @@ function verifyBenchmarkRetention() {
   legacy.close();
 }
 
+async function verifyManualBenchmarkFinalization() {
+  class Provider extends EventEmitter {
+    async health() { return { healthy: true, model_ready: true, state: "running" }; }
+    async startSession() {}
+    async addTrack() {}
+    async stopSession(sessionId) {
+      this.emit("hypothesis", {
+        session_id: sessionId, track_id: source, text: "manual ending", final: true, new_utterance: true,
+        words: [{ text: "manual", latency_ms: 600, confidence: .94, captured_at_ms: 1000 }],
+        model_id: "small.en", backend: "cpu"
+      });
+      await new Promise((resolve) => setImmediate(resolve));
+    }
+  }
+  const provider = new Provider();
+  const source = crypto.randomUUID();
+  let deliveryStopped = false;
+  let finalRecorded = false;
+  const sent = [];
+  const benchmarks = {
+    start: () => "benchmark-id",
+    record: (_sessionId, event) => { finalRecorded = event.final && !deliveryStopped; },
+    finish: () => ({ id: "benchmark-id", status: "completed", transcript: "manual ending", stats: { latency: metricStats([600]), confidence: metricStats([.94]) }, words: [{ text: "manual", latency_ms: 600, confidence: .94, final: true }] })
+  };
+  const coordinator = new SessionCoordinator({
+    provider, benchmarks,
+    deliveryFactory: () => ({
+      start: async () => {}, stop: async () => { deliveryStopped = true; }, pause: async () => {}, resume: async () => {},
+      deliver: async () => ({ disposition: "simulated" })
+    })
+  });
+  const { session } = coordinator.create({ id: "device" }, (type, payload) => sent.push({ type, payload }));
+  coordinator.updateSource(session.id, { source_uuid: source, display_name: "Mic", primary: true, program_active: true });
+  await coordinator.start(session.id, { mode: "benchmark" });
+  await coordinator.stop(session.id, "benchmark_complete");
+  assert.equal(finalRecorded, true);
+  assert.equal(sent.at(-1).type, "benchmark_complete");
+  assert.equal(sent.at(-1).payload.stats.confidence.average, .94);
+  await coordinator.close();
+}
+
 async function verifyBenchmarkStartRollback() {
   class Provider extends EventEmitter {
     constructor() { super(); this.starts = 0; }
@@ -339,9 +393,11 @@ async function verifyNativeWorkerBoundary() {
   const cmake = fs.readFileSync(path.join(sourceRoot, "CMakeLists.txt"), "utf8");
   const source = fs.readFileSync(path.join(sourceRoot, "src/main.cpp"), "utf8");
   assert.match(cmake, /f049fff95a089aa9969deb009cdd4892b3e74916/);
-  assert.match(source, /max_samples = sample_rate \* 6/);
+  assert.match(source, /max_samples = sample_rate \* 15/);
   assert.match(source, /_setmode\(_fileno\(stdin\), _O_BINARY\)/);
   assert.match(source, /token_timestamps = true/);
+  assert.match(source, /last_decode_at/);
+  assert.match(source, /data\.id >= whisper_token_eot/);
   assert.match(source, /session_stopped/);
   const bridge = fs.readFileSync(path.join(__dirname, "../../../companion/native/obs-bridge/src/plugin.cpp"), "utf8");
   assert.match(bridge, /selection_state/);
@@ -357,10 +413,11 @@ async function verifyAuthenticatedGateway() {
   const devices = new DeviceStore(db);
   const sessionId = crypto.randomUUID();
   let disconnected = false;
+  let audioMessages = 0;
   const sessions = {
     create: (_device, send) => ({ session: { id: sessionId, state: "idle", send }, resumed: false }),
     disconnect: () => { disconnected = true; },
-    audio: async () => ({ accepted: true }), updateSource: () => ({}), updateObsState: async () => ({}), start: async () => ({}), stop: async () => ({})
+    audio: async () => { audioMessages += 1; return { accepted: true }; }, updateSource: () => ({}), updateObsState: async () => ({}), start: async () => ({}), stop: async () => ({})
   };
   const gateway = new CompanionGateway({ devices, sessions });
   const registry = createWebUpgradeRegistry();
@@ -379,6 +436,15 @@ async function verifyAuthenticatedGateway() {
   assert.equal(response.type, "hello_ack");
   assert.equal(response.session_id, sessionId);
   assert.equal(devices.list().find((device) => device.id === credential.device_id).metadata.companion_version, "0.1.0-experimental.6");
+  const sourceUuid = crypto.randomUUID();
+  const audioFrame = protocol.encodeAudioFrame({ session_id: sessionId, source_uuid: sourceUuid, sequence: 1, capture_timestamp_us: Date.now() * 1000, pcm: Buffer.alloc(640) });
+  for (let index = 0; index < 350; index += 1) client.send(audioFrame);
+  await new Promise((resolve) => setTimeout(resolve, 250));
+  assert.equal(client.readyState, WebSocket.OPEN, "Audio bursts must be bounded without closing the authenticated control connection");
+  assert.ok(audioMessages > 0 && audioMessages < 350, "Excess audio frames were not softly rate-limited");
+  for (let index = 0; index < 1100; index += 1) client.send(JSON.stringify(protocol.envelope("source_update", { source_uuid: crypto.randomUUID(), display_name: `OBS source ${index}` }, sessionId)));
+  await new Promise((resolve) => setTimeout(resolve, 250));
+  assert.equal(client.readyState, WebSocket.OPEN, "OBS source inventory bursts must not close the authenticated control connection");
   await new Promise((resolve) => { client.once("close", resolve); client.close(); });
   for (let attempt = 0; attempt < 20 && !disconnected; attempt += 1) await new Promise((resolve) => setTimeout(resolve, 5));
   assert.equal(disconnected, true);
@@ -403,6 +469,19 @@ function verifyArtifactsAndLogs(temp) {
   const file = path.join(artifactRoot, "model.bin"); fs.writeFileSync(file, "verified");
   const entry = { id: "model", filename: "model.bin", url: "https://example.invalid/model.bin", sha256: sha256File(file) };
   assert.equal(new ArtifactManager(artifactRoot).status(entry).valid, true);
+  const runtimeZip = path.join(temp, "runtime.zip");
+  const archive = new (require("adm-zip"))();
+  archive.addFile("bin/lumi-whisper-worker.exe", Buffer.from("portable-worker"));
+  archive.writeZip(runtimeZip);
+  const runtimeEntry = {
+    id: "windows-x64-cpu", url: "https://example.invalid/runtime.zip", sha256: sha256File(runtimeZip),
+    expected_paths: ["lumi-whisper-worker.exe"], backend: "cpu"
+  };
+  const runtimeRoot = path.join(temp, "runtime");
+  const manager = new ArtifactManager(runtimeRoot);
+  manager.installZip(runtimeEntry, runtimeZip);
+  manager.installZip(runtimeEntry, runtimeZip);
+  assert.equal(fs.readFileSync(path.join(runtimeRoot, runtimeEntry.id, "bin", "lumi-whisper-worker.exe"), "utf8"), "portable-worker");
   assert.equal(sanitize({ pcm: Buffer.alloc(10), device_secret: "secret", stable_text: "hello" }, false).pcm, "[redacted]");
   const logsRoot = path.join(temp, "logs");
   const logs = new JsonlDiagnosticLog(logsRoot, { retentionDays: 1, maxBytes: 100 });
@@ -424,11 +503,18 @@ async function verifyCompanionPackage(temp) {
     entrypoint: "Lumi.Companion.App.exe", url: "https://example.invalid/companion.zip", sha256: sha256File(sourcePath), bytes: fs.statSync(sourcePath).size
   }] };
   const service = new CompanionPackageService(root, manifest);
-  const bundle = await service.build({ pairing_id: "pairing", bootstrap: { format: "lumi-companion-bootstrap-v1", token: "single-use" } });
+  const bundle = await service.build({ pairing_id: "pairing", bootstrap: {
+    format: "lumi-companion-bootstrap-v1", token: "single-use", host: "https://lumi.example.test",
+    operator_name: "Example Host", operator_contact: "privacy@example.test", privacy_url: "https://lumi.example.test/privacy"
+  } });
   const output = new (require("adm-zip"))(bundle.buffer);
   assert.equal(output.readAsText("Lumi.Companion.App.exe"), "portable-app");
   assert.match(output.readAsText("lumi-companion-pairing.lumi-pairing.json"), /single-use/);
   assert.match(output.readAsText("START-HERE.txt"), /works once/i);
+  assert.match(output.readAsText("START-HERE.txt"), /https:\/\/lumi\.example\.test/);
+  assert.match(output.readAsText("HOST-OPERATOR-NOTICE.txt"), /Example Host/);
+  assert.match(output.readAsText("HOST-OPERATOR-NOTICE.txt"), /privacy@example\.test/);
+  assert.match(output.readAsText("HOST-OPERATOR-NOTICE.txt"), /responsibility follows the actual facts and applicable law/i);
   const manifestPath = path.join(root, "manifest.json");
   fs.writeFileSync(manifestPath, JSON.stringify(manifest));
   const liveManifestService = new CompanionPackageService(root, manifestPath);
@@ -443,11 +529,14 @@ async function verifyCompanionPackage(temp) {
     id: "windows-x64-installer", filename: "Lumi.Companion-Setup.exe", url: "https://example.invalid/setup.exe",
     sha256: sha256File(installerPath), bytes: fs.statSync(installerPath).size
   } };
-  const installerBundle = await new CompanionPackageService(root, installerManifest).build({ pairing_id: "installed", bootstrap: { token: "installer-pairing" } });
+  const installerBundle = await new CompanionPackageService(root, installerManifest).build({ pairing_id: "installed", bootstrap: {
+    token: "installer-pairing", host: "https://installed.example.test", operator_name: "Installed Host"
+  } });
   const installedOutput = new (require("adm-zip"))(installerBundle.buffer);
   assert.equal(installedOutput.readAsText("Lumi.Companion-Setup.exe"), "installer");
   assert.equal(installedOutput.getEntry("Lumi.Companion.App.exe"), null);
   assert.match(installedOutput.readAsText("START-HERE.txt"), /Start menu/i);
+  assert.match(installedOutput.readAsText("HOST-OPERATOR-NOTICE.txt"), /Installed Host/);
 }
 
 async function verifyPluginIsolation() {

plugins/lumi_transcription/views/settings.ejs

@@ -45,6 +45,14 @@
     <% if (!providerHealth.healthy) { const workerReason = providerHealth.last_error?.message || (providerHealth.last_exit ? `Last exit code: ${providerHealth.last_exit.code ?? 'unknown'}` : null) || providerHealth.last_diagnostic?.message || 'No worker failure detail has been reported yet.'; %>
       <div class="callout warning"><strong>Speech recognition needs attention</strong><p><%= workerReason %> Reload the verified model below, then rerun the Companion test.</p></div>
     <% } %>
+    <div class="button-row runtime-actions">
+      <% runtimeManifest.artifacts.forEach((artifact) => { %>
+        <button class="button <%= artifact.backend === 'cpu' ? 'subtle' : '' %>" type="button" data-install-runtime="<%= artifact.id %>" data-runtime-label="<%= artifact.label %>" data-runtime-size="<%= Math.ceil((artifact.bytes || 0) / 1048576) %>">
+          <%= artifact.backend === 'cuda' ? 'Install / upgrade GPU runtime' : 'Install CPU fallback' %>
+        </button>
+      <% }) %>
+    </div>
+    <p class="hint">The low-latency package targets <%= runtimeManifest.artifacts.find((artifact) => artifact.backend === 'cuda')?.minimum_gpu || 'a supported NVIDIA GPU' %> and newer. Runtime changes activate immediately when no transcription session is active.</p>
     <div class="callout info"><strong>Shared GPU awareness</strong><p>Lumi warns and benchmarks when Lumi AI already occupies GPU memory. It never unloads AI models automatically.</p></div>
   </section>
 

plugins/now_playing/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Song Overlay changelog
+
+## 0.1.2
+
+- Added Spotify playback capture through Lumi Companion with shared paired-device authentication.
+- Added a configurable Lumi Overlay source with transparent OBS rendering, live song changes, cover-derived colors, progress, and animation controls.
+- Added optional Twitch and YouTube announcements plus the shared-template `!music` command on Discord, Twitch, and YouTube.
+- Added resilient event delivery with canonical state re-fetching and connection fallback.

plugins/now_playing/plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "now_playing",
+  "name": "Song Overlay",
+  "version": "0.1.2",
+  "description": "Provider-neutral song state, chat announcements, and a customizable Lumi Overlay source.",
+  "main": "index.js",
+  "channel": "stable",
+  "compatible_from": "0.1.0",
+  "rollback_safe": true
+}

plugins/now_playing/public/admin.css

@@ -0,0 +1 @@
+.np-status-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:12px}.np-status-grid>div{display:grid;gap:4px;padding:12px;border:1px solid var(--border);border-radius:var(--radius-sm,8px);background:color-mix(in srgb,var(--card) 80%,transparent)}.np-status-grid span{font-size:.82rem;color:var(--muted)}.tone-success{color:var(--sea,#34d399)}.tone-warning{color:var(--warning,#fbbf24)}.np-copy-row{display:flex;gap:8px;align-items:center}.np-copy-row input{flex:1}.np-check-grid{display:flex;gap:14px;flex-wrap:wrap}.np-check-grid label{display:flex;align-items:center;gap:7px}.np-placeholder-list{display:flex;gap:8px;flex-wrap:wrap;margin-top:10px}.np-placeholder-list code{padding:5px 8px;border:1px solid var(--border);border-radius:6px}.sticky-save{position:sticky;bottom:12px;z-index:8;display:flex;justify-content:flex-end;margin:14px 0;padding:10px;border:1px solid var(--border);border-radius:10px;background:color-mix(in srgb,var(--background,#0b1020) 92%,transparent);backdrop-filter:blur(12px)}@media(max-width:700px){.np-copy-row{align-items:stretch;flex-direction:column}.sticky-save .button{width:100%}}

plugins/now_playing/public/admin.js

@@ -0,0 +1,14 @@
+(() => {
+  document.addEventListener("click", async (event) => {
+    const button = event.target.closest("[data-copy]");
+    if (!button) return;
+    try {
+      await navigator.clipboard.writeText(button.dataset.copy || "");
+      const original = button.textContent;
+      button.textContent = "Copied";
+      setTimeout(() => { button.textContent = original; }, 1200);
+    } catch {
+      button.closest(".np-copy-row")?.querySelector("input")?.select();
+    }
+  });
+})();