chore: archive refactor milestones and remove structural quality-gates task

- Remove structural quality gates task and references from task-27 roadmap.
- Remove structural-gates-adjacent work from scripts/positioning cleanup context, including check-main-lines adjustments.
- Archive completed backlog tasks 11 and 27.7 by moving them to completed directory.
- Finish task-27.5 module split by moving/anonymizing anki-integration and renderer positioning files into their dedicated directories and updating paths.

src/anki-integration/field-grouping.ts

@@ -0,0 +1,253 @@
+import { KikuMergePreviewResponse } from "../types";
+import { createLogger } from "../logger";
+
+const log = createLogger("anki").child("integration.field-grouping");
+
+interface FieldGroupingNoteInfo {
+  noteId: number;
+  fields: Record<string, { value: string }>;
+}
+
+interface FieldGroupingDeps {
+  getEffectiveSentenceCardConfig: () => {
+    model?: string;
+    sentenceField: string;
+    audioField: string;
+    lapisEnabled: boolean;
+    kikuEnabled: boolean;
+    kikuFieldGrouping: "auto" | "manual" | "disabled";
+    kikuDeleteDuplicateInAuto: boolean;
+  };
+  isUpdateInProgress: () => boolean;
+  getDeck?: () => string | undefined;
+  withUpdateProgress: <T>(initialMessage: string, action: () => Promise<T>) => Promise<T>;
+  showOsdNotification: (text: string) => void;
+  findNotes: (
+    query: string,
+    options?: {
+      maxRetries?: number;
+    },
+  ) => Promise<number[]>;
+  notesInfo: (noteIds: number[]) => Promise<FieldGroupingNoteInfo[]>;
+  extractFields: (fields: Record<string, { value: string }>) => Record<string, string>;
+  findDuplicateNote: (
+    expression: string,
+    excludeNoteId: number,
+    noteInfo: FieldGroupingNoteInfo,
+  ) => Promise<number | null>;
+  hasAllConfiguredFields: (
+    noteInfo: FieldGroupingNoteInfo,
+    configuredFieldNames: (string | undefined)[],
+  ) => boolean;
+  processNewCard: (
+    noteId: number,
+    options?: { skipKikuFieldGrouping?: boolean },
+  ) => Promise<void>;
+  getSentenceCardImageFieldName: () => string | undefined;
+  resolveFieldName: (
+    availableFieldNames: string[],
+    preferredName: string,
+  ) => string | null;
+  computeFieldGroupingMergedFields: (
+    keepNoteId: number,
+    deleteNoteId: number,
+    keepNoteInfo: FieldGroupingNoteInfo,
+    deleteNoteInfo: FieldGroupingNoteInfo,
+    includeGeneratedMedia: boolean,
+  ) => Promise<Record<string, string>>;
+  getNoteFieldMap: (noteInfo: FieldGroupingNoteInfo) => Record<string, string>;
+  handleFieldGroupingAuto: (
+    originalNoteId: number,
+    newNoteId: number,
+    newNoteInfo: FieldGroupingNoteInfo,
+    expression: string,
+  ) => Promise<void>;
+  handleFieldGroupingManual: (
+    originalNoteId: number,
+    newNoteId: number,
+    newNoteInfo: FieldGroupingNoteInfo,
+    expression: string,
+  ) => Promise<boolean>;
+}
+
+export class FieldGroupingService {
+  constructor(private readonly deps: FieldGroupingDeps) {}
+
+  async triggerFieldGroupingForLastAddedCard(): Promise<void> {
+    const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
+    if (!sentenceCardConfig.kikuEnabled) {
+      this.deps.showOsdNotification("Kiku mode is not enabled");
+      return;
+    }
+    if (sentenceCardConfig.kikuFieldGrouping === "disabled") {
+      this.deps.showOsdNotification("Kiku field grouping is disabled");
+      return;
+    }
+
+    if (this.deps.isUpdateInProgress()) {
+      this.deps.showOsdNotification("Anki update already in progress");
+      return;
+    }
+
+    try {
+      await this.deps.withUpdateProgress("Grouping duplicate cards", async () => {
+        const deck = this.deps.getDeck ? this.deps.getDeck() : undefined;
+        const query = deck ? `"deck:${deck}" added:1` : "added:1";
+        const noteIds = await this.deps.findNotes(query);
+        if (!noteIds || noteIds.length === 0) {
+          this.deps.showOsdNotification("No recently added cards found");
+          return;
+        }
+
+        const noteId = Math.max(...noteIds);
+        const notesInfoResult = await this.deps.notesInfo([noteId]);
+        const notesInfo = notesInfoResult as FieldGroupingNoteInfo[];
+        if (!notesInfo || notesInfo.length === 0) {
+          this.deps.showOsdNotification("Card not found");
+          return;
+        }
+        const noteInfoBeforeUpdate = notesInfo[0];
+        const fields = this.deps.extractFields(noteInfoBeforeUpdate.fields);
+        const expressionText = fields.expression || fields.word || "";
+        if (!expressionText) {
+          this.deps.showOsdNotification("No expression/word field found");
+          return;
+        }
+
+        const duplicateNoteId = await this.deps.findDuplicateNote(
+          expressionText,
+          noteId,
+          noteInfoBeforeUpdate,
+        );
+        if (duplicateNoteId === null) {
+          this.deps.showOsdNotification("No duplicate card found");
+          return;
+        }
+
+        if (
+          !this.deps.hasAllConfiguredFields(noteInfoBeforeUpdate, [
+            this.deps.getSentenceCardImageFieldName(),
+          ])
+        ) {
+          await this.deps.processNewCard(noteId, { skipKikuFieldGrouping: true });
+        }
+
+        const refreshedInfoResult = await this.deps.notesInfo([noteId]);
+        const refreshedInfo = refreshedInfoResult as FieldGroupingNoteInfo[];
+        if (!refreshedInfo || refreshedInfo.length === 0) {
+          this.deps.showOsdNotification("Card not found");
+          return;
+        }
+
+        const noteInfo = refreshedInfo[0];
+
+        if (sentenceCardConfig.kikuFieldGrouping === "auto") {
+          await this.deps.handleFieldGroupingAuto(
+            duplicateNoteId,
+            noteId,
+            noteInfo,
+            expressionText,
+          );
+          return;
+        }
+        const handled = await this.deps.handleFieldGroupingManual(
+          duplicateNoteId,
+          noteId,
+          noteInfo,
+          expressionText,
+        );
+        if (!handled) {
+          this.deps.showOsdNotification("Field grouping cancelled");
+        }
+      });
+    } catch (error) {
+      log.error(
+        "Error triggering field grouping:",
+        (error as Error).message,
+      );
+      this.deps.showOsdNotification(
+        `Field grouping failed: ${(error as Error).message}`,
+      );
+    }
+  }
+
+  async buildFieldGroupingPreview(
+    keepNoteId: number,
+    deleteNoteId: number,
+    deleteDuplicate: boolean,
+  ): Promise<KikuMergePreviewResponse> {
+    try {
+      const notesInfoResult = await this.deps.notesInfo([
+        keepNoteId,
+        deleteNoteId,
+      ]);
+      const notesInfo = notesInfoResult as FieldGroupingNoteInfo[];
+      const keepNoteInfo = notesInfo.find((note) => note.noteId === keepNoteId);
+      const deleteNoteInfo = notesInfo.find(
+        (note) => note.noteId === deleteNoteId,
+      );
+
+      if (!keepNoteInfo || !deleteNoteInfo) {
+        return { ok: false, error: "Could not load selected notes" };
+      }
+
+      const mergedFields = await this.deps.computeFieldGroupingMergedFields(
+        keepNoteId,
+        deleteNoteId,
+        keepNoteInfo,
+        deleteNoteInfo,
+        false,
+      );
+      const keepBefore = this.deps.getNoteFieldMap(keepNoteInfo);
+      const keepAfter = { ...keepBefore, ...mergedFields };
+      const sourceBefore = this.deps.getNoteFieldMap(deleteNoteInfo);
+
+      const compactFields: Record<string, string> = {};
+      for (const fieldName of [
+        "Sentence",
+        "SentenceFurigana",
+        "SentenceAudio",
+        "Picture",
+        "MiscInfo",
+      ]) {
+        const resolved = this.deps.resolveFieldName(
+          Object.keys(keepAfter),
+          fieldName,
+        );
+        if (!resolved) continue;
+        compactFields[fieldName] = keepAfter[resolved] || "";
+      }
+
+      return {
+        ok: true,
+        compact: {
+          action: {
+            keepNoteId,
+            deleteNoteId,
+            deleteDuplicate,
+          },
+          mergedFields: compactFields,
+        },
+        full: {
+          keepNote: {
+            id: keepNoteId,
+            fieldsBefore: keepBefore,
+          },
+          sourceNote: {
+            id: deleteNoteId,
+            fieldsBefore: sourceBefore,
+          },
+          result: {
+            fieldsAfter: keepAfter,
+            wouldDeleteNoteId: deleteDuplicate ? deleteNoteId : null,
+          },
+        },
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        error: `Failed to build preview: ${(error as Error).message}`,
+      };
+    }
+  }
+}

src/anki-integration/known-word-cache.ts

