Release 0.1.4: document current limits and tighten volume control state

Author: rowild

.plans/01-initial-plan.md

@@ -2,9 +2,9 @@
 
 Version snapshot:
 
-- release version: `0.1.3`
-- build number: `4`
-- snapshot date: `2026-04-09`
+- release version: `0.1.4`
+- build number: `5`
+- snapshot date: `2026-04-10`
 
 ## Goal
 
@@ -52,8 +52,8 @@ The extension is a view-based Quick Look preview extension with:
 
 Current behavior:
 
-- playback starts paused in all Quick Look contexts
 - compact Finder column preview is non-live summary mode
+- expanded Quick Look preview autoplays
 - large Quick Look preview is the live playback surface
 
 This was a deliberate change. Autoplay in the small Finder preview was too disruptive and Finder does not expose a reliable public “column preview vs full preview” switch for the extension.
@@ -142,14 +142,14 @@ In practice, the custom owned UTIs are what made routing predictable.
 - Finder can route supported files to `MKVQuickLook`
 - `mkv`, `webm`, and Ogg video preview path are working
 - problematic `Reflections.mkv` is now selected through the extension and renders in the correct position
-- playback starts paused
 - large preview exposes manual controls
 - volume and seek controls exist
 - play/pause now lives in the control row beside the seek bar
 - diagnostics exist for volume and seek latency
-- dragging the volume knob applies immediately
+- dragging the volume knob lands at the release point correctly again
 - dragging the seek knob works
 - pure click behavior on the seek bar was repeatedly problematic in Finder-hosted Quick Look and required custom handling
+- autoplay in expanded Quick Look works again without re-enabling the old compact-preview autoplay bug
 
 ### Deliberate Constraints
 
@@ -163,7 +163,7 @@ In practice, the custom owned UTIs are what made routing predictable.
 These findings are specific enough that they should remain documented here:
 
 - volume drag is responsive because the app writes directly to `mediaPlayer.audio?.volume`
-- volume bar click had an observable lag even when drag felt immediate
+- volume bar click still has an observable lag on the target machine even after the handle-position regressions were corrected
 - seek drag and seek pure-click were not equivalent in Finder-hosted Quick Look
 - a plain click on the seek bar could trigger internal activity without moving the handle or visibly changing position
 - click-plus-small-drag on the seek bar behaved differently and did move to the target
@@ -174,10 +174,44 @@ Current engineering interpretation:
 - seek-bar click behavior is at least partly an interaction-delivery problem, not just a simple seek-timing problem
 - Finder-hosted Quick Look control behavior must be treated as distinct from generic AppKit assumptions
 
+Implementation-level findings from the later volume investigation:
+
+- the custom slider path must distinguish knob drags from track clicks; pre-applying an absolute value on knob drag start is wrong
+- track-click targeting must use AppKit slider bar geometry (`NSSliderCell.barRectFlipped(_:)` / `knobRectFlipped(_:)`), not raw `bounds.width`
+- volume needs the same kind of interaction protection that seek needed:
+  - a persistent interaction identity during the drag/click
+  - a pending requested value that stays authoritative
+- the deeper correction is stronger than that:
+  - for this app, the displayed volume should not be driven by repeated player read-backs at all
+  - volume is a local user command, not a media timeline
+  - letting VLCKit metric publications re-drive the slider reintroduces drift and apparent delay after release
+- another concrete failure that actually happened:
+  - the custom slider was still pre-applying an absolute value on knob drag start
+  - that was wrong for knob drags and caused volume-handle movement to be inconsistent with the real drag gesture
+- otherwise a late metrics publication from VLCKit can overwrite the just-released handle position and make the control feel delayed or imprecise
+
+Primary sources used for this conclusion:
+
+- AppKit SDK header: `NSSliderCell.h`
+  - `-knobRectFlipped:`
+  - `-barRectFlipped:`
+- AppKit SDK header: `NSCell.h`
+  - `-hitTestForEvent:inRect:ofView:`
+- repository-local playback diagnostics logs and the `TrackingSlider` / `VLCKitMediaPreviewPlayer` code paths
+
 Current diagnostic support:
 
 - timestamped unified logging exists for seek and volume UI events, controller handoff, player apply, and post-apply metrics
 - this must be used before making more speculative “speed” changes
