SubMiner/composability.md

SubMiner Composability and Extensibility Plan

Goals

• Reduce coupling concentrated in src/main.ts.
• Make new features additive (new files/modules) instead of invasive (edits across many files).
• Standardize extension points for trackers, subtitle processing, IPC actions, and integrations.
• Preserve existing behavior while incrementally migrating architecture.

Current Constraints (From Existing Code)

• src/main.ts is the effective integration bus (~5k LOC) and mixes lifecycle, IPC, shortcuts, mpv integration, overlay control, and feature flows.
• Input surfaces are fragmented (CLI args, global shortcuts, renderer IPC) and often route through separate logic paths.
• Some extension points already exist (src/window-trackers/*, centralized config definitions in src/config/definitions.ts) but still use hardcoded selection/wiring.
• Type contracts are duplicated between main/preload/renderer in places, which increases drift risk.

Target Architecture

1. Composition Root + Services

• Keep src/main.ts as bootstrap only.
• Move behavior into focused services:
  • src/core/app-orchestrator.ts
  • src/core/services/overlay-service.ts
  • src/core/services/mpv-service.ts
  • src/core/services/shortcut-service.ts
  • src/core/services/ipc-service.ts
  • src/core/services/subtitle-service.ts

2. Module System

• Introduce module contract:
  • src/core/module.ts
  • src/core/module-registry.ts
• Built-in features become modules:
  • anki module
  • jimaku module
  • runtime options module
  • texthooker/websocket module
  • subsync module

3. Action Bus

• Add typed action dispatch (single command path for CLI/shortcut/IPC):
  • src/core/actions.ts (action type map)
  • src/core/action-bus.ts (register/dispatch)
• All triggers emit actions; business logic subscribes once.

4. Provider Registries (Strategy Pattern)

• Replace hardcoded switch/if wiring with registries:
  • tracker providers
  • tokenizer providers
  • translation providers
  • subsync backend providers

5. Shared IPC Contract

• Single source of truth for IPC channels and payloads:
  • src/ipc/contract.ts
  • src/ipc/main-api.ts
  • src/ipc/renderer-api.ts
• preload.ts and renderer consume typed wrappers instead of ad hoc channel strings.

6. Subtitle Pipeline

• Middleware/stage pipeline:
  • ingest -> normalize -> tokenize -> merge -> enrich -> emit
• Files:
  • src/subtitle/pipeline.ts
  • src/subtitle/stages/*.ts

7. Module-Owned Config Extensions

• Keep src/config/definitions.ts as the central resolved output.
• Add registration path so modules can contribute config/runtime option metadata and defaults before final resolution.

Phased Delivery Plan

Phase 0: Baseline and Safety Net

Scope

• Add architecture docs and migration guardrails.
• Increase tests around currently stable behavior before structural changes.

Changes

• Add architecture decision notes:
  • docs/development.md (new section: architecture/migration)
  • docs/architecture.md (new)
• Add basic smoke tests for command routing, overlay visibility toggles, and config load behavior.

Exit Criteria

• Existing behavior documented with acceptance checklist.
• CI/build + config tests green.

Phase 1: Extract I/O Surfaces

Scope

• Isolate IPC and global shortcut registration from src/main.ts without changing semantics.

Changes

• Create:
  • src/core/services/ipc-service.ts
  • src/core/services/shortcut-service.ts
• Move ipcMain.handle/on registration blocks from src/main.ts into IpcService.register(...).
• Move global shortcut registration into ShortcutService.registerGlobal(...).
• Keep old entrypoints in main.ts delegating to new service methods.

Exit Criteria

• No user-visible behavior changes.
• src/main.ts shrinks materially.
• Manual verification:
  • overlay toggles
  • copy/mine shortcuts
  • runtime options open/cycle

Phase 2: Introduce Action Bus

Scope

• Canonicalize command execution path.

Changes

• Add typed action bus (src/core/action-bus.ts, src/core/actions.ts).
• Convert these triggers to dispatch actions instead of direct calls:
  • CLI handling (handleCliCommand path)
  • shortcut handlers
  • IPC command handlers
• Keep existing business functions as subscribers initially.

Exit Criteria

• One action path per command (no duplicated behavior branches).
• Unit tests for command mapping (CLI -> action, shortcut -> action, IPC -> action).

Phase 3: Module Runtime Skeleton

Scope

• Add module contract and migrate one low-risk feature first.

Changes

• Introduce:
  • src/core/module.ts
  • src/core/module-registry.ts
  • src/core/app-context.ts
• First migration target: runtime options
  • create src/modules/runtime-options/module.ts
  • wire existing RuntimeOptionsManager through module lifecycle.

Exit Criteria

• Runtime options fully owned by module.
• Core app can start with module list and deterministic module init order.

Phase 4: Provider Registries

Scope

• Remove hardcoded provider selection.

Changes

• Window tracker:
  • Replace switch in src/window-trackers/index.ts with registry API.
  • Add provider objects for hyprland/sway/x11/macos.
• Tokenizer/translator/subsync:
  • Add analogous registries in new provider directories.

Exit Criteria

• Adding a provider requires adding one file + registration line.
• No edits required in composition root for new provider variants.

Phase 5: Shared IPC Contract

Scope

• Eliminate channel/payload drift between main/preload/renderer.

Changes

• Add typed IPC contract files under src/ipc/.
• Refactor src/preload.ts to generate API from shared contract wrappers.
• Refactor renderer calls to consume typed API interface from shared module.

Exit Criteria

• Channel names declared once.
• Compile-time checking across main/preload/renderer for payload mismatch.

Phase 6: Subtitle Pipeline

Scope

• Extract subtitle transformations into composable stages.

Changes

• Create pipeline framework and migrate existing tokenization/merge flow:
  • stage: normalize subtitle
  • stage: tokenize (MecabTokenizer adapter)
  • stage: merge tokens (mergeTokens adapter)
  • stage: post-processing/enrichment hooks
• Integrate pipeline execution into subtitle update loop.

Exit Criteria

• Current output parity for tokenization/merged token behavior.
• Stage-level tests for deterministic input/output.

Phase 7: Moduleized Integrations

Scope

• Convert major features to modules in descending complexity.

Migration Order

1. Jimaku
2. Texthooker/WebSocket bridge
3. Subsync
4. Anki integration

Exit Criteria

• Each feature has independent init/start/stop lifecycle.
• App startup composes modules instead of hardcoded inline setup.

Recommended File Layout (Target)

src/
  core/
    app-orchestrator.ts
    app-context.ts
    actions.ts
    action-bus.ts
    module.ts
    module-registry.ts
    services/
      ipc-service.ts
      shortcut-service.ts
      overlay-service.ts
      mpv-service.ts
      subtitle-service.ts
  modules/
    runtime-options/module.ts
    jimaku/module.ts
    texthooker/module.ts
    subsync/module.ts
    anki/module.ts
  ipc/
    contract.ts
    main-api.ts
    renderer-api.ts
  subtitle/
    pipeline.ts
    stages/
      normalize.ts
      tokenize-mecab.ts
      merge-default.ts
      enrich.ts

PR Breakdown (Suggested)

1. PR1: Phase 1 (IpcService, ShortcutService, no behavior changes)
2. PR2: Phase 2 (action bus + trigger mapping)
3. PR3: Phase 3 (module skeleton + runtime options module)
4. PR4: Phase 4 (window tracker registry + provider pattern)
5. PR5: Phase 5 (shared IPC contract)
6. PR6: Phase 6 (subtitle pipeline)
7. PR7+: Phase 7 (feature-by-feature module migrations)

Validation Matrix

• Build/typecheck:
  • pnpm run build
• Config correctness:
  • pnpm run test:config
• Manual checks per PR:
  • app start/stop/toggle CLI
  • visible/invisible overlay control
  • global shortcuts
  • subtitle render and token display
  • runtime options open + cycle
  • anki mine flow + update-from-clipboard

Backward Compatibility Rules

• Preserve existing CLI flags and IPC channel behavior during migration.
• Maintain config shape compatibility; only additive changes unless versioned migration is added.
• Keep default behavior equivalent for all supported compositor backends.

Key Risks and Mitigations

• Risk: behavior regressions during extraction.
  • Mitigation: move code verbatim first, refactor second; keep thin delegates in main.ts until stable.
• Risk: module lifecycle race conditions.
  • Mitigation: explicit init order, idempotent start/stop, and startup dependency checks.
• Risk: IPC contract churn breaks renderer.
  • Mitigation: contract wrappers and compile-time types; temporary compatibility adapters.
• Risk: feature coupling around anki/mine flows.
  • Mitigation: defer high-coupling module migrations until action bus and shared app context are stable.

Definition of Done (Program-Level)

• src/main.ts reduced to bootstrap/composition responsibilities.
• New feature prototype can be added as an isolated module with:
  • module file
  • optional provider registration
  • optional config schema registration
  • no invasive edits across unrelated subsystems
• IPC and command routing are single-path and typed.
• Existing user workflows remain intact.