@@ -0,0 +1,398 @@
+import fs from "fs";
+import path from "path";
+
+import { DEFAULT_ANKI_CONNECT_CONFIG } from "../config";
+import { AnkiConnectConfig } from "../types";
+import { createLogger } from "../logger";
+
+const log = createLogger("anki").child("integration.known-word-cache");
+
+export interface KnownWordCacheNoteInfo {
+  noteId: number;
+  fields: Record<string, { value: string }>;
+}
+
+interface KnownWordCacheState {
+  readonly version: 1;
+  readonly refreshedAtMs: number;
+  readonly scope: string;
+  readonly words: string[];
+}
+
+interface KnownWordCacheClient {
+  findNotes: (
+    query: string,
+    options?: {
+      maxRetries?: number;
+    },
+  ) => Promise<unknown>;
+  notesInfo: (noteIds: number[]) => Promise<unknown>;
+}
+
+interface KnownWordCacheDeps {
+  client: KnownWordCacheClient;
+  getConfig: () => AnkiConnectConfig;
+  knownWordCacheStatePath?: string;
+  showStatusNotification: (message: string) => void;
+}
+
+export class KnownWordCacheManager {
+  private knownWordsLastRefreshedAtMs = 0;
+  private knownWordsScope = "";
+  private knownWords: Set<string> = new Set();
+  private knownWordsRefreshTimer: ReturnType<typeof setInterval> | null = null;
+  private isRefreshingKnownWords = false;
+  private readonly statePath: string;
+
+  constructor(private readonly deps: KnownWordCacheDeps) {
+    this.statePath = path.normalize(
+      deps.knownWordCacheStatePath || path.join(process.cwd(), "known-words-cache.json"),
+    );
+  }
+
+  isKnownWord(text: string): boolean {
+    if (!this.isKnownWordCacheEnabled()) {
+      return false;
+    }
+
+    const normalized = this.normalizeKnownWordForLookup(text);
+    return normalized.length > 0 ? this.knownWords.has(normalized) : false;
+  }
+
+  refresh(force = false): Promise<void> {
+    return this.refreshKnownWords(force);
+  }
+
+  startLifecycle(): void {
+    this.stopLifecycle();
+    if (!this.isKnownWordCacheEnabled()) {
+      log.info("Known-word cache disabled; clearing local cache state");
+      this.clearKnownWordCacheState();
+      return;
+    }
+
+    const refreshMinutes = this.getKnownWordRefreshIntervalMs() / 60_000;
+    const scope = this.getKnownWordCacheScope();
+    log.info(
+      "Known-word cache lifecycle enabled",
+      `scope=${scope}`,
+      `refreshMinutes=${refreshMinutes}`,
+      `cachePath=${this.statePath}`,
+    );
+
+    this.loadKnownWordCacheState();
+    void this.refreshKnownWords();
+    const refreshIntervalMs = this.getKnownWordRefreshIntervalMs();
+    this.knownWordsRefreshTimer = setInterval(() => {
+      void this.refreshKnownWords();
+    }, refreshIntervalMs);
+  }
+
+  stopLifecycle(): void {
+    if (this.knownWordsRefreshTimer) {
+      clearInterval(this.knownWordsRefreshTimer);
+      this.knownWordsRefreshTimer = null;
+    }
+  }
+
+  appendFromNoteInfo(noteInfo: KnownWordCacheNoteInfo): void {
+    if (!this.isKnownWordCacheEnabled()) {
+      return;
+    }
+
+    const currentScope = this.getKnownWordCacheScope();
+    if (this.knownWordsScope && this.knownWordsScope !== currentScope) {
+      this.clearKnownWordCacheState();
+    }
+    if (!this.knownWordsScope) {
+      this.knownWordsScope = currentScope;
+    }
+
+    let addedCount = 0;
+    for (const rawWord of this.extractKnownWordsFromNoteInfo(noteInfo)) {
+      const normalized = this.normalizeKnownWordForLookup(rawWord);
+      if (!normalized || this.knownWords.has(normalized)) {
+        continue;
+      }
+      this.knownWords.add(normalized);
+      addedCount += 1;
+    }
+
+    if (addedCount > 0) {
+      if (this.knownWordsLastRefreshedAtMs <= 0) {
+        this.knownWordsLastRefreshedAtMs = Date.now();
+      }
+      this.persistKnownWordCacheState();
+      log.info(
+        "Known-word cache updated in-session",
+        `added=${addedCount}`,
+        `scope=${currentScope}`,
+      );
+    }
+  }
+
+  clearKnownWordCacheState(): void {
+    this.knownWords = new Set();
+    this.knownWordsLastRefreshedAtMs = 0;
+    this.knownWordsScope = this.getKnownWordCacheScope();
+    try {
+      if (fs.existsSync(this.statePath)) {
+        fs.unlinkSync(this.statePath);
+      }
+    } catch (error) {
+      log.warn("Failed to clear known-word cache state:", (error as Error).message);
+    }
+  }
+
+  private async refreshKnownWords(force = false): Promise<void> {
+    if (!this.isKnownWordCacheEnabled()) {
+      log.debug("Known-word cache refresh skipped; feature disabled");
+      return;
+    }
+    if (this.isRefreshingKnownWords) {
+      log.debug("Known-word cache refresh skipped; already refreshing");
+      return;
+    }
+    if (!force && !this.isKnownWordCacheStale()) {
+      log.debug("Known-word cache refresh skipped; cache is fresh");
+      return;
+    }
+
+    this.isRefreshingKnownWords = true;
+    try {
+      const query = this.buildKnownWordsQuery();
+      log.debug("Refreshing known-word cache", `query=${query}`);
+      const noteIds = (await this.deps.client.findNotes(query, {
+        maxRetries: 0,
+      })) as number[];
+
+      const nextKnownWords = new Set<string>();
+      if (noteIds.length > 0) {
+        const chunkSize = 50;
+        for (let i = 0; i < noteIds.length; i += chunkSize) {
+          const chunk = noteIds.slice(i, i + chunkSize);
+          const notesInfoResult = (await this.deps.client.notesInfo(chunk)) as unknown[];
+          const notesInfo = notesInfoResult as KnownWordCacheNoteInfo[];
+
+          for (const noteInfo of notesInfo) {
+            for (const word of this.extractKnownWordsFromNoteInfo(noteInfo)) {
+              const normalized = this.normalizeKnownWordForLookup(word);
+              if (normalized) {
+                nextKnownWords.add(normalized);
+              }
+            }
+          }
+        }
+      }
+
+      this.knownWords = nextKnownWords;
+      this.knownWordsLastRefreshedAtMs = Date.now();
+      this.knownWordsScope = this.getKnownWordCacheScope();
+      this.persistKnownWordCacheState();
+      log.info(
+        "Known-word cache refreshed",
+        `noteCount=${noteIds.length}`,
+        `wordCount=${nextKnownWords.size}`,
+      );
+    } catch (error) {
+      log.warn("Failed to refresh known-word cache:", (error as Error).message);
+      this.deps.showStatusNotification("AnkiConnect: unable to refresh known words");
+    } finally {
+      this.isRefreshingKnownWords = false;
+    }
+  }
+
+  private isKnownWordCacheEnabled(): boolean {
+    return this.deps.getConfig().nPlusOne?.highlightEnabled === true;
+  }
+
+  private getKnownWordRefreshIntervalMs(): number {
+    const minutes = this.deps.getConfig().nPlusOne?.refreshMinutes;
+    const safeMinutes =
+      typeof minutes === "number" && Number.isFinite(minutes) && minutes > 0
+        ? minutes
+        : DEFAULT_ANKI_CONNECT_CONFIG.nPlusOne.refreshMinutes;
+    return safeMinutes * 60_000;
+  }
+
+  private getKnownWordDecks(): string[] {
+    const configuredDecks = this.deps.getConfig().nPlusOne?.decks;
+    if (Array.isArray(configuredDecks)) {
+      const decks = configuredDecks
+        .filter((entry): entry is string => typeof entry === "string")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+      return [...new Set(decks)];
+    }
+
+    const deck = this.deps.getConfig().deck?.trim();
+    return deck ? [deck] : [];
+  }
+
+  private buildKnownWordsQuery(): string {
+    const decks = this.getKnownWordDecks();
+    if (decks.length === 0) {
+      return "is:note";
+    }
+
+    if (decks.length === 1) {
+      return `deck:"${escapeAnkiSearchValue(decks[0])}"`;
+    }
+
+    const deckQueries = decks.map(
+      (deck) => `deck:"${escapeAnkiSearchValue(deck)}"`,
+    );
+    return `(${deckQueries.join(" OR ")})`;
+  }
+
+  private getKnownWordCacheScope(): string {
+    const decks = this.getKnownWordDecks();
+    if (decks.length === 0) {
+      return "is:note";
+    }
+    return `decks:${JSON.stringify(decks)}`;
+  }
+
+  private isKnownWordCacheStale(): boolean {
+    if (!this.isKnownWordCacheEnabled()) {
+      return true;
+    }
+    if (this.knownWordsScope !== this.getKnownWordCacheScope()) {
+      return true;
+    }
+    if (this.knownWordsLastRefreshedAtMs <= 0) {
+      return true;
+    }
+    return (
+      Date.now() - this.knownWordsLastRefreshedAtMs >=
+      this.getKnownWordRefreshIntervalMs()
+    );
+  }
+
+  private loadKnownWordCacheState(): void {
+    try {
+      if (!fs.existsSync(this.statePath)) {
+        this.knownWords = new Set();
+        this.knownWordsLastRefreshedAtMs = 0;
+        this.knownWordsScope = this.getKnownWordCacheScope();
+        return;
+      }
+
+      const raw = fs.readFileSync(this.statePath, "utf-8");
+      if (!raw.trim()) {
+        this.knownWords = new Set();
+        this.knownWordsLastRefreshedAtMs = 0;
+        this.knownWordsScope = this.getKnownWordCacheScope();
+        return;
+      }
+
+      const parsed = JSON.parse(raw) as unknown;
+      if (!this.isKnownWordCacheStateValid(parsed)) {
+        this.knownWords = new Set();
+        this.knownWordsLastRefreshedAtMs = 0;
+        this.knownWordsScope = this.getKnownWordCacheScope();
+        return;
+      }
+
+      if (parsed.scope !== this.getKnownWordCacheScope()) {
+        this.knownWords = new Set();
+        this.knownWordsLastRefreshedAtMs = 0;
+        this.knownWordsScope = this.getKnownWordCacheScope();
+        return;
+      }
+
+      const nextKnownWords = new Set<string>();
+      for (const value of parsed.words) {
+        const normalized = this.normalizeKnownWordForLookup(value);
+        if (normalized) {
+          nextKnownWords.add(normalized);
+        }
+      }
+
+      this.knownWords = nextKnownWords;
+      this.knownWordsLastRefreshedAtMs = parsed.refreshedAtMs;
+      this.knownWordsScope = parsed.scope;
+    } catch (error) {
+      log.warn("Failed to load known-word cache state:", (error as Error).message);
+      this.knownWords = new Set();
+      this.knownWordsLastRefreshedAtMs = 0;
+      this.knownWordsScope = this.getKnownWordCacheScope();
+    }
+  }
+
+  private persistKnownWordCacheState(): void {
+    try {
+      const state: KnownWordCacheState = {
+        version: 1,
+        refreshedAtMs: this.knownWordsLastRefreshedAtMs,
+        scope: this.knownWordsScope,
+        words: Array.from(this.knownWords),
+      };
+      fs.writeFileSync(this.statePath, JSON.stringify(state), "utf-8");
+    } catch (error) {
+      log.warn("Failed to persist known-word cache state:", (error as Error).message);
+    }
+  }
+
+  private isKnownWordCacheStateValid(
+    value: unknown,
+  ): value is KnownWordCacheState {
+    if (typeof value !== "object" || value === null) return false;
+    const candidate = value as Partial<KnownWordCacheState>;
+    if (candidate.version !== 1) return false;
+    if (typeof candidate.refreshedAtMs !== "number") return false;
+    if (typeof candidate.scope !== "string") return false;
+    if (!Array.isArray(candidate.words)) return false;
+    if (!candidate.words.every((entry) => typeof entry === "string")) {
+      return false;
+    }
+    return true;
+  }
+
+  private extractKnownWordsFromNoteInfo(noteInfo: KnownWordCacheNoteInfo): string[] {
+    const words: string[] = [];
+    const preferredFields = ["Expression", "Word"];
+    for (const preferredField of preferredFields) {
+      const fieldName = resolveFieldName(Object.keys(noteInfo.fields), preferredField);
+      if (!fieldName) continue;
+
+      const raw = noteInfo.fields[fieldName]?.value;
+      if (!raw) continue;
+
+      const extracted = this.normalizeRawKnownWordValue(raw);
+      if (extracted) {
+        words.push(extracted);
+      }
+    }
+    return words;
+  }
+
+  private normalizeRawKnownWordValue(value: string): string {
+    return value
+      .replace(/<[^>]*>/g, "")
+      .replace(/\u3000/g, " ")
+      .trim();
+  }
+
+  private normalizeKnownWordForLookup(value: string): string {
+    return this.normalizeRawKnownWordValue(value).toLowerCase();
+  }
+}
+
+function resolveFieldName(
+  availableFieldNames: string[],
+  preferredName: string,
+): string | null {
+  const exact = availableFieldNames.find((name) => name === preferredName);
+  if (exact) return exact;
+
+  const lower = preferredName.toLowerCase();
+  return availableFieldNames.find((name) => name.toLowerCase() === lower) || null;
+}
+
+function escapeAnkiSearchValue(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")
+    .replace(/\"/g, "\\\"")
+    .replace(/([:*?()\[\]{}])/g, "\\$1");
+}

