Fix child-process arg warning

2026-02-27 18:22:41 -08:00 · 2026-02-16 23:33:03 -08:00
parent 1cd1cdb11d
commit 4d28efabd0
24 changed files with 1951 additions and 33 deletions
--- a/src/anki-integration.ts
+++ b/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,
--- a/src/anki-integration/card-creation.ts
+++ b/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 {
--- a/src/config/config.test.ts
+++ b/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(
--- a/src/config/definitions.ts
+++ b/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 {
--- a/src/config/service.ts
+++ b/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,
--- a/src/core/services/app-ready-service.test.ts
+++ b/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,22 @@ 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 defer message when overlay not auto-started", async () => {
--- a/src/core/services/immersion-tracker-service.ts
+++ b/src/core/services/immersion-tracker-service.ts
--- a/src/core/services/index.ts
+++ b/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";
--- a/src/core/services/mining-service.test.ts
+++ b/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);
 });
--- a/src/core/services/mining-service.ts
+++ b/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}`);
--- a/src/core/services/mpv-properties.ts
+++ b/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,
--- a/src/core/services/mpv-protocol.test.ts
+++ b/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),
--- a/src/core/services/mpv-protocol.ts
+++ b/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) {
--- a/src/core/services/mpv-service.ts
+++ b/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);
      },
--- a/src/core/services/startup-service.ts
+++ b/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,12 @@ export async function runAppReadyRuntimeService(
  }

  deps.createSubtitleTimingTracker();
+  if (deps.createImmersionTracker) {
+    deps.log("Runtime ready: invoking createImmersionTracker.");
+    deps.createImmersionTracker();
+  } else {
+    deps.log("Runtime ready: createImmersionTracker dependency is missing.");
+  }
  await deps.loadYomitanExtension();

  if (deps.texthookerOnlyMode) {
--- a/src/main.ts
+++ b/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,26 @@ 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;
+          }
+          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,
+          });
+          if (appState.mpvClient && !appState.mpvClient.connected) {
+            logger.info("Auto-connecting MPV client for immersion tracking");
+            appState.mpvClient.connect();
+          }
+          seedImmersionTrackerFromCurrentMedia();
+        },
        loadYomitanExtension: async () => {
          await loadYomitanExtension();
        },
@@ -1208,6 +1369,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 +1457,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 +1488,14 @@ function bindMpvClientEventHandlers(mpvClient: MpvIpcClient): void {
    broadcastToOverlayWindows("secondary-subtitle:set", text);
  });
  mpvClient.on("subtitle-timing", ({ text, start, end }) => {
-    if (text.trim() && appState.subtitleTimingTracker) {
-      appState.subtitleTimingTracker.recordSubtitle(text, start, end);
+    if (!text.trim()) {
+      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 +1508,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 +1545,7 @@ function createMpvClientRuntimeService(): MpvIpcClient {
    },
  });
  bindMpvClientEventHandlers(mpvClient);
+  mpvClient.connect();
  return mpvClient;
 }

@@ -1395,7 +1584,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 +1914,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 +1954,9 @@ function handleMineSentenceDigit(count: number): void {
      logError: (message, err) => {
        logger.error(message, err);
      },
+      onCardsMined: (cards) => {
+        appState.immersionTracker?.recordCardsMined(cards);
+      },
    },
  );
 }
--- a/src/main/app-lifecycle.ts
+++ b/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:
--- a/src/main/state.ts
+++ b/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,
--- a/src/types.ts
+++ b/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";
  };