SubMiner/backlog/tasks/task-73 - MPV-plugin-split-into-modules-and-optimize-startup-command-runtime.md

id, title, status, assignee, created_date, labels, dependencies, references, priority

id	title	status	assignee	created_date	labels	dependencies	references	priority
TASK-73	MPV plugin: split into modules and optimize startup/command runtime	In Progress		2026-02-28 20:50			plugin/subminer/main.lua plugin/subminer/bootstrap.lua plugin/subminer/process.lua plugin/subminer/lifecycle.lua plugin/subminer/messages.lua plugin/subminer/ui.lua plugin/subminer/hover.lua plugin/subminer/options.lua plugin/subminer/state.lua plugin/subminer.conf scripts/test-plugin-start-gate.lua scripts/test-plugin-process-start-retries.lua launcher/commands/playback-command.ts launcher/mpv.ts launcher/mpv.test.ts launcher/smoke.e2e.test.ts Makefile package.json docs/mpv-plugin.md docs/installation.md docs/architecture.md README.md	medium

Description

Scope: Replace monolithic plugin/subminer.lua with modular plugin runtime; optimize command execution paths; align install/docs/tests; fix launcher smoke instability.

Delivered behavior:

• Full plugin cutover to plugin/subminer/main.lua + module directory (no runtime compatibility shim with old monolith file).
• Process/control command path moved toward async subprocess usage for non-start actions (stop, toggle, settings, restart stop leg), reducing synchronous blocking in mpv script runtime.
• Startup/runtime loading updated with lazy module initialization via bootstrap proxies.
• Plugin install flow updated to copy plugin/subminer/ directory and remove legacy ~/.config/mpv/scripts/subminer.lua file.
• Added plugin gate script wiring to package scripts (test:plugin:src) and launcher test flow.
• Smoke tests stabilized across sandbox environments where UNIX socket bind can return EPERM while preserving normal-path assertions.
• Playback command cleanup race fixed when mpv exits before exit-listener registration.

Risk/impact context:

• mpv plugin loading path changed from single-file to module directory; packaging/install paths must stay consistent with release assets.
• Async control path changes reduce blocking but can surface timing differences; regression checks added for cold start and launcher smoke behavior.

Final Summary

Startup fixed-sleep removal delivered in launcher + plugin start paths:

• launcher/mpv.ts:startOverlay no longer blocks on hard 2000ms; now uses bounded readiness/event checks:
  • bounded wait for mpv IPC socket readiness
  • bounded wait for spawned overlay command settle (exit/error)
• plugin/subminer/process.lua removed fixed 0.35s texthooker delay and fixed 0.6s startup visibility delay.
• Overlay start now uses short bounded retries on non-ready start failures, then applies startup overlay visibility once start succeeds.

Regression coverage added:

• launcher/mpv.test.ts adds guard that startOverlay resolves quickly when readiness arrives.
• scripts/test-plugin-process-start-retries.lua asserts retry behavior and guards against reintroducing fixed 0.35/0.6 timers.

Validation run:

• bun test launcher/mpv.test.ts pass.
• lua scripts/test-plugin-process-start-retries.lua pass.
• Existing broader plugin gate suite still has unrelated failure in current tree (scripts/test-plugin-start-gate.lua AniSkip async curl assertion).