feat: add first-run setup flow

src/core/services/app-lifecycle.test.ts

@@ -11,6 +11,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
     toggle: false,
     toggleVisibleOverlay: false,
     settings: false,
+    setup: false,
     show: false,
     hide: false,
     showVisibleOverlay: false,

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

@@ -4,7 +4,8 @@ import { AppReadyRuntimeDeps, runAppReadyRuntime } from './startup';
 
 function makeDeps(overrides: Partial<AppReadyRuntimeDeps> = {}) {
   const calls: string[] = [];
-  const deps: AppReadyRuntimeDeps = {
+  const deps = {
+    ensureDefaultConfigBootstrap: () => calls.push('ensureDefaultConfigBootstrap'),
     loadSubtitlePosition: () => calls.push('loadSubtitlePosition'),
     resolveKeybindings: () => calls.push('resolveKeybindings'),
     createMpvClient: () => calls.push('createMpvClient'),
@@ -20,8 +21,13 @@ function makeDeps(overrides: Partial<AppReadyRuntimeDeps> = {}) {
     setSecondarySubMode: (mode) => calls.push(`setSecondarySubMode:${mode}`),
     defaultSecondarySubMode: 'hover',
     defaultWebsocketPort: 9001,
+    defaultAnnotationWebsocketPort: 6678,
+    defaultTexthookerPort: 5174,
     hasMpvWebsocketPlugin: () => true,
     startSubtitleWebsocket: (port) => calls.push(`startSubtitleWebsocket:${port}`),
+    startAnnotationWebsocket: (port) => calls.push(`startAnnotationWebsocket:${port}`),
+    startTexthooker: (port, websocketUrl) =>
+      calls.push(`startTexthooker:${port}:${websocketUrl ?? ''}`),
     log: (message) => calls.push(`log:${message}`),
     createMecabTokenizerAndCheck: async () => {
       calls.push('createMecabTokenizerAndCheck');
@@ -34,6 +40,9 @@ function makeDeps(overrides: Partial<AppReadyRuntimeDeps> = {}) {
     loadYomitanExtension: async () => {
       calls.push('loadYomitanExtension');
     },
+    handleFirstRunSetup: async () => {
+      calls.push('handleFirstRunSetup');
+    },
     prewarmSubtitleDictionaries: async () => {
       calls.push('prewarmSubtitleDictionaries');
     },
@@ -48,7 +57,7 @@ function makeDeps(overrides: Partial<AppReadyRuntimeDeps> = {}) {
     logDebug: (message) => calls.push(`debug:${message}`),
     now: () => 1000,
     ...overrides,
-  };
+  } as AppReadyRuntimeDeps;
   return { deps, calls };
 }
 
@@ -57,7 +66,9 @@ test('runAppReadyRuntime starts websocket in auto mode when plugin missing', asy
     hasMpvWebsocketPlugin: () => false,
   });
   await runAppReadyRuntime(deps);
+  assert.ok(calls.includes('ensureDefaultConfigBootstrap'));
   assert.ok(calls.includes('startSubtitleWebsocket:9001'));
+  assert.ok(calls.includes('startAnnotationWebsocket:6678'));
   assert.ok(calls.includes('setVisibleOverlayVisible:true'));
   assert.ok(calls.includes('initializeOverlayRuntime'));
   assert.ok(
@@ -71,6 +82,47 @@ test('runAppReadyRuntime starts websocket in auto mode when plugin missing', asy
   );
 });
 
+test('runAppReadyRuntime starts texthooker on startup when enabled in config', async () => {
+  const { deps, calls } = makeDeps({
+    getResolvedConfig: () => ({
+      websocket: { enabled: 'auto' },
+      secondarySub: {},
+      texthooker: { launchAtStartup: true },
+    }),
+  });
+
+  await runAppReadyRuntime(deps);
+
+  assert.ok(calls.includes('startTexthooker:5174:ws://127.0.0.1:6678'));
+  assert.ok(calls.indexOf('handleFirstRunSetup') < calls.indexOf('handleInitialArgs'));
+  assert.ok(
+    calls.indexOf('createMpvClient') < calls.indexOf('startTexthooker:5174:ws://127.0.0.1:6678'),
+  );
+  assert.ok(
+    calls.indexOf('startTexthooker:5174:ws://127.0.0.1:6678') <
+      calls.indexOf('handleInitialArgs'),
+  );
+});
+
+test('runAppReadyRuntime keeps annotation websocket enabled when regular websocket auto-skips', async () => {
+  const { deps, calls } = makeDeps({
+    getResolvedConfig: () => ({
+      websocket: { enabled: 'auto' },
+      annotationWebsocket: { enabled: true, port: 6678 },
+      secondarySub: {},
+      texthooker: { launchAtStartup: true },
+    }),
+    hasMpvWebsocketPlugin: () => true,
+  });
+
+  await runAppReadyRuntime(deps);
+
+  assert.equal(calls.includes('startSubtitleWebsocket:9001'), false);
+  assert.ok(calls.includes('startAnnotationWebsocket:6678'));
+  assert.ok(calls.includes('startTexthooker:5174:ws://127.0.0.1:6678'));
+  assert.ok(calls.includes('log:mpv_websocket detected, skipping built-in WebSocket server'));
+});
+
 test('runAppReadyRuntime skips heavy startup when shouldSkipHeavyStartup returns true', async () => {
   const { deps, calls } = makeDeps({
     shouldSkipHeavyStartup: () => true,
@@ -102,6 +154,7 @@ test('runAppReadyRuntime skips heavy startup when shouldSkipHeavyStartup returns
 
   await runAppReadyRuntime(deps);
 
+  assert.equal(calls.includes('ensureDefaultConfigBootstrap'), true);
   assert.equal(calls.includes('reloadConfig'), false);
   assert.equal(calls.includes('getResolvedConfig'), false);
   assert.equal(calls.includes('getConfigWarnings'), false);
@@ -116,7 +169,10 @@ test('runAppReadyRuntime skips heavy startup when shouldSkipHeavyStartup returns
   assert.equal(calls.includes('logConfigWarning'), false);
   assert.equal(calls.includes('handleInitialArgs'), true);
   assert.equal(calls.includes('loadYomitanExtension'), true);
+  assert.equal(calls.includes('handleFirstRunSetup'), true);
   assert.ok(calls.indexOf('loadYomitanExtension') < calls.indexOf('handleInitialArgs'));
+  assert.ok(calls.indexOf('loadYomitanExtension') < calls.indexOf('handleFirstRunSetup'));
+  assert.ok(calls.indexOf('handleFirstRunSetup') < calls.indexOf('handleInitialArgs'));
 });
 
 test('runAppReadyRuntime skips Jellyfin remote startup when dependency is not wired', async () => {

src/core/services/cli-command.test.ts

@@ -11,6 +11,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
     toggle: false,
     toggleVisibleOverlay: false,
     settings: false,
+    setup: false,
     show: false,
     hide: false,
     showVisibleOverlay: false,
@@ -96,6 +97,9 @@ function createDeps(overrides: Partial<CliCommandServiceDeps> = {}) {
     openYomitanSettingsDelayed: (delayMs) => {
       calls.push(`openYomitanSettingsDelayed:${delayMs}`);
     },
+    openFirstRunSetup: () => {
+      calls.push('openFirstRunSetup');
+    },
     setVisibleOverlayVisible: (visible) => {
       calls.push(`setVisibleOverlayVisible:${visible}`);
     },
@@ -229,6 +233,16 @@ test('handleCliCommand processes --start for second-instance when overlay runtim
   );
 });
 
+test('handleCliCommand opens first-run setup window for --setup', () => {
+  const { deps, calls } = createDeps();
+
+  handleCliCommand(makeArgs({ setup: true }), 'initial', deps);
+
+  assert.ok(calls.includes('openFirstRunSetup'));
+  assert.ok(calls.includes('log:Opened first-run setup flow.'));
+  assert.equal(calls.includes('openYomitanSettingsDelayed:1000'), false);
+});
+
 test('handleCliCommand applies cli log level for second-instance commands', () => {
   const { deps, calls } = createDeps({
     setLogLevel: (level) => {

src/core/services/cli-command.ts

@@ -17,6 +17,7 @@ export interface CliCommandServiceDeps {
   isOverlayRuntimeInitialized: () => boolean;
   initializeOverlayRuntime: () => void;
   toggleVisibleOverlay: () => void;
+  openFirstRunSetup: () => void;
   openYomitanSettingsDelayed: (delayMs: number) => void;
   setVisibleOverlayVisible: (visible: boolean) => void;
   copyCurrentSubtitle: () => void;
@@ -115,6 +116,7 @@ interface MiningCliRuntime {
 }
 
 interface UiCliRuntime {
+  openFirstRunSetup: () => void;
   openYomitanSettings: () => void;
   cycleSecondarySubMode: () => void;
   openRuntimeOptionsPalette: () => void;
@@ -195,6 +197,7 @@ export function createCliCommandDepsRuntime(
     isOverlayRuntimeInitialized: options.overlay.isInitialized,
     initializeOverlayRuntime: options.overlay.initialize,
     toggleVisibleOverlay: options.overlay.toggleVisible,
+    openFirstRunSetup: options.ui.openFirstRunSetup,
     openYomitanSettingsDelayed: (delayMs) => {
       options.schedule(() => {
         options.ui.openYomitanSettings();
@@ -298,6 +301,9 @@ export function handleCliCommand(
 
   if (args.toggle || args.toggleVisibleOverlay) {
     deps.toggleVisibleOverlay();
+  } else if (args.setup) {
+    deps.openFirstRunSetup();
+    deps.log('Opened first-run setup flow.');
   } else if (args.settings) {
     deps.openYomitanSettingsDelayed(1000);
   } else if (args.show || args.showVisibleOverlay) {

src/core/services/startup-bootstrap.test.ts

@@ -11,6 +11,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
     toggle: false,
     toggleVisibleOverlay: false,
     settings: false,
+    setup: false,
     show: false,
     hide: false,
     showVisibleOverlay: false,

src/core/services/startup.ts

@@ -69,6 +69,13 @@ export function runStartupBootstrapRuntime(
 }
 
 interface AppReadyConfigLike {
+  annotationWebsocket?: {
+    enabled?: boolean;
+    port?: number;
+  };
+  texthooker?: {
+    launchAtStartup?: boolean;
+  };
   secondarySub?: {
     defaultMode?: SecondarySubMode;
   };
@@ -92,6 +99,7 @@ interface AppReadyConfigLike {
 }
 
 export interface AppReadyRuntimeDeps {
+  ensureDefaultConfigBootstrap: () => void;
   loadSubtitlePosition: () => void;
   resolveKeybindings: () => void;
   createMpvClient: () => void;
@@ -104,14 +112,19 @@ export interface AppReadyRuntimeDeps {
   setSecondarySubMode: (mode: SecondarySubMode) => void;
   defaultSecondarySubMode: SecondarySubMode;
   defaultWebsocketPort: number;
+  defaultAnnotationWebsocketPort: number;
+  defaultTexthookerPort: number;
   hasMpvWebsocketPlugin: () => boolean;
   startSubtitleWebsocket: (port: number) => void;
+  startAnnotationWebsocket: (port: number) => void;
+  startTexthooker: (port: number, websocketUrl?: string) => void;
   log: (message: string) => void;
   createMecabTokenizerAndCheck: () => Promise<void>;
   createSubtitleTimingTracker: () => void;
   createImmersionTracker?: () => void;
   startJellyfinRemoteSession?: () => Promise<void>;
   loadYomitanExtension: () => Promise<void>;
+  handleFirstRunSetup: () => Promise<void>;
   prewarmSubtitleDictionaries?: () => Promise<void>;
   startBackgroundWarmups: () => void;
   texthookerOnlyMode: boolean;
@@ -169,8 +182,10 @@ export function isAutoUpdateEnabledRuntime(
 export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<void> {
   const now = deps.now ?? (() => Date.now());
   const startupStartedAtMs = now();
+  deps.ensureDefaultConfigBootstrap();
   if (deps.shouldSkipHeavyStartup?.()) {
     await deps.loadYomitanExtension();
+    await deps.handleFirstRunSetup();
     deps.handleInitialArgs();
     return;
   }
@@ -179,6 +194,7 @@ export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<voi
 
   if (deps.shouldSkipHeavyStartup?.()) {
     await deps.loadYomitanExtension();
+    await deps.handleFirstRunSetup();
     deps.handleInitialArgs();
     deps.logDebug?.(`App-ready critical path finished in ${now() - startupStartedAtMs}ms.`);
     return;
@@ -210,6 +226,11 @@ export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<voi
   const wsConfig = config.websocket || {};
   const wsEnabled = wsConfig.enabled ?? 'auto';
   const wsPort = wsConfig.port || deps.defaultWebsocketPort;
+  const annotationWsConfig = config.annotationWebsocket || {};
+  const annotationWsEnabled = annotationWsConfig.enabled !== false;
+  const annotationWsPort = annotationWsConfig.port || deps.defaultAnnotationWebsocketPort;
+  const texthookerPort = deps.defaultTexthookerPort;
+  let texthookerWebsocketUrl: string | undefined;
 
   if (wsEnabled === true || (wsEnabled === 'auto' && !deps.hasMpvWebsocketPlugin())) {
     deps.startSubtitleWebsocket(wsPort);
@@ -217,6 +238,17 @@ export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<voi
     deps.log('mpv_websocket detected, skipping built-in WebSocket server');
   }
 
+  if (annotationWsEnabled) {
+    deps.startAnnotationWebsocket(annotationWsPort);
+    texthookerWebsocketUrl = `ws://127.0.0.1:${annotationWsPort}`;
+  } else if (wsEnabled === true || (wsEnabled === 'auto' && !deps.hasMpvWebsocketPlugin())) {
+    texthookerWebsocketUrl = `ws://127.0.0.1:${wsPort}`;
+  }
+
+  if (config.texthooker?.launchAtStartup !== false) {
+    deps.startTexthooker(texthookerPort, texthookerWebsocketUrl);
+  }
+
   deps.createSubtitleTimingTracker();
   if (deps.createImmersionTracker) {
     deps.log('Runtime ready: immersion tracker startup deferred until first media activity.');
@@ -233,6 +265,8 @@ export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<voi
     deps.log('Overlay runtime deferred: waiting for explicit overlay command.');
   }
 
+  await deps.loadYomitanExtension();
+  await deps.handleFirstRunSetup();
   deps.handleInitialArgs();
   deps.logDebug?.(`App-ready critical path finished in ${now() - startupStartedAtMs}ms.`);
 }