Merge pull request #8 from ksyasuda/feature/add-sqlite-session-tracking

Add SQLite session tracking with docs updates

.github/workflows/ci.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: pnpm
 
       - name: Install dependencies

config.example.jsonc

@@ -260,5 +260,15 @@
   "anilist": {
     "enabled": false,
     "accessToken": ""
+  },
+
+  // ==========================================
+  // Immersion Tracking
+  // Enable/disable immersion tracking.
+  // Set dbPath to override the default app data path.
+  // ==========================================
+  "immersionTracking": {
+    "enabled": true,
+    "dbPath": ""
   }
 }

docs/configuration.md

@@ -61,6 +61,7 @@ The configuration file includes several main sections:
 - [**Subtitle Style**](#subtitle-style) - Appearance customization
 - [**Texthooker**](#texthooker) - Control browser opening behavior
 - [**WebSocket Server**](#websocket-server) - Built-in subtitle broadcasting server
+- [**Immersion Tracking**](#immersion-tracking) - Track subtitle sessions and mining activity in SQLite
 - [**YouTube Subtitle Generation**](#youtube-subtitle-generation) - Launcher defaults for yt-dlp + local whisper fallback
 
 ### AnkiConnect
@@ -693,6 +694,32 @@ See `config.example.jsonc` for detailed configuration options.
 | `enabled` | `true`, `false`, `"auto"` | `"auto"` (default) disables if mpv_websocket is detected |
 | `port`    | number                    | WebSocket server port (default: 6677)                    |
 
+### Immersion Tracking
+
+Enable or disable local immersion analytics stored in SQLite for mined subtitles and media sessions:
+
+```json
+{
+  "immersionTracking": {
+    "enabled": true,
+    "dbPath": ""
+  }
+}
+```
+
+| Option     | Values                     | Description |
+| ---------- | -------------------------- | ----------- |
+| `enabled`  | `true`, `false`            | Enable immersion tracking. Defaults to `true`. |
+| `dbPath`   | string                     | Optional SQLite database path. Leave empty to use default app-data path at `<config dir>/immersion.sqlite`. |
+
+When `dbPath` is blank or omitted, SubMiner writes telemetry and session summaries to the default app-data location:
+
+```text
+<config directory>/immersion.sqlite
+```
+
+Set `dbPath` only if you want to relocate the database (for backup, syncing, or inspection workflows). The database is created when tracking starts for the first time.
+
 ### YouTube Subtitle Generation
 
 Set defaults used by the `subminer` launcher for YouTube subtitle extraction/transcription:

docs/mining-workflow.md

@@ -192,3 +192,19 @@ When enabled, SubMiner highlights words you already know in your Anki deck, maki
 - **Immersion tracking**: Quickly identify which sentences contain only known words vs. those with new vocabulary
 - **Mining focus**: Target sentences with exactly one unknown word (true N+1)
 - **Progress visualization**: See your growing vocabulary visually represented in real content
+
+### Immersion Tracking Storage
+
+Immersion data is persisted to SQLite when enabled in `immersionTracking`:
+
+```json
+{
+  "immersionTracking": {
+    "enabled": true,
+    "dbPath": ""
+  }
+}
+```
+
+- `dbPath` can be empty (default) to use SubMiner’s app-data `immersion.sqlite`.
+- Set an explicit path to move the database (for backups, cloud syncing, or easier inspection).

docs/public/config.example.jsonc

@@ -46,6 +46,14 @@
     "level": "info"
   },
 
+  // Immersion Tracking
+  // Persist mined subtitle/session telemetry for analytics.
+  // ==========================================
+  "immersionTracking": {
+    "enabled": true,
+    "dbPath": ""
+  },
+
   // ==========================================
   // AnkiConnect Integration
   // Automatic Anki updates and media generation options.

package.json

@@ -14,7 +14,7 @@
     "docs:build": "VITE_EXTRA_EXTENSIONS=jsonc vitepress build docs",
     "docs:preview": "VITE_EXTRA_EXTENSIONS=jsonc vitepress preview docs --host 0.0.0.0 --port 4173 --strictPort",
     "test:config:dist": "node --test dist/config/config.test.js",
-    "test:core:dist": "node --test dist/cli/args.test.js dist/cli/help.test.js dist/core/services/cli-command-service.test.js dist/core/services/field-grouping-overlay-service.test.js dist/core/services/numeric-shortcut-session-service.test.js dist/core/services/secondary-subtitle-service.test.js dist/core/services/mpv-render-metrics-service.test.js dist/core/services/overlay-content-measurement-service.test.js dist/core/services/mpv-control-service.test.js dist/core/services/mpv-service.test.js dist/core/services/runtime-options-ipc-service.test.js dist/core/services/runtime-config-service.test.js dist/core/services/tokenizer-service.test.js dist/core/services/subsync-service.test.js dist/core/services/overlay-bridge-service.test.js dist/core/services/overlay-manager-service.test.js dist/core/services/overlay-shortcut-handler.test.js dist/core/services/mining-service.test.js dist/core/services/anki-jimaku-service.test.js dist/core/services/app-ready-service.test.js dist/core/services/startup-bootstrap-service.test.js dist/subsync/utils.test.js dist/main/anilist-url-guard.test.js",
+    "test:core:dist": "node --test dist/cli/args.test.js dist/cli/help.test.js dist/core/services/cli-command-service.test.js dist/core/services/field-grouping-overlay-service.test.js dist/core/services/numeric-shortcut-session-service.test.js dist/core/services/secondary-subtitle-service.test.js dist/core/services/mpv-render-metrics-service.test.js dist/core/services/overlay-content-measurement-service.test.js dist/core/services/mpv-control-service.test.js dist/core/services/mpv-service.test.js dist/core/services/runtime-options-ipc-service.test.js dist/core/services/runtime-config-service.test.js dist/core/services/tokenizer-service.test.js dist/core/services/subsync-service.test.js dist/core/services/overlay-bridge-service.test.js dist/core/services/overlay-manager-service.test.js dist/core/services/overlay-shortcut-handler.test.js dist/core/services/mining-service.test.js dist/core/services/anki-jimaku-service.test.js dist/core/services/immersion-tracker-service.test.js dist/core/services/app-ready-service.test.js dist/core/services/startup-bootstrap-service.test.js dist/subsync/utils.test.js dist/main/anilist-url-guard.test.js",
     "test:subtitle:dist": "echo \"Subtitle tests are currently not configured\"",
     "test": "pnpm run test:config && pnpm run test:core",
     "test:config": "pnpm run build && pnpm run test:config:dist",

scripts/build-macos-helper.sh

@@ -7,21 +7,48 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 SWIFT_SOURCE="$SCRIPT_DIR/get-mpv-window-macos.swift"
 OUTPUT_DIR="$SCRIPT_DIR/../dist/scripts"
 OUTPUT_BINARY="$OUTPUT_DIR/get-mpv-window-macos"
+OUTPUT_SOURCE_COPY="$OUTPUT_DIR/get-mpv-window-macos.swift"
+
+fallback_to_source() {
+  echo "Falling back to source fallback: $OUTPUT_SOURCE_COPY"
+  mkdir -p "$OUTPUT_DIR"
+  cp "$SWIFT_SOURCE" "$OUTPUT_SOURCE_COPY"
+}
+
+build_swift_helper() {
+  echo "Compiling macOS window tracking helper..."
+  if ! command -v swiftc >/dev/null 2>&1; then
+    echo "swiftc not found in PATH; skipping compilation."
+    return 1
+  fi
+
+  if ! swiftc -O "$SWIFT_SOURCE" -o "$OUTPUT_BINARY"; then
+    return 1
+  fi
+
+  chmod +x "$OUTPUT_BINARY"
+  echo "✓ Built $OUTPUT_BINARY"
+  return 0
+}
+
+# Optional skip flag for non-macOS CI/dev environments
+if [[ "${SUBMINER_SKIP_MACOS_HELPER_BUILD:-}" == "1" ]]; then
+  echo "Skipping macOS helper build (SUBMINER_SKIP_MACOS_HELPER_BUILD=1)"
+  fallback_to_source
+  exit 0
+fi
 
 # Only build on macOS
 if [[ "$(uname)" != "Darwin" ]]; then
   echo "Skipping macOS helper build (not on macOS)"
+  fallback_to_source
   exit 0
 fi
 
 # Create output directory
 mkdir -p "$OUTPUT_DIR"
 
-# Compile Swift script to binary
+# Compile Swift script to binary, fallback to source if unavailable or compilation fails
-echo "Compiling macOS window tracking helper..."
+if ! build_swift_helper; then
-swiftc -O "$SWIFT_SOURCE" -o "$OUTPUT_BINARY"
+  fallback_to_source
-
+fi
-# Make executable
-chmod +x "$OUTPUT_BINARY"
-
-echo "✓ Built $OUTPUT_BINARY"

src/anki-integration.ts

@@ -1054,7 +1054,7 @@ export class AnkiIntegration {
     startTime: number,
     endTime: number,
     secondarySubText?: string,
-  ): Promise<void> {
+  ): Promise<boolean> {
     return this.cardCreationService.createSentenceCard(
       sentence,
       startTime,

src/anki-integration/card-creation.ts

@@ -460,23 +460,23 @@ export class CardCreationService {
     startTime: number,
     endTime: number,
     secondarySubText?: string,
-  ): Promise<void> {
+  ): Promise<boolean> {
     if (this.deps.isUpdateInProgress()) {
       this.deps.showOsdNotification("Anki update already in progress");
-      return;
+      return false;
     }
 
     const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
     const sentenceCardModel = sentenceCardConfig.model;
     if (!sentenceCardModel) {
       this.deps.showOsdNotification("sentenceCardModel not configured");
-      return;
+      return false;
     }
 
     const mpvClient = this.deps.getMpvClient();
     if (!mpvClient || !mpvClient.currentVideoPath) {
       this.deps.showOsdNotification("No video loaded");
-      return;
+      return false;
     }
 
     const maxMediaDuration = this.deps.getConfig().media?.maxMediaDuration ?? 30;
@@ -488,7 +488,8 @@ export class CardCreationService {
     }
 
     this.deps.showOsdNotification("Creating sentence card...");
-    await this.deps.withUpdateProgress("Creating sentence card", async () => {
+    try {
+      return await this.deps.withUpdateProgress("Creating sentence card", async () => {
       const videoPath = mpvClient.currentVideoPath;
       const fields: Record<string, string> = {};
       const errors: string[] = [];
@@ -533,7 +534,7 @@ export class CardCreationService {
         this.deps.showOsdNotification(
           `Sentence card failed: ${(error as Error).message}`,
         );
-        return;
+        return false;
       }
 
       try {
@@ -637,7 +638,18 @@ export class CardCreationService {
       const errorSuffix =
         errors.length > 0 ? `${errors.join(", ")} failed` : undefined;
       await this.deps.showNotification(noteId, label, errorSuffix);
+      return true;
     });
+    } catch (error) {
+      log.error(
+        "Error creating sentence card:",
+        (error as Error).message,
+      );
+      this.deps.showOsdNotification(
+        `Sentence card failed: ${(error as Error).message}`,
+      );
+      return false;
+    }
   }
 
   private getResolvedSentenceAudioFieldName(noteInfo: CardCreationNoteInfo): string | null {

src/config/config.test.ts

@@ -18,6 +18,8 @@ test("loads defaults when config is missing", () => {
   assert.equal(config.websocket.port, DEFAULT_CONFIG.websocket.port);
   assert.equal(config.ankiConnect.behavior.autoUpdateNewCards, true);
   assert.equal(config.anilist.enabled, false);
+  assert.equal(config.immersionTracking.enabled, true);
+  assert.equal(config.immersionTracking.dbPath, undefined);
 });
 
 test("parses anilist.enabled and warns for invalid value", () => {
@@ -43,6 +45,26 @@ test("parses anilist.enabled and warns for invalid value", () => {
   assert.equal(service.getConfig().anilist.enabled, true);
 });
 
+test("accepts immersion tracking config values", () => {
+  const dir = makeTempDir();
+  fs.writeFileSync(
+    path.join(dir, "config.jsonc"),
+    `{
+      "immersionTracking": {
+        "enabled": false,
+        "dbPath": "/tmp/immersions/custom.sqlite"
+      }
+    }`,
+    "utf-8",
+  );
+
+  const service = new ConfigService(dir);
+  const config = service.getConfig();
+
+  assert.equal(config.immersionTracking.enabled, false);
+  assert.equal(config.immersionTracking.dbPath, "/tmp/immersions/custom.sqlite");
+});
+
 test("parses jsonc and warns/falls back on invalid value", () => {
   const dir = makeTempDir();
   fs.writeFileSync(

src/config/definitions.ts

@@ -239,6 +239,9 @@ export const DEFAULT_CONFIG: ResolvedConfig = {
   invisibleOverlay: {
     startupVisibility: "platform-default",
   },
+  immersionTracking: {
+    enabled: true,
+  },
 };
 
 export const DEFAULT_ANKI_CONNECT_CONFIG = DEFAULT_CONFIG.ankiConnect;
@@ -509,6 +512,19 @@ export const CONFIG_OPTION_REGISTRY: ConfigOptionRegistryEntry[] = [
     description:
       "Comma-separated primary subtitle language priority used by the launcher.",
   },
+  {
+    path: "immersionTracking.enabled",
+    kind: "boolean",
+    defaultValue: DEFAULT_CONFIG.immersionTracking.enabled,
+    description: "Enable immersion tracking for mined subtitle metadata.",
+  },
+  {
+    path: "immersionTracking.dbPath",
+    kind: "string",
+    defaultValue: DEFAULT_CONFIG.immersionTracking.dbPath,
+    description:
+      "Optional SQLite database path for immersion tracking. Empty value uses the default app data path.",
+  },
 ];
 
 export const CONFIG_TEMPLATE_SECTIONS: ConfigTemplateSection[] = [
@@ -621,6 +637,14 @@ export const CONFIG_TEMPLATE_SECTIONS: ConfigTemplateSection[] = [
     description: ["Anilist API credentials and update behavior."],
     key: "anilist",
   },
+  {
+    title: "Immersion Tracking",
+    description: [
+      "Enable/disable immersion tracking.",
+      "Set dbPath to override the default sqlite database location.",
+    ],
+    key: "immersionTracking",
+  },
 ];
 
 export function deepCloneConfig(config: ResolvedConfig): ResolvedConfig {

src/config/service.ts

@@ -485,6 +485,32 @@ export class ConfigService {
       );
     }
 
+    if (isObject(src.immersionTracking)) {
+      const enabled = asBoolean(src.immersionTracking.enabled);
+      if (enabled !== undefined) {
+        resolved.immersionTracking.enabled = enabled;
+      } else if (src.immersionTracking.enabled !== undefined) {
+        warn(
+          "immersionTracking.enabled",
+          src.immersionTracking.enabled,
+          resolved.immersionTracking.enabled,
+          "Expected boolean.",
+        );
+      }
+
+      const dbPath = asString(src.immersionTracking.dbPath);
+      if (dbPath !== undefined) {
+        resolved.immersionTracking.dbPath = dbPath;
+      } else if (src.immersionTracking.dbPath !== undefined) {
+        warn(
+          "immersionTracking.dbPath",
+          src.immersionTracking.dbPath,
+          resolved.immersionTracking.dbPath,
+          "Expected string.",
+        );
+      }
+    }
+
     if (isObject(src.subtitleStyle)) {
       resolved.subtitleStyle = {
         ...resolved.subtitleStyle,

src/core/services/app-ready-service.test.ts

@@ -24,6 +24,7 @@ function makeDeps(overrides: Partial<AppReadyRuntimeDeps> = {}) {
       calls.push("createMecabTokenizerAndCheck");
     },
     createSubtitleTimingTracker: () => calls.push("createSubtitleTimingTracker"),
+    createImmersionTracker: () => calls.push("createImmersionTracker"),
     loadYomitanExtension: async () => {
       calls.push("loadYomitanExtension");
     },
@@ -43,6 +44,40 @@ test("runAppReadyRuntimeService starts websocket in auto mode when plugin missin
   await runAppReadyRuntimeService(deps);
   assert.ok(calls.includes("startSubtitleWebsocket:9001"));
   assert.ok(calls.includes("initializeOverlayRuntime"));
+  assert.ok(calls.includes("createImmersionTracker"));
+  assert.ok(
+    calls.includes("log:Runtime ready: invoking createImmersionTracker."),
+  );
+});
+
+test("runAppReadyRuntimeService logs when createImmersionTracker dependency is missing", async () => {
+  const { deps, calls } = makeDeps({
+    createImmersionTracker: undefined,
+  });
+  await runAppReadyRuntimeService(deps);
+  assert.ok(
+    calls.includes(
+      "log:Runtime ready: createImmersionTracker dependency is missing.",
+    ),
+  );
+});
+
+test("runAppReadyRuntimeService logs and continues when createImmersionTracker throws", async () => {
+  const { deps, calls } = makeDeps({
+    createImmersionTracker: () => {
+      calls.push("createImmersionTracker");
+      throw new Error("immersion init failed");
+    },
+  });
+  await runAppReadyRuntimeService(deps);
+  assert.ok(calls.includes("createImmersionTracker"));
+  assert.ok(
+    calls.includes(
+      "log:Runtime ready: createImmersionTracker failed: immersion init failed",
+    ),
+  );
+  assert.ok(calls.includes("initializeOverlayRuntime"));
+  assert.ok(calls.includes("handleInitialArgs"));
 });
 
 test("runAppReadyRuntimeService logs defer message when overlay not auto-started", async () => {

src/core/services/immersion-tracker-service.test.ts

@@ -0,0 +1,371 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { ImmersionTrackerService } from "./immersion-tracker-service";
+
+function makeDbPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "subminer-immersion-test-"));
+  return path.join(dir, "immersion.sqlite");
+}
+
+function cleanupDbPath(dbPath: string): void {
+  const dir = path.dirname(dbPath);
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("startSession generates UUID-like session identifiers", () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+
+  try {
+    tracker = new ImmersionTrackerService({ dbPath });
+    tracker.handleMediaChange("/tmp/episode.mkv", "Episode");
+
+    const privateApi = tracker as unknown as {
+      flushTelemetry: (force?: boolean) => void;
+      flushNow: () => void;
+    };
+    privateApi.flushTelemetry(true);
+    privateApi.flushNow();
+
+    const db = new DatabaseSync(dbPath);
+    const row = db
+      .prepare("SELECT session_uuid FROM imm_sessions LIMIT 1")
+      .get() as { session_uuid: string } | null;
+    db.close();
+
+    assert.equal(typeof row?.session_uuid, "string");
+    assert.equal(row?.session_uuid?.startsWith("session-"), false);
+    assert.ok(/^[0-9a-fA-F-]{36}$/.test(row?.session_uuid || ""));
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test("destroy finalizes active session and persists final telemetry", () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+
+  try {
+    tracker = new ImmersionTrackerService({ dbPath });
+
+    tracker.handleMediaChange("/tmp/episode-2.mkv", "Episode 2");
+    tracker.recordSubtitleLine("Hello immersion", 0, 1);
+    tracker.destroy();
+
+    const db = new DatabaseSync(dbPath);
+    const sessionRow = db
+      .prepare("SELECT ended_at_ms FROM imm_sessions LIMIT 1")
+      .get() as { ended_at_ms: number | null } | null;
+    const telemetryCountRow = db
+      .prepare("SELECT COUNT(*) AS total FROM imm_session_telemetry")
+      .get() as { total: number };
+    db.close();
+
+    assert.ok(sessionRow);
+    assert.ok(Number(sessionRow?.ended_at_ms ?? 0) > 0);
+    assert.ok(Number(telemetryCountRow.total) >= 2);
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test("monthly rollups are grouped by calendar month", async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+
+  try {
+    tracker = new ImmersionTrackerService({ dbPath });
+    const privateApi = tracker as unknown as {
+      db: DatabaseSync;
+      runRollupMaintenance: () => void;
+    };
+
+    const januaryStartedAtMs = Date.UTC(2026, 0, 31, 23, 59, 59, 0);
+    const februaryStartedAtMs = Date.UTC(2026, 1, 1, 0, 0, 1, 0);
+
+    privateApi.db.exec(`
+      INSERT INTO imm_videos (
+        video_id,
+        video_key,
+        canonical_title,
+        source_type,
+        duration_ms,
+        created_at_ms,
+        updated_at_ms
+      ) VALUES (
+        1,
+        'local:/tmp/video.mkv',
+        'Episode',
+        1,
+        0,
+        ${januaryStartedAtMs},
+        ${januaryStartedAtMs}
+      )
+    `);
+
+    privateApi.db.exec(`
+      INSERT INTO imm_sessions (
+        session_id,
+        session_uuid,
+        video_id,
+        started_at_ms,
+        status,
+        created_at_ms,
+        updated_at_ms,
+        ended_at_ms
+      ) VALUES (
+        1,
+        '11111111-1111-1111-1111-111111111111',
+        1,
+        ${januaryStartedAtMs},
+        2,
+        ${januaryStartedAtMs},
+        ${januaryStartedAtMs},
+        ${januaryStartedAtMs + 5000}
+      )
+    `);
+    privateApi.db.exec(`
+      INSERT INTO imm_session_telemetry (
+        session_id,
+        sample_ms,
+        total_watched_ms,
+        active_watched_ms,
+        lines_seen,
+        words_seen,
+        tokens_seen,
+        cards_mined,
+        lookup_count,
+        lookup_hits,
+        pause_count,
+        pause_ms,
+        seek_forward_count,
+        seek_backward_count,
+        media_buffer_events
+      ) VALUES (
+        1,
+        ${januaryStartedAtMs + 1000},
+        5000,
+        5000,
+        1,
+        2,
+        2,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0
+      )
+    `);
+
+    privateApi.db.exec(`
+      INSERT INTO imm_sessions (
+        session_id,
+        session_uuid,
+        video_id,
+        started_at_ms,
+        status,
+        created_at_ms,
+        updated_at_ms,
+        ended_at_ms
+      ) VALUES (
+        2,
+        '22222222-2222-2222-2222-222222222222',
+        1,
+        ${februaryStartedAtMs},
+        2,
+        ${februaryStartedAtMs},
+        ${februaryStartedAtMs},
+        ${februaryStartedAtMs + 5000}
+      )
+    `);
+    privateApi.db.exec(`
+      INSERT INTO imm_session_telemetry (
+        session_id,
+        sample_ms,
+        total_watched_ms,
+        active_watched_ms,
+        lines_seen,
+        words_seen,
+        tokens_seen,
+        cards_mined,
+        lookup_count,
+        lookup_hits,
+        pause_count,
+        pause_ms,
+        seek_forward_count,
+        seek_backward_count,
+        media_buffer_events
+      ) VALUES (
+        2,
+        ${februaryStartedAtMs + 1000},
+        4000,
+        4000,
+        2,
+        3,
+        3,
+        1,
+        1,
+        1,
+        0,
+        0,
+        0,
+        0,
+        0
+      )
+    `);
+
+    privateApi.runRollupMaintenance();
+
+    const rows = await tracker.getMonthlyRollups(10);
+    const videoRows = rows.filter((row) => row.videoId === 1);
+
+    assert.equal(videoRows.length, 2);
+    assert.equal(videoRows[0].rollupDayOrMonth, 202602);
+    assert.equal(videoRows[1].rollupDayOrMonth, 202601);
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test("flushSingle reuses cached prepared statements", () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+  let originalPrepare: DatabaseSync["prepare"] | null = null;
+
+  try {
+    tracker = new ImmersionTrackerService({ dbPath });
+    const privateApi = tracker as unknown as {
+      db: DatabaseSync;
+      flushSingle: (write: {
+        kind: "telemetry" | "event";
+        sessionId: number;
+        sampleMs: number;
+        eventType?: number;
+        lineIndex?: number | null;
+        segmentStartMs?: number | null;
+        segmentEndMs?: number | null;
+        wordsDelta?: number;
+        cardsDelta?: number;
+        payloadJson?: string | null;
+        totalWatchedMs?: number;
+        activeWatchedMs?: number;
+        linesSeen?: number;
+        wordsSeen?: number;
+        tokensSeen?: number;
+        cardsMined?: number;
+        lookupCount?: number;
+        lookupHits?: number;
+        pauseCount?: number;
+        pauseMs?: number;
+        seekForwardCount?: number;
+        seekBackwardCount?: number;
+        mediaBufferEvents?: number;
+      }) => void;
+    };
+
+    originalPrepare = privateApi.db.prepare;
+    let prepareCalls = 0;
+    privateApi.db.prepare = (...args: Parameters<DatabaseSync["prepare"]>) => {
+      prepareCalls += 1;
+      return originalPrepare!.apply(privateApi.db, args);
+    };
+    const preparedRestore = originalPrepare;
+
+    privateApi.db.exec(`
+      INSERT INTO imm_videos (
+        video_id,
+        video_key,
+        canonical_title,
+        source_type,
+        duration_ms,
+        created_at_ms,
+        updated_at_ms
+      ) VALUES (
+        1,
+        'local:/tmp/prepared.mkv',
+        'Prepared',
+        1,
+        0,
+        1000,
+        1000
+      )
+    `);
+
+    privateApi.db.exec(`
+      INSERT INTO imm_sessions (
+        session_id,
+        session_uuid,
+        video_id,
+        started_at_ms,
+        status,
+        created_at_ms,
+        updated_at_ms,
+        ended_at_ms
+      ) VALUES (
+        1,
+        '33333333-3333-3333-3333-333333333333',
+        1,
+        1000,
+        2,
+        1000,
+        1000,
+        2000
+      )
+    `);
+
+    privateApi.flushSingle({
+      kind: "telemetry",
+      sessionId: 1,
+      sampleMs: 1500,
+      totalWatchedMs: 1000,
+      activeWatchedMs: 1000,
+      linesSeen: 1,
+      wordsSeen: 2,
+      tokensSeen: 2,
+      cardsMined: 0,
+      lookupCount: 0,
+      lookupHits: 0,
+      pauseCount: 0,
+      pauseMs: 0,
+      seekForwardCount: 0,
+      seekBackwardCount: 0,
+      mediaBufferEvents: 0,
+    });
+
+    privateApi.flushSingle({
+      kind: "event",
+      sessionId: 1,
+      sampleMs: 1600,
+      eventType: 1,
+      lineIndex: 1,
+      segmentStartMs: 0,
+      segmentEndMs: 1000,
+      wordsDelta: 2,
+      cardsDelta: 0,
+      payloadJson: '{"event":"subtitle-line"}',
+    });
+
+    privateApi.db.prepare = preparedRestore;
+
+    assert.equal(prepareCalls, 0);
+  } finally {
+    if (tracker && originalPrepare) {
+      const privateApi = tracker as unknown as { db: DatabaseSync };
+      privateApi.db.prepare = originalPrepare;
+    }
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});

src/core/services/index.ts

@@ -89,6 +89,7 @@ export {
 } from "./mpv-render-metrics-service";
 export { createOverlayContentMeasurementStoreService } from "./overlay-content-measurement-service";
 export { handleMpvCommandFromIpcService } from "./ipc-command-service";
+export { ImmersionTrackerService } from "./immersion-tracker-service";
 export { createFieldGroupingOverlayRuntimeService } from "./field-grouping-overlay-service";
 export { createNumericShortcutRuntimeService } from "./numeric-shortcut-service";
 export { runStartupBootstrapRuntimeService } from "./startup-service";

src/core/services/mining-service.test.ts

@@ -52,19 +52,23 @@ test("copyCurrentSubtitleService copies current subtitle text", () => {
 test("mineSentenceCardService handles missing integration and disconnected mpv", async () => {
   const osd: string[] = [];
 
-  await mineSentenceCardService({
+  assert.equal(
+    await mineSentenceCardService({
     ankiIntegration: null,
     mpvClient: null,
     showMpvOsd: (text) => osd.push(text),
-  });
+    }),
+    false,
+  );
   assert.equal(osd.at(-1), "AnkiConnect integration not enabled");
 
-  await mineSentenceCardService({
+    assert.equal(
+    await mineSentenceCardService({
     ankiIntegration: {
       updateLastAddedFromClipboard: async () => {},
       triggerFieldGroupingForLastAddedCard: async () => {},
       markLastCardAsAudioCard: async () => {},
-      createSentenceCard: async () => {},
+      createSentenceCard: async () => false,
     },
     mpvClient: {
       connected: false,
@@ -73,7 +77,9 @@ test("mineSentenceCardService handles missing integration and disconnected mpv",
       currentSubEnd: 2,
     },
     showMpvOsd: (text) => osd.push(text),
-  });
+    }),
+    false,
+  );
 
   assert.equal(osd.at(-1), "MPV not connected");
 });
@@ -86,13 +92,14 @@ test("mineSentenceCardService creates sentence card from mpv subtitle state", as
     secondarySub?: string;
   }> = [];
 
-  await mineSentenceCardService({
+  const createdCard = await mineSentenceCardService({
     ankiIntegration: {
       updateLastAddedFromClipboard: async () => {},
       triggerFieldGroupingForLastAddedCard: async () => {},
       markLastCardAsAudioCard: async () => {},
       createSentenceCard: async (sentence, startTime, endTime, secondarySub) => {
         created.push({ sentence, startTime, endTime, secondarySub });
+        return true;
       },
     },
     mpvClient: {
@@ -105,6 +112,7 @@ test("mineSentenceCardService creates sentence card from mpv subtitle state", as
     showMpvOsd: () => {},
   });
 
+  assert.equal(createdCard, true);
   assert.deepEqual(created, [
     {
       sentence: "subtitle line",
@@ -136,6 +144,7 @@ test("handleMultiCopyDigitService copies available history and reports truncatio
 test("handleMineSentenceDigitService reports async create failures", async () => {
   const osd: string[] = [];
   const logs: Array<{ message: string; err: unknown }> = [];
+  let cardsMined = 0;
 
   handleMineSentenceDigitService(2, {
     subtitleTimingTracker: {
@@ -157,6 +166,9 @@ test("handleMineSentenceDigitService reports async create failures", async () =>
     getCurrentSecondarySubText: () => "sub2",
     showMpvOsd: (text) => osd.push(text),
     logError: (message, err) => logs.push({ message, err }),
+    onCardsMined: (count) => {
+      cardsMined += count;
+    },
   });
 
   await new Promise((resolve) => setImmediate(resolve));
@@ -165,4 +177,37 @@ test("handleMineSentenceDigitService reports async create failures", async () =>
   assert.equal(logs[0]?.message, "mineSentenceMultiple failed:");
   assert.equal((logs[0]?.err as Error).message, "mine boom");
   assert.ok(osd.some((entry) => entry.includes("Mine sentence failed: mine boom")));
+  assert.equal(cardsMined, 0);
+});
+
+test("handleMineSentenceDigitService increments successful card count", async () => {
+  const osd: string[] = [];
+  let cardsMined = 0;
+
+  handleMineSentenceDigitService(2, {
+    subtitleTimingTracker: {
+      getRecentBlocks: () => ["one", "two"],
+      getCurrentSubtitle: () => null,
+      findTiming: (text) =>
+        text === "one"
+          ? { startTime: 1, endTime: 3 }
+          : { startTime: 4, endTime: 7 },
+    },
+    ankiIntegration: {
+      updateLastAddedFromClipboard: async () => {},
+      triggerFieldGroupingForLastAddedCard: async () => {},
+      markLastCardAsAudioCard: async () => {},
+      createSentenceCard: async () => true,
+    },
+    getCurrentSecondarySubText: () => "sub2",
+    showMpvOsd: (text) => osd.push(text),
+    logError: () => {},
+    onCardsMined: (count) => {
+      cardsMined += count;
+    },
+  });
+
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.equal(cardsMined, 1);
 });

src/core/services/mining-service.ts

@@ -13,7 +13,7 @@ interface AnkiIntegrationLike {
     startTime: number,
     endTime: number,
     secondarySub?: string,
-  ) => Promise<void>;
+  ) => Promise<boolean>;
 }
 
 interface MpvClientLike {
@@ -111,21 +111,21 @@ export async function mineSentenceCardService(deps: {
   ankiIntegration: AnkiIntegrationLike | null;
   mpvClient: MpvClientLike | null;
   showMpvOsd: (text: string) => void;
-}): Promise<void> {
+}): Promise<boolean> {
   const anki = requireAnkiIntegration(deps.ankiIntegration, deps.showMpvOsd);
-  if (!anki) return;
+  if (!anki) return false;
 
   const mpvClient = deps.mpvClient;
   if (!mpvClient || !mpvClient.connected) {
     deps.showMpvOsd("MPV not connected");
-    return;
+    return false;
   }
   if (!mpvClient.currentSubText) {
     deps.showMpvOsd("No current subtitle");
-    return;
+    return false;
   }
 
-  await anki.createSentenceCard(
+  return await anki.createSentenceCard(
     mpvClient.currentSubText,
     mpvClient.currentSubStart,
     mpvClient.currentSubEnd,
@@ -141,6 +141,7 @@ export function handleMineSentenceDigitService(
     getCurrentSecondarySubText: () => string | undefined;
     showMpvOsd: (text: string) => void;
     logError: (message: string, err: unknown) => void;
+    onCardsMined?: (count: number) => void;
   },
 ): void {
   if (!deps.subtitleTimingTracker || !deps.ankiIntegration) return;
@@ -165,6 +166,7 @@ export function handleMineSentenceDigitService(
   const rangeStart = Math.min(...timings.map((t) => t.startTime));
   const rangeEnd = Math.max(...timings.map((t) => t.endTime));
   const sentence = blocks.join(" ");
+  const cardsToMine = 1;
   deps.ankiIntegration
     .createSentenceCard(
       sentence,
@@ -172,6 +174,11 @@ export function handleMineSentenceDigitService(
       rangeEnd,
       deps.getCurrentSecondarySubText(),
     )
+    .then((created) => {
+      if (created) {
+        deps.onCardsMined?.(cardsToMine);
+      }
+    })
     .catch((err) => {
       deps.logError("mineSentenceMultiple failed:", err);
       deps.showMpvOsd(`Mine sentence failed: ${(err as Error).message}`);

src/core/services/mpv-properties.ts

@@ -21,6 +21,7 @@ import {
   MPV_REQUEST_ID_SUBTEXT,
   MPV_REQUEST_ID_SUBTEXT_ASS,
   MPV_REQUEST_ID_SUB_USE_MARGINS,
+  MPV_REQUEST_ID_PAUSE,
 } from "./mpv-protocol";
 
 type MpvProtocolCommand = {
@@ -57,6 +58,7 @@ const MPV_SUBTITLE_PROPERTY_OBSERVATIONS: string[] = [
   "sub-shadow-offset",
   "sub-ass-override",
   "sub-use-margins",
+  "pause",
   "media-title",
 ];
 
@@ -76,6 +78,10 @@ const MPV_INITIAL_PROPERTY_REQUESTS: Array<MpvProtocolCommand> = [
   {
     command: ["get_property", "media-title"],
   },
+  {
+    command: ["get_property", "pause"],
+    request_id: MPV_REQUEST_ID_PAUSE,
+  },
   {
     command: ["get_property", "secondary-sub-text"],
     request_id: MPV_REQUEST_ID_SECONDARY_SUBTEXT,

src/core/services/mpv-protocol.test.ts

@@ -84,6 +84,8 @@ function createDeps(overrides: Partial<MpvProtocolHandleMessageDeps> = {}): {
       setPendingPauseAtSubEnd: () => {},
       getPauseAtTime: () => null,
       setPauseAtTime: () => {},
+      emitTimePosChange: () => {},
+      emitPauseChange: () => {},
       autoLoadSecondarySubTrack: () => {},
       setCurrentVideoPath: () => {},
       emitSecondarySubtitleVisibility: (payload) => state.events.push(payload),

src/core/services/mpv-protocol.ts

@@ -30,6 +30,7 @@ export const MPV_REQUEST_ID_SUB_BORDER_SIZE = 119;
 export const MPV_REQUEST_ID_SUB_SHADOW_OFFSET = 120;
 export const MPV_REQUEST_ID_SUB_ASS_OVERRIDE = 121;
 export const MPV_REQUEST_ID_SUB_USE_MARGINS = 122;
+export const MPV_REQUEST_ID_PAUSE = 123;
 export const MPV_REQUEST_ID_TRACK_LIST_SECONDARY = 200;
 export const MPV_REQUEST_ID_TRACK_LIST_AUDIO = 201;
 
@@ -60,6 +61,8 @@ export interface MpvProtocolHandleMessageDeps {
   getCurrentSubEnd: () => number;
   emitMediaPathChange: (payload: { path: string }) => void;
   emitMediaTitleChange: (payload: { title: string | null }) => void;
+  emitTimePosChange: (payload: { time: number }) => void;
+  emitPauseChange: (payload: { paused: boolean }) => void;
   emitSubtitleMetricsChange: (payload: Partial<MpvSubtitleRenderMetrics>) => void;
   setCurrentSecondarySubText: (text: string) => void;
   resolvePendingRequest: (requestId: number, message: MpvMessage) => boolean;
@@ -160,6 +163,7 @@ export async function dispatchMpvProtocolMessage(
       );
       deps.syncCurrentAudioStreamIndex();
     } else if (msg.name === "time-pos") {
+      deps.emitTimePosChange({ time: (msg.data as number) || 0 });
       deps.setCurrentTimePos((msg.data as number) || 0);
       if (
         deps.getPauseAtTime() !== null &&
@@ -168,6 +172,8 @@ export async function dispatchMpvProtocolMessage(
         deps.setPauseAtTime(null);
         deps.sendCommand({ command: ["set_property", "pause", true] });
       }
+    } else if (msg.name === "pause") {
+      deps.emitPauseChange({ paused: asBoolean(msg.data, false) });
     } else if (msg.name === "media-title") {
       deps.emitMediaTitleChange({
         title: typeof msg.data === "string" ? msg.data.trim() : null,
@@ -348,6 +354,8 @@ export async function dispatchMpvProtocolMessage(
           deps.getSubtitleMetrics().subUseMargins,
         ),
       });
+    } else if (msg.request_id === MPV_REQUEST_ID_PAUSE) {
+      deps.emitPauseChange({ paused: asBoolean(msg.data, false) });
     } else if (msg.request_id === MPV_REQUEST_ID_OSD_HEIGHT) {
       deps.emitSubtitleMetricsChange({ osdHeight: msg.data as number });
     } else if (msg.request_id === MPV_REQUEST_ID_OSD_DIMENSIONS) {

src/core/services/mpv-service.ts

@@ -117,6 +117,8 @@ export interface MpvIpcClientEventMap {
   "subtitle-change": { text: string; isOverlayVisible: boolean };
   "subtitle-ass-change": { text: string };
   "subtitle-timing": { text: string; start: number; end: number };
+  "time-pos-change": { time: number };
+  "pause-change": { paused: boolean };
   "secondary-subtitle-change": { text: string };
   "media-path-change": { path: string };
   "media-title-change": { title: string | null };
@@ -258,9 +260,13 @@ export class MpvIpcClient implements MpvClient {
 
   connect(): void {
     if (this.connected || this.connecting) {
+      logger.debug(
+        `MPV IPC connect request skipped; connected=${this.connected}, connecting=${this.connecting}`,
+      );
       return;
     }
 
+    logger.info("MPV IPC connect requested.");
     this.connecting = true;
     this.transport.connect();
   }
@@ -313,6 +319,12 @@ export class MpvIpcClient implements MpvClient {
       emitSubtitleTiming: (payload) => {
         this.emit("subtitle-timing", payload);
       },
+      emitTimePosChange: (payload) => {
+        this.emit("time-pos-change", payload);
+      },
+      emitPauseChange: (payload) => {
+        this.emit("pause-change", payload);
+      },
       emitSecondarySubtitleChange: (payload) => {
         this.emit("secondary-subtitle-change", payload);
       },

src/core/services/startup-service.ts

@@ -99,6 +99,7 @@ export interface AppReadyRuntimeDeps {
   log: (message: string) => void;
   createMecabTokenizerAndCheck: () => Promise<void>;
   createSubtitleTimingTracker: () => void;
+  createImmersionTracker?: () => void;
   loadYomitanExtension: () => Promise<void>;
   texthookerOnlyMode: boolean;
   shouldAutoInitializeOverlayRuntimeFromConfig: () => boolean;
@@ -173,6 +174,16 @@ export async function runAppReadyRuntimeService(
   }
 
   deps.createSubtitleTimingTracker();
+  if (deps.createImmersionTracker) {
+    deps.log("Runtime ready: invoking createImmersionTracker.");
+    try {
+      deps.createImmersionTracker();
+    } catch (error) {
+      deps.log(`Runtime ready: createImmersionTracker failed: ${(error as Error).message}`);
+    }
+  } else {
+    deps.log("Runtime ready: createImmersionTracker dependency is missing.");
+  }
   await deps.loadYomitanExtension();
 
   if (deps.texthookerOnlyMode) {

src/main.ts

@@ -113,6 +113,7 @@ import {
   markLastCardAsAudioCardService,
   DEFAULT_MPV_SUBTITLE_RENDER_METRICS,
   mineSentenceCardService,
+  ImmersionTrackerService,
   openYomitanSettingsWindow,
   playNextSubtitleRuntimeService,
   registerGlobalShortcutsService,
@@ -262,6 +263,7 @@ function resolveConfigDir(): string {
 const CONFIG_DIR = resolveConfigDir();
 const USER_DATA_PATH = CONFIG_DIR;
 const DEFAULT_MPV_LOG_PATH = process.env.SUBMINER_MPV_LOG?.trim() || DEFAULT_MPV_LOG_FILE;
+const DEFAULT_IMMERSION_DB_PATH = path.join(USER_DATA_PATH, "immersion.sqlite");
 const configService = new ConfigService(CONFIG_DIR);
 const anilistTokenStore = createAnilistTokenStore(
   path.join(USER_DATA_PATH, ANILIST_TOKEN_STORE_FILE),
@@ -580,6 +582,68 @@ function openRuntimeOptionsPalette(): void {
 }
 
 function getResolvedConfig() { return configService.getConfig(); }
+function getConfiguredImmersionDbPath(): string {
+  const configuredDbPath = getResolvedConfig().immersionTracking?.dbPath?.trim();
+  return configuredDbPath
+    ? configuredDbPath
+    : DEFAULT_IMMERSION_DB_PATH;
+}
+
+let isImmersionTrackerMediaSeedInProgress = false;
+
+type ImmersionMediaState = {
+  path: string | null;
+  title: string | null;
+};
+
+async function readMpvPropertyAsString(
+  mpvClient: MpvIpcClient | null | undefined,
+  propertyName: string,
+): Promise<string | null> {
+  if (!mpvClient) {
+    return null;
+  }
+  try {
+    const value = await mpvClient.requestProperty(propertyName);
+    return typeof value === "string" ? value.trim() || null : null;
+  } catch {
+    return null;
+  }
+}
+
+async function getCurrentMpvMediaStateForTracker(): Promise<ImmersionMediaState> {
+  const statePath = appState.currentMediaPath?.trim() || null;
+  if (statePath) {
+    return {
+      path: statePath,
+      title: appState.currentMediaTitle?.trim() || null,
+    };
+  }
+
+  const mpvClient = appState.mpvClient;
+  const trackedPath = mpvClient?.currentVideoPath?.trim() || null;
+  if (trackedPath) {
+    return {
+      path: trackedPath,
+      title: appState.currentMediaTitle?.trim() || null,
+    };
+  }
+
+  const [pathFromProperty, filenameFromProperty, titleFromProperty] =
+    await Promise.all([
+      readMpvPropertyAsString(mpvClient, "path"),
+      readMpvPropertyAsString(mpvClient, "filename"),
+      readMpvPropertyAsString(mpvClient, "media-title"),
+    ]);
+
+  const resolvedPath = pathFromProperty || filenameFromProperty || null;
+  const resolvedTitle = appState.currentMediaTitle?.trim() || titleFromProperty || null;
+
+  return {
+    path: resolvedPath,
+    title: resolvedTitle,
+  };
+}
 
 function getInitialInvisibleOverlayVisibility(): boolean {
   return getInitialInvisibleOverlayVisibilityService(
@@ -609,6 +673,83 @@ function getJimakuMaxEntryResults(): number { return getJimakuMaxEntryResultsSer
 
 async function resolveJimakuApiKey(): Promise<string | null> { return resolveJimakuApiKeyService(() => getResolvedConfig()); }
 
+function seedImmersionTrackerFromCurrentMedia(): void {
+  const tracker = appState.immersionTracker;
+  if (!tracker) {
+    logger.debug("Immersion tracker seeding skipped: tracker not initialized.");
+    return;
+  }
+  if (isImmersionTrackerMediaSeedInProgress) {
+    logger.debug(
+      "Immersion tracker seeding already in progress; skipping duplicate call.",
+    );
+    return;
+  }
+  logger.debug("Starting immersion tracker media-state seed loop.");
+  isImmersionTrackerMediaSeedInProgress = true;
+
+  void (async () => {
+    const waitMs = 250;
+    const attempts = 120;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      const mediaState = await getCurrentMpvMediaStateForTracker();
+      if (mediaState.path) {
+        logger.info(
+          `Seeded immersion tracker media state at attempt ${attempt + 1}/${attempts}: ` +
+            `${mediaState.path}`,
+        );
+        tracker.handleMediaChange(mediaState.path, mediaState.title);
+        return;
+      }
+
+      const mpvClient = appState.mpvClient;
+      if (!mpvClient || !mpvClient.connected) {
+        await new Promise((resolve) => setTimeout(resolve, waitMs));
+        continue;
+      }
+      if (attempt < attempts - 1) {
+        await new Promise((resolve) => setTimeout(resolve, waitMs));
+      }
+    }
+
+    logger.info(
+      "Immersion tracker seed failed: media path still unavailable after startup warmup",
+    );
+  })().finally(() => {
+    isImmersionTrackerMediaSeedInProgress = false;
+  });
+}
+
+function syncImmersionTrackerFromCurrentMediaState(): void {
+  const tracker = appState.immersionTracker;
+  if (!tracker) {
+    logger.debug(
+      "Immersion tracker sync skipped: tracker not initialized yet.",
+    );
+    return;
+  }
+
+  const pathFromState = appState.currentMediaPath?.trim() || appState.mpvClient?.currentVideoPath?.trim();
+  if (pathFromState) {
+    logger.debug(
+      "Immersion tracker sync using path from current media state.",
+    );
+    tracker.handleMediaChange(pathFromState, appState.currentMediaTitle);
+    return;
+  }
+
+  if (!isImmersionTrackerMediaSeedInProgress) {
+    logger.debug(
+      "Immersion tracker sync did not find media path; starting seed loop.",
+    );
+    seedImmersionTrackerFromCurrentMedia();
+  } else {
+    logger.debug(
+      "Immersion tracker sync found seed loop already running.",
+    );
+  }
+}
+
 async function jimakuFetchJson<T>(
   endpoint: string,
   query: Record<string, string | number | boolean | null | undefined> = {},
@@ -1176,6 +1317,32 @@ const startupState = runStartupBootstrapRuntimeService(
           const tracker = new SubtitleTimingTracker();
           appState.subtitleTimingTracker = tracker;
         },
+        createImmersionTracker: () => {
+          const config = getResolvedConfig();
+          if (config.immersionTracking?.enabled === false) {
+            logger.info("Immersion tracking disabled in config");
+            return;
+          }
+          try {
+            logger.debug(
+              "Immersion tracker startup requested: creating tracker service.",
+            );
+            const dbPath = getConfiguredImmersionDbPath();
+            logger.info(`Creating immersion tracker with dbPath=${dbPath}`);
+            appState.immersionTracker = new ImmersionTrackerService({
+              dbPath,
+            });
+            logger.debug("Immersion tracker initialized successfully.");
+            if (appState.mpvClient && !appState.mpvClient.connected) {
+              logger.info("Auto-connecting MPV client for immersion tracking");
+              appState.mpvClient.connect();
+            }
+            seedImmersionTrackerFromCurrentMedia();
+          } catch (error) {
+            logger.warn("Immersion tracker startup failed; disabling tracking.", error);
+            appState.immersionTracker = null;
+          }
+        },
         loadYomitanExtension: async () => {
           await loadYomitanExtension();
         },
@@ -1208,6 +1375,10 @@ const startupState = runStartupBootstrapRuntimeService(
         if (appState.subtitleTimingTracker) {
           appState.subtitleTimingTracker.destroy();
         }
+        if (appState.immersionTracker) {
+          appState.immersionTracker.destroy();
+          appState.immersionTracker = null;
+        }
         if (appState.ankiIntegration) {
           appState.ankiIntegration.destroy();
         }
@@ -1292,6 +1463,15 @@ function handleCliCommand(
 
 function handleInitialArgs(): void {
   if (!appState.initialArgs) return;
+  if (
+    !appState.texthookerOnlyMode &&
+    appState.immersionTracker &&
+    appState.mpvClient &&
+    !appState.mpvClient.connected
+  ) {
+    logger.info("Auto-connecting MPV client for immersion tracking");
+    appState.mpvClient.connect();
+  }
   handleCliCommand(appState.initialArgs, "initial");
 }
 
@@ -1314,9 +1494,14 @@ function bindMpvClientEventHandlers(mpvClient: MpvIpcClient): void {
     broadcastToOverlayWindows("secondary-subtitle:set", text);
   });
   mpvClient.on("subtitle-timing", ({ text, start, end }) => {
-    if (text.trim() && appState.subtitleTimingTracker) {
+    if (!text.trim()) {
-      appState.subtitleTimingTracker.recordSubtitle(text, start, end);
+      return;
     }
+    appState.immersionTracker?.recordSubtitleLine(text, start, end);
+    if (!appState.subtitleTimingTracker) {
+      return;
+    }
+    appState.subtitleTimingTracker.recordSubtitle(text, start, end);
     void maybeRunAnilistPostWatchUpdate().catch((error) => {
       logger.error("AniList post-watch update failed unexpectedly", error);
     });
@@ -1329,11 +1514,20 @@ function bindMpvClientEventHandlers(mpvClient: MpvIpcClient): void {
       void maybeProbeAnilistDuration(mediaKey);
       void ensureAnilistMediaGuess(mediaKey);
     }
+    syncImmersionTrackerFromCurrentMediaState();
   });
   mpvClient.on("media-title-change", ({ title }) => {
     mediaRuntime.updateCurrentMediaTitle(title);
     anilistCurrentMediaGuess = null;
     anilistCurrentMediaGuessPromise = null;
+    appState.immersionTracker?.handleMediaTitleUpdate(title);
+    syncImmersionTrackerFromCurrentMediaState();
+  });
+  mpvClient.on("time-pos-change", ({ time }) => {
+    appState.immersionTracker?.recordPlaybackPosition(time);
+  });
+  mpvClient.on("pause-change", ({ paused }) => {
+    appState.immersionTracker?.recordPauseState(paused);
   });
   mpvClient.on("subtitle-metrics-change", ({ patch }) => {
     updateMpvSubtitleRenderMetrics(patch);
@@ -1357,6 +1551,7 @@ function createMpvClientRuntimeService(): MpvIpcClient {
     },
   });
   bindMpvClientEventHandlers(mpvClient);
+  mpvClient.connect();
   return mpvClient;
 }
 
@@ -1395,7 +1590,11 @@ async function tokenizeSubtitle(text: string): Promise<SubtitleData> {
         appState.yomitanParserInitPromise = promise;
       },
       isKnownWord: (text) =>
-        Boolean(appState.ankiIntegration?.isKnownWord(text)),
+        (() => {
+          const hit = Boolean(appState.ankiIntegration?.isKnownWord(text));
+          appState.immersionTracker?.recordLookup(hit);
+          return hit;
+        })(),
       getKnownWordMatchMode: () =>
         appState.ankiIntegration?.getKnownWordMatchMode() ??
         getResolvedConfig().ankiConnect.nPlusOne.matchMode,
@@ -1721,13 +1920,16 @@ async function markLastCardAsAudioCard(): Promise<void> {
 }
 
 async function mineSentenceCard(): Promise<void> {
-  await mineSentenceCardService(
+  const created = await mineSentenceCardService(
     {
       ankiIntegration: appState.ankiIntegration,
       mpvClient: appState.mpvClient,
       showMpvOsd: (text) => showMpvOsd(text),
     },
   );
+  if (created) {
+    appState.immersionTracker?.recordCardsMined(1);
+  }
 }
 
 function cancelPendingMineSentenceMultiple(): void {
@@ -1758,6 +1960,9 @@ function handleMineSentenceDigit(count: number): void {
       logError: (message, err) => {
         logger.error(message, err);
       },
+      onCardsMined: (cards) => {
+        appState.immersionTracker?.recordCardsMined(cards);
+      },
     },
   );
 }

src/main/app-lifecycle.ts

@@ -35,6 +35,7 @@ export interface AppReadyRuntimeDepsFactoryInput {
   setLogLevel: AppReadyRuntimeDeps["setLogLevel"];
   createMecabTokenizerAndCheck: AppReadyRuntimeDeps["createMecabTokenizerAndCheck"];
   createSubtitleTimingTracker: AppReadyRuntimeDeps["createSubtitleTimingTracker"];
+  createImmersionTracker?: AppReadyRuntimeDeps["createImmersionTracker"];
   loadYomitanExtension: AppReadyRuntimeDeps["loadYomitanExtension"];
   texthookerOnlyMode: AppReadyRuntimeDeps["texthookerOnlyMode"];
   shouldAutoInitializeOverlayRuntimeFromConfig: AppReadyRuntimeDeps["shouldAutoInitializeOverlayRuntimeFromConfig"];
@@ -81,6 +82,7 @@ export function createAppReadyRuntimeDeps(
     setLogLevel: params.setLogLevel,
     createMecabTokenizerAndCheck: params.createMecabTokenizerAndCheck,
     createSubtitleTimingTracker: params.createSubtitleTimingTracker,
+    createImmersionTracker: params.createImmersionTracker,
     loadYomitanExtension: params.loadYomitanExtension,
     texthookerOnlyMode: params.texthookerOnlyMode,
     shouldAutoInitializeOverlayRuntimeFromConfig:

src/main/state.ts

@@ -12,6 +12,7 @@ import type {
 import type { CliArgs } from "../cli/args";
 import type { SubtitleTimingTracker } from "../subtitle-timing-tracker";
 import type { AnkiIntegration } from "../anki-integration";
+import type { ImmersionTrackerService } from "../core/services";
 import type { MpvIpcClient } from "../core/services";
 import { DEFAULT_MPV_SUBTITLE_RENDER_METRICS } from "../core/services";
 import type { RuntimeOptionsManager } from "../runtime-options";
@@ -54,6 +55,7 @@ export interface AppState {
   mecabTokenizer: MecabTokenizer | null;
   keybindings: Keybinding[];
   subtitleTimingTracker: SubtitleTimingTracker | null;
+  immersionTracker: ImmersionTrackerService | null;
   ankiIntegration: AnkiIntegration | null;
   secondarySubMode: SecondarySubMode;
   lastSecondarySubToggleAtMs: number;
@@ -123,6 +125,7 @@ export function createAppState(values: AppStateInitialValues): AppState {
     mecabTokenizer: null,
     keybindings: [],
     subtitleTimingTracker: null,
+    immersionTracker: null,
     ankiIntegration: null,
     secondarySubMode: "hover",
     lastSecondarySubToggleAtMs: 0,

src/types.ts

@@ -351,6 +351,11 @@ export interface YoutubeSubgenConfig {
   primarySubLanguages?: string[];
 }
 
+export interface ImmersionTrackingConfig {
+  enabled?: boolean;
+  dbPath?: string;
+}
+
 export interface Config {
   subtitlePosition?: SubtitlePosition;
   keybindings?: Keybinding[];
@@ -367,6 +372,7 @@ export interface Config {
   anilist?: AnilistConfig;
   invisibleOverlay?: InvisibleOverlayConfig;
   youtubeSubgen?: YoutubeSubgenConfig;
+  immersionTracking?: ImmersionTrackingConfig;
   logging?: {
     level?: "debug" | "info" | "warn" | "error";
   };
@@ -481,6 +487,10 @@ export interface ResolvedConfig {
     whisperModel: string;
     primarySubLanguages: string[];
   };
+  immersionTracking: {
+    enabled: boolean;
+    dbPath?: string;
+  };
   logging: {
     level: "debug" | "info" | "warn" | "error";
   };

subminer

@@ -2440,11 +2440,37 @@ function parseArgs(
       fail(`Unknown option: ${arg}`);
     }
 
-    break;
+    if (!parsed.target) {
+      if (isUrlTarget(arg)) {
+        parsed.target = arg;
+        parsed.targetKind = "url";
+      } else {
+        const resolved = resolvePathMaybe(arg);
+        if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) {
+          parsed.target = resolved;
+          parsed.targetKind = "file";
+        } else if (
+          fs.existsSync(resolved) &&
+          fs.statSync(resolved).isDirectory()
+        ) {
+          parsed.directory = resolved;
+        } else {
+          fail(`Not a file, directory, or supported URL: ${arg}`);
+        }
+      }
+      i += 1;
+      continue;
+    }
+
+    fail(`Unexpected positional argument: ${arg}`);
   }
 
   const positional = argv.slice(i);
   if (positional.length > 0) {
+    if (parsed.target || parsed.directory) {
+      fail(`Unexpected positional argument: ${positional[0]}`);
+    }
+
     const target = positional[0];
     if (isUrlTarget(target)) {
       parsed.target = target;
@@ -2463,6 +2489,10 @@ function parseArgs(
         fail(`Not a file, directory, or supported URL: ${target}`);
       }
     }
+
+    if (positional.length > 1) {
+      fail(`Unexpected positional argument: ${positional[1]}`);
+    }
   }
 
   return parsed;