// packages/core — 팝업/오버레이 배치 기하 정본. // // 두 가지를 담는다: // 1) 좌표 공간 — UIA(사이드카)는 물리 픽셀, Electron screen API 는 DIP 를 쓴다. 둘을 같은 // `UiRect` 로 섞으면 125%/150% 배율에서 오버레이가 캐럿에서 멀리 떨어지거나 작업 영역 // 모서리에 붙는다. 그래서 공간을 타입으로 표기하고(PhysicalRect/DipRect), 변환은 // ScreenGeometryPort 한 곳(Electron 어댑터)에서만 한다 — core 는 좌표를 만든 OS API 를 모른다. // 2) 배치 정책 — 캐럿/요소 앵커 배치(anchorFloatingPanel), 커서 기준 팝업 배치 // (placeNearCursor), 내용 높이에 맞춘 창 줄이기(fitAnchoredPanel). // // 순수 함수만 둔다 — Electron/Node 의존 금지. // ============================================================ // 좌표 공간 // ============================================================ export interface UiRect { x: number y: number width: number height: number } export interface UiPoint { x: number y: number } export interface UiSize { width: number height: number } /** 타입 전용 표지 — 런타임 값은 없다. */ declare const COORDINATE_SPACE: unique symbol /** * 물리 픽셀 사각형 (UIA BoundingRectangle, GetWindowRect 등 DPI-aware 네이티브 API 가 주는 값). * * 표지는 선택적이다 — 네이티브 경계(UIA 페이로드)에서 들어온 평범한 UiRect 도 받아들이되, * DipRect 는 받지 않는다(표지 값이 'dip' 이라 충돌한다). */ export type PhysicalRect = UiRect & { readonly [COORDINATE_SPACE]?: 'physical' } /** Electron DIP 사각형 — 반드시 ScreenGeometryPort(또는 asDipRect)로만 만든다. */ export type DipRect = UiRect & { readonly [COORDINATE_SPACE]: 'dip' } /** Electron DIP 점. */ export type DipPoint = UiPoint & { readonly [COORDINATE_SPACE]: 'dip' } /** 이미 DIP 인 값(Electron screen API 결과)에 표지를 붙인다. 어댑터 경계에서만 쓴다. */ export function asDipRect(rect: UiRect): DipRect { return { x: rect.x, y: rect.y, width: rect.width, height: rect.height } as DipRect } /** 이미 DIP 인 점(Electron screen API 결과)에 표지를 붙인다. 어댑터 경계에서만 쓴다. */ export function asDipPoint(point: UiPoint): DipPoint { return { x: point.x, y: point.y } as DipPoint } /** * 화면 기하 포트 — 좌표 공간 변환과 작업 영역 조회를 한 곳에 모은다 (DIP). * * Electron 어댑터는 win32 에서 screen.screenToDipRect 를, 그 밖에서는 항등 변환을 쓴다. * 배치 정책은 이 포트만 보고 DIP 로만 계산한다. */ export interface ScreenGeometryPort { /** 물리 픽셀 사각형 → DIP (배율이 다른 모니터에서도 그 모니터 기준으로 변환한다) */ toDip(rect: PhysicalRect): DipRect /** 이 점에서 가장 가까운 모니터의 작업 영역 (DIP) */ workAreaNear(point: DipPoint): DipRect /** 마우스 커서 위치 (DIP) */ cursor(): DipPoint } // ============================================================ // 캐럿/요소 앵커 배치 // ============================================================ /** * 앵커 rect 가 케어렛(한 줄 위치)인지 포커스 요소 전체인지. * * 케어렛을 못 주는 제공자가 많아(Chrome, Windows Terminal 등 caret=-1) 그때는 * elementRect 로 폴백하는데, 두 경우는 배치 전략이 달라야 한다 — 케어렛은 "그 * 줄 아래" 에 붙이면 되지만, elementRect(멀티라인/큰 입력창 전체)는 그 규칙을 * 그대로 쓰면 텍스트와 멀리 떨어지거나 텍스트 위에 겹친다. */ export type AnchorKind = 'caret' | 'element' | null function clamp(value: number, min: number, max: number): number { if (max < min) return min return Math.max(min, Math.min(value, max)) } function fitsInWorkArea(x: number, y: number, size: UiSize, workArea: UiRect): boolean { return ( x >= workArea.x && y >= workArea.y && x + size.width <= workArea.x + workArea.width && y + size.height <= workArea.y + workArea.height ) } function isUsableRect(rect: UiRect | null): rect is UiRect { return rect !== null && rect.width >= 0 && rect.height >= 0 } /** * 오버레이 좌표 계산. * * 모든 인자는 같은 좌표 공간이어야 한다 — 공간을 타입으로 강제하려면 * anchorFloatingPanelInDips 를 쓴다. * * 케어렛 앵커(또는 앵커 없음 → 커서)는 앵커 아래에 붙이는 것이 기본 — IME 후보창과 * 같은 관례다. 아래 공간이 없으면 위로 뒤집는다. * 요소 앵커(케어렛을 못 얻어 elementRect 로 폴백한 경우)는 요소 "바깥" 에 붙인다 — * 아래/위/오른쪽/왼쪽 순으로 작업영역에 들어맞는 첫 방향을 쓴다. * 마지막으로 항상 작업영역 안으로 클램프한다. */ export function anchorFloatingPanel( anchor: UiRect | null, anchorKind: AnchorKind, cursor: UiPoint, size: UiSize, workArea: UiRect, gap = 6 ): UiPoint { if (anchorKind === 'element' && isUsableRect(anchor)) { return anchorOutsideElement(anchor, size, workArea, gap) } const rect: UiRect = isUsableRect(anchor) ? anchor : { x: cursor.x, y: cursor.y, width: 0, height: 0 } const anchorBottom = rect.y + Math.max(rect.height, 0) const desiredY = anchorBottom + gap const fitsBelow = desiredY + size.height <= workArea.y + workArea.height const above = rect.y - gap - size.height const y = fitsBelow ? desiredY : above >= workArea.y ? above : desiredY return { x: clamp(rect.x, workArea.x, workArea.x + workArea.width - size.width), y: clamp(y, workArea.y, workArea.y + workArea.height - size.height) } } /** anchorFloatingPanel 의 DIP 전용 형태 — 물리 픽셀 값이 섞이면 컴파일되지 않는다. */ export function anchorFloatingPanelInDips( anchor: DipRect | null, anchorKind: AnchorKind, cursor: DipPoint, size: UiSize, workArea: DipRect, gap = 6 ): DipPoint { return asDipPoint(anchorFloatingPanel(anchor, anchorKind, cursor, size, workArea, gap)) } /** * 요소 앵커를 요소 "바깥" 에 배치한다. * * 케어렛을 못 얻어 elementRect(입력창 전체)로 폴백했을 때, 기존 "앵커 아래/위" 규칙을 * 그대로 쓰면 큰/여러 줄 요소에서는 텍스트와 멀리 떨어지거나 텍스트 위에 겹친다 * (실측: 2·3번째 생성에서 패널이 튐). 아래→위→오른쪽→왼쪽 순으로 작업영역에 * 맞는 첫 방향을 쓰고, 전부 안 맞으면 요소 안쪽 우하단 모서리로 물러난다. */ function anchorOutsideElement(element: UiRect, size: UiSize, workArea: UiRect, gap: number): UiPoint { const candidates: UiPoint[] = [ { x: element.x, y: element.y + element.height + gap }, // 아래 { x: element.x, y: element.y - gap - size.height }, // 위 { x: element.x + element.width + gap, y: element.y }, // 오른쪽 { x: element.x - gap - size.width, y: element.y } // 왼쪽 ] for (const candidate of candidates) { if (fitsInWorkArea(candidate.x, candidate.y, size, workArea)) return candidate } const fallback = { x: element.x + element.width - size.width - gap, y: element.y + element.height - size.height - gap } return { x: clamp(fallback.x, workArea.x, workArea.x + workArea.width - size.width), y: clamp(fallback.y, workArea.y, workArea.y + workArea.height - size.height) } } /** * 앵커 기준으로 배치한 패널 자리. 창 높이는 내용에 따라 줄어들 수 있다(fitAnchoredPanel). * * `grow` 는 내용이 늘 때 창이 자라는 방향이다 — 앵커 위로 뒤집혀 배치됐으면 아래쪽 모서리를 * 앵커 곁에 고정하고 위로 자란다. */ export interface AnchoredPanelPlacement { x: number y: number width: number /** 배치 계산에 쓴 최대 높이 */ maxHeight: number grow: 'down' | 'up' } /** * 물리 픽셀 앵커로 오버레이 자리를 잡는다 — 변환은 포트로 한 번만 한다. * * 모니터 선택도 변환된 DIP 점으로 한다 (물리 좌표로 고르면 배율이 다른 모니터가 여럿일 때 * 엉뚱한 모니터의 작업 영역을 고른다). */ export function placeAnchoredPanel( port: ScreenGeometryPort, anchor: PhysicalRect | null, anchorKind: AnchorKind, size: UiSize, gap = 6 ): AnchoredPanelPlacement { const cursor = port.cursor() const dipAnchor = isUsableRect(anchor) ? port.toDip(anchor) : null const anchorPoint = dipAnchor ? asDipPoint({ x: dipAnchor.x, y: dipAnchor.y + dipAnchor.height }) : cursor const workArea = port.workAreaNear(anchorPoint) const position = anchorFloatingPanelInDips(dipAnchor, anchorKind, cursor, size, workArea, gap) const referenceTop = dipAnchor ? dipAnchor.y : cursor.y return { x: position.x, y: position.y, width: size.width, maxHeight: size.height, grow: position.y + size.height <= referenceTop ? 'up' : 'down' } } /** * 배치된 패널 창을 실제 내용 높이로 줄인다. * * 투명 창이라도 창 영역은 클릭을 삼킨다 — 보이지 않는 여백이 캐럿 아래 줄의 클릭을 막지 * 않도록 창을 그려진 패널만큼만 둔다. 위로 뒤집힌 배치는 아래 모서리(앵커 쪽)를 고정한다. */ export function fitAnchoredPanel(placement: AnchoredPanelPlacement, contentHeight: number): UiRect { const height = clamp(Math.round(contentHeight), 1, placement.maxHeight) const y = placement.grow === 'up' ? placement.y + placement.maxHeight - height : placement.y return { x: placement.x, y, width: placement.width, height } } // ============================================================ // 커서 기준 팝업 배치 // ============================================================ /** * 커서 기준 팝업 배치 (녹음 팁 · 결과 · 기록 · 명령 팝업 공통). * * 커서 위 `gap` 에 가로 가운데로 두고, 위 공간이 없으면 커서 아래로 뒤집는다. * 그다음 작업 영역 안으로 네 방향 모두 클램프한다 (아래로 뒤집힌 큰 팝업이 화면 밖으로 * 잘리지 않게). 음수 좌표(주 모니터 왼쪽/위쪽 모니터)도 그대로 다룬다. */ export function placeNearCursor(cursor: UiPoint, size: UiSize, workArea: UiRect, gap = 20): UiPoint { const x = clamp( cursor.x - Math.round(size.width / 2), workArea.x, workArea.x + workArea.width - size.width ) let y = cursor.y - size.height - gap if (y < workArea.y) y = cursor.y + gap if (y + size.height > workArea.y + workArea.height) { y = Math.max(workArea.y, workArea.y + workArea.height - size.height) } return { x, y } }