refactor(embedded-mpv): split session controller into focused collaborators [2/7]

[larsemig]

Note

Maintainer rebuild on top of merged #1148. The original decomposition is preserved, while the transparent/native-overlay hooks are intentionally excluded because the frame-copy direction supersedes them.

Step 2 of the revised 7-step shared-controls rollout.

Summary

• Split the embedded-MPV session controller into focused command, session-factory, and stalled-tracking collaborators.
• Keep the decomposition frame-copy-safe: measureBounds remains in the format utilities; embedded-mpv-compositor, attach(), createAttachingSession(), and boundsTick are not shipped.
• Harden asynchronous session replacement and teardown so stale work cannot overwrite or command a newer session.
• Update the canonical embedded-MPV renderer architecture documentation.

Why this shape

The frame-copy implementation in #1169, #1171, and #1175 renders video into a normal DOM canvas. That removes the need for the transparent/native-view overlay and native-fullscreen concepts proposed in #1150 and #1151.

This PR therefore lands only the reusable renderer decomposition and lifecycle safety needed by the replacement embedded-MPV shared-controls PR. It does not switch the current player UI, enable shared controls, add transparent overlay windows, or add native fullscreen.

Changes

• embedded-mpv-command-runner.ts owns transport, track, and recording IPC delegation plus snapshot reconciliation.
• embedded-mpv-session-factory.ts owns pure loading/error placeholders and startup-paint waiting.
• embedded-mpv-stalled-tracker.ts owns the 30-second loading timer.
• EmbeddedMpvSessionController remains the lifecycle coordinator for support probing, prepare/create/load/dispose, frame attachment, bounds sync, and native updates.
• Removed superseded compositor/attachment/bounds-tick APIs and their tests.

Lifecycle hardening

• The constructor support probe remains canonical; startSession() no longer rewrites it after prepare.
• Teardown during session creation, playback load, or frame attachment stops the old asynchronous startup before any late frame/bounds work.
• Command replies are applied only when the current session ID and returned snapshot ID both match the command capture.
• Default recording-folder resolution revalidates the session before issuing recording IPC, preventing a late side effect against a superseded stream.

Validation

• ui-playback: 36 suites / 361 tests passed.
• ui-playback lint passed.
• Web and Electron backend typechecks passed.
• i18n drift, Prettier, diff checks, and max-lines baseline passed.
• Electron smoke E2E: 3/3 passed.
• Local native/frame-copy playback was not runnable in this worktree because the vendored darwin-arm64 MPV runtime is absent; the pushed cross-platform build and Electron E2E jobs provide the runtime/package gate.

Revised rollout

Step	PR	Purpose
1	#1148	Shared engine-agnostic controls core — merged
2	#1149	Frame-copy-safe embedded-MPV controller decomposition
3	planned replacement PR	Embedded MPV adopts shared controls on the frame-copy/DOM path, without transparent windows or native fullscreen
4	#1152	HTML5 adopts shared controls
5	#1153	Video.js adopts shared controls
6	#1154	ArtPlayer adopts shared controls
7	planned rollout PR	Final integration, flags, and rollout validation

#1150 and #1151 are superseded by the frame-copy replacement direction and will be closed with a link to that replacement PR.

Original architecture and decomposition work by @larsemig; maintainer rebuild and hardening by @4gray.

[greptile-apps]

Greptile Summary

This PR refactors the embedded-MPV session controller into smaller collaborators. The main changes are:

• Command IPC moved into a dedicated command runner.
• Loading and error session snapshots moved into a session factory.
• Stalled-loading timer state moved into a stalled tracker.
• Session startup and teardown now guard more async replacement paths.
• Embedded-MPV architecture docs and focused tests were updated.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.ts	Keeps lifecycle coordination while delegating commands, placeholders, and stalled tracking.
libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-command-runner.ts	Adds a command runner that gates IPC replies against the current session id.
libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-factory.ts	Adds pure helpers for loading and error session snapshots.
libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-stalled-tracker.ts	Adds a focused stalled-loading timer helper.
docs/architecture/embedded-mpv-native.md	Documents the new embedded-MPV collaborator split and lifecycle behavior.

_{Reviews (2): Last reviewed commit: "docs(embedded-mpv): clarify renderer saf..." | Re-trigger Greptile}

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 96.83544% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 60.10%. Comparing base (e91cbd5) to head (977fe0c).
⚠️ Report is 1996 commits behind head on master.

Files with missing lines	Patch %	Lines
...mbedded-mpv-player/embedded-mpv-session-factory.ts	78.57%	1 Missing and 2 partials ⚠️
...embedded-mpv-player/embedded-mpv-command-runner.ts	98.90%	0 Missing and 1 partial ⚠️
...dded-mpv-player/embedded-mpv-session-controller.ts	96.87%	0 Missing and 1 partial ⚠️
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

❗ There is a different number of reports uploaded between BASE (e91cbd5) and HEAD (977fe0c). Click for more details.

HEAD has 4 uploads less than BASE

Flag	BASE (e91cbd5)	HEAD (977fe0c)
	4	0

Additional details and impacted files

@@             Coverage Diff             @@
##           master    #1149       +/-   ##
===========================================
- Coverage   71.05%   60.10%   -10.96%     
===========================================
  Files          40      616      +576     
  Lines         691    35551    +34860     
  Branches       87     7989     +7902     
===========================================
+ Hits          491    21368    +20877     
- Misses        176    11184    +11008     
- Partials       24     2999     +2975     

Flag	Coverage Δ
unit	60.10% <96.83%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[4gray]

@greptileai

[4gray]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

Reviewed commit: 977fe0c958

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".