+- those diagnostics already answer one key question:
+  - the app does measure UI-change, controller handoff, player apply, and later metrics timestamps
+  - so when the slider still feels wrong after `apply`, the remaining problem is not “missing measurement”; it is usually wrong control architecture or downstream audio/output behavior
+- local VLCKit volume notifications are now also logged, so future work must compare:
+  - `ui-change`
+  - `controller-change`
+  - `apply`
+  - `vlc-notification`
+  - `metrics`
 
 ## Test Strategy That Must Stay In Place
 
@@ -202,6 +236,14 @@ Important CI exception:
 - reason: they depend on visible AppKit/VLCKit rendering and are not reliable on hosted release runners
 - they remain mandatory for local verification
 
+### Control Regression Tests
+
+The test suite must also keep explicit regression coverage for control-state bugs that already happened:
+
+- volume state must keep the latest requested value even if the player reports an older one
+- playback metrics must not overwrite the user-controlled volume slider position
+- active preview session replacement must stop the previous player
+
 ### Metadata Tests
 
 These tests are also mandatory because Finder selection depends on metadata correctness:
@@ -535,7 +577,7 @@ Rule:
 
 - keep and use the host-app playback lab for the same shared renderer path
 
-### 4. Do Not Autoplay In Finder By Default
+### 4. Do Not Autoplay In Compact Finder Preview
 
 What went wrong:
 
@@ -548,12 +590,12 @@ Reason:
 
 Rule:
 
-- default to paused
-- require explicit user play
+- compact Finder preview must stay non-live
+- any autoplay behavior must be restricted to the expanded Quick Look path only
 
 No-go:
 
-- do not reintroduce autoplay unless there is a reliable host-context discriminator and a test for it
+- do not reintroduce autoplay in compact Finder preview unless there is a reliable host-context discriminator and a test for it
 
 ### 5. Do Not Trust VLC State Enums As The Only Playback Truth
 
@@ -587,10 +629,13 @@ Rule:
 - for seek, test both while playback is active:
   - knob drag
   - bar click with no drag
+- for volume, backend playback metrics must not be allowed to re-drive the visible slider position during or after user interaction
+- for knob drags, do not pre-apply an absolute track-click value at mouse-down
 
 No-go:
 
 - do not claim control fixes complete until both interaction styles are verified in Finder
+- do not let player read-backs overwrite the user-commanded volume slider state
 
 ### 7. Do Not Use Clever Paused-Start State Machines Without End-To-End Playback Verification
 
@@ -648,6 +693,22 @@ No-go:
 - no ffmpeg/remux/transcode fallback in the normal preview path
 - no persistent generated media files
 
+### 11. Do Not Describe Work As Solved Before Evidence Exists
+
+What went wrong:
+
+- some explanations used probability language or confidence language before the underlying behavior was fully verified
+- that weakened trust and violated the repository communication standard
+
+Rule:
+
+- separate observed fact, evidence, hypothesis, fix, and remaining unverified risk
+- do not describe a fix as complete until tests and observed behavior support that claim
+
+No-go:
+
+- do not present guesses, partial reasoning, or under-verified fixes as if they were solid conclusions
+
 ## Recommended Debug Workflow For Future Changes
 
 When something breaks, use this order:
@@ -712,6 +773,6 @@ These are reasonable future changes:
 These are risky and should be approached carefully:
 
 - changing renderer integration again
-- reintroducing autoplay
+- changing expanded-preview autoplay behavior without re-checking compact-preview isolation
 - trying to force Finder compact preview sizing
 - adding conversion/remux fallback logic

AGENTS.md

@@ -2,6 +2,31 @@
 
 This file defines mandatory working rules for agents operating in this repository.
 
