SubMiner/backlog/tasks/task-27.5 - Split-renderer-positioning.ts-into-focused-modules.md

id, title, status, assignee, created_date, updated_date, labels, dependencies, references, documentation, parent_task_id, priority

id	title	status	assignee	created_date	updated_date	labels	dependencies	references	documentation	parent_task_id	priority
TASK-27.5	Split renderer positioning.ts into focused modules	To Do	frontend	2026-02-13 17:13	2026-02-13 21:17	refactor renderer	TASK-27.1	src/renderer/renderer.ts src/renderer/subtitle-render.ts src/renderer/positioning.ts src/renderer/handlers/keyboard.ts src/renderer/handlers/mouse.ts	docs/architecture.md	TASK-27	low

Description

Split positioning.ts (513 LOC) — the only oversized file in the renderer — into focused modules. The rest of the renderer structure is already well-organized and does not need reorganization.

Current Renderer State (already good)

• renderer.ts (241 lines) — pure composition, well-factored
• state.ts (132 lines), context.ts (14 lines), subtitle-render.ts (206 lines) — reasonable sizes
• handlers/keyboard.ts (238 lines), handlers/mouse.ts (271 lines) — focused
• modals/ — 4 modal implementations, each self-contained
• Communication already uses explicit ctx pattern and function parameters, not globals

What Actually Needs Work

positioning.ts mixes visible overlay positioning, invisible overlay positioning, MPV subtitle render metrics layout, and position persistence. These are distinct concerns that should be separate modules.

Acceptance Criteria

• #1 Split positioning.ts into at least 2 focused modules (e.g., visible-positioning and invisible-positioning, or by concern: layout, persistence, metrics).
• #2 No module exceeds 300 LOC.
• #3 Existing overlay behavior (subtitle positioning, drag, invisible layer metrics) unchanged.
• #4 renderer.ts imports stay clean — use an index re-export if needed.
• #5 Manual validation: subtitle positioning, drag/select, invisible layer alignment all work correctly.

Implementation Notes

Downscope Rationale

Original task proposed creating src/renderer/subtitles/, src/renderer/input/, src/renderer/state/ directories and introducing "explicit interfaces/events for keyboard/mouse/positioning/state updates to avoid global mutable coupling."

Review found:

1. The renderer already uses a ctx composition pattern — no global mutable coupling exists
2. Files are already organized by concern (handlers/, modals/, utils/)
3. Only positioning.ts (513 LOC) exceeds the 400 LOC threshold
4. Creating new directory structures for files under 300 lines adds churn without proportional benefit

Reduced scope to: split positioning.ts only. If future feature work (JLPT tagging, frequency highlighting) adds significant renderer complexity, a broader reorganization can be reconsidered then.