issue-sticker 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# 변경 이력
+
+npm 패키지 `issue-sticker`의 변경 이력입니다. 설치·업그레이드에 영향을 주는 변경만 기록합니다.
+
+## 0.2.0 - 2026-08-05
+
+### 주의가 필요한 변경
+
+- 패키지 루트(`issue-sticker`)와 `issue-sticker/runtime` 엔트리를 제거했습니다. 공개 엔트리는 `issue-sticker/react`, `issue-sticker/headless`, `issue-sticker/headless/react` 세 개입니다.
+- UMD 산출물(`dist/issue-sticker.umd.js`) 배포를 중단했습니다. `<script>` 태그로 패키지 파일을 직접 불러오는 방식은 지원하지 않습니다.
+
+마이그레이션:
+
+```diff
+-import { IssueSticker } from 'issue-sticker';
++import { IssueSticker } from 'issue-sticker/react';
+```
+
+`issue-sticker/runtime`을 직접 사용하던 코드는 `issue-sticker/react`의 `useIssueSticker()` 또는 `IssueSticker.init()`으로 옮기세요. 위젯 UI 없이 이슈 플로우를 직접 제어하려면 `issue-sticker/headless`를 사용하세요.
+
+### 추가
+
+- `issue-sticker/headless` — 위젯 UI 없이 이슈 플로우를 구독·제어하는 controller API. `subscribe()`로 snapshot을 구독하고 `startIssueCapture()`·`submitDraft()`로 이슈를 생성합니다. 제목·설명·동적 필드 입력은 호스트 앱이 소유하며 `submitDraft({ title, description, dynamicFields })`로 전달합니다.
+- `issue-sticker/headless/react` — Headless UI를 직접 만들 때 사용하는 최소 React helper.
+- 이슈 팝오버에서 코딩 에이전트에 붙여 넣을 LLM 프롬프트 복사.
+- 이슈 상세에서 네트워크 요청의 메서드·상태·헤더·본문과 콘솔 로그 확인.
+- `multi_select` 커스텀 필드를 이슈 필터에서 사용.
+
+### 개선
+
+- 이슈 생성 시 클릭 즉시 폼이 뜨고 스크린샷은 백그라운드에서 캡처됩니다. 캡처가 끝나기 전에 제출해도 완료를 기다린 뒤 업로드하며, 캡처가 실패하면 스크린샷 없이 제출을 계속합니다.
+- FAB 트리거와 툴바를 브랜드 컬러 기반으로 정리하고 심볼을 인라인 SVG로 교체했습니다.
+- 캡처 단축키 안내에 `⌘⌥`와 `⌃⌥`를 함께 표시합니다.
+- 세션 리플레이 녹화에서 이슈스티커 위젯 자체가 남기던 노이즈를 제거했습니다.
+- 마커 렌더링을 문서 좌표 기준으로 단일화해 스크롤·리사이즈 시 위치가 어긋나는 경로를 없앴습니다.
+
+### 수정
+
+- `issue-sticker/react`를 서버에서 평가하는 환경(Next.js client component의 SSR 패스 등)에서 import 즉시 `document is not defined`로 실패하던 문제를 수정했습니다. 번들에 포함되던 마크다운 의존성이 모듈 스코프에서 `document`를 사용하던 것이 원인입니다.
+- 이슈 생성 모드와 화면 녹화가 동시에 켜질 수 있던 문제를 양방향으로 차단했습니다.
+- 온보딩을 시작하면 이슈 생성 모드가 먼저 해제됩니다.
+- 외부 연동 생성이 실패해도 아무 안내가 없던 문제를 toast 알림으로 수정했습니다.
+- 성공 toast가 회색 표면으로 표시되던 문제를 수정했습니다.
+- 이슈 목록·스티커, Jira 연동 필드 응답 처리를 서버 응답 형식에 맞게 정정했습니다.

package/README.md

@@ -1,483 +1,150 @@
 # IssueSticker SDK
 