+## EXTREMELY IMPORTANT - MUST-OBEY RULE
+
+Before giving any answer, proposing any fix, or claiming that a problem is solved, the agent must stop and ask itself:
+
+`Did I really think through everything?`
+
+This question must be answered honestly, without self-flattery, without face-saving language, and without pretending that partial understanding is enough.
+
+If the honest answer is `no`, the agent must not present the work as complete.
+
+It must instead:
+
+- go back to the problem
+- dig deeper
+- verify more
+- reduce uncertainty
+- test the relevant behavior again
+- only answer once the result is genuinely thought through
+
+The agent must never use reassuring language to cover incomplete reasoning.
+The agent must never present guesses, shallow interpretations, or half-verified fixes as if they were solid conclusions.
+The agent must never speak as if luck, hope, or impression is an acceptable substitute for understanding.
+
+This rule is crucial. If it is violated, costs and rework can explode far beyond the original estimate.
+
 ## Critical Rule
 
 The standards below are not optional polish. They are crucial.
@@ -50,9 +75,12 @@ Agents must therefore optimize for correctness, depth, testability, and honesty,
 - Be honest, direct, and technically precise.
 - Do not flatter yourself.
 - Do not claim certainty that has not been earned.
+- Do not use language that suggests guessing, hoping, luck, or superficial confidence.
+- Do not hide incomplete reasoning behind smooth wording.
 - If something is broken, risky, unverified, poorly understood, or likely to regress, say so plainly.
 - When explaining a problem, prefer uncomfortable truth over reassuring vagueness.
 - If a previous approach was wrong, say so directly and explain the correction.
+- When answering, first apply the must-obey rule above and only speak after the answer has been honestly pressure-tested.
 
 ## User-Idea Evaluation
 

CHANGELOG.md

@@ -2,18 +2,31 @@
 
 ## Unreleased
 
+## 0.1.4 - 2026-04-10
+
 ### Added
 
 - Added owned `.opus` audio support in the app and extension metadata.
 - Added an audio-only Quick Look mode that keeps playback controls visible without showing an empty video frame.
+- Added stronger regression tests for volume state handling and for preventing playback metrics from overwriting the user-controlled volume slider position.
+- Added local VLCKit volume-notification diagnostics so downstream audio timing can be measured instead of guessed.
+
+### Changed
+
+- Full Quick Look preview autoplays again in expanded mode; compact Finder preview remains a non-live summary.
+- Volume slider state is now driven by the last user-commanded value instead of repeated backend metric write-backs.
 
 ### Fixed
 
-- Switching to another file while a preview is already open now stops the previous player before the new one is attached, preventing stray audio from continuing in the background.
+- Selecting another file while a preview is already open now stops the previously active preview session before the new one loads, preventing stray audio from continuing in the background.
+- Pause now cuts audible output immediately before VLC finishes its own state transition, so the control feels more responsive.
+- Volume handle release now stays at the released position instead of snapping back to the earlier pickup position.
+- The custom slider no longer pre-applies an absolute value on knob drag start, which was a real source of incorrect volume-handle movement.
 
-### Notes
+### Known Issues
 
-- `.opus` is audio-only support, not video support hidden behind another extension.
+- Direct click on the volume bar still has an observable delay on the target machine even though handle placement is now exact.
+- The remaining volume-click latency is instrumented but not fully eliminated in Finder-hosted Quick Look.
 
 ## 0.1.3 - 2026-04-09
 

MKVQuickLook.xcodeproj/project.pbxproj

@@ -548,7 +548,7 @@
 				CLANG_WARN_UNREACHABLE_CODE = YES;
 				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
 				COPY_PHASE_STRIP = NO;
-				CURRENT_PROJECT_VERSION = 4;
+				CURRENT_PROJECT_VERSION = 5;
 				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
 				ENABLE_NS_ASSERTIONS = NO;
 				ENABLE_STRICT_OBJC_MSGSEND = YES;
