@su-record/vibe 2.7.2 → 2.7.5

package/dist/pc/browser/BrowserService.d.ts

@@ -0,0 +1,66 @@
+/**
+ * BrowserService — Playwright CDP 연결 관리 (팩토리 패턴)
+ *
+ * IBrowserProvider를 통해 Local(Phase1) / Sandbox(Phase5) 분기.
+ * 연결 캐싱, 자동 재연결 (exponential backoff + jitter), 테넌트별 격리.
+ */
+import type { Page } from 'playwright';
+import type { IBrowserProvider, BrowserServiceConfig, BrowserSessionInfo, BrowserError, PageState, RoleRefMap, RoleRefsCacheEntry } from './types.js';
+type Logger = (level: string, message: string, data?: unknown) => void;
+export declare class BrowserService {
+    private browser;
+    private contexts;
+    private pageStates;
+    private refCache;
+    private config;
+    private logger;
+    private connecting;
+    constructor(logger: Logger, config?: BrowserServiceConfig);
+    /** CDP provider를 통해 브라우저에 연결 */
+    connect(provider: IBrowserProvider): Promise<void>;
+    /** 연결 해제 및 정리 */
+    disconnect(): Promise<void>;
+    /** 연결 상태 확인 */
+    isConnected(): boolean;
+    /** 테넌트별 격리된 Page 객체 반환 */
+    getPage(tenantId: string, targetId?: string): Promise<Page>;
+    /** 활성 페이지 목록 조회 */
+    listPages(tenantId: string): Promise<BrowserSessionInfo[]>;
+    /** 새 탭 열기 (URL 검증 포함) */
+    openPage(tenantId: string, url: string): Promise<Page>;
+    /** 특정 탭 닫기 */
+    closePage(tenantId: string, targetId: string): Promise<void>;
+    /** 테넌트 컨텍스트 전체 삭제 (ephemeral) */
+    destroyContext(tenantId: string): Promise<void>;
+    /** 페이지 상태 저장/조회 */
+    getPageState(page: Page): PageState | undefined;
+    setPageState(page: Page, state: PageState): void;
+    /** ref 캐시 관리 */
+    cacheRefs(targetId: string, refs: RoleRefMap, version: number): void;
+    getCachedRefs(targetId: string): RoleRefsCacheEntry | undefined;
+    /** 활성 세션 수 */
+    get activeSessionCount(): number;
+    get actionTimeout(): number;
+    /** URL 보안 검증 (SSRF 방지) */
+    private validateNavigationUrl;
+    /** exponential backoff + jitter 재시도 */
+    private connectWithRetry;
+    private ensureConnected;
+    private enforceSessionLimit;
+    private getTargetId;
+    private setupDialogHandler;
+    private sleep;
+    /** 구조화된 에러 생성 */
+    createError(code: BrowserError['error'], message: string, extra?: Partial<BrowserError>): BrowserError & Error;
+}
+export declare class LocalBrowserProvider implements IBrowserProvider {
+    readonly name = "local";
+    private cdpPort;
+    private process;
+    constructor(cdpPort?: number);
+    getCDPUrl(): Promise<string>;
+    isSandboxed(): boolean;
+    terminate(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=BrowserService.d.ts.map

package/dist/pc/browser/BrowserService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserService.d.ts","sourceRoot":"","sources":["../../../src/pc/browser/BrowserService.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAA2B,IAAI,EAAE,MAAM,YAAY,CAAC;AAEhE,OAAO,KAAK,EACV,gBAAgB,EAEhB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,UAAU,EACV,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAGpB,KAAK,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAkCvE,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,QAAQ,CAAgD;IAChE,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAiC;gBAEvC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,oBAAoB;IAYzD,gCAAgC;IAC1B,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBxD,iBAAiB;IACX,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBjC,eAAe;IACf,WAAW,IAAI,OAAO;IAItB,0BAA0B;IACpB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBjE,mBAAmB;IACb,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAchE,yBAAyB;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5D,cAAc;IACR,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlE,iCAAiC;IAC3B,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrD,mBAAmB;IACnB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,GAAG,SAAS;IAI/C,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI;IAIhD,gBAAgB;IAChB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAQpE,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAI/D,cAAc;IACd,IAAI,kBAAkB,IAAI,MAAM,CAE/B;IAED,IAAI,aAAa,IAAI,MAAM,CAE1B;IAMD,0BAA0B;IAC1B,OAAO,CAAC,qBAAqB;IAuB7B,uCAAuC;YACzB,gBAAgB;IAyB9B,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,kBAAkB;IAa1B,OAAO,CAAC,KAAK;IAIb,iBAAiB;IACjB,WAAW,CAAC,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,GAAG,KAAK;CAS/G;AAMD,qBAAa,oBAAqB,YAAW,gBAAgB;IAC3D,QAAQ,CAAC,IAAI,WAAW;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAA0D;gBAE7D,OAAO,SAAO;IAIpB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAgBlC,WAAW,IAAI,OAAO;IAIhB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAMjC"}

package/dist/pc/browser/BrowserService.js

@@ -0,0 +1,319 @@
+/**
+ * BrowserService — Playwright CDP 연결 관리 (팩토리 패턴)
+ *
+ * IBrowserProvider를 통해 Local(Phase1) / Sandbox(Phase5) 분기.
+ * 연결 캐싱, 자동 재연결 (exponential backoff + jitter), 테넌트별 격리.
+ */
+import { chromium } from 'playwright';
+import * as crypto from 'node:crypto';
+import { DEFAULT_CONFIG, ALLOWED_SCHEMES, BLOCKED_HOSTNAMES, BLOCKED_IP_PATTERNS } from './types.js';
+/** LRU 캐시 — targetId 기반 ref 캐싱 (최대 50개) */
+class LRUCache {
+    maxSize;
+    cache = new Map();
+    constructor(maxSize) {
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const value = this.cache.get(key);
+        if (value !== undefined) {
+            this.cache.delete(key);
+            this.cache.set(key, value);
+        }
+        return value;
+    }
+    set(key, value) {
+        this.cache.delete(key);
+        if (this.cache.size >= this.maxSize) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined)
+                this.cache.delete(oldest);
+        }
+        this.cache.set(key, value);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    get size() {
+        return this.cache.size;
+    }
+}
+export class BrowserService {
+    browser = null;
+    contexts = new Map();
+    pageStates = new WeakMap();
+    refCache = new LRUCache(50);
+    config;
+    logger;
+    connecting = null;
+    constructor(logger, config) {
+        this.logger = logger;
+        this.config = {
+            connectTimeout: config?.connectTimeout ?? DEFAULT_CONFIG.connectTimeout,
+            actionTimeout: config?.actionTimeout ?? DEFAULT_CONFIG.actionTimeout,
+            maxRetries: config?.maxRetries ?? DEFAULT_CONFIG.maxRetries,
+            maxLocalSessions: config?.maxLocalSessions ?? DEFAULT_CONFIG.maxLocalSessions,
+            maxSaasSessionsPerUser: config?.maxSaasSessionsPerUser ?? DEFAULT_CONFIG.maxSaasSessionsPerUser,
+            screenshotDir: config?.screenshotDir ?? '',
+        };
+    }
+    /** CDP provider를 통해 브라우저에 연결 */
+    async connect(provider) {
+        if (this.browser?.isConnected())
+            return;
+        if (this.connecting) {
+            await this.connecting;
+            return;
+        }
+        this.connecting = this.connectWithRetry(provider);
+        try {
+            this.browser = await this.connecting;
+            this.logger('info', `Browser connected via ${provider.name}`);
+        }
+        finally {
+            this.connecting = null;
+        }
+    }
+    /** 연결 해제 및 정리 */
+    async disconnect() {
+        for (const [tenantId, ctx] of this.contexts) {
+            try {
+                await ctx.close();
+            }
+            catch (err) {
+                this.logger('warn', `Failed to close context for tenant "${tenantId}"`, {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            this.contexts.delete(tenantId);
+        }
+        if (this.browser) {
+            try {
+                await this.browser.close();
+            }
+            catch (err) {
+                this.logger('warn', 'Failed to close browser', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            this.browser = null;
+        }
+        this.refCache.clear();
+        this.logger('info', 'Browser disconnected');
+    }
+    /** 연결 상태 확인 */
+    isConnected() {
+        return this.browser?.isConnected() ?? false;
+    }
+    /** 테넌트별 격리된 Page 객체 반환 */
+    async getPage(tenantId, targetId) {
+        this.ensureConnected();
+        let context = this.contexts.get(tenantId);
+        if (!context) {
+            this.enforceSessionLimit(tenantId);
+            context = await this.browser.newContext();
+            this.contexts.set(tenantId, context);
+        }
+        if (targetId) {
+            const existing = context.pages().find(p => this.getTargetId(p) === targetId);
+            if (existing)
+                return existing;
+        }
+        const pages = context.pages();
+        if (pages.length > 0 && !targetId)
+            return pages[0];
+        const page = await context.newPage();
+        this.setupDialogHandler(page);
+        return page;
+    }
+    /** 활성 페이지 목록 조회 */
+    async listPages(tenantId) {
+        const context = this.contexts.get(tenantId);
+        if (!context)
+            return [];
+        return context.pages().map(page => ({
+            tenantId,
+            targetId: this.getTargetId(page),
+            url: page.url(),
+            title: '', // sync access only
+            connected: this.isConnected(),
+            createdAt: new Date().toISOString(),
+        }));
+    }
+    /** 새 탭 열기 (URL 검증 포함) */
+    async openPage(tenantId, url) {
+        this.validateNavigationUrl(url);
+        const page = await this.getPage(tenantId);
+        await page.goto(url, { timeout: this.config.connectTimeout });
+        return page;
+    }
+    /** 특정 탭 닫기 */
+    async closePage(tenantId, targetId) {
+        const context = this.contexts.get(tenantId);
+        if (!context)
+            return;
+        const page = context.pages().find(p => this.getTargetId(p) === targetId);
+        if (page)
+            await page.close();
+    }
+    /** 테넌트 컨텍스트 전체 삭제 (ephemeral) */
+    async destroyContext(tenantId) {
+        const context = this.contexts.get(tenantId);
+        if (context) {
+            await context.close();
+            this.contexts.delete(tenantId);
+        }
+    }
+    /** 페이지 상태 저장/조회 */
+    getPageState(page) {
+        return this.pageStates.get(page);
+    }
+    setPageState(page, state) {
+        this.pageStates.set(page, state);
+    }
+    /** ref 캐시 관리 */
+    cacheRefs(targetId, refs, version) {
+        this.refCache.set(targetId, {
+            refs,
+            snapshotVersion: version,
+            cachedAt: Date.now(),
+        });
+    }
+    getCachedRefs(targetId) {
+        return this.refCache.get(targetId);
+    }
+    /** 활성 세션 수 */
+    get activeSessionCount() {
+        return this.contexts.size;
+    }
+    get actionTimeout() {
+        return this.config.actionTimeout;
+    }
+    // ──────────────────────────────────────────────────────────
+    // Private
+    // ──────────────────────────────────────────────────────────
+    /** URL 보안 검증 (SSRF 방지) */
+    validateNavigationUrl(url) {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw this.createError('NAVIGATION_BLOCKED', `Invalid URL: ${url}`);
+        }
+        if (!ALLOWED_SCHEMES.has(parsed.protocol)) {
+            throw this.createError('NAVIGATION_BLOCKED', `Blocked scheme "${parsed.protocol}". Only http/https allowed.`);
+        }
+        if (BLOCKED_HOSTNAMES.has(parsed.hostname.toLowerCase())) {
+            throw this.createError('NAVIGATION_BLOCKED', `Blocked hostname: ${parsed.hostname}`);
+        }
+        for (const pattern of BLOCKED_IP_PATTERNS) {
+            if (pattern.test(parsed.hostname)) {
+                throw this.createError('NAVIGATION_BLOCKED', `Blocked private/metadata IP: ${parsed.hostname}`);
+            }
+        }
+    }
+    /** exponential backoff + jitter 재시도 */
+    async connectWithRetry(provider) {
+        let lastError = null;
+        for (let attempt = 0; attempt < this.config.maxRetries; attempt++) {
+            try {
+                const cdpUrl = await provider.getCDPUrl();
+                const browser = await chromium.connectOverCDP(cdpUrl, {
+                    timeout: this.config.connectTimeout,
+                });
+                return browser;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                const baseDelay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
+                const jitter = Math.random() * 1000 - 500; // ±500ms
+                const delay = Math.max(0, baseDelay + jitter);
+                this.logger('warn', `CDP connection attempt ${attempt + 1}/${this.config.maxRetries} failed, retrying in ${Math.round(delay)}ms`, {
+                    error: lastError.message,
+                });
+                await this.sleep(delay);
+            }
+        }
+        throw lastError ?? new Error('CDP connection failed');
+    }
+    ensureConnected() {
+        if (!this.browser?.isConnected()) {
+            throw this.createError('BROWSER_DISCONNECTED', 'Browser is not connected');
+        }
+    }
+    enforceSessionLimit(tenantId) {
+        if (this.contexts.size >= this.config.maxLocalSessions) {
+            throw this.createError('MAX_SESSIONS_REACHED', `Maximum ${this.config.maxLocalSessions} concurrent sessions reached`);
+        }
+    }
+    getTargetId(page) {
+        // URL-based identifier (CDP target ID not directly available)
+        return crypto.createHash('md5').update(page.url()).digest('hex').slice(0, 8);
+    }
+    setupDialogHandler(page) {
+        page.on('dialog', async (dialog) => {
+            try {
+                this.logger('info', `Auto-dismissing ${dialog.type()} dialog: ${dialog.message()}`);
+                await dialog.dismiss();
+            }
+            catch (err) {
+                this.logger('warn', 'Failed to dismiss dialog', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        });
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /** 구조화된 에러 생성 */
+    createError(code, message, extra) {
+        const error = new Error(message);
+        error.error = code;
+        error.message = message;
+        if (extra?.retries !== undefined)
+            error.retries = extra.retries;
+        if (extra?.timeout !== undefined)
+            error.timeout = extra.timeout;
+        if (extra?.details !== undefined)
+            error.details = extra.details;
+        return error;
+    }
+}
+// ============================================================================
+// LocalBrowserProvider — Phase 1 (로컬 Chrome CDP 연결)
+// ============================================================================
+export class LocalBrowserProvider {
+    name = 'local';
+    cdpPort;
+    process = null;
+    constructor(cdpPort = 9222) {
+        this.cdpPort = cdpPort;
+    }
+    async getCDPUrl() {
+        // 기존 Chrome CDP 엔드포인트 탐색
+        try {
+            const resp = await fetch(`http://127.0.0.1:${this.cdpPort}/json/version`);
+            const data = await resp.json();
+            if (data.webSocketDebuggerUrl) {
+                return data.webSocketDebuggerUrl;
+            }
+        }
+        catch {
+            // CDP 미실행 — Playwright 내장 브라우저로 대체
+        }
+        // Playwright chromium launch (CDP 서버 포함)
+        return `http://127.0.0.1:${this.cdpPort}`;
+    }
+    isSandboxed() {
+        return false;
+    }
+    async terminate() {
+        if (this.process) {
+            this.process.kill();
+            this.process = null;
+        }
+    }
+}
+//# sourceMappingURL=BrowserService.js.map

package/dist/pc/browser/BrowserService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserService.js","sourceRoot":"","sources":["../../../src/pc/browser/BrowserService.ts"],"names":[],"mappings":"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"}

package/dist/pc/browser/BrowserService.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * BrowserService Unit Tests
+ *
+ * IBrowserProvider 팩토리, 테넌트 격리, 재연결 로직.
+ */
+export {};
+//# sourceMappingURL=BrowserService.test.d.ts.map

package/dist/pc/browser/BrowserService.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserService.test.d.ts","sourceRoot":"","sources":["../../../src/pc/browser/BrowserService.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/pc/browser/BrowserService.test.js

@@ -0,0 +1,160 @@
+/**
+ * BrowserService Unit Tests
+ *
+ * IBrowserProvider 팩토리, 테넌트 격리, 재연결 로직.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { BrowserService, LocalBrowserProvider } from './BrowserService.js';
+const noopLogger = (_level, _msg, _data) => { };
+// ============================================================================
+// Mock Provider
+// ============================================================================
+class MockBrowserProvider {
+    name = 'mock';
+    shouldFail = false;
+    terminateCalled = false;
+    setFail(fail) {
+        this.shouldFail = fail;
+    }
+    async getCDPUrl() {
+        if (this.shouldFail)
+            throw new Error('Mock CDP failure');
+        return 'ws://127.0.0.1:9222/devtools/browser/mock-id';
+    }
+    isSandboxed() {
+        return false;
+    }
+    async terminate() {
+        this.terminateCalled = true;
+    }
+}
+// ============================================================================
+// Scenario 6: Ephemeral 브라우저 컨텍스트 (테넌트 격리)
+// ============================================================================
+describe('BrowserService: Tenant Isolation', () => {
+    let service;
+    beforeEach(() => {
+        service = new BrowserService(noopLogger, {
+            maxRetries: 1,
+            maxLocalSessions: 3,
+        });
+    });
+    it('should start with no active sessions', () => {
+        expect(service.activeSessionCount).toBe(0);
+    });
+    it('should not be connected initially', () => {
+        expect(service.isConnected()).toBe(false);
+    });
+    it('should report disconnect after construction', () => {
+        expect(service.isConnected()).toBe(false);
+        expect(service.activeSessionCount).toBe(0);
+    });
+});
+// ============================================================================
+// Scenario 8: CDP 연결 실패 시 JSON 에러 반환
+// ============================================================================
+describe('BrowserService: CDP Connection Errors', () => {
+    it('should create structured error with code', () => {
+        const service = new BrowserService(noopLogger, { maxRetries: 1 });
+        const error = service.createError('CDP_CONNECTION_FAILED', 'Connection failed', { retries: 3 });
+        expect(error.error).toBe('CDP_CONNECTION_FAILED');
+        expect(error.message).toBe('Connection failed');
+        expect(error.retries).toBe(3);
+        expect(error instanceof Error).toBe(true);
+    });
+    it('should create error with timeout info', () => {
+        const service = new BrowserService(noopLogger);
+        const error = service.createError('ACTION_TIMEOUT', 'Timed out', { timeout: 8000 });
+        expect(error.error).toBe('ACTION_TIMEOUT');
+        expect(error.timeout).toBe(8000);
+    });
+});
+// ============================================================================
+// IBrowserProvider Interface
+// ============================================================================
+describe('IBrowserProvider: LocalBrowserProvider', () => {
+    it('should have name "local"', () => {
+        const provider = new LocalBrowserProvider();
+        expect(provider.name).toBe('local');
+    });
+    it('should not be sandboxed', () => {
+        const provider = new LocalBrowserProvider();
+        expect(provider.isSandboxed()).toBe(false);
+    });
+    it('should use custom CDP port', () => {
+        const provider = new LocalBrowserProvider(9333);
+        expect(provider.isSandboxed()).toBe(false);
+    });
+    it('should terminate without error', async () => {
+        const provider = new LocalBrowserProvider();
+        await expect(provider.terminate()).resolves.not.toThrow();
+    });
+});
+describe('IBrowserProvider: MockBrowserProvider', () => {
+    it('should return CDP URL', async () => {
+        const provider = new MockBrowserProvider();
+        const url = await provider.getCDPUrl();
+        expect(url).toContain('ws://');
+        expect(url).toContain('9222');
+    });
+    it('should throw when set to fail', async () => {
+        const provider = new MockBrowserProvider();
+        provider.setFail(true);
+        await expect(provider.getCDPUrl()).rejects.toThrow('Mock CDP failure');
+    });
+    it('should track terminate calls', async () => {
+        const provider = new MockBrowserProvider();
+        expect(provider.terminateCalled).toBe(false);
+        await provider.terminate();
+        expect(provider.terminateCalled).toBe(true);
+    });
+});
+// ============================================================================
+// Session Limit Enforcement
+// ============================================================================
+describe('BrowserService: Session Limits', () => {
+    it('should enforce max local sessions via config', () => {
+        const service = new BrowserService(noopLogger, {
+            maxLocalSessions: 2,
+            maxSaasSessionsPerUser: 1,
+        });
+        expect(service.actionTimeout).toBe(8000);
+    });
+    it('should use default config when not provided', () => {
+        const service = new BrowserService(noopLogger);
+        expect(service.actionTimeout).toBe(8000);
+    });
+    it('should use custom action timeout', () => {
+        const service = new BrowserService(noopLogger, { actionTimeout: 5000 });
+        expect(service.actionTimeout).toBe(5000);
+    });
+});
+// ============================================================================
+// PageState Management
+// ============================================================================
+describe('BrowserService: PageState', () => {
+    it('should store and retrieve ref cache entries', () => {
+        const service = new BrowserService(noopLogger);
+        service.cacheRefs('target-1', { e1: { role: 'button', name: 'Submit' } }, 1);
+        const cached = service.getCachedRefs('target-1');
+        expect(cached).toBeDefined();
+        expect(cached.refs.e1.role).toBe('button');
+        expect(cached.snapshotVersion).toBe(1);
+    });
+    it('should return undefined for uncached targets', () => {
+        const service = new BrowserService(noopLogger);
+        expect(service.getCachedRefs('nonexistent')).toBeUndefined();
+    });
+    it('should evict oldest entry when LRU limit reached', () => {
+        const service = new BrowserService(noopLogger);
+        // Fill cache with 50 entries
+        for (let i = 0; i < 50; i++) {
+            service.cacheRefs(`target-${i}`, { e1: { role: 'button' } }, i);
+        }
+        // Add one more (should evict target-0)
+        service.cacheRefs('target-50', { e1: { role: 'link' } }, 50);
+        expect(service.getCachedRefs('target-0')).toBeUndefined();
+        expect(service.getCachedRefs('target-50')).toBeDefined();
+    });
+});
+//# sourceMappingURL=BrowserService.test.js.map

package/dist/pc/browser/BrowserService.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserService.test.js","sourceRoot":"","sources":["../../../src/pc/browser/BrowserService.test.ts"],"names":[],"mappings":"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"}

package/dist/pc/browser/RefLocator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * RefLocator — Ref ID → Playwright Locator 변환
+ *
+ * "e1" → `page.getByRole(role, { name, exact: true })` 변환.
+ * nth 처리 (동일 role+name 중복 시), stale ref 감지.
+ */
+import type { Page, Locator } from 'playwright';
+import type { PageState } from './types.js';
+export declare class RefLocator {
+    /**
+     * ref ID를 Playwright Locator로 변환
+     *
+     * @param page - 대상 페이지
+     * @param ref - ref ID (e.g., "e1", "e3")
+     * @param state - 현재 페이지 상태 (refs + snapshotVersion)
+     * @returns Playwright Locator
+     * @throws REF_NOT_FOUND | REF_STALE
+     */
+    resolve(page: Page, ref: string, state: PageState): Locator;
+    /**
+     * 여러 ref를 한번에 해석
+     */
+    resolveAll(page: Page, refs: string[], state: PageState): Map<string, Locator>;
+    /**
+     * ref 형식 정규화: "@e1", "ref=e1", "e1" → "e1"
+     */
+    normalizeRef(ref: string): string;
+    /**
+     * ref가 stale인지 확인 (현재 snapshotVersion과 비교)
+     */
+    isStale(refSnapshotVersion: number, currentSnapshotVersion: number): boolean;
+    /** RoleRef → Playwright Locator 빌드 */
+    private buildLocator;
+    /** 사용 가능한 ref ID 목록 (에러 메시지용) */
+    private listAvailableRefs;
+    /** 구조화된 ref 에러 생성 */
+    private createRefError;
+}
+//# sourceMappingURL=RefLocator.d.ts.map

package/dist/pc/browser/RefLocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RefLocator.d.ts","sourceRoot":"","sources":["../../../src/pc/browser/RefLocator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAuB,SAAS,EAAgB,MAAM,YAAY,CAAC;AAE/E,qBAAa,UAAU;IACrB;;;;;;;;OAQG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO;IAY3D;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAQ9E;;OAEG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAMjC;;OAEG;IACH,OAAO,CACL,kBAAkB,EAAE,MAAM,EAC1B,sBAAsB,EAAE,MAAM,GAC7B,OAAO;IAQV,sCAAsC;IACtC,OAAO,CAAC,YAAY;IAoBpB,iCAAiC;IACjC,OAAO,CAAC,iBAAiB;IAOzB,qBAAqB;IACrB,OAAO,CAAC,cAAc;CAMvB"}