src/anki-integration/polling.ts

@@ -0,0 +1,123 @@
+export interface PollingRunnerDeps {
+  getDeck: () => string | undefined;
+  getPollingRate: () => number;
+  findNotes: (
+    query: string,
+    options?: {
+      maxRetries?: number;
+    },
+  ) => Promise<number[]>;
+  shouldAutoUpdateNewCards: () => boolean;
+  processNewCard: (noteId: number) => Promise<void>;
+  isUpdateInProgress: () => boolean;
+  setUpdateInProgress: (value: boolean) => void;
+  getTrackedNoteIds: () => Set<number>;
+  setTrackedNoteIds: (noteIds: Set<number>) => void;
+  showStatusNotification: (message: string) => void;
+  logDebug: (...args: unknown[]) => void;
+  logInfo: (...args: unknown[]) => void;
+  logWarn: (...args: unknown[]) => void;
+}
+
+export class PollingRunner {
+  private pollingInterval: ReturnType<typeof setInterval> | null = null;
+  private initialized = false;
+  private backoffMs = 200;
+  private maxBackoffMs = 5000;
+  private nextPollTime = 0;
+
+  constructor(private readonly deps: PollingRunnerDeps) {}
+
+  get isRunning(): boolean {
+    return this.pollingInterval !== null;
+  }
+
+  start(): void {
+    if (this.pollingInterval) {
+      this.stop();
+    }
+
+    void this.pollOnce();
+    this.pollingInterval = setInterval(() => {
+      void this.pollOnce();
+    }, this.deps.getPollingRate());
+  }
+
+  stop(): void {
+    if (this.pollingInterval) {
+      clearInterval(this.pollingInterval);
+      this.pollingInterval = null;
+    }
+  }
+
+  async pollOnce(): Promise<void> {
+    if (this.deps.isUpdateInProgress()) return;
+    if (Date.now() < this.nextPollTime) return;
+
+    this.deps.setUpdateInProgress(true);
+    try {
+      const query = this.deps.getDeck() ? `"deck:${this.deps.getDeck()}" added:1` : "added:1";
+      const noteIds = await this.deps.findNotes(query, {
+        maxRetries: 0,
+      });
+      const currentNoteIds = new Set(noteIds);
+
+      const previousNoteIds = this.deps.getTrackedNoteIds();
+      if (!this.initialized) {
+        this.deps.setTrackedNoteIds(currentNoteIds);
+        this.initialized = true;
+        this.deps.logInfo(
+          `AnkiConnect initialized with ${currentNoteIds.size} existing cards`,
+        );
+        this.backoffMs = 200;
+        return;
+      }
+
+      const newNoteIds = Array.from(currentNoteIds).filter(
+        (id) => !previousNoteIds.has(id),
+      );
+
+      if (newNoteIds.length > 0) {
+        this.deps.logInfo("Found new cards:", newNoteIds);
+
+        for (const noteId of newNoteIds) {
+          previousNoteIds.add(noteId);
+        }
+        this.deps.setTrackedNoteIds(previousNoteIds);
+
+        if (this.deps.shouldAutoUpdateNewCards()) {
+          for (const noteId of newNoteIds) {
+            await this.deps.processNewCard(noteId);
+          }
+        } else {
+          this.deps.logInfo(
+            "New card detected (auto-update disabled). Press Ctrl+V to update from clipboard.",
+          );
+        }
+      }
+
+      if (this.backoffMs > 200) {
+        this.deps.logInfo("AnkiConnect connection restored");
+      }
+      this.backoffMs = 200;
+    } catch (error) {
+      const wasBackingOff = this.backoffMs > 200;
+      this.backoffMs = Math.min(this.backoffMs * 2, this.maxBackoffMs);
+      this.nextPollTime = Date.now() + this.backoffMs;
+      if (!wasBackingOff) {
+        this.deps.logWarn("AnkiConnect polling failed, backing off...");
+        this.deps.showStatusNotification("AnkiConnect: unable to connect");
+      }
+      this.deps.logWarn((error as Error).message);
+    } finally {
+      this.deps.setUpdateInProgress(false);
+    }
+  }
+
+  async poll(): Promise<void> {
+    if (this.pollingInterval) {
+      return;
+    }
+    return this.pollOnce();
+  }
+}

src/anki-integration/ui-feedback.ts