@@ -561,7 +561,7 @@
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
 				MACOSX_DEPLOYMENT_TARGET = 14.0;
-				MARKETING_VERSION = 0.1.3;
+				MARKETING_VERSION = 0.1.4;
 				MTL_ENABLE_DEBUG_INFO = NO;
 				MTL_FAST_MATH = YES;
 				PRODUCT_NAME = "$(TARGET_NAME)";
@@ -721,7 +721,7 @@
 				CLANG_WARN_UNREACHABLE_CODE = YES;
 				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
 				COPY_PHASE_STRIP = NO;
-				CURRENT_PROJECT_VERSION = 4;
+				CURRENT_PROJECT_VERSION = 5;
 				DEBUG_INFORMATION_FORMAT = dwarf;
 				ENABLE_STRICT_OBJC_MSGSEND = YES;
 				ENABLE_TESTABILITY = YES;
@@ -740,7 +740,7 @@
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
 				MACOSX_DEPLOYMENT_TARGET = 14.0;
-				MARKETING_VERSION = 0.1.3;
+				MARKETING_VERSION = 0.1.4;
 				MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
 				MTL_FAST_MATH = YES;
 				ONLY_ACTIVE_ARCH = YES;

MKVQuickLookApp/Sources/PlaybackLabViewController.swift

@@ -23,6 +23,7 @@ final class PlaybackLabViewController: NSViewController {
     override func viewDidDisappear() {
         super.viewDidDisappear()
         player.stop()
+        MediaPreviewPlayerSession.deactivate(player)
     }
 
     func loadFile(_ url: URL?) {
@@ -67,7 +68,12 @@ final class PlaybackLabViewController: NSViewController {
         )
         previewContentView.attachRenderView(player.renderView)
         previewContentView.playbackToggleHandler = { [weak self] in
-            self?.player.togglePlayback()
+            guard let self else {
+                return
+            }
+
+            MediaPreviewPlayerSession.activate(self.player)
+            self.player.togglePlayback()
         }
         previewContentView.seekTrackingHandler = { [weak self] isTracking, interactionID in
             guard let self else {

MKVQuickLookPreviewExtension/Sources/PreviewViewController.swift

@@ -20,7 +20,12 @@ final class PreviewViewController: NSViewController, QLPreviewingController {
         super.viewDidLoad()
         preferredContentSize = Self.expandedPreferredContentSize
         previewContentView.playbackToggleHandler = { [weak self] in
-            self?.player?.togglePlayback()
+            guard let self, let player = self.player else {
+                return
+            }
+
+            MediaPreviewPlayerSession.activate(player)
+            player.togglePlayback()
         }
         previewContentView.seekTrackingHandler = { [weak self] isTracking, interactionID in
             guard let self else {
@@ -54,11 +59,13 @@ final class PreviewViewController: NSViewController, QLPreviewingController {
     override func viewDidDisappear() {
         super.viewDidDisappear()
         player?.stop()
+        MediaPreviewPlayerSession.deactivate(player)
         isMediaLoaded = false
     }
 
     func preparePreviewOfFile(at url: URL) async throws {
         do {
+            MediaPreviewPlayerSession.stopActivePreview()
             let metadata = try PreviewMetadata(fileURL: url)
             let player = VLCKitMediaPreviewPlayer()
             player.playbackStateDidChange = { [weak self] state in
@@ -106,13 +113,17 @@ final class PreviewViewController: NSViewController, QLPreviewingController {
         case .compact:
             if isMediaLoaded && modeChanged {
                 player?.stop()
+                MediaPreviewPlayerSession.deactivate(player)
                 isMediaLoaded = false
             }
         case .expanded:
             if !isMediaLoaded, let currentFileURL {
                 player?.loadMedia(from: currentFileURL)
                 isMediaLoaded = true
-                player?.primeForPausedStart()
+                if let player {
+                    MediaPreviewPlayerSession.activate(player)
+                    player.play()
+                }
             }
         }
     }