-웹 애플리케이션에 시각적 버그 트래킹 위젯을 삽입하는 SDK입니다.
-사용자가 페이지 위에서 직접 클릭하여 이슈를 생성하고, 스크린샷/네트워크 로그/콘솔 로그를 자동으로 수집합니다.
+**IssueSticker**는 웹서비스에서 발견한 버그를 화면 위에서 바로 기록하는 도구입니다. 문제 지점을 클릭해 이슈를 남기면 스크린샷·네트워크 로그·콘솔 로그·화면 녹화가 함께 수집되어, 재현에 필요한 맥락이 빠짐없이 남습니다.
 
----
+이 npm 패키지 `issue-sticker`는 **SDK 위젯**입니다. 자사 웹앱에 몇 줄만 추가하면 고객·베타 사용자·내부 QA가 제품을 벗어나지 않고 그 자리에서 피드백을 남길 수 있습니다. 수집된 이슈는 [관리자 콘솔](https://app.issuesticker.com)에서 관리하고 Jira·Notion으로 내보낼 수 있습니다. 임의의 웹페이지에서 사용할 수 있는 [Chrome Extension](https://issuesticker.com/guide/products/extension)은 별도 제품으로 제공합니다.
 
-## 목차
+## 문서
 
-- [주요 기능](#주요-기능)
-- [설치](#설치)
-- [빠른 시작](#빠른-시작)
-- [동작 모드](#동작-모드)
-- [API 레퍼런스](#api-레퍼런스)
-- [설정 옵션](#설정-옵션)
-- [이벤트](#이벤트)
-- [키보드 단축키](#키보드-단축키)
-- [위젯 기능](#위젯-기능)
-- [브라우저 지원](#브라우저-지원)
-- [FAQ](#faq)
-- [라이선스](#라이선스)
+이 README는 설치와 API 표면만 다룹니다. 자세한 설명은 홈페이지 가이드에서 확인하세요.
 
----
-
-## 주요 기능
-
-- **클릭 기반 이슈 생성** — 페이지 위 원하는 위치를 클릭하여 마커 생성
-- **자동 스크린샷 캡처** — 이슈 생성 시점의 화면을 자동으로 캡처
-- **네트워크/콘솔 로그 수집** — 이슈 발생 전후의 네트워크 요청 및 콘솔 로그 자동 기록
-- **화면 녹화** — 버그 재현 과정을 영상으로 기록
-- **마커 표시** — 생성된 이슈를 페이지 위에 마커로 표시
-
----
+| 문서                                                             | 내용                                  |
+| ---------------------------------------------------------------- | ------------------------------------- |
+| [시작 준비](https://issuesticker.com/guide/products/setup)       | 프로젝트·허용 도메인·API key 발급     |
+| [SDK Widget](https://issuesticker.com/guide/products/sdk)        | 위젯 설치, 초기화, 운영에서 켜는 조건 |
+| [SDK Headless](https://issuesticker.com/guide/products/headless) | Headless 클라이언트 전체 레퍼런스     |
+| [외부 연동](https://issuesticker.com/guide/integrations)         | Jira·Notion 연결과 필드 동기화        |
+| [FAQ](https://issuesticker.com/guide/faq)                        | 권한·도메인·key·필드 동기화 문제 해결 |
 
 ## 설치
 
-### npm
-
 ```bash
 npm install issue-sticker
 ```
 
-### yarn
-
-```bash
-yarn add issue-sticker
-```
-
-### pnpm
-
-```bash
-pnpm add issue-sticker
-```
-
-### React 어댑터 사용 시 peer dependency
-
-`issue-sticker/react`를 사용할 경우 호스트 앱에 `react`, `react-dom`이 필요합니다.
-
-### CDN (script 태그)
-
-```html
-<script src="https://cdn.issuesticker.com/sdk/issue-sticker.umd.js"></script>
-<script>
-  IssueSticker.init({ apiKey: 'YOUR_API_KEY' });
-</script>
-```
-
----
-
-## 빠른 시작
-
-### 엔트리포인트
-
-- `issue-sticker/runtime` — 프레임워크 비의존 코어 런타임 API (`IssueSticker`) (UI 마운트 없음)
-- `issue-sticker/react` — React 어댑터 API (`IssueSticker`, `useIssueSticker`) (위젯 UI 마운트 포함)
-
-화면 위젯(FAB/이슈 폼/마커)을 사용하려면 `issue-sticker/react` 경로를 사용해야 합니다.
-
-### React / Next.js
-
-`useIssueSticker` 훅을 사용하면 초기화와 정리를 자동으로 처리합니다.
-
-```tsx
-import { useIssueSticker } from 'issue-sticker/react';
-
-function App() {
-  useIssueSticker({ apiKey: 'YOUR_API_KEY' });
-
-  return <div>My Application</div>;
-}
-```
-
-### Vanilla JavaScript
-
-```typescript
-import { IssueSticker } from 'issue-sticker/runtime';
-
-IssueSticker.init({ apiKey: 'YOUR_API_KEY' });
-```
-
-`issue-sticker/runtime`은 코어 런타임 경로로, React UI 마운트 없이 SDK 엔진 라이프사이클/API 이벤트를 다룰 때 사용합니다.
-
-### HTML
-
-```html
-<script src="https://cdn.issuesticker.com/sdk/issue-sticker.umd.js"></script>
-<script>
-  IssueSticker.init({ apiKey: 'YOUR_API_KEY' });
-</script>
-```
-
-UMD(`issue-sticker.umd.js`)는 런타임 경로 기준입니다.
-UMD 경로는 위젯 UI를 자동 마운트하지 않습니다.
+`issue-sticker/react`와 `issue-sticker/headless/react`를 사용하려면 호스트 앱에 `react`, `react-dom`(18 또는 19)이 설치되어 있어야 합니다.
 
----
+## 엔트리포인트
 
-## 동작 모드
+| 경로                           | 용도                                                  |
+| ------------------------------ | ----------------------------------------------------- |
+| `issue-sticker/react`          | 위젯 UI(FAB·이슈 폼·마커)를 마운트하는 React 어댑터   |
+| `issue-sticker/headless`       | UI 없이 이슈 플로우를 구독·제어하는 controller API    |
+| `issue-sticker/headless/react` | Headless UI를 직접 만들 때 사용하는 최소 React helper |
 
-SDK는 `user` 옵션 전달 여부에 따라 두 가지 모드로 동작합니다.
-아래 화면 동작(폼/마커/FAB)은 `issue-sticker/react` 경로로 위젯이 마운트된 상태를 기준으로 설명합니다.
+패키지 루트(`issue-sticker`)와 `issue-sticker/runtime`은 공개 엔트리포인트가 아닙니다.
 
-### 익명 모드 (기본)
-
-`user` 옵션 없이 초기화합니다. 이슈는 익명으로 생성되며, 사용자별 이슈 조회는 불가능합니다.
+## 빠른 시작 — 위젯
 
 ```tsx
-useIssueSticker({ apiKey: 'YOUR_API_KEY' });
-```
-
-| 항목        | 동작               |
-| ----------- | ------------------ |
-| 이슈 생성   | 익명으로 생성      |
-| 이슈 조회   | 불가 (생성만 가능) |
-| 보고자 표시 | 표시 안 됨         |
-
-### 사용자 식별 모드
-
-호스트 앱의 사용자 정보를 `user`에 전달합니다. 이슈에 보고자 정보가 기록되고, 해당 사용자가 생성한 이슈만 조회할 수 있습니다.
-
-```tsx
-useIssueSticker({
-  apiKey: 'YOUR_API_KEY',
-  user: {
-    id: 'user-123',
-    name: 'Hong Gildong',
-  },
-});
-```
-
-| 항목        | 동작                             |
-| ----------- | -------------------------------- |
-| 이슈 생성   | 사용자 정보와 함께 생성          |
-| 이슈 조회   | 해당 사용자가 생성한 이슈만 표시 |
-| 보고자 표시 | `user.name`으로 표시             |
-
-### 멤버 모드
-
-워크스페이스에 등록된 멤버 계정으로 로그인합니다. FAB 메뉴의 "멤버 로그인"을 통해 진입할 수 있습니다.
-멤버 모드에서는 프로젝트의 모든 이슈를 조회/관리할 수 있으며, 마커를 페이지 위에 표시합니다.
-
-| 항목      | 동작                                      |
-| --------- | ----------------------------------------- |
-| 이슈 생성 | 멤버 계정으로 생성                        |
-| 이슈 조회 | 프로젝트의 모든 이슈 조회 가능            |
-| 마커      | 현재 페이지의 이슈를 마커로 표시          |
-| 이슈 관리 | 상태 변경, 심각도 변경, 댓글 등 전체 기능 |
+'use client'; // Next.js App Router
 
----
-
-## API 레퍼런스
-
-### `useIssueSticker(config)`
-
-React 커스텀 훅. 컴포넌트 마운트 시 SDK를 초기화하고, 언마운트 시 자동으로 정리합니다.
-
-```tsx
 import { useIssueSticker } from 'issue-sticker/react';
 
 function App() {
   useIssueSticker({
-    apiKey: 'YOUR_API_KEY',
-    user: { id: 'user-123', name: 'Hong Gildong' },
+    apiKey: process.env.NEXT_PUBLIC_ISSUE_STICKER_SDK_KEY!,
+    user: { id: 'user-123', name: 'Hong Gildong' }, // 선택: 보고자 식별
+    enabled: isStaging || isAdmin, // 선택: 노출 조건 (기본 true)
   });
 
-  return <div>My App</div>;
+  return <div>My Application</div>;
 }
 ```
 
-`config.apiKey`, `config.user`, `config.enabled`가 변경되면 SDK를 자동으로 재초기화합니다.
-
----
-
-### `IssueSticker.init(config)`
-
-SDK 코어 런타임을 초기화합니다.
-이 API(`issue-sticker/runtime`)는 위젯 UI를 자동 마운트하지 않습니다.
-React 환경에서는 `useIssueSticker` 훅 사용을 권장합니다.
-
-```typescript
-import { IssueSticker } from 'issue-sticker/runtime';
-```
-
-```typescript
-IssueSticker.init(config: SDKConfig): void
-```
-
-| 이름     | 타입        | 필수 | 설명          |
-| -------- | ----------- | ---- | ------------- |
-| `config` | `SDKConfig` | Yes  | SDK 설정 객체 |
-
-이미 초기화된 상태에서 다시 호출하면, 기존 런타임 상태를 정리한 뒤 새로 초기화합니다.
-
----
+앱 최상위에서 한 번만 호출하세요. 훅이 마운트 시 초기화하고 언마운트 시 정리합니다.
 
-### `IssueSticker.destroy()`
+우측 하단에 표시되는 FAB(드래그로 위치 이동 가능)에서는 이슈 생성, 화면 녹화, 마커 표시 토글, 마커 표시 기준 전환(생성 위치 기준 / 대상 요소 기준), 미표시 스티커 확인, 가이드 다시 보기, 멤버 로그인·로그아웃을 사용할 수 있습니다. 이슈 생성 모드와 화면 녹화는 동시에 켤 수 없습니다.
 
-SDK 코어 런타임을 종료합니다.
-`issue-sticker/runtime` 경로에서는 위젯 언마운트를 수행하지 않습니다.
+## 빠른 시작 — Headless
 
 ```typescript
-IssueSticker.destroy(): void
-```
-
----
+import { createIssueStickerHeadless } from 'issue-sticker/headless';
 
-### `IssueSticker.on(event, callback)`
+const client = createIssueStickerHeadless({
+  apiKey: 'YOUR_API_KEY',
+  user: { id: 'user-123', name: 'Hong Gildong' },
+});
 
-SDK 이벤트를 구독합니다.
+client.subscribe((snapshot) => renderIssueUI(snapshot));
 
-```typescript
-IssueSticker.on(event: SDKEvent, callback: (...args: unknown[]) => void): void
+await client.initialize();
+await client.refreshIssues();
 ```
 
-**예시:**
+현재 상태는 읽기 전용 snapshot으로 제공되며, 이슈 생성은 `startIssueCapture()`로 시작합니다. 전체 메서드·snapshot 타입·동적 필드 descriptor·에러 코드는 [Headless 가이드](https://issuesticker.com/guide/products/headless)를 참고하세요.
 
-```typescript
-IssueSticker.on('issue:created', (issue) => {
-  console.log('새 이슈:', issue);
-});
-
-IssueSticker.on('error', (error) => {
-  console.error('SDK 오류:', error);
-});
-```
+## API — `issue-sticker/react`
 
----
+### `useIssueSticker(config)`
 
-### `IssueSticker.off(event, callback)`
+React 훅. `apiKey` 또는 `enabled`가 바뀌면 위젯을 다시 초기화하고, `user`가 바뀌면 위젯은 유지하고 설정만 갱신합니다.
 
-등록된 이벤트 구독을 해제합니다.
+### `IssueSticker`
 
-```typescript
-IssueSticker.off(event: SDKEvent, callback: (...args: unknown[]) => void): void
-```
+훅을 사용할 수 없는 환경에서 직접 제어할 때 사용합니다.
 
-**예시:**
+| 메서드                            | 설명                                                                                          |
+| --------------------------------- | --------------------------------------------------------------------------------------------- |
+| `init(config: SDKConfig)`         | SDK를 초기화하고 위젯을 마운트. 이미 초기화된 상태라면 설정을 갱신하고 위젯을 다시 마운트한다 |
+| `updateConfig(config: SDKConfig)` | 위젯을 유지한 채 설정만 교체. 초기화 전이면 `init`과 동일하게 동작                            |
+| `destroy()`                       | 위젯을 언마운트하고 SDK를 종료                                                                |
 
 ```typescript
-const handler = (issue) => console.log(issue);
-IssueSticker.on('issue:created', handler);
+import { IssueSticker } from 'issue-sticker/react';
 
-// 나중에 구독 해제
-IssueSticker.off('issue:created', handler);
+IssueSticker.init({ apiKey: 'YOUR_API_KEY' });
 ```
 
----
-
-## 설정 옵션
+이슈 생성·제출 같은 흐름을 호스트 앱에서 직접 구독하거나 제어해야 한다면 Headless 클라이언트를 사용하세요. 상태는 `subscribe()`로 구독하고 캡처·제출은 메서드로 제어할 수 있습니다. 자세한 내용은 [Headless 가이드](https://issuesticker.com/guide/products/headless)를 참고하세요.
 
 ### `SDKConfig`
 
-| 속성      | 타입      | 필수 | 설명                                                           |
-| --------- | --------- | ---- | -------------------------------------------------------------- |
-| `apiKey`  | `string`  | Yes  | IssueSticker API 키. [대시보드](https://app.issuesticker.com)에서 발급 |
-| `user`    | `SDKUser` | No   | 호스트 앱의 사용자 정보. 전달 시 사용자 식별 모드로 동작       |
-| `enabled` | `boolean` | No   | SDK 활성화 여부 (기본값: `true`). `useIssueSticker` 훅 전용        |
-
-### `SDKUser`
-
-| 속성   | 타입     | 필수 | 설명               |
-| ------ | -------- | ---- | ------------------ |
-| `id`   | `string` | Yes  | 사용자 고유 식별자 |
-| `name` | `string` | Yes  | 사용자 표시 이름   |
-
----
-
-## 이벤트
-
-SDK는 다양한 이벤트를 발생시켜 위젯의 상태 변화를 알려줍니다.
-
-| 이벤트              | 발생 시점           | 콜백 인자           |
-| ------------------- | ------------------- | ------------------- |
-| `ready`             | SDK 초기화 완료     | —                   |
-| `error`             | 오류 발생           | `error: string`     |
-| `issue:created`     | 이슈 생성 완료      | `issue: object`     |
-| `issue:updated`     | 이슈 수정 완료      | `issue: object`     |
-| `issue:clicked`     | 마커 클릭           | `issueId: string`   |
-| `mode:changed`      | 이슈 생성 모드 변경 | `isActive: boolean` |
-| `recording:started` | 화면 녹화 시작      | —                   |
-| `recording:stopped` | 화면 녹화 종료      | —                   |
-| `auth:login`        | 멤버 로그인 성공    | —                   |
-| `auth:logout`       | 로그아웃 완료       | —                   |
-
----
-
-## 키보드 단축키
-
-| 단축키               | 기능                |
-| -------------------- | ------------------- |
-| `Ctrl/Cmd + Alt + 1` | 이슈 생성 모드 토글 |
-| `Ctrl/Cmd + Alt + 2` | 화면 녹화 시작/중지 |
-| `Esc`                | 이슈 생성 모드 종료 |
-
----
-
-## 위젯 기능
-
-### FAB (Floating Action Button)
-
-`issue-sticker/react` 경로로 SDK를 초기화하면 우측 하단에 플로팅 버튼이 나타납니다.
-
-| 메뉴             | 설명                     | 조건           |
-| ---------------- | ------------------------ | -------------- |
-| 이슈 생성        | 이슈 생성 모드 진입/종료 | 항상 표시      |
-| 화면 녹화        | 화면 녹화 시작/중지      | 항상 표시      |
-| 마커 보기/숨기기 | 마커 표시 토글           | 멤버 로그인 시 |
-| 멤버 로그인      | 워크스페이스 멤버 로그인 | 비로그인 시    |
-| 로그아웃         | 멤버 로그아웃            | 로그인 시      |
-
-### 이슈 생성 모드
-
-이슈 생성은 **스크린샷 모드**와 **영상 녹화 모드** 두 가지 방식을 지원합니다.
-
-#### 스크린샷 모드
-
-이슈 생성 시점의 화면을 정지 이미지로 캡처합니다.
-
-1. FAB 메뉴에서 "이슈 생성" 클릭 또는 `Ctrl/Cmd + Alt + 1`
-2. 커서가 십자 모양으로 변경되고, 마우스 오버 시 요소가 하이라이트됨
-3. 원하는 위치 클릭 → 이슈 생성 폼 표시 (스크린샷 자동 첨부)
-4. 폼 작성 후 제출
-
-#### 영상 녹화 모드
-
-버그 재현 과정을 영상으로 기록한 후 이슈에 첨부합니다.
-
-1. FAB 메뉴에서 "화면 녹화" 클릭 또는 `Ctrl/Cmd + Alt + 2`
-2. 화면 녹화가 시작됨 (녹화 인디케이터 표시)
-3. 버그를 재현한 후, FAB 메뉴에서 "녹화 중지" 클릭 또는 `Ctrl/Cmd + Alt + 2`
-4. 녹화 종료 후 자동으로 이슈 생성 모드 진입
-5. 원하는 위치 클릭 → 이슈 생성 폼 표시 (녹화 영상 자동 첨부)
-6. 폼 작성 후 제출
-
-> **참고**: SDK의 영상 녹화는 브라우저 `getDisplayMedia` API를 사용합니다. 녹화 중 페이지를 리로드하거나 다른 페이지로 이동하면 녹화가 중단되며 녹화 데이터가 유실됩니다. 페이지 이동에도 끊김 없는 녹화가 필요한 경우, [IssueSticker Chrome Extension](https://chrome.google.com/webstore)을 설치하면 백그라운드 녹화를 지원하여 페이지 리로드에도 녹화가 유지됩니다.
+| 속성                    | 타입                                 | 필수 | 설명                                                                           |
+| ----------------------- | ------------------------------------ | ---- | ------------------------------------------------------------------------------ |
+| `apiKey`                | `string`                             | Yes  | [관리자 콘솔](https://app.issuesticker.com)에서 발급한 SDK API key             |
+| `user`                  | `SDKUser`                            | No   | 호스트 앱의 사용자 정보. 전달하면 보고자가 기록되고 본인 이슈를 조회할 수 있다 |
+| `onboarding`            | `'off' \| 'onMount' \| 'onFABClick'` | No   | 온보딩 가이드 트리거 (기본 `'onMount'`). `'off'`면 "가이드 다시 보기"도 숨긴다 |
+| `screenshotCompression` | `{ useWebWorker?: boolean }`         | No   | 스크린샷 압축을 Web Worker에서 수행할지 여부                                   |
+| `enabled`               | `boolean`                            | No   | 위젯 활성화 여부 (기본 `true`). `useIssueSticker` 전용 옵션                    |
 
-### 자동 수집 데이터
+`SDKUser`는 `id`, `name` 두 필드 모두 필수입니다.
 
-| 데이터        | 설명                                           |
-| ------------- | ---------------------------------------------- |
-| 스크린샷      | 클릭 시점의 페이지 스크린샷                    |
-| 영상          | 화면 녹화 영상 (녹화 모드 사용 시)             |
-| 네트워크 로그 | 최근 50개 네트워크 요청 (URL, 상태, 소요 시간) |
-| 콘솔 로그     | 최근 50개 콘솔 출력 (log, warn, error)         |
-| User Agent    | 브라우저 및 OS 정보                            |
-| 클릭 위치     | 클릭한 요소의 CSS 선택자 및 XPath              |
+### 키보드 단축키
 
-> **참고**: 출시 이후 SDK 위젯 내부에 1회성 제품 안내가 추가될 수 있습니다. 이 안내는 `SDKConfig` 옵션이나 public API로 제어하지 않고, IssueSticker Shadow DOM 내부 UI만 대상으로 하며 localStorage로 기본 1회 노출 여부를 관리합니다.
+| 기능                | macOS       | Windows·Linux |
+| ------------------- | ----------- | ------------- |
+| 이슈 생성 모드 토글 | `⌘⌥1` `⌃⌥1` | `Ctrl+Alt+1`  |
+| 화면 녹화 시작/중지 | `⌘⌥2` `⌃⌥2` | `Ctrl+Alt+2`  |
+| 이슈 생성 모드 종료 | `Esc`       | `Esc`         |
 
----
+## 이슈에 담기는 정보
 
-## 브라우저 지원
+- 스크린샷 — 화면 전체와 클릭한 요소 영역 (클릭 직후 백그라운드에서 캡처)
+- 화면 녹화 영상 — 녹화 모드로 생성한 경우
+- 네트워크·콘솔 로그 — 각각 최근 50개, IssueSticker 자체 트래픽은 제외
+- 브라우저·OS 정보, 발생 URL, 클릭한 요소의 CSS 선택자와 XPath
+- 세션 리플레이 — 워크스페이스에서 사용할 수 있는 경우, 이슈 폼에서 첨부 여부를 선택
 
-| 브라우저 | 최소 버전 |
-| -------- | --------- |
-| Chrome   | 90+       |
-| Firefox  | 90+       |
-| Safari   | 15+       |
-| Edge     | 90+       |
+화면의 마커를 클릭하면 이슈 팝오버에서 제목·설명 수정, 삭제, 코딩 에이전트에 붙여 넣을 LLM 프롬프트를 복사할 수 있습니다. 연동된 Jira·Notion 정보는 멤버로 로그인했을 때 함께 표시됩니다.
 
----
+화면 녹화는 브라우저 `getDisplayMedia` API를 사용하므로, 녹화 중 페이지를 새로고침하거나 다른 페이지로 이동하면 녹화가 중단되고 데이터가 유실됩니다. 페이지 이동에도 끊기지 않는 녹화가 필요하면 [Chrome Extension](https://issuesticker.com/guide/products/extension)을 사용하세요.
 
-## FAQ
+## 사용자 식별
 
-### API 키는 어디서 발급받나요?
+| 모드        | 진입 방법           | 이슈 조회 범위                                        |
+| ----------- | ------------------- | ----------------------------------------------------- |
+| 익명        | `user` 없이 초기화  | 조회 없음 (이번 세션에서 생성한 이슈만 화면에 표시됨) |
+| 사용자 식별 | `user` 전달         | 해당 사용자가 생성한 이슈                             |
+| 멤버        | FAB의 "멤버 로그인" | 프로젝트의 모든 이슈                                  |
 
-[IssueSticker 대시보드](https://app.issuesticker.com)에서 프로젝트를 생성한 후 SDK 설정 페이지에서 API 키를 발급받을 수 있습니다.
+## 문제 해결
 
-### 호스트 페이지의 CSS에 영향을 주나요?
+`Invalid hook call` 또는 `Cannot read properties of null (reading 'useRef')` 오류는 대부분 React 인스턴스가 중복으로 로드될 때 발생합니다. `npm ls react react-dom`으로 중복을 확인하고, Vite는 `resolve.dedupe: ['react', 'react-dom']`, Webpack/Next.js는 alias로 경로를 단일화하세요.
 
-`issue-sticker/react` 경로를 사용하는 경우, SDK 위젯은 호스트 페이지의 스타일과 격리되어 동작합니다. 단, 이슈 생성 모드에서 커서 변경과 요소 하이라이트를 위한 최소한의 스타일이 추가됩니다.
-
-### SPA(Single Page Application)에서 사용할 수 있나요?
-
-네. URL 변경을 자동으로 감지하여 새 페이지의 이슈를 로드합니다. 위젯 UI까지 사용하려면 `useIssueSticker`를 `issue-sticker/react`에서 import해 앱 최상위에서 사용하는 방식을 권장합니다.
-
-### `Invalid hook call` / `Cannot read properties of null (reading 'useRef')` 오류가 나요
-
-이 오류는 대부분 **호스트 앱에 React 인스턴스가 2개 이상 로드**될 때 발생합니다.
-
-1. 의존성 중복 확인
-
-```bash
-npm ls react react-dom
-```
-
-`react`, `react-dom`이 단일 버전으로 정리되어 있는지 확인하세요.
-
-2. Vite 사용 시 dedupe 설정
-
-```ts
-// vite.config.ts
-import { defineConfig } from 'vite';
-
-export default defineConfig({
-  resolve: {
-    dedupe: ['react', 'react-dom'],
-  },
-});
-```
-
-Webpack/Next.js 사용 시에는 alias로 React 경로를 단일화하세요.
-
-```js
-// next.config.js 또는 webpack config
-const path = require('path');
-
-module.exports = {
-  webpack: (config) => {
-    config.resolve.alias = {
-      ...(config.resolve.alias || {}),
-      react: path.resolve(__dirname, 'node_modules/react'),
-      'react-dom': path.resolve(__dirname, 'node_modules/react-dom'),
-    };
-    return config;
-  },
-};
-```
-
-3. import 경로 점검
-
-- React 환경: `import { useIssueSticker } from 'issue-sticker/react'`
-- 비 React 환경: `import { IssueSticker } from 'issue-sticker/runtime'`
-
-루트(`issue-sticker`)에서 React 훅을 import하지 않도록 주의하세요.
-`issue-sticker/react`를 사용할 때는 호스트 앱에 `react`, `react-dom`이 반드시 설치되어 있어야 합니다.
-
-`[plugin:vite:import-analysis] Missing "./react" specifier in "issue-sticker" package` 오류가 보이면,
-설치된 SDK tarball/lockfile이 오래된 상태일 가능성이 큽니다. `node_modules`와 lockfile을 갱신한 뒤 SDK를 재설치하세요.
-
-### 리액트 없이도 사용할 수 있나요?
-
-네. `issue-sticker/runtime`으로 코어 런타임 초기화/이벤트 연동은 가능합니다.
-다만 FAB/이슈 폼/마커 같은 위젯 UI 기능은 `issue-sticker/react` 경로(React 환경)에서만 동작합니다.
-
-### user 정보를 넣으면 어떤 효과가 있나요?
-
-[동작 모드](#동작-모드) 섹션을 참조하세요. `user.id`를 전달하면 사용자 식별 모드로 동작하여 해당 사용자가 생성한 이슈만 조회할 수 있고, `user.name`이 보고자로 기록됩니다.
-
-### 이슈 데이터는 어디에 저장되나요?
-
-IssueSticker 클라우드 서버에 안전하게 저장됩니다. API 키에 연결된 프로젝트에 이슈가 귀속됩니다.
-
-### 프로덕션 환경에서도 사용해도 되나요?
-
-네. 다만 일반 사용자에게 노출하지 않으려면 특정 조건(예: 관리자 모드, 스테이징 환경)에서만 SDK를 초기화하도록 분기 처리하는 것을 권장합니다.
-
-```tsx
-import { useIssueSticker } from 'issue-sticker/react';
-
-function App() {
-  useIssueSticker({
-    apiKey: 'YOUR_API_KEY',
-    enabled: isAdminMode || isStagingEnv,
-  });
-
-  return <div>My App</div>;
-}
-```
+`Missing "./react" specifier in "issue-sticker" package` 오류는 설치된 패키지가 오래된 경우입니다. `node_modules`와 lockfile을 갱신한 뒤 다시 설치하세요.
 
----
+그 밖의 문제는 [FAQ](https://issuesticker.com/guide/faq)를 참고하세요.
 
 ## 라이선스