@@ -1,4 +1,4 @@
-import { NotificationOptions } from "./types";
+import { NotificationOptions } from "../types";
 
 export interface UiFeedbackState {
   progressDepth: number;

src/renderer/positioning.ts

@@ -1,513 +1 @@
-import type { MpvSubtitleRenderMetrics, SubtitlePosition } from "../types";
-import type { ModalStateReader, RendererContext } from "./context";
-
-const INVISIBLE_MACOS_VERTICAL_NUDGE_PX = 5;
-const INVISIBLE_MACOS_LINE_HEIGHT_SINGLE = "0.92";
-const INVISIBLE_MACOS_LINE_HEIGHT_MULTI = "1.2";
-const INVISIBLE_MACOS_LINE_HEIGHT_MULTI_DENSE = "1.3";
-
-function clampYPercent(yPercent: number): number {
-  return Math.max(2, Math.min(80, yPercent));
-}
-
-export function createPositioningController(
-  ctx: RendererContext,
-  options: {
-    modalStateReader: Pick<ModalStateReader, "isAnySettingsModalOpen">;
-    applySubtitleFontSize: (fontSize: number) => void;
-  },
-) {
-  function getCurrentYPercent(): number {
-    if (ctx.state.currentYPercent !== null) {
-      return ctx.state.currentYPercent;
-    }
-    const marginBottom = parseFloat(ctx.dom.subtitleContainer.style.marginBottom) || 60;
-    ctx.state.currentYPercent = clampYPercent((marginBottom / window.innerHeight) * 100);
-    return ctx.state.currentYPercent;
-  }
-
-  function applyYPercent(yPercent: number): void {
-    const clampedPercent = clampYPercent(yPercent);
-    ctx.state.currentYPercent = clampedPercent;
-    const marginBottom = (clampedPercent / 100) * window.innerHeight;
-
-    ctx.dom.subtitleContainer.style.position = "";
-    ctx.dom.subtitleContainer.style.left = "";
-    ctx.dom.subtitleContainer.style.top = "";
-    ctx.dom.subtitleContainer.style.right = "";
-    ctx.dom.subtitleContainer.style.transform = "";
-
-    ctx.dom.subtitleContainer.style.marginBottom = `${marginBottom}px`;
-  }
-
-  function updatePersistedSubtitlePosition(position: SubtitlePosition | null): void {
-    const nextYPercent =
-      position &&
-      typeof position.yPercent === "number" &&
-      Number.isFinite(position.yPercent)
-        ? position.yPercent
-        : ctx.state.persistedSubtitlePosition.yPercent;
-    const nextXOffset =
-      position &&
-      typeof position.invisibleOffsetXPx === "number" &&
-      Number.isFinite(position.invisibleOffsetXPx)
-        ? position.invisibleOffsetXPx
-        : 0;
-    const nextYOffset =
-      position &&
-      typeof position.invisibleOffsetYPx === "number" &&
-      Number.isFinite(position.invisibleOffsetYPx)
-        ? position.invisibleOffsetYPx
-        : 0;
-
-    ctx.state.persistedSubtitlePosition = {
-      yPercent: nextYPercent,
-      invisibleOffsetXPx: nextXOffset,
-      invisibleOffsetYPx: nextYOffset,
-    };
-  }
-
-  function persistSubtitlePositionPatch(patch: Partial<SubtitlePosition>): void {
-    const nextPosition: SubtitlePosition = {
-      yPercent:
-        typeof patch.yPercent === "number" && Number.isFinite(patch.yPercent)
-          ? patch.yPercent
-          : ctx.state.persistedSubtitlePosition.yPercent,
-      invisibleOffsetXPx:
-        typeof patch.invisibleOffsetXPx === "number" &&
-        Number.isFinite(patch.invisibleOffsetXPx)
-          ? patch.invisibleOffsetXPx
-          : ctx.state.persistedSubtitlePosition.invisibleOffsetXPx ?? 0,
-      invisibleOffsetYPx:
-        typeof patch.invisibleOffsetYPx === "number" &&
-        Number.isFinite(patch.invisibleOffsetYPx)
-          ? patch.invisibleOffsetYPx
-          : ctx.state.persistedSubtitlePosition.invisibleOffsetYPx ?? 0,
-    };
-
-    ctx.state.persistedSubtitlePosition = nextPosition;
-    window.electronAPI.saveSubtitlePosition(nextPosition);
-  }
-
-  function applyStoredSubtitlePosition(
-    position: SubtitlePosition | null,
-    source: string,
-  ): void {
-    updatePersistedSubtitlePosition(position);
-    if (position && position.yPercent !== undefined) {
-      applyYPercent(position.yPercent);
-      console.log(
-        "Applied subtitle position from",
-        source,
-        ":",
-        position.yPercent,
-        "%",
-      );
-      return;
-    }
-
-    const defaultMarginBottom = 60;
-    const defaultYPercent = (defaultMarginBottom / window.innerHeight) * 100;
-    applyYPercent(defaultYPercent);
-    console.log("Applied default subtitle position from", source);
-  }
-
-  function applyInvisibleSubtitleOffsetPosition(): void {
-    const nextLeft =
-      ctx.state.invisibleLayoutBaseLeftPx + ctx.state.invisibleSubtitleOffsetXPx;
-    ctx.dom.subtitleContainer.style.left = `${nextLeft}px`;
-
-    if (ctx.state.invisibleLayoutBaseBottomPx !== null) {
-      ctx.dom.subtitleContainer.style.bottom = `${Math.max(
-        0,
-        ctx.state.invisibleLayoutBaseBottomPx + ctx.state.invisibleSubtitleOffsetYPx,
-      )}px`;
-      ctx.dom.subtitleContainer.style.top = "";
-      return;
-    }
-
-    if (ctx.state.invisibleLayoutBaseTopPx !== null) {
-      ctx.dom.subtitleContainer.style.top = `${Math.max(
-        0,
-        ctx.state.invisibleLayoutBaseTopPx - ctx.state.invisibleSubtitleOffsetYPx,
-      )}px`;
-      ctx.dom.subtitleContainer.style.bottom = "";
-    }
-  }
-
-  function updateInvisiblePositionEditHud(): void {
-    if (!ctx.state.invisiblePositionEditHud) return;
-    ctx.state.invisiblePositionEditHud.textContent =
-      `Position Edit  Ctrl/Cmd+Shift+P toggle  Arrow keys move  Enter/Ctrl+S save  Esc cancel  x:${Math.round(ctx.state.invisibleSubtitleOffsetXPx)} y:${Math.round(ctx.state.invisibleSubtitleOffsetYPx)}`;
-  }
-
-  function setInvisiblePositionEditMode(enabled: boolean): void {
-    if (!ctx.platform.isInvisibleLayer) return;
-    if (ctx.state.invisiblePositionEditMode === enabled) return;
-
-    ctx.state.invisiblePositionEditMode = enabled;
-    document.body.classList.toggle("invisible-position-edit", enabled);
-
-    if (enabled) {
-      ctx.state.invisiblePositionEditStartX = ctx.state.invisibleSubtitleOffsetXPx;
-      ctx.state.invisiblePositionEditStartY = ctx.state.invisibleSubtitleOffsetYPx;
-      ctx.dom.overlay.classList.add("interactive");
-      if (ctx.platform.shouldToggleMouseIgnore) {
-        window.electronAPI.setIgnoreMouseEvents(false);
-      }
-    } else if (
-      !ctx.state.isOverSubtitle &&
-      !options.modalStateReader.isAnySettingsModalOpen()
-    ) {
-      ctx.dom.overlay.classList.remove("interactive");
-      if (ctx.platform.shouldToggleMouseIgnore) {
-        window.electronAPI.setIgnoreMouseEvents(true, { forward: true });
-      }
-    }
-
-    updateInvisiblePositionEditHud();
-  }
-
-  function applyInvisibleStoredSubtitlePosition(
-    position: SubtitlePosition | null,
-    source: string,
-  ): void {
-    updatePersistedSubtitlePosition(position);
-    ctx.state.invisibleSubtitleOffsetXPx =
-      ctx.state.persistedSubtitlePosition.invisibleOffsetXPx ?? 0;
-    ctx.state.invisibleSubtitleOffsetYPx =
-      ctx.state.persistedSubtitlePosition.invisibleOffsetYPx ?? 0;
-    applyInvisibleSubtitleOffsetPosition();
-    console.log(
-      "[invisible-overlay] Applied subtitle offset from",
-      source,
-      `${ctx.state.invisibleSubtitleOffsetXPx}px`,
-      `${ctx.state.invisibleSubtitleOffsetYPx}px`,
-    );
-    updateInvisiblePositionEditHud();
-  }
-
-  function computeOsdToCssScale(metrics: MpvSubtitleRenderMetrics): number {
-    const dims = metrics.osdDimensions;
-    const dpr = window.devicePixelRatio || 1;
-    if (!ctx.platform.isMacOSPlatform || !dims) {
-      return dpr;
-    }
-
-    const ratios = [
-      dims.w / Math.max(1, window.innerWidth),
-      dims.h / Math.max(1, window.innerHeight),
-    ].filter((value) => Number.isFinite(value) && value > 0);
-
-    const avgRatio =
-      ratios.length > 0
-        ? ratios.reduce((sum, value) => sum + value, 0) / ratios.length
-        : dpr;
-
-    return avgRatio > 1.25 ? avgRatio : 1;
-  }
-
-  function applySubtitleContainerBaseLayout(params: {
-    horizontalAvailable: number;
-    leftInset: number;
-    marginX: number;
-    hAlign: 0 | 1 | 2;
-  }): void {
-    ctx.dom.subtitleContainer.style.position = "absolute";
-    ctx.dom.subtitleContainer.style.maxWidth = `${params.horizontalAvailable}px`;
-    ctx.dom.subtitleContainer.style.width = `${params.horizontalAvailable}px`;
-    ctx.dom.subtitleContainer.style.padding = "0";
-    ctx.dom.subtitleContainer.style.background = "transparent";
-    ctx.dom.subtitleContainer.style.marginBottom = "0";
-    ctx.dom.subtitleContainer.style.pointerEvents = "none";
-
-    ctx.dom.subtitleContainer.style.left = `${params.leftInset + params.marginX}px`;
-    ctx.dom.subtitleContainer.style.right = "";
-    ctx.dom.subtitleContainer.style.transform = "";
-    ctx.dom.subtitleContainer.style.textAlign = "";
-
-    if (params.hAlign === 0) {
-      ctx.dom.subtitleContainer.style.textAlign = "left";
-      ctx.dom.subtitleRoot.style.textAlign = "left";
-    } else if (params.hAlign === 2) {
-      ctx.dom.subtitleContainer.style.textAlign = "right";
-      ctx.dom.subtitleRoot.style.textAlign = "right";
-    } else {
-      ctx.dom.subtitleContainer.style.textAlign = "center";
-      ctx.dom.subtitleRoot.style.textAlign = "center";
-    }
-
-    ctx.dom.subtitleRoot.style.display = "inline-block";
-    ctx.dom.subtitleRoot.style.maxWidth = "100%";
-    ctx.dom.subtitleRoot.style.pointerEvents = "auto";
-  }
-
-  function applySubtitleVerticalPosition(params: {
-    metrics: MpvSubtitleRenderMetrics;
-    renderAreaHeight: number;
-    topInset: number;
-    bottomInset: number;
-    marginY: number;
-    effectiveFontSize: number;
-    vAlign: 0 | 1 | 2;
-  }): void {
-    const lineCount = Math.max(1, ctx.state.currentInvisibleSubtitleLineCount);
-    const multiline = lineCount > 1;
-    const baselineCompensationFactor =
-      lineCount >= 3 ? 0.46 : multiline ? 0.58 : 0.7;
-    const baselineCompensationPx = Math.max(
-      0,
-      params.effectiveFontSize * baselineCompensationFactor,
-    );
-
-    if (params.vAlign === 2) {
-      ctx.dom.subtitleContainer.style.top = `${Math.max(
-        0,
-        params.topInset + params.marginY - baselineCompensationPx,
-      )}px`;
-      ctx.dom.subtitleContainer.style.bottom = "";
-      return;
-    }
-
-    if (params.vAlign === 1) {
-      ctx.dom.subtitleContainer.style.top = "50%";
-      ctx.dom.subtitleContainer.style.bottom = "";
-      ctx.dom.subtitleContainer.style.transform = "translateY(-50%)";
-      return;
-    }
-
-    const subPosMargin =
-      ((100 - params.metrics.subPos) / 100) * params.renderAreaHeight;
-    const effectiveMargin = Math.max(params.marginY, subPosMargin);
-    const bottomPx = Math.max(
-      0,
-      params.bottomInset + effectiveMargin + baselineCompensationPx,
-    );
-
-    ctx.dom.subtitleContainer.style.top = "";
-    ctx.dom.subtitleContainer.style.bottom = `${bottomPx}px`;
-  }
-
-  function applySubtitleTypography(params: {
-    metrics: MpvSubtitleRenderMetrics;
-    pxPerScaledPixel: number;
-    effectiveFontSize: number;
-  }): void {
-    const lineCount = Math.max(1, ctx.state.currentInvisibleSubtitleLineCount);
-    const multiline = lineCount > 1;
-
-    ctx.dom.subtitleRoot.style.setProperty(
-      "line-height",
-      ctx.platform.isMacOSPlatform
-        ? lineCount >= 3
-          ? INVISIBLE_MACOS_LINE_HEIGHT_MULTI_DENSE
-          : multiline
-            ? INVISIBLE_MACOS_LINE_HEIGHT_MULTI
-            : INVISIBLE_MACOS_LINE_HEIGHT_SINGLE
-        : "normal",
-      ctx.platform.isMacOSPlatform ? "important" : "",
-    );
-
-    const rawFont = params.metrics.subFont;
-    const strippedFont = rawFont
-      .replace(
-        /\s+(Regular|Bold|Italic|Light|Medium|Semi\s*Bold|Extra\s*Bold|Extra\s*Light|Thin|Black|Heavy|Demi\s*Bold|Book|Condensed)\s*$/i,
-        "",
-      )
-      .trim();
-
-    ctx.dom.subtitleRoot.style.fontFamily =
-      strippedFont !== rawFont
-        ? `"${rawFont}", "${strippedFont}", sans-serif`
-        : `"${rawFont}", sans-serif`;
-
-    const effectiveSpacing = params.metrics.subSpacing;
-    ctx.dom.subtitleRoot.style.setProperty(
-      "letter-spacing",
-      Math.abs(effectiveSpacing) > 0.0001
-        ? `${effectiveSpacing * params.pxPerScaledPixel * (ctx.platform.isMacOSPlatform ? 0.7 : 1)}px`
-        : ctx.platform.isMacOSPlatform
-          ? "-0.02em"
-          : "0px",
-      ctx.platform.isMacOSPlatform ? "important" : "",
-    );
-
-    ctx.dom.subtitleRoot.style.fontKerning = ctx.platform.isMacOSPlatform
-      ? "auto"
-      : "none";
-    ctx.dom.subtitleRoot.style.fontWeight = params.metrics.subBold ? "700" : "400";
-    ctx.dom.subtitleRoot.style.fontStyle = params.metrics.subItalic
-      ? "italic"
-      : "normal";
-
-    const scaleX = 1;
-    const scaleY = 1;
-    if (Math.abs(scaleX - 1) > 0.0001 || Math.abs(scaleY - 1) > 0.0001) {
-      ctx.dom.subtitleRoot.style.transform = `scale(${scaleX}, ${scaleY})`;
-      ctx.dom.subtitleRoot.style.transformOrigin = "50% 100%";
-    } else {
-      ctx.dom.subtitleRoot.style.transform = "";
-      ctx.dom.subtitleRoot.style.transformOrigin = "";
-    }
-
-    const computedLineHeight = parseFloat(getComputedStyle(ctx.dom.subtitleRoot).lineHeight);
-    if (
-      Number.isFinite(computedLineHeight) &&
-      computedLineHeight > params.effectiveFontSize
-    ) {
-      const halfLeading = (computedLineHeight - params.effectiveFontSize) / 2;
-      const currentBottom = parseFloat(ctx.dom.subtitleContainer.style.bottom);
-      const currentTop = parseFloat(ctx.dom.subtitleContainer.style.top);
-
-      if (halfLeading > 0.5 && Number.isFinite(currentBottom)) {
-        ctx.dom.subtitleContainer.style.bottom = `${Math.max(
-          0,
-          currentBottom - halfLeading,
-        )}px`;
-      }
-
-      if (halfLeading > 0.5 && Number.isFinite(currentTop)) {
-        ctx.dom.subtitleContainer.style.top = `${Math.max(0, currentTop - halfLeading)}px`;
-      }
-    }
-
-    if (ctx.platform.isMacOSPlatform) {
-      const currentBottom = parseFloat(ctx.dom.subtitleContainer.style.bottom);
-      if (Number.isFinite(currentBottom)) {
-        ctx.dom.subtitleContainer.style.bottom = `${Math.max(
-          0,
-          currentBottom + INVISIBLE_MACOS_VERTICAL_NUDGE_PX,
-        )}px`;
-      }
-    }
-  }
-
-  function applyInvisibleSubtitleLayoutFromMpvMetrics(
-    metrics: MpvSubtitleRenderMetrics,
-    source: string,
-  ): void {
-    ctx.state.mpvSubtitleRenderMetrics = metrics;
-
-    const dims = metrics.osdDimensions;
-    const osdToCssScale = computeOsdToCssScale(metrics);
-    const renderAreaHeight = dims ? dims.h / osdToCssScale : window.innerHeight;
-    const renderAreaWidth = dims ? dims.w / osdToCssScale : window.innerWidth;
-    const videoLeftInset = dims ? dims.ml / osdToCssScale : 0;
-    const videoRightInset = dims ? dims.mr / osdToCssScale : 0;
-    const videoTopInset = dims ? dims.mt / osdToCssScale : 0;
-    const videoBottomInset = dims ? dims.mb / osdToCssScale : 0;
-
-    const anchorToVideoArea = !metrics.subUseMargins;
-    const leftInset = anchorToVideoArea ? videoLeftInset : 0;
-    const rightInset = anchorToVideoArea ? videoRightInset : 0;
-    const topInset = anchorToVideoArea ? videoTopInset : 0;
-    const bottomInset = anchorToVideoArea ? videoBottomInset : 0;
-
-    const videoHeight = renderAreaHeight - videoTopInset - videoBottomInset;
-    const scaleRefHeight = metrics.subScaleByWindow ? renderAreaHeight : videoHeight;
-    const pxPerScaledPixel = Math.max(0.1, scaleRefHeight / 720);
-    const computedFontSize =
-      metrics.subFontSize *
-      metrics.subScale *
-      (ctx.platform.isLinuxPlatform ? 1 : pxPerScaledPixel);
-
-    const effectiveFontSize =
-      computedFontSize * (ctx.platform.isMacOSPlatform ? 0.87 : 1);
-    options.applySubtitleFontSize(effectiveFontSize);
-
-    const marginY = metrics.subMarginY * pxPerScaledPixel;
-    const marginX = Math.max(0, metrics.subMarginX * pxPerScaledPixel);
-    const horizontalAvailable = Math.max(
-      0,
-      renderAreaWidth - leftInset - rightInset - Math.round(marginX * 2),
-    );
-
-    const effectiveBorderSize = metrics.subBorderSize * pxPerScaledPixel;
-    document.documentElement.style.setProperty(
-      "--sub-border-size",
-      `${effectiveBorderSize}px`,
-    );
-
-    const alignment = 2;
-    const hAlign = ((alignment - 1) % 3) as 0 | 1 | 2;
-    const vAlign = Math.floor((alignment - 1) / 3) as 0 | 1 | 2;
-
-    applySubtitleContainerBaseLayout({
-      horizontalAvailable,
-      leftInset,
-      marginX,
-      hAlign,
-    });
-
-    applySubtitleVerticalPosition({
-      metrics,
-      renderAreaHeight,
-      topInset,
-      bottomInset,
-      marginY,
-      effectiveFontSize,
-      vAlign,
-    });
-
-    applySubtitleTypography({ metrics, pxPerScaledPixel, effectiveFontSize });
-
-    ctx.state.invisibleLayoutBaseLeftPx =
-      parseFloat(ctx.dom.subtitleContainer.style.left) || 0;
-
-    const parsedBottom = parseFloat(ctx.dom.subtitleContainer.style.bottom);
-    ctx.state.invisibleLayoutBaseBottomPx = Number.isFinite(parsedBottom)
-      ? parsedBottom
-      : null;
-
-    const parsedTop = parseFloat(ctx.dom.subtitleContainer.style.top);
-    ctx.state.invisibleLayoutBaseTopPx = Number.isFinite(parsedTop) ? parsedTop : null;
-
-    applyInvisibleSubtitleOffsetPosition();
-    updateInvisiblePositionEditHud();
-
-    console.log(
-      "[invisible-overlay] Applied mpv subtitle render metrics from",
-      source,
-    );
-  }
-
-  function saveInvisiblePositionEdit(): void {
-    persistSubtitlePositionPatch({
-      invisibleOffsetXPx: ctx.state.invisibleSubtitleOffsetXPx,
-      invisibleOffsetYPx: ctx.state.invisibleSubtitleOffsetYPx,
-    });
-    setInvisiblePositionEditMode(false);
-  }
-
-  function cancelInvisiblePositionEdit(): void {
-    ctx.state.invisibleSubtitleOffsetXPx = ctx.state.invisiblePositionEditStartX;
-    ctx.state.invisibleSubtitleOffsetYPx = ctx.state.invisiblePositionEditStartY;
-    applyInvisibleSubtitleOffsetPosition();
-    setInvisiblePositionEditMode(false);
-  }
-
-  function setupInvisiblePositionEditHud(): void {
-    if (!ctx.platform.isInvisibleLayer) return;
-    const hud = document.createElement("div");
-    hud.id = "invisiblePositionEditHud";
-    hud.className = "invisible-position-edit-hud";
-    ctx.dom.overlay.appendChild(hud);
-    ctx.state.invisiblePositionEditHud = hud;
-    updateInvisiblePositionEditHud();
-  }
-
-  return {
-    applyInvisibleStoredSubtitlePosition,
-    applyInvisibleSubtitleLayoutFromMpvMetrics,
-    applyInvisibleSubtitleOffsetPosition,
-    applyStoredSubtitlePosition,
-    applyYPercent,
-    cancelInvisiblePositionEdit,
-    getCurrentYPercent,
-    persistSubtitlePositionPatch,
-    saveInvisiblePositionEdit,
-    setInvisiblePositionEditMode,
-    setupInvisiblePositionEditHud,
-    updateInvisiblePositionEditHud,
-  };
-}
+export { createPositioningController } from "./positioning/controller.js";

src/renderer/positioning/controller.ts

@@ -0,0 +1,46 @@
+import type { ModalStateReader, RendererContext } from "../context";
+import {
+  createInMemorySubtitlePositionController,
+  type SubtitlePositionController,
+} from "./position-state.js";
+import {
+  createInvisibleOffsetController,
+  type InvisibleOffsetController,
+} from "./invisible-offset.js";
+import {
+  createMpvSubtitleLayoutController,
+  type MpvSubtitleLayoutController,
+} from "./invisible-layout.js";
+
+type PositioningControllerOptions = {
+  modalStateReader: Pick<ModalStateReader, "isAnySettingsModalOpen">;
+  applySubtitleFontSize: (fontSize: number) => void;
+};
+
+export function createPositioningController(
+  ctx: RendererContext,
+  options: PositioningControllerOptions,
+) {
+  const visible = createInMemorySubtitlePositionController(ctx);
+  const invisibleOffset = createInvisibleOffsetController(
+    ctx,
+    options.modalStateReader,
+  );
+  const invisibleLayout = createMpvSubtitleLayoutController(
+    ctx,
+    options.applySubtitleFontSize,
+    {
+      applyInvisibleSubtitleOffsetPosition:
+        invisibleOffset.applyInvisibleSubtitleOffsetPosition,
+      updateInvisiblePositionEditHud: invisibleOffset.updateInvisiblePositionEditHud,
+    },
+  );
+
+  return {
+    ...visible,
+    ...invisibleOffset,
+    ...invisibleLayout,
+  } as SubtitlePositionController &
+    InvisibleOffsetController &
+    MpvSubtitleLayoutController;
+}

src/renderer/positioning/invisible-layout-helpers.ts

@@ -0,0 +1,185 @@
+import type { MpvSubtitleRenderMetrics } from "../../types";
+import type { RendererContext } from "../context";
+
+const INVISIBLE_MACOS_VERTICAL_NUDGE_PX = 5;
+const INVISIBLE_MACOS_LINE_HEIGHT_SINGLE = "0.92";
+const INVISIBLE_MACOS_LINE_HEIGHT_MULTI = "1.2";
+const INVISIBLE_MACOS_LINE_HEIGHT_MULTI_DENSE = "1.3";
+
+export function applyContainerBaseLayout(ctx: RendererContext, params: {
+  horizontalAvailable: number;
+  leftInset: number;
+  marginX: number;
+  hAlign: 0 | 1 | 2;
+}): void {
+  const { horizontalAvailable, leftInset, marginX, hAlign } = params;
+
+  ctx.dom.subtitleContainer.style.position = "absolute";
+  ctx.dom.subtitleContainer.style.maxWidth = `${horizontalAvailable}px`;
+  ctx.dom.subtitleContainer.style.width = `${horizontalAvailable}px`;
+  ctx.dom.subtitleContainer.style.padding = "0";
+  ctx.dom.subtitleContainer.style.background = "transparent";
+  ctx.dom.subtitleContainer.style.marginBottom = "0";
+  ctx.dom.subtitleContainer.style.pointerEvents = "none";
+  ctx.dom.subtitleContainer.style.left = `${leftInset + marginX}px`;
+  ctx.dom.subtitleContainer.style.right = "";
+  ctx.dom.subtitleContainer.style.transform = "";
+  ctx.dom.subtitleContainer.style.textAlign = "";
+
+  if (hAlign === 0) {
+    ctx.dom.subtitleContainer.style.textAlign = "left";
+    ctx.dom.subtitleRoot.style.textAlign = "left";
+  } else if (hAlign === 2) {
+    ctx.dom.subtitleContainer.style.textAlign = "right";
+    ctx.dom.subtitleRoot.style.textAlign = "right";
+  } else {
+    ctx.dom.subtitleContainer.style.textAlign = "center";
+    ctx.dom.subtitleRoot.style.textAlign = "center";
+  }
+
+  ctx.dom.subtitleRoot.style.display = "inline-block";
+  ctx.dom.subtitleRoot.style.maxWidth = "100%";
+  ctx.dom.subtitleRoot.style.pointerEvents = "auto";
+}
+
+export function applyVerticalPosition(ctx: RendererContext, params: {
+  metrics: MpvSubtitleRenderMetrics;
+  renderAreaHeight: number;
+  topInset: number;
+  bottomInset: number;
+  marginY: number;
+  effectiveFontSize: number;
+  vAlign: 0 | 1 | 2;
+}): void {
+  const lineCount = Math.max(1, ctx.state.currentInvisibleSubtitleLineCount);
+  const multiline = lineCount > 1;
+  const baselineCompensationFactor = lineCount >= 3 ? 0.46 : multiline ? 0.58 : 0.7;
+  const baselineCompensationPx = Math.max(0, params.effectiveFontSize * baselineCompensationFactor);
+
+  if (params.vAlign === 2) {
+    ctx.dom.subtitleContainer.style.top = `${Math.max(
+      0,
+      params.topInset + params.marginY - baselineCompensationPx,
+    )}px`;
+    ctx.dom.subtitleContainer.style.bottom = "";
+    return;
+  }
+
+  if (params.vAlign === 1) {
+    ctx.dom.subtitleContainer.style.top = "50%";
+    ctx.dom.subtitleContainer.style.bottom = "";
+    ctx.dom.subtitleContainer.style.transform = "translateY(-50%)";
+    return;
+  }
+
+  const subPosMargin = ((100 - params.metrics.subPos) / 100) * params.renderAreaHeight;
+  const effectiveMargin = Math.max(params.marginY, subPosMargin);
+  const bottomPx = Math.max(
+    0,
+    params.bottomInset + effectiveMargin + baselineCompensationPx,
+  );
+
+  ctx.dom.subtitleContainer.style.top = "";
+  ctx.dom.subtitleContainer.style.bottom = `${bottomPx}px`;
+}
+
+function resolveFontFamily(rawFont: string): string {
+  const strippedFont = rawFont
+    .replace(
+      /\s+(Regular|Bold|Italic|Light|Medium|Semi\s*Bold|Extra\s*Bold|Extra\s*Light|Thin|Black|Heavy|Demi\s*Bold|Book|Condensed)\s*$/i,
+      "",
+    )
+    .trim();
+
+  return strippedFont !== rawFont
+    ? `"${rawFont}", "${strippedFont}", sans-serif`
+    : `"${rawFont}", sans-serif`;
+}
+
+function resolveLineHeight(lineCount: number, isMacOSPlatform: boolean): string {
+  if (!isMacOSPlatform) return "normal";
+  if (lineCount >= 3) return INVISIBLE_MACOS_LINE_HEIGHT_MULTI_DENSE;
+  if (lineCount >= 2) return INVISIBLE_MACOS_LINE_HEIGHT_MULTI;
+  return INVISIBLE_MACOS_LINE_HEIGHT_SINGLE;
+}
+
+function resolveLetterSpacing(
+  spacing: number,
+  pxPerScaledPixel: number,
+  isMacOSPlatform: boolean,
+): string {
+  if (Math.abs(spacing) > 0.0001) {
+    return `${spacing * pxPerScaledPixel * (isMacOSPlatform ? 0.7 : 1)}px`;
+  }
+
+  return isMacOSPlatform ? "-0.02em" : "0px";
+}
+
+function applyComputedLineHeightCompensation(ctx: RendererContext, effectiveFontSize: number): void {
+  const computedLineHeight = parseFloat(getComputedStyle(ctx.dom.subtitleRoot).lineHeight);
+  if (
+    !Number.isFinite(computedLineHeight) ||
+    computedLineHeight <= effectiveFontSize
+  ) {
+    return;
+  }
+
+  const halfLeading = (computedLineHeight - effectiveFontSize) / 2;
+  if (halfLeading <= 0.5) return;
+
+  const currentBottom = parseFloat(ctx.dom.subtitleContainer.style.bottom);
+  if (Number.isFinite(currentBottom)) {
+    ctx.dom.subtitleContainer.style.bottom = `${Math.max(0, currentBottom - halfLeading)}px`;
+  }
+
+  const currentTop = parseFloat(ctx.dom.subtitleContainer.style.top);
+  if (Number.isFinite(currentTop)) {
+    ctx.dom.subtitleContainer.style.top = `${Math.max(0, currentTop - halfLeading)}px`;
+  }
+}
+
+function applyMacOSAdjustments(ctx: RendererContext): void {
+  const isMacOSPlatform = ctx.platform.isMacOSPlatform;
+  if (!isMacOSPlatform) return;
+
+  const currentBottom = parseFloat(ctx.dom.subtitleContainer.style.bottom);
+  if (!Number.isFinite(currentBottom)) return;
+
+  ctx.dom.subtitleContainer.style.bottom = `${Math.max(
+    0,
+    currentBottom + INVISIBLE_MACOS_VERTICAL_NUDGE_PX,
+  )}px`;
+}
+
+export function applyTypography(ctx: RendererContext, params: {
+  metrics: MpvSubtitleRenderMetrics;
+  pxPerScaledPixel: number;
+  effectiveFontSize: number;
+}): void {
+  const lineCount = Math.max(1, ctx.state.currentInvisibleSubtitleLineCount);
+  const isMacOSPlatform = ctx.platform.isMacOSPlatform;
+
+  ctx.dom.subtitleRoot.style.setProperty(
+    "line-height",
+    resolveLineHeight(lineCount, isMacOSPlatform),
+    isMacOSPlatform ? "important" : "",
+  );
+  ctx.dom.subtitleRoot.style.fontFamily = resolveFontFamily(params.metrics.subFont);
+  ctx.dom.subtitleRoot.style.setProperty(
+    "letter-spacing",
+    resolveLetterSpacing(
+      params.metrics.subSpacing,
+      params.pxPerScaledPixel,
+      isMacOSPlatform,
+    ),
+    isMacOSPlatform ? "important" : "",
+  );
+  ctx.dom.subtitleRoot.style.fontKerning = isMacOSPlatform ? "auto" : "none";
+  ctx.dom.subtitleRoot.style.fontWeight = params.metrics.subBold ? "700" : "400";
+  ctx.dom.subtitleRoot.style.fontStyle = params.metrics.subItalic ? "italic" : "normal";
+  ctx.dom.subtitleRoot.style.transform = "";
+  ctx.dom.subtitleRoot.style.transformOrigin = "";
+
+  applyComputedLineHeightCompensation(ctx, params.effectiveFontSize);
+  applyMacOSAdjustments(ctx);
+}

src/renderer/positioning/invisible-layout-metrics.ts

@@ -0,0 +1,134 @@
+import type { MpvSubtitleRenderMetrics } from "../../types";
+import type { RendererContext } from "../context";
+
+export type SubtitleAlignment = { hAlign: 0 | 1 | 2; vAlign: 0 | 1 | 2 };
+
+export type SubtitleLayoutGeometry = {
+  renderAreaHeight: number;
+  renderAreaWidth: number;
+  leftInset: number;
+  rightInset: number;
+  topInset: number;
+  bottomInset: number;
+  horizontalAvailable: number;
+  marginY: number;
+  marginX: number;
+  pxPerScaledPixel: number;
+  effectiveFontSize: number;
+};
+
+export function calculateOsdScale(
+  metrics: MpvSubtitleRenderMetrics,
+  isMacOSPlatform: boolean,
+  viewportWidth: number,
+  viewportHeight: number,
+  devicePixelRatio: number,
+): number {
+  const dims = metrics.osdDimensions;
+
+  if (!isMacOSPlatform || !dims) {
+    return devicePixelRatio;
+  }
+
+  const ratios = [
+    dims.w / Math.max(1, viewportWidth),
+    dims.h / Math.max(1, viewportHeight),
+  ].filter((value) => Number.isFinite(value) && value > 0);
+
+  const avgRatio =
+    ratios.length > 0
+      ? ratios.reduce((sum, value) => sum + value, 0) / ratios.length
+      : devicePixelRatio;
+
+  return avgRatio > 1.25 ? avgRatio : 1;
+}
+
+export function calculateSubtitlePosition(
+  _metrics: MpvSubtitleRenderMetrics,
+  _scale: number,
+  alignment: number,
+): SubtitleAlignment {
+  return {
+    hAlign: ((alignment - 1) % 3) as 0 | 1 | 2,
+    vAlign: Math.floor((alignment - 1) / 3) as 0 | 1 | 2,
+  };
+}
+
+function resolveLinePadding(
+  metrics: MpvSubtitleRenderMetrics,
+  pxPerScaledPixel: number,
+): { marginY: number; marginX: number } {
+  return {
+    marginY: metrics.subMarginY * pxPerScaledPixel,
+    marginX: Math.max(0, metrics.subMarginX * pxPerScaledPixel),
+  };
+}
+
+export function applyPlatformFontCompensation(
+  fontSizePx: number,
+  isMacOSPlatform: boolean,
+): number {
+  return isMacOSPlatform ? fontSizePx * 0.87 : fontSizePx;
+}
+
+function calculateGeometry(
+  metrics: MpvSubtitleRenderMetrics,
+  osdToCssScale: number,
+): Omit<SubtitleLayoutGeometry, "marginY" | "marginX" | "pxPerScaledPixel" | "effectiveFontSize"> {
+  const dims = metrics.osdDimensions;
+  const renderAreaHeight = dims ? dims.h / osdToCssScale : window.innerHeight;
+  const renderAreaWidth = dims ? dims.w / osdToCssScale : window.innerWidth;
+  const videoLeftInset = dims ? dims.ml / osdToCssScale : 0;
+  const videoRightInset = dims ? dims.mr / osdToCssScale : 0;
+  const videoTopInset = dims ? dims.mt / osdToCssScale : 0;
+  const videoBottomInset = dims ? dims.mb / osdToCssScale : 0;
+
+  const anchorToVideoArea = !metrics.subUseMargins;
+  const leftInset = anchorToVideoArea ? videoLeftInset : 0;
+  const rightInset = anchorToVideoArea ? videoRightInset : 0;
+  const topInset = anchorToVideoArea ? videoTopInset : 0;
+  const bottomInset = anchorToVideoArea ? videoBottomInset : 0;
+  const horizontalAvailable = Math.max(0, renderAreaWidth - leftInset - rightInset);
+
+  return {
+    renderAreaHeight,
+    renderAreaWidth,
+    leftInset,
+    rightInset,
+    topInset,
+    bottomInset,
+    horizontalAvailable,
+  };
+}
+
+export function calculateSubtitleMetrics(
+  ctx: RendererContext,
+  metrics: MpvSubtitleRenderMetrics,
+): SubtitleLayoutGeometry {
+  const osdToCssScale = calculateOsdScale(
+    metrics,
+    ctx.platform.isMacOSPlatform,
+    window.innerWidth,
+    window.innerHeight,
+    window.devicePixelRatio || 1,
+  );
+  const geometry = calculateGeometry(metrics, osdToCssScale);
+  const videoHeight = geometry.renderAreaHeight - geometry.topInset - geometry.bottomInset;
+  const scaleRefHeight = metrics.subScaleByWindow ? geometry.renderAreaHeight : videoHeight;
+  const pxPerScaledPixel = Math.max(0.1, scaleRefHeight / 720);
+  const computedFontSize =
+    metrics.subFontSize * metrics.subScale * (ctx.platform.isLinuxPlatform ? 1 : pxPerScaledPixel);
+  const effectiveFontSize = applyPlatformFontCompensation(
+    computedFontSize,
+    ctx.platform.isMacOSPlatform,
+  );
+  const spacing = resolveLinePadding(metrics, pxPerScaledPixel);
+
+  return {
+    ...geometry,
+    marginY: spacing.marginY,
+    marginX: spacing.marginX,
+    pxPerScaledPixel,
+    effectiveFontSize,
+  };
+}

src/renderer/positioning/invisible-layout.ts

@@ -0,0 +1,90 @@
+import type { MpvSubtitleRenderMetrics } from "../../types";
+import type { RendererContext } from "../context";
+import {
+  applyContainerBaseLayout,
+  applyTypography,
+  applyVerticalPosition,
+} from "./invisible-layout-helpers.js";
+import {
+  calculateSubtitleMetrics,
+  calculateSubtitlePosition,
+} from "./invisible-layout-metrics.js";
+
+export type MpvSubtitleLayoutController = {
+  applyInvisibleSubtitleLayoutFromMpvMetrics: (metrics: MpvSubtitleRenderMetrics, source: string) => void;
+};
+
+export function createMpvSubtitleLayoutController(
+  ctx: RendererContext,
+  applySubtitleFontSize: (fontSize: number) => void,
+  options: {
+    applyInvisibleSubtitleOffsetPosition: () => void;
+    updateInvisiblePositionEditHud: () => void;
+  },
+): MpvSubtitleLayoutController {
+  function applyInvisibleSubtitleLayoutFromMpvMetrics(
+    metrics: MpvSubtitleRenderMetrics,
+    source: string,
+  ): void {
+    ctx.state.mpvSubtitleRenderMetrics = metrics;
+
+    const geometry = calculateSubtitleMetrics(ctx, metrics);
+    const alignment = calculateSubtitlePosition(metrics, geometry.pxPerScaledPixel, 2);
+
+    applySubtitleFontSize(geometry.effectiveFontSize);
+    const effectiveBorderSize = metrics.subBorderSize * geometry.pxPerScaledPixel;
+
+    document.documentElement.style.setProperty(
+      "--sub-border-size",
+      `${effectiveBorderSize}px`,
+    );
+
+    applyContainerBaseLayout(ctx, {
+      horizontalAvailable: Math.max(
+        0,
+        geometry.horizontalAvailable - Math.round(geometry.marginX * 2),
+      ),
+      leftInset: geometry.leftInset,
+      marginX: geometry.marginX,
+      hAlign: alignment.hAlign,
+    });
+
+    applyVerticalPosition(ctx, {
+      metrics,
+      renderAreaHeight: geometry.renderAreaHeight,
+      topInset: geometry.topInset,
+      bottomInset: geometry.bottomInset,
+      marginY: geometry.marginY,
+      effectiveFontSize: geometry.effectiveFontSize,
+      vAlign: alignment.vAlign,
+    });
+
+    applyTypography(ctx, {
+      metrics,
+      pxPerScaledPixel: geometry.pxPerScaledPixel,
+      effectiveFontSize: geometry.effectiveFontSize,
+    });
+
+    ctx.state.invisibleLayoutBaseLeftPx =
+      parseFloat(ctx.dom.subtitleContainer.style.left) || 0;
+
+    const parsedBottom = parseFloat(ctx.dom.subtitleContainer.style.bottom);
+    ctx.state.invisibleLayoutBaseBottomPx = Number.isFinite(parsedBottom)
+      ? parsedBottom
+      : null;
+
+    const parsedTop = parseFloat(ctx.dom.subtitleContainer.style.top);
+    ctx.state.invisibleLayoutBaseTopPx = Number.isFinite(parsedTop)
+      ? parsedTop
+      : null;
+
+    options.applyInvisibleSubtitleOffsetPosition();
+    options.updateInvisiblePositionEditHud();
+
+    console.log("[invisible-overlay] Applied mpv subtitle render metrics from", source);
+  }
+
+  return {
+    applyInvisibleSubtitleLayoutFromMpvMetrics,
+  };
+}

src/renderer/positioning/invisible-offset.ts

@@ -0,0 +1,163 @@
+import type { SubtitlePosition } from "../../types";
+import type { ModalStateReader, RendererContext } from "../context";
+
+export type InvisibleOffsetController = {
+  applyInvisibleStoredSubtitlePosition: (position: SubtitlePosition | null, source: string) => void;
+  applyInvisibleSubtitleOffsetPosition: () => void;
+  updateInvisiblePositionEditHud: () => void;
+  setInvisiblePositionEditMode: (enabled: boolean) => void;
+  saveInvisiblePositionEdit: () => void;
+  cancelInvisiblePositionEdit: () => void;
+  setupInvisiblePositionEditHud: () => void;
+};
+
+function formatEditHudText(offsetX: number, offsetY: number): string {
+  return `Position Edit  Ctrl/Cmd+Shift+P toggle  Arrow keys move  Enter/Ctrl+S save  Esc cancel  x:${Math.round(offsetX)} y:${Math.round(offsetY)}`;
+}
+
+function createEditPositionText(
+  ctx: RendererContext,
+): string {
+  return formatEditHudText(
+    ctx.state.invisibleSubtitleOffsetXPx,
+    ctx.state.invisibleSubtitleOffsetYPx,
+  );
+}
+
+function applyOffsetByBasePosition(ctx: RendererContext): void {
+  const nextLeft =
+    ctx.state.invisibleLayoutBaseLeftPx + ctx.state.invisibleSubtitleOffsetXPx;
+  ctx.dom.subtitleContainer.style.left = `${nextLeft}px`;
+
+  if (ctx.state.invisibleLayoutBaseBottomPx !== null) {
+    ctx.dom.subtitleContainer.style.bottom = `${Math.max(
+      0,
+      ctx.state.invisibleLayoutBaseBottomPx + ctx.state.invisibleSubtitleOffsetYPx,
+    )}px`;
+    ctx.dom.subtitleContainer.style.top = "";
+    return;
+  }
+
+  if (ctx.state.invisibleLayoutBaseTopPx !== null) {
+    ctx.dom.subtitleContainer.style.top = `${Math.max(
+      0,
+      ctx.state.invisibleLayoutBaseTopPx - ctx.state.invisibleSubtitleOffsetYPx,
+    )}px`;
+    ctx.dom.subtitleContainer.style.bottom = "";
+  }
+}
+
+export function createInvisibleOffsetController(
+  ctx: RendererContext,
+  modalStateReader: Pick<ModalStateReader, "isAnySettingsModalOpen">,
+): InvisibleOffsetController {
+  function setInvisiblePositionEditMode(enabled: boolean): void {
+    if (!ctx.platform.isInvisibleLayer) return;
+    if (ctx.state.invisiblePositionEditMode === enabled) return;
+
+    ctx.state.invisiblePositionEditMode = enabled;
+    document.body.classList.toggle("invisible-position-edit", enabled);
+
+    if (enabled) {
+      ctx.state.invisiblePositionEditStartX = ctx.state.invisibleSubtitleOffsetXPx;
+      ctx.state.invisiblePositionEditStartY = ctx.state.invisibleSubtitleOffsetYPx;
+      ctx.dom.overlay.classList.add("interactive");
+      if (ctx.platform.shouldToggleMouseIgnore) {
+        window.electronAPI.setIgnoreMouseEvents(false);
+      }
+    } else {
+      if (!ctx.state.isOverSubtitle && !modalStateReader.isAnySettingsModalOpen()) {
+        ctx.dom.overlay.classList.remove("interactive");
+        if (ctx.platform.shouldToggleMouseIgnore) {
+          window.electronAPI.setIgnoreMouseEvents(true, { forward: true });
+        }
+      }
+    }
+
+    updateInvisiblePositionEditHud();
+  }
+
+  function updateInvisiblePositionEditHud(): void {
+    if (!ctx.state.invisiblePositionEditHud) return;
+    ctx.state.invisiblePositionEditHud.textContent = createEditPositionText(ctx);
+  }
+
+  function applyInvisibleSubtitleOffsetPosition(): void {
+    applyOffsetByBasePosition(ctx);
+  }
+
+  function applyInvisibleStoredSubtitlePosition(position: SubtitlePosition | null, source: string): void {
+    if (
+      position &&
+      typeof position.yPercent === "number" &&
+      Number.isFinite(position.yPercent)
+    ) {
+      ctx.state.persistedSubtitlePosition = {
+        ...ctx.state.persistedSubtitlePosition,
+        yPercent: position.yPercent,
+      };
+    }
+
+    if (position) {
+      const nextX =
+        typeof position.invisibleOffsetXPx === "number" && Number.isFinite(position.invisibleOffsetXPx)
+          ? position.invisibleOffsetXPx
+          : 0;
+      const nextY =
+        typeof position.invisibleOffsetYPx === "number" && Number.isFinite(position.invisibleOffsetYPx)
+          ? position.invisibleOffsetYPx
+          : 0;
+      ctx.state.invisibleSubtitleOffsetXPx = nextX;
+      ctx.state.invisibleSubtitleOffsetYPx = nextY;
+    } else {
+      ctx.state.invisibleSubtitleOffsetXPx = 0;
+      ctx.state.invisibleSubtitleOffsetYPx = 0;
+    }
+
+    applyOffsetByBasePosition(ctx);
+    console.log(
+      "[invisible-overlay] Applied subtitle offset from",
+      source,
+      `${ctx.state.invisibleSubtitleOffsetXPx}px`,
+      `${ctx.state.invisibleSubtitleOffsetYPx}px`,
+    );
+    updateInvisiblePositionEditHud();
+  }
+
+  function saveInvisiblePositionEdit(): void {
+    const nextPosition = {
+      yPercent: ctx.state.persistedSubtitlePosition.yPercent,
+      invisibleOffsetXPx: ctx.state.invisibleSubtitleOffsetXPx,
+      invisibleOffsetYPx: ctx.state.invisibleSubtitleOffsetYPx,
+    };
+    window.electronAPI.saveSubtitlePosition(nextPosition);
+    setInvisiblePositionEditMode(false);
+  }
+
+  function cancelInvisiblePositionEdit(): void {
+    ctx.state.invisibleSubtitleOffsetXPx = ctx.state.invisiblePositionEditStartX;
+    ctx.state.invisibleSubtitleOffsetYPx = ctx.state.invisiblePositionEditStartY;
+    applyOffsetByBasePosition(ctx);
+    setInvisiblePositionEditMode(false);
+  }
+
+  function setupInvisiblePositionEditHud(): void {
+    if (!ctx.platform.isInvisibleLayer) return;
+    const hud = document.createElement("div");
+    hud.id = "invisiblePositionEditHud";
+    hud.className = "invisible-position-edit-hud";
+    ctx.dom.overlay.appendChild(hud);
+    ctx.state.invisiblePositionEditHud = hud;
+    updateInvisiblePositionEditHud();
+  }
+
+  return {
+    applyInvisibleStoredSubtitlePosition,
+    applyInvisibleSubtitleOffsetPosition,
+    updateInvisiblePositionEditHud,
+    setInvisiblePositionEditMode,
+    saveInvisiblePositionEdit,
+    cancelInvisiblePositionEdit,
+    setupInvisiblePositionEditHud,
+  };
+}

src/renderer/positioning/position-state.ts

@@ -0,0 +1,136 @@
+import type { SubtitlePosition } from "../../types";
+import type { RendererContext } from "../context";
+
+const PREFERRED_Y_PERCENT_MIN = 2;
+const PREFERRED_Y_PERCENT_MAX = 80;
+
+export type SubtitlePositionController = {
+  applyStoredSubtitlePosition: (position: SubtitlePosition | null, source: string) => void;
+  getCurrentYPercent: () => number;
+  applyYPercent: (yPercent: number) => void;
+  persistSubtitlePositionPatch: (patch: Partial<SubtitlePosition>) => void;
+};
+
+function clampYPercent(yPercent: number): number {
+  return Math.max(PREFERRED_Y_PERCENT_MIN, Math.min(PREFERRED_Y_PERCENT_MAX, yPercent));
+}
+
+function getPersistedYPercent(
+  ctx: RendererContext,
+  position: SubtitlePosition | null,
+): number {
+  if (!position || typeof position.yPercent !== "number" || !Number.isFinite(position.yPercent)) {
+    return ctx.state.persistedSubtitlePosition.yPercent;
+  }
+
+  return position.yPercent;
+}
+
+function getPersistedOffset(
+  ctx: RendererContext,
+  position: SubtitlePosition | null,
+  key: "invisibleOffsetXPx" | "invisibleOffsetYPx",
+): number {
+  if (
+    position &&
+    typeof position[key] === "number" &&
+    Number.isFinite(position[key])
+  ) {
+    return position[key];
+  }
+
+  return 0;
+}
+
+function updatePersistedSubtitlePosition(
+  ctx: RendererContext,
+  position: SubtitlePosition | null,
+): void {
+  ctx.state.persistedSubtitlePosition = {
+    yPercent: getPersistedYPercent(ctx, position),
+    invisibleOffsetXPx: getPersistedOffset(ctx, position, "invisibleOffsetXPx"),
+    invisibleOffsetYPx: getPersistedOffset(ctx, position, "invisibleOffsetYPx"),
+  };
+}
+
+function getNextPersistedPosition(
+  ctx: RendererContext,
+  patch: Partial<SubtitlePosition>,
+): SubtitlePosition {
+  return {
+    yPercent:
+      typeof patch.yPercent === "number" && Number.isFinite(patch.yPercent)
+        ? patch.yPercent
+        : ctx.state.persistedSubtitlePosition.yPercent,
+    invisibleOffsetXPx:
+      typeof patch.invisibleOffsetXPx === "number" &&
+      Number.isFinite(patch.invisibleOffsetXPx)
+        ? patch.invisibleOffsetXPx
+        : ctx.state.persistedSubtitlePosition.invisibleOffsetXPx ?? 0,
+    invisibleOffsetYPx:
+      typeof patch.invisibleOffsetYPx === "number" &&
+      Number.isFinite(patch.invisibleOffsetYPx)
+        ? patch.invisibleOffsetYPx
+        : ctx.state.persistedSubtitlePosition.invisibleOffsetYPx ?? 0,
+  };
+}
+
+export function createInMemorySubtitlePositionController(
+  ctx: RendererContext,
+): SubtitlePositionController {
+  function getCurrentYPercent(): number {
+    if (ctx.state.currentYPercent !== null) {
+      return ctx.state.currentYPercent;
+    }
+
+    const marginBottom = parseFloat(ctx.dom.subtitleContainer.style.marginBottom) || 60;
+    ctx.state.currentYPercent = clampYPercent((marginBottom / window.innerHeight) * 100);
+    return ctx.state.currentYPercent;
+  }
+
+  function applyYPercent(yPercent: number): void {
+    const clampedPercent = clampYPercent(yPercent);
+    ctx.state.currentYPercent = clampedPercent;
+    const marginBottom = (clampedPercent / 100) * window.innerHeight;
+
+    ctx.dom.subtitleContainer.style.position = "";
+    ctx.dom.subtitleContainer.style.left = "";
+    ctx.dom.subtitleContainer.style.top = "";
+    ctx.dom.subtitleContainer.style.right = "";
+    ctx.dom.subtitleContainer.style.transform = "";
+    ctx.dom.subtitleContainer.style.marginBottom = `${marginBottom}px`;
+  }
+
+  function persistSubtitlePositionPatch(patch: Partial<SubtitlePosition>): void {
+    const nextPosition = getNextPersistedPosition(ctx, patch);
+    ctx.state.persistedSubtitlePosition = nextPosition;
+    window.electronAPI.saveSubtitlePosition(nextPosition);
+  }
+
+  function applyStoredSubtitlePosition(position: SubtitlePosition | null, source: string): void {
+    updatePersistedSubtitlePosition(ctx, position);
+    if (position && position.yPercent !== undefined) {
+      applyYPercent(position.yPercent);
+      console.log(
+        "Applied subtitle position from",
+        source,
+        ":",
+        position.yPercent,
+        "%",
+      );
+      return;
+    }
+
+    const defaultMarginBottom = 60;
+    const defaultYPercent = (defaultMarginBottom / window.innerHeight) * 100;
+    applyYPercent(defaultYPercent);
+    console.log("Applied default subtitle position from", source);
+  }
+
+  return {
+    applyStoredSubtitlePosition,
+    getCurrentYPercent,
+    applyYPercent,
+    persistSubtitlePositionPatch,
+  };
+}