claude-ai-office 0.29.1 → 0.30.1

package/README.en.md

@@ -159,7 +159,7 @@ With two or more floors, 🏢 **Building view** (`O`) appears in the header. Flo
 
 A resident app that shows the web UI in a window. It starts the Node server itself (or reuses one that is already running) and lives in the menu bar / system tray; left- or right-click the icon for the menu: Open, Hide, Always on top, Launch at login, Reinstall hooks, Check for updates, Apply update and Quit. When a session is waiting for you or an update is ready, a **red dot** appears on the menu bar icon and on the Dock (Windows: taskbar) icon, like a chat app; there is no count, and the tooltip says what it is. **Launch at login** is turned on at first run; when started at login the app stays in the menu bar without a window. You can turn it off from the menu. Closing the window hides it; Quit stops the server too. Node is bundled: on first launch the app copies the server files to `~/.ai-office/app` and the Node binary to `~/.ai-office/node`, then registers the hooks, so moving or deleting the app does not break them.
 
-**Updates**: the app checks for a new version 10 seconds after launch and every 6 hours and only **downloads** it in the background (signature verified; a failed check is retried after 5 minutes), then shows the red dot and enables "Apply vX update (restart)". Applying stops the server, installs and restarts; nothing is installed without asking and the running app is never replaced underneath you. "Check for updates" in the menu shows whether you are up to date or why a check failed. Releases are built by GitHub Actions for macOS (Apple Silicon) and Windows (x64) and signed for the updater.
+**Updates**: the app checks for a new version 10 seconds after launch and every 6 hours and only **downloads** it in the background (signature verified; a failed check is retried after 5 minutes), then shows the red dot and enables "Apply vX update (restart)". Applying stops the server, installs and restarts; nothing is installed without asking and the running app is never replaced underneath you. Clicking **"Check for updates"** opens a small update window: it checks, and if there is a new version shows a `Downloading… 12.3MB / 42.8MB` progress bar (cancelable), then installing and restart; otherwise it says you are up to date or why the check failed. Applying a downloaded update shows "Installing…" in the same window. Releases are built by GitHub Actions for macOS (Apple Silicon) and Windows (x64) and signed for the updater.
 
 > **Download**: [macOS AI-Office-mac-arm64.dmg](https://github.com/cozyuj/AI-office/releases/latest/download/AI-Office-mac-arm64.dmg) · [Windows AI-Office-windows-x64-setup.exe](https://github.com/cozyuj/AI-office/releases/latest/download/AI-Office-windows-x64-setup.exe) (always the latest; older versions in [Releases](https://github.com/cozyuj/AI-office/releases)). The macOS app is not notarized: **right-click → Open** the first time; on macOS 15+ use System Settings → Privacy & Security → **Open Anyway**, and if it still says "damaged", run `xattr -dr com.apple.quarantine "/Applications/AI Office.app"` once. To build it yourself:
 

package/README.md

@@ -161,7 +161,7 @@ node bin/ai-office.js            # 또는 npm run install-hooks && npm start
 
 웹 버전을 그대로 창에 담은 상주 앱입니다(맥 메뉴바 · Windows 트레이). 앱이 Node 서버를 직접 띄우고(이미 떠 있으면 재사용) 아이콘을 왼쪽이나 오른쪽 클릭하면 메뉴가 뜹니다. 메뉴는 열기 · 숨기기 · 항상 위 · 로그인 시 자동 실행 · 훅 다시 설치 · 업데이트 확인 · 업데이트 적용 · 종료입니다. 답을 기다리는 세션이 있거나 받아 둔 업데이트가 있으면 카카오톡처럼 메뉴바 아이콘과 Dock(Windows 는 작업 표시줄) 아이콘에 **빨간 점**이 뜹니다. 숫자는 없고, 무엇인지는 아이콘에 마우스를 올리면 툴팁으로 보입니다. **로그인 시 자동 실행**은 처음 실행 때 켜지며, 자동으로 켜질 땐 창 없이 메뉴바에만 뜹니다. 메뉴에서 끌 수 있습니다. 창을 닫아도 메뉴바에 남고, 종료하면 서버도 함께 내려갑니다(앱이 강제 종료돼도 서버가 스스로 끝납니다). 앱에는 Node 가 내장되어 있고, 첫 실행 때 서버 파일을 `~/.ai-office/app` 에, Node 를 `~/.ai-office/node` 에 복사하고 그 경로로 훅을 등록하므로 앱을 옮기거나 지워도 훅이 깨지지 않습니다.
 
-**자동 업데이트**: 앱이 시작 10초 뒤와 6시간마다 새 버전을 확인해 백그라운드로 **받아 두기만** 하고(서명 검증까지, 확인에 실패하면 5분 뒤 다시), 빨간 점을 띄우며 메뉴의 "vX 업데이트 적용 (다시 시작)" 이 켜집니다. 누르면 서버를 내리고 설치한 뒤 다시 시작합니다. 묻지 않고 설치하거나 쓰던 중에 앱 파일을 바꾸지 않습니다. 메뉴의 "업데이트 확인" 에 최신 여부나 실패 이유가 보입니다. 릴리스는 태그를 올리면 GitHub Actions 가 맥(Apple Silicon)·Windows(x64) 로 빌드하고 서명해 올립니다.
+**자동 업데이트**: 앱이 시작 10초 뒤와 6시간마다 새 버전을 확인해 백그라운드로 **받아 두기만** 하고(서명 검증까지, 확인에 실패하면 5분 뒤 다시), 빨간 점을 띄우며 메뉴의 "vX 업데이트 적용 (다시 시작)" 이 켜집니다. 누르면 서버를 내리고 설치한 뒤 다시 시작합니다. 묻지 않고 설치하거나 쓰던 중에 앱 파일을 바꾸지 않습니다. 메뉴의 **"업데이트 확인"** 을 누르면 작은 업데이트 창이 떠서 확인 → 새 버전이면 `다운로드 중… 12.3MB / 42.8MB` 진행 막대(취소 가능) → 설치 중 → 다시 시작까지 보여 주고, 최신이거나 실패하면 그 이유를 보여 줍니다. 받아 둔 업데이트를 적용할 때도 같은 창에 "설치 중" 이 뜹니다. 릴리스는 태그를 올리면 GitHub Actions 가 맥(Apple Silicon)·Windows(x64) 로 빌드하고 서명해 올립니다.
 
 > **다운로드**: ⬇️ **[맥 AI-Office-mac-arm64.dmg](https://github.com/cozyuj/AI-office/releases/latest/download/AI-Office-mac-arm64.dmg)** · **[Windows AI-Office-windows-x64-setup.exe](https://github.com/cozyuj/AI-office/releases/latest/download/AI-Office-windows-x64-setup.exe)** (항상 최신) · 이전 버전은 [Releases](https://github.com/cozyuj/AI-office/releases). DMG 를 열어 `AI Office.app` 을 응용 프로그램 폴더에 넣으세요. 코드 서명이 없어 처음엔 "확인되지 않은 개발자" 경고가 뜨니 앱을 **우클릭 → 열기** 로 한 번 허용하고, macOS 15 이상에서 안 열리면 시스템 설정 → 개인정보 보호 및 보안 → **그래도 열기**, 그래도 "손상됨" 이라고 나오면 터미널에서 `xattr -dr com.apple.quarantine "/Applications/AI Office.app"` 를 한 번 실행하세요. Intel 맥·Linux 는 위의 `npx claude-ai-office` 한 줄로 웹 버전을 쓰세요. 직접 빌드하려면:
 

package/docs/ARCHITECTURE.md

@@ -1,72 +1,88 @@
-# AI Office 구조 설계 (웹 버전)
+# AI Office 구조 설계
 
-Claude Code 세션이 지금 무엇을 하는지 아이소메트릭 사무실 화면으로 실시간 보여주는 로컬 웹 앱.
+Claude Code 세션이 지금 무엇을 하는지 아이소메트릭 사무실 화면으로 실시간 보여주는 로컬 앱 (웹 + macOS/Windows 데스크톱).
 파일을 읽으면 자료실, 명령을 돌리면 서버실, 막히면 그 자리에서 고민, 서브에이전트는 엘리베이터로 출근.
 
+> 이 문서는 v0.29 기준이다. 기능 소개·스크린샷은 `docs/AI-Office-소개.html`.
+
 ## 1. 전체 흐름
 
 ```
-Claude Code 세션 (여러 터미널, 여러 프로젝트)
-  │  settings.json hooks (PreToolUse, PostToolUse, SubagentStart, Stop, ...)
+Claude Code 세션 (여러 터미널, 여러 프로젝트, 워크트리)
+  │  ~/.claude/settings.json hooks (11개 이벤트)
   ▼
-hooks/emit.sh            stdin JSON → curl POST (1초 타임아웃, 백그라운드, 항상 exit 0)
+hooks/emit.js            stdin JSON → POST 127.0.0.1:<port>/hook (Node 만 사용, 1초 타임아웃, 항상 exit 0)
   │
   ▼  POST /hook
-server.js (Node 18+, 외부 의존성 0)
-  ├─ normalize   훅 payload → 내부 Event (도구명/대상 파일/서브에이전트 id 추출, 대용량 필드 제거)
-  ├─ reduce      Event → Floor/Session/Agent 상태 갱신 (상태 머신)
-  ├─ log         최근 500건 ring buffer
-  └─ broadcast   SSE /events 로 {snapshot | update} 전송
+server.js (Node 18+, 외부 의존성 0, 127.0.0.1 에만 listen)
+  ├─ 접근 검사   Host 루프백 · Origin 허용 목록 (9절)
+  ├─ journal     payload 를 ~/.ai-office/events.jsonl 에 append → 기동 시 최근 2시간 재생
+  ├─ normalize   payload → 작은 Event (도구→방·말풍선, 큰 필드 자르기)        lib/normalize.js
+  ├─ state       Event → 층/세션/캐릭터 상태 머신, 활동 로그 500건, sweep      lib/state.js
+  └─ broadcast   SSE /events 로 snapshot · update · remove · floor · demo
   │
   ▼  GET /events (SSE), GET /api/state
 public/ (브라우저, 번들러 없음, ES module)
-  ├─ store       서버 상태 미러 + 구독
-  ├─ scene       canvas 아이소메트릭 사무실: 맵, 가구, 캐릭터 이동(A*), 말풍선, 카메라
-  └─ panels      좌: 층(프로젝트)·세션 목록 / 우: 사무실 사람들·활동 로그·범례
+  ├─ store       서버 상태 미러 + 선택·접기 상태 + 구독
+  ├─ scene       canvas 아이소메트릭 사무실: 층 레이아웃, 가구, 캐릭터 이동(A*), 말풍선, 카메라, 시간대 조명
+  ├─ panels      좌: 층별 안내(층·세션 목록) / 우: 사무실 사람들·활동 로그·범례 / 전체 보기(건물 단면)
+  └─ i18n        한국어 원문 + 영어 번역 (DOM 자동, 캔버스는 tr())
 ```
 
 - 훅은 Claude 실행을 절대 막지 않는다. 서버가 꺼져 있어도 1초 안에 조용히 포기한다.
 - 서버는 "지금 상태"의 단일 진실 공급원이다. 브라우저는 상태를 받아 애니메이션만 담당한다.
-- 브라우저를 몇 개 열어도, 새로 열어도 같은 화면이다 (접속 시 snapshot 수신).
+- 브라우저를 몇 개 열어도, 새로 열어도 같은 화면이다 (접속 시 snapshot 수신). 서버를 다시 켜도 저널 재생으로 같은 화면이 돌아온다.
+- 데스크톱 앱은 같은 서버를 사이드카 Node 로 띄우고 창에 같은 화면을 연다 (10절).
 
 ## 2. 데이터 모델
 
 ```ts
-Floor {                      // 프로젝트 = 층. key = cwd 절대경로
-  id: string                 // cwd
-  name: string               // basename(cwd)  예: "nccx"
-  no: number                 // 출현 순서로 1F, 2F, ... 부여
-  sessions: Map<sessionId, Session>
-  lastActivity: number       // epoch ms
+Floor {                      // 프로젝트 = 층. id = git 저장소 루트 (lib/project.js 가 .git 을 위로 찾는다. 없으면 cwd)
+  id: string                 // 워크트리도 원래 저장소의 층으로 모인다
+  name: string               // basename(id). 이름이 겹치면 상위 폴더를 붙여 구분
+  no: number                 // 출현 순서로 1F, 2F, ...
+  style: string              // 인테리어 프리셋 id (직접 선택 > 층 id 해시). ~/.ai-office/floor-styles.json
+  sessions: Set<sessionId>
+  lastActivity: number
 }
 
 Session {
   id: string                 // hook.session_id
-  floorId: string
-  title: string              // 첫 UserPromptSubmit 의 prompt 앞 40자 (session_title 있으면 그것)
+  floorId: string            // 처음 정해진 층 유지 (cwd 가 하위 폴더로 바뀌어도)
+  title: string              // 훅 session_title > transcript 의 마지막 custom-title > 첫 요청 앞부분
+  firstPrompt, lastPrompt    // 첫 요청(transcript 앞 1MB 에서 복원), 최근 요청
   status: 'thinking' | 'working' | 'waiting' | 'idle' | 'ended'
+  cwd, branch, worktree      // 헤더·툴팁 표시용
+  transcriptPath             // 제목 갱신·생존 확인(stat)용
   startedAt, lastActivity: number
-  agents: Map<agentId, Agent> // 'main' + 서브에이전트들
-  pendingSubagents: string[]  // Agent 툴 PreToolUse 의 description 큐 (SubagentStart 와 짝지음)
+  agents: { [agentId]: Agent } // 'main' + 서브에이전트들
+  pendingSubagents: string[] // Agent 툴 PreToolUse 의 description 큐 (SubagentStart 와 짝지음)
 }
 
 Agent {                      // 화면의 캐릭터 한 명
   id: 'main' | agent_id
-  sessionId: string
   kind: 'main' | 'sub'
-  name: string               // "Claude" | agent_type ("Explore") | Agent 툴 description
+  name: string               // "Claude" | Agent 툴 description | agent_type. 화면 이름은 클라이언트 names.js 가 별명으로 바꾼다
   room: RoomId               // 지금 있어야 할 방
-  activity: ActivityId       // 'think' | 'read' | 'search' | 'run' | 'edit' | 'web' | 'delegate' | 'ask' | 'wait' | 'rest' | 'compact' | 'leave'
-  bubble: string             // 말풍선 텍스트  예: "server.js 읽는 중"
-  tool?: { name, useId, target }
+  activity: ActivityId       // 'arrive' | 'think' | 'read' | 'search' | 'run' | 'edit' | 'web' | 'delegate' | 'plan' | 'ask' | 'rest' | 'compact' | 'work' | 'leave'
+  icon, bubble: string       // 말풍선  예: "📖 server.js 읽는 중"
+  tool?: { name, useId, target, detail }
   since: number              // 현재 activity 시작 시각 (경과 시간 표시용)
 }
 
 LogEntry { t, floorId, sessionId, agentId, agentName, icon, text }
 
-RoomId = 'library' | 'dev' | 'research' | 'server' | 'meeting' | 'lounge' | 'cafe' | 'terrace' | 'mydesk' | 'lobby' | 'elevator' | 'corridor'
+RoomId = 'library' | 'dev' | 'research' | 'server' | 'meeting' | 'lounge' | 'cafe' | 'terrace' | 'mydesk' | 'lobby' | 'elevator'
+         // cafe/terrace 는 서버의 "휴식 방" id. 층 레이아웃이 실제 편의시설(헬스장·구내식당 …)로 별칭한다 (6절)
 ```
 
+세션 생명주기 (sweep 은 1초마다, transcript stat 은 세션당 1분에 한 번)
+- 30분 무활동 → 휴식 방으로 "자리 비움"
+- 10분 무활동부터 transcript 를 확인해 60분 동안 갱신이 없으면 퇴근 처리 (터미널을 그냥 닫은 경우)
+- 2시간 무활동 → 퇴근. SessionEnd 후 10초 뒤 제거
+- 사용자가 화면에서 치운 세션(DELETE)은 저널에 `SessionEnd(reason: dismissed)` 로 남겨 재시작해도 되살아나지 않는다
+- 제목: 훅의 session_title 이 바뀔 때마다 따르고(분리된 세션), transcript 끝 64KB 의 custom-title 을 mtime 이 바뀌었을 때만 1분에 한 번 읽는다. 바뀌면 로그 "🏷️ 제목: …"
+
 ## 3. 훅 이벤트 → 상태 전이
 
 Claude Code 2.1.x 훅 payload 기준. 서브에이전트가 낸 도구 호출은 `agent_id` 가 실려 오므로 그 값으로 캐릭터를 찾는다. 없으면 `main`.
@@ -74,7 +90,7 @@ Claude Code 2.1.x 훅 payload 기준. 서브에이전트가 낸 도구 호출은
 | 훅 이벤트 | 대상 | 방 | activity | 말풍선 | 비고 |
 |---|---|---|---|---|---|
 | SessionStart | main 생성 | elevator → mydesk | wait | "출근" | source=resume/compact 는 기존 세션 유지 |
-| UserPromptSubmit | main | 현재 위치 | think | "고민 중…" | title 미설정이면 prompt 로 설정. status=thinking |
+| UserPromptSubmit | main | 현재 위치 | think | "고민 중…" | firstPrompt(없을 때)·lastPrompt 갱신. status=thinking |
 | PreToolUse | agent_id 또는 main | 도구별 방 (4절) | 도구별 | 도구별 문구 | status=working |
 | PostToolUse | 동일 | 그 자리 | think | "고민 중…" | tool 해제. duration_ms 로그 |
 | PostToolUseFailure | 동일 | 그 자리 | think | "❌ 실패, 다시 생각 중" | error 앞 80자 로그 |
@@ -112,94 +128,153 @@ Claude Code 2.1.x 훅 payload 기준. 서브에이전트가 낸 도구 호출은
 | AskUserQuestion | mydesk | ask | `질문 있어요` |
 | 그 외 | dev | work | `{tool} 사용 중` |
 
+
 ## 5. 서버 API
 
 | 메서드 | 경로 | 설명 |
 |---|---|---|
-| POST | `/hook` | 훅 payload 수신. body 2MB 제한. 항상 204 |
-| GET | `/events` | SSE. 접속 즉시 `snapshot` 1회, 이후 `update` (갱신된 Session 전체 + 새 LogEntry) |
-| GET | `/api/state` | 현재 전체 상태 JSON (디버그용) |
+| POST | `/hook` | 훅 payload 수신. body 2MB 제한. 먼저 204 를 돌려주고 처리. 데모가 꺼져 있으면 `/demo/` 이벤트는 무시 |
+| GET | `/events` | SSE. 접속 즉시 `snapshot` 1회, 25초마다 ping |
+| GET | `/api/state` | 현재 전체 상태 JSON (snapshot 과 같은 모양) |
+| POST | `/api/floors/style` | `{ floorId, style }` 층 인테리어 프리셋 지정 (null 이면 자동) |
+| DELETE | `/api/sessions/:id` | 끝난/자리 비운 세션을 목록에서 치운다 |
+| POST | `/api/demo/start` · `/api/demo/stop` | 데모 세션 시작 / 중지(데모 세션 전부 제거) |
 | GET | `/` | `public/` 정적 파일 |
 
 SSE 메시지
 ```
-event: snapshot   data: { me: "jinyu", floors: Floor[], log: LogEntry[] }
-event: update     data: { session: Session, floor: {id,name,no,lastActivity}, log?: LogEntry }
+event: snapshot   data: { me, floors, sessions, log, serverPort, hookPort, version, demo, journal }
+event: update     data: { session, floor, log? }
 event: remove     data: { sessionId, floorId? }
+event: floor      data: Floor            // 이름 구분·프리셋 변경
+event: demo       data: { on }
 ```
 
-포트 기본 4777, 환경변수 `AI_OFFICE_PORT` 로 변경. 서버/훅 양쪽이 같은 변수를 본다.
+- 포트 기본 4777, `AI_OFFICE_PORT` 로 변경. 훅 명령에 포트가 박혀 있어(`lib/hookport.js` 로 읽음) 서버 포트와 다르면 화면에 경고한다.
+- 홈 폴더 `~/.ai-office` (`AI_OFFICE_HOME`). `--no-journal` 로 저널 끄기.
+- `AI_OFFICE_WATCH_PARENT=1` 이면 부모 프로세스(앱·CLI)가 강제 종료될 때 서버도 스스로 끝난다.
+
+### 저널 (lib/journal.js)
+
+- 훅 payload 를 큰 필드를 자른 채 한 줄씩 append (데모 이벤트는 남기지 않음).
+- 기동 시 최근 2시간(SESSION_TTL)만 시간 순서대로 `state.apply` 에 다시 흘려 상태를 복원한다.
+- 매시간 + 20MB 초과 시 오래된 줄을 버리고 다시 쓴다(압축). `ai-office compact` 로 즉시 압축, `ai-office doctor` 가 크기를 보여준다.
 
 ## 6. 프론트엔드 모듈
 
 ```
 public/
-  index.html          3단 레이아웃 (좌 260px / 중앙 canvas / 우 300px), 상단 헤더(층 이름·세션 제목·LIVE)
-  style.css           라이트 톤, 패널 카드 스타일
+  index.html          3단 레이아웃 (좌 층별 안내 / 중앙 canvas / 우 사람들·로그), 상단 헤더(층·세션 제목·브랜치·LIVE)
+  style.css           라이트/다크 테마 토큰, 패널 카드
+  fonts/              서브셋 웹폰트 (scripts/subset-fonts.sh)
   js/
-    main.js           SSE 연결, store 갱신, requestAnimationFrame 루프
-    store.js          floors/sessions/log 미러, 선택된 floor/session, subscribe()
-    panels.js         좌·우 패널 DOM 렌더 (층 목록, 세션 목록, 사람들, 활동 로그, 범례)
+    main.js           SSE 연결·재접속, store 갱신, 알림(소리·브라우저 알림), 설정, 키보드(1~9 층 이동)
+    store.js          floors/sessions/log 미러, 선택된 층/세션, 층 접기(auto/all/none), subscribe()
+    panels.js         좌·우 패널 DOM (층 목록 + 모두 펼치기/접기, 세션 목록, 사람들, 활동 로그, 범례)
+    overview.js       전체 보기: 층을 건물처럼 쌓아 미니 사무실 + 캐릭터 점
+    i18n.js           언어: 한국어 원문, 영어는 사전 → 패턴 규칙 → 구절 치환. 사용자 요청·제목은 번역하지 않는다
+    names.js          세션별 캐릭터 별명 (localStorage)
+    customize.js, avatarStore.js   캐릭터 외형 커스터마이즈 (몸 종류·파츠·색·악세사리)
+    floorStylePicker.js            층 🎨 → 인테리어 프리셋 선택 (서버에 저장)
+    tooltip.js, texttip.js         캐릭터 툴팁, 잘린 글자 툴팁
     scene/
-      map.js          28x22 타일 그리드, 방 영역, 가구 footprint, 벽, 서 있는 자리(slot), 통행 가능 맵
-      pathfind.js     A* (4방향), 타일 단위
+      layouts.js      층 레이아웃 생성기: 4열 × 띠 격자에 방 배치, 방 크기에 맞는 가구·서는 자리·휴식 명소
+      floorStyle.js   인테리어 프리셋(색) ↔ 레이아웃 연결
+      map.js          타일 격자(x 1..35, y 1..21), 벽·문, 통행 맵, 투영. setLayout() 으로 층마다 교체
+      pathfind.js     A* (4방향), 벽 edge 와 solid 가구 회피
       actors.js       Agent → Actor(위치, 경로, 걷기 애니, 말풍선, 슬롯 점유/해제, 휴식 방 안 배회)
-      spots.js        휴식 방(휴게실·카페·테라스) 안 명소 목록: 타일, 말풍선, 머무는 시간
-      render.js       canvas 2D 아이소메트릭: 바닥 → 깊이 정렬된 가구/벽/캐릭터 → 말풍선/이름표 → 선택 하이라이트
-      camera.js       pan(드래그), zoom(휠/버튼), 초기 fit, 선택 세션 따라가기
-      sprites.js      가구/캐릭터를 코드로 그리는 함수들 (외부 이미지 없음, 색상 팔레트)
-      daylight.js     시간대 조명: 실제 시각 → 아침/낮/저녁/밤, 창문·테라스·실내 틴트 팔레트 (설정 '시간대 조명', aiOffice.daylight)
+      spots.js        휴식 방 명소 (레이아웃이 채우는 live 객체)
+      avatar.js       치비 캐릭터 그리기 (사람·로봇·고양이·곰)
+      render.js       바닥 → 3D AABB 깊이 정렬된 가구/벽/캐릭터 → 방 이름표·말풍선
+      sprites.js      가구·벽을 코드로 그리는 함수들 (외부 이미지 없음)
+      camera.js       팬·줌·맵 맞춤·클릭 판정, 선택 세션 따라가기
+      daylight.js     실제 시각 → 아침/낮/저녁/밤 창문·실내 틴트
 ```
 
-맵 레이아웃 (타일 좌표, 그림 참고)
+층 레이아웃과 인테리어 프리셋
 
-```
-        x 1-8          x 10-17         x 19-26          x 28-35
-y 1-7   자료실(책장)     개발실(책상6)     정보검색실(대형 화면, 지구본)   카페(북쪽 유리창, 카운터·커피머신·테이블)
-y 8-9   ───────────── 복도 ─────────────────────────────
-y 10-15 회의실(테이블)   휴게실(소파)      서버실(랙 2열)    테라스(데크 바닥, 난간, 파라솔·벤치·나무)
-y 16-17 ───────────── 복도 ─────────────                  (테라스는 y 10-21 까지, 북쪽 벽 문으로 출입)
-y 18-21 내 자리(사용자)   로비(안내, 화분)   엘리베이터(문 2개)
-```
-
-- x 27 은 세로 복도. 카페는 남쪽 벽 문, 테라스는 북쪽 벽 문으로 드나든다. 카페·테라스는 도구 매핑 대상이 아니라 휴게실과 함께 휴식 방(세션마다 하나)이며, 쉬는 캐릭터가 방 안 명소를 옮겨 다닌다. "생동감" 자율 행동(대기 중 산책)의 목적지이기도 하다.
-- 테라스 난간은 격자 밖(x 36, y 22)에 놓인 낮은 벽이라 통행에는 영향이 없다.
+| 프리셋 | 레이아웃 | 휴식 방 cafe / terrace 가 되는 곳 |
+|---|---|---|
+| 따뜻한 우드 · 파스텔 | classic | 카페 / 테라스 |
+| 쿨 그레이 | studio | 스튜디오 / 세미나실 |
+| 민트 | fitness | 헬스장 / 옥상정원 |
+| 라벤더 | play | 북 라운지 / 게임룸 |
+| 샌드 | canteen | 구내식당 / 수면실 |
 
-- 캐릭터는 방마다 정해진 "서는 자리(slot)" 중 빈 곳을 차지한다. 같은 방에 여럿이면 옆 자리로.
-- 이동은 A* 경로를 따라 초당 4타일. 걷는 동안 상하 바운스, 발밑 그림자.
-- 서브에이전트는 엘리베이터 타일에서 생성되어 회의실로 걸어오고, 끝나면 엘리베이터로 걸어가 사라진다.
-- 말풍선: `{아이콘} {bubble} · {경과시간}`. 선택된 세션의 캐릭터는 테두리 강조, 나머지는 반투명.
-- 사용자 캐릭터("{me} (나)")는 내 자리에 항상 앉아 있다. Claude 가 `ask` 상태면 그 옆에 와서 선다.
-- 한 층 = 한 프로젝트. 그 프로젝트의 모든 세션 캐릭터가 같은 층에 보인다. 좌측에서 층을 바꾸면 맵이 통째로 바뀐다.
+- 업무 방 9개(library·dev·research·meeting·lounge·server·mydesk·lobby·elevator)는 모든 레이아웃에 있다. 위치만 다르다.
+- 서버(`lib/floorStyle.js`)가 같은 표를 CommonJS 로 들고 있어 휴식 말풍선을 그 층 편의시설에 맞춘다 (`test/floorStyleShared.test.js` 가 두 표 일치를 고정).
+- 캐릭터는 방마다 정해진 "서는 자리(slot)" 중 빈 곳을 차지한다. 이동은 A* 경로, 초당 4타일.
+- 휴식 중인 캐릭터는 그 방 명소를 10~30초마다 옮겨 다닌다. 새 이벤트가 오면 즉시 해당 방으로 간다.
+- 서브에이전트는 엘리베이터에서 생성되어 회의실로 걸어오고, 끝나면 엘리베이터로 걸어가 사라진다.
+- 사용자 캐릭터("{me} (나)")는 내 자리에 앉아 있다. Claude 가 `ask` 상태면 그 옆에 와서 선다.
 
-## 7. 설치·운영 스크립트
+## 7. CLI · 설치 스크립트
 
 | 파일 | 역할 |
 |---|---|
-| `hooks/emit.sh` | 훅 명령. stdin → POST. 실패 무시 |
-| `scripts/install-hooks.js` | `~/.claude/settings.json` 백업 후 11개 이벤트에 emit.sh 항목을 병합. 이미 있으면 건너뜀. `--remove` 로 제거 |
-| `scripts/demo.js` | 가짜 세션 2개(프로젝트 2개)가 읽기→검색→실행→수정→서브에이전트→질문→휴식 시나리오를 반복 POST. UI 개발·시연용 |
-| `npm start` | 서버 기동. 콘솔에 접속 URL 출력 |
+| `bin/ai-office.js` | `ai-office` (설치 + 훅 등록 + 서버 + 브라우저), `install [--force]`, `install-hooks`, `uninstall-hooks`, `start`, `demo`, `doctor`, `compact` |
+| `hooks/emit.js` | 훅 명령. stdin → POST. 실패 무시 (`emit.sh` 는 예전 curl 버전. 등록돼 있으면 install-hooks 가 emit.js 로 바꾼다) |
+| `scripts/install-hooks.js` | `settings.json` 백업 후 11개 이벤트에 emit.js 항목 병합, 이미 있으면 건너뜀, `--remove` 로 제거 |
+| `lib/nodepath.js` | 훅 명령에 넣을 Node 경로: `~/.ai-office/node` > Homebrew Cellar 버전 폴더 → 버전 없는 opt 링크 > 현재 Node. Node 를 업그레이드해도 훅이 안 깨지게 |
+| `scripts/demo.js` | 가짜 세션들이 읽기→검색→실행→수정→서브에이전트→질문→휴식 시나리오를 반복 POST |
+| `scripts/bump-version.js` | 버전을 package.json · app/package.json · tauri.conf.json · Cargo.toml 에 동시 반영 (`npm run bump:patch|minor`) |
+| `scripts/fetch-node.js` | 데스크톱 앱 사이드카용 Node 바이너리 다운로드 (커밋하지 않음) |
+| `scripts/update-homebrew.js` | 릴리스 뒤 Homebrew tap 의 cask·formula 버전과 sha256 갱신 |
+| `scripts/make-tray-icon.js` | 메뉴바 템플릿 아이콘(빨간 점 변형 포함) 생성 |
+
+- CLI 는 앱 파일을 `~/.ai-office/app` 에 복사해 두고 거기서 실행한다(npx 캐시가 지워져도 훅이 살아 있게). 데스크톱 앱이 깔아 둔 것(`.app-version`)은 `--force` 없이는 덮어쓰지 않는다.
+
 
 ## 8. 설계상 결정
 
-- **의존성 0**: 설치 마찰을 없애고 나중에 Electron/Tauri 로 감쌀 때 그대로 옮기기 위해 Node 내장 모듈과 바닐라 JS 만 쓴다.
+- **의존성 0**: 설치 마찰을 없애고 데스크톱 앱(사이드카 Node)으로 그대로 옮기기 위해 Node 내장 모듈과 바닐라 JS 만 쓴다.
 - **SSE, WebSocket 아님**: 서버→브라우저 단방향이면 충분하고 재접속이 브라우저에 내장돼 있다.
 - **상태는 서버에서 계산**: 훅 이벤트 해석 규칙이 한 곳에 있어야 테스트하기 쉽고, 브라우저는 "어디로 가서 무슨 말풍선" 만 받는다.
-- **그림 자산 없음**: 가구·캐릭터를 canvas 코드로 그린다. 처음엔 단순한 상자 조합으로 시작하고, 나중에 스프라이트 시트로 교체 가능하도록 sprites.js 에 격리한다.
-- **메모리 상태**: 서버 재시작 시 상태는 사라진다. 다음 훅부터 다시 채워진다. 필요해지면 `~/.ai-office/events.jsonl` 로 append 후 재생하는 옵션을 추가한다.
+- **그림 자산 없음**: 가구·캐릭터를 canvas 코드로 그린다 (sprites.js · avatar.js).
+- **재생 가능한 저널**: 상태를 직접 저장하지 않고 원본 이벤트를 남겨 재생한다. 상태 머신이 바뀌어도 저널은 그대로 쓸 수 있다.
+- **뷰어 설정은 브라우저에**: 별명·외형·언어·테마는 localStorage. 층 인테리어처럼 모두가 같이 봐야 하는 것만 서버에 둔다.
+- **범위**: Claude Code 훅만 받는다. claude.ai 채팅·클라우드 세션은 훅이 없어 다루지 않는다.
+
+## 9. 보안 (BE-21)
+
+서버는 `127.0.0.1` 에만 열리지만, 브라우저에 열린 다른 웹사이트도 그 주소로 요청할 수 있다. 세션 제목·요청·경로를 읽거나 가짜 이벤트를 넣지 못하게:
+
+- `Host` 이름이 `127.0.0.1` / `localhost` / `[::1]` 이 아니면 403 → DNS 리바인딩 차단
+- `Origin` 이 있으면 이 서버 화면(같은 포트), 데스크톱 앱 창(`tauri://localhost`, `http(s)://tauri.localhost`)만 허용, 나머지(`null` 포함) 403
+- `Access-Control-Allow-Origin` 은 허용된 Origin 만 그대로 돌려준다 (`*` 쓰지 않음)
+- 훅(emit.js)·CLI·curl 은 Origin 을 보내지 않으므로 영향 없음
+
+## 10. 데스크톱 앱 (app/, Tauri 2)
 
-## 9. 티켓 분할
+```
+AI Office.app / AI Office.exe  (app/src-tauri/src/lib.rs)
+  ├─ 리소스(server.js·lib·public·hooks·scripts) → ~/.ai-office/app 에 복사 (.app-version 이 다를 때만)
+  ├─ 사이드카 Node → ~/.ai-office/node 에 복사 → 훅 명령도 이 Node 를 쓴다
+  ├─ 훅 등록 (install-hooks.js --app-dir …)
+  ├─ 서버 자식 프로세스 (AI_OFFICE_WATCH_PARENT=1, Windows 는 CREATE_NO_WINDOW). 포트가 이미 열려 있으면 그 서버를 쓴다
+  ├─ 창: app/dist/index.html 로더가 /api/state 가 뜰 때까지 기다렸다 http://127.0.0.1:<port>/ 로 이동
+  ├─ 트레이(메뉴바): 왼쪽·오른쪽 클릭 모두 메뉴. 기다리는 세션이나 받아 둔 업데이트가 있으면 빨간 점
+  │    (macOS 는 status item 의 effectiveAppearance 로 글자 색 결정), Dock 배지 / Windows 오버레이 아이콘도 같은 규칙
+  ├─ 업데이터 (tauri-plugin-updater): 백그라운드에서 내려받기만 → 메뉴 "업데이트 적용" 때 서버 종료 → 설치 → 재시작.
+  │    성공 전엔 5분마다, 성공 뒤엔 6시간마다 확인
+  │    메뉴 "업데이트 확인"·"업데이트 적용" 은 진행 창(app/dist/update.html)을 띄운다: 확인 → 다운로드 막대(취소) → 설치 중 → 재시작.
+  │    창은 IPC 권한 없이 Rust 가 eval 로 상태를 넣고, 버튼은 가짜 주소 이동 → on_navigation 이 받는다
+  └─ 로그인 시 자동 실행 (tauri-plugin-autostart, LaunchAgent / Run 키, --hidden). 첫 실행에 한 번 켜고 메뉴 체크박스로 끔
+```
+
+## 11. 배포 · CI
+
+| 경로 | 내용 |
+|---|---|
+| GitHub Release | 태그 `v*` → `.github/workflows/release.yml`: macOS arm64 dmg + `.app.tar.gz(.sig)`, Windows NSIS(.sig), `latest.json`(업데이터), 고정 이름 사본(`AI-Office-mac-arm64.dmg`, `AI-Office-windows-x64-setup.exe`), Windows 설치 스모크 테스트 |
+| npm | `claude-ai-office` (bin `ai-office`). 2FA 때문에 사람이 `npm publish` |
+| Homebrew | `cozyuj/homebrew-tap`: `Casks/ai-office.rb`(dmg, 격리 속성 제거), `Formula/claude-ai-office.rb`(npm tarball). release 가 성공하면 `homebrew.yml` 이 둘을 갱신해 푸시(formula 는 npm 에 그 버전이 있을 때). npm publish 뒤엔 `gh workflow run homebrew.yml -f version=x.y.z` |
 
-BE
-1. `BE-01` 훅 수신 서버 + emit.sh + install-hooks (POST /hook, SSE, 정적 서빙)
-2. `BE-02` 이벤트 정규화 + 상태 머신 (3·4절 표 구현, 단위 테스트는 `node --test`)
-3. `BE-03` 데모 시나리오 스크립트
+- `test.yml`: `npm test` (node --test) 를 ubuntu · windows · macos 에서
+- `app-check.yml`: `app/**` 가 바뀌면 macOS · Windows 에서 `cargo check --locked`
+- 아직 서명·공증 전이라 macOS 는 처음 열 때 "확인되지 않은 개발자" 경고가 뜬다 (Homebrew cask 는 격리 속성을 지워 우회).
 
-FE
-4. `FE-01` 3단 레이아웃 + 좌·우 패널 (층/세션 목록, 사람들, 활동 로그, 범례), SSE 연결·store
-5. `FE-02` 아이소메트릭 맵 + 가구 + 카메라 (정적 사무실이 그려지는 단계)
-6. `FE-03` 캐릭터 이동(A*)·말풍선·슬롯·엘리베이터 출퇴근
-7. `FE-04` 선택/하이라이트/따라가기, 경과 시간, 마무리 다듬기
+## 12. 작업 규칙
 
-순서: BE-01 → BE-02 → BE-03 → FE-01 → FE-02 → FE-03 → FE-04. 브랜치는 `feature/BE-01`, `fix/FE-02`, `test/BE-02` 처럼 `<type>/<티켓ID>`. FE 는 BE-03 데모로 실제 훅 없이도 개발·검증한다.
+- 작업마다 GitHub 이슈 `[FE-nn]` / `[BE-nn]` / `[APP-nn]` → main 에서 `feature|fix|test|docs/<ID>` 브랜치 → PR → CI(test, app-check) 통과 후 머지 → 이슈에 결과·테스트·캡처 댓글.
+- 변경마다 버전을 올린다: 버그·문서 `npm run bump:patch`, 기능 `npm run bump:minor`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-ai-office",
-  "version": "0.29.1",
+  "version": "0.30.1",
   "description": "Claude Code 세션 활동을 아이소메트릭 사무실로 실시간 시각화",
   "keywords": [
     "claude",

package/scripts/bump-version.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // 버전을 네 파일에 동시에 반영한다: package.json, app/package.json, app/src-tauri/tauri.conf.json, app/src-tauri/Cargo.toml
+// (+ Cargo.lock 의 이 크레이트 항목. 안 맞으면 CI 의 cargo check --locked 가 실패한다)
 //   node scripts/bump-version.js patch|minor|major|1.2.3   (버그 수정 = patch, 기능 = minor, 호환 깨짐 = major)
 const fs = require('fs');
 const path = require('path');
@@ -11,6 +12,7 @@ const FILES = {
   appPkg: path.join(ROOT, 'app', 'package.json'),
   tauri: path.join(ROOT, 'app', 'src-tauri', 'tauri.conf.json'),
   cargo: path.join(ROOT, 'app', 'src-tauri', 'Cargo.toml'),
+  lock: path.join(ROOT, 'app', 'src-tauri', 'Cargo.lock'),
 };
 
 function next(current, how) {
@@ -40,9 +42,16 @@ function bump(how) {
     changed.push(FILES.tauri);
   }
   if (fs.existsSync(FILES.cargo)) {
-    const t = fs.readFileSync(FILES.cargo, 'utf8').replace(/^version = "[^"]+"/m, `version = "${to}"`);
-    fs.writeFileSync(FILES.cargo, t);
+    const toml = fs.readFileSync(FILES.cargo, 'utf8');
+    fs.writeFileSync(FILES.cargo, toml.replace(/^version = "[^"]+"/m, `version = "${to}"`));
     changed.push(FILES.cargo);
+    const name = (/^name = "([^"]+)"/m.exec(toml) || [])[1];
+    if (name && fs.existsSync(FILES.lock)) {
+      const esc = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const lock = fs.readFileSync(FILES.lock, 'utf8');
+      const t = lock.replace(new RegExp(`(\\[\\[package\\]\\]\\r?\\nname = "${esc}"\\r?\\nversion = )"[^"]+"`), `$1"${to}"`);
+      if (t !== lock) { fs.writeFileSync(FILES.lock, t); changed.push(FILES.lock); }
+    }
   }
   return { from: pkg.version, to, changed };
 }

package/scripts/update-homebrew.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 'use strict';
-// 릴리스 뒤 Homebrew tap(cozyuj/homebrew-tap)의 cask·formula 버전과 sha256 을 갱신한다.
+// 릴리스 뒤 Homebrew tap(cozyuj/homebrew-tap)의 cask·formula 버전과 sha256 을 갱신한다. CI 에선 .github/workflows/homebrew.yml 이 돌린다.
 //   node scripts/update-homebrew.js [--tap ../homebrew-tap] [--version 0.25.0]
 // cask: GitHub Release 의 AI.Office_<v>_aarch64.dmg, formula: npm 의 claude-ai-office-<v>.tgz (npm 에 그 버전이 있을 때만)
 const fs = require('fs');
@@ -10,7 +10,8 @@ const crypto = require('crypto');
 const arg = (name, def) => { const i = process.argv.indexOf(`--${name}`); return i >= 0 ? process.argv[i + 1] : def; };
 const ROOT = path.join(__dirname, '..');
 const TAP = path.resolve(arg('tap', path.join(ROOT, '..', 'homebrew-tap')));
-const VERSION = arg('version', require(path.join(ROOT, 'package.json')).version);
+const VERSION = arg('version', require(path.join(ROOT, 'package.json')).version).replace(/^v/, '');
+if (!/^\d+\.\d+\.\d+$/.test(VERSION)) { console.error(`버전 형식이 아닙니다: '${VERSION}' — 숫자 x.y.z 로 넣으세요 (예: 0.29.5)`); process.exit(1); }
 
 async function sha256Of(url) {
   const res = await fetch(url, { redirect: 'follow' });

package/server.js

@@ -96,7 +96,7 @@ async function handleFloorStyle(req, res) {
   const id = typeof body.id === 'string' ? body.id : '';
   if (!id) { res.writeHead(400).end(); return; }
   const floor = state.setFloorStyle(id, typeof body.style === 'string' ? body.style : null);
-  res.writeHead(200, { 'Content-Type': MIME['.json'], 'Access-Control-Allow-Origin': '*' });
+  res.writeHead(200, { 'Content-Type': MIME['.json'], ...cors(req) });
   res.end(JSON.stringify({ floor }));
 }
 
@@ -125,7 +125,7 @@ async function handleHook(req, res) {
 
 function handleEvents(req, res) {
   res.writeHead(200, {
-    'Access-Control-Allow-Origin': '*',
+    ...cors(req),
     'Content-Type': 'text/event-stream',
     'Cache-Control': 'no-cache',
     Connection: 'keep-alive',
@@ -150,13 +150,42 @@ function serveStatic(req, res) {
   });
 }
 
+// ---------- 접근 검사 (BE-21) ----------
+// 로컬 서버라도 브라우저에 열린 다른 웹사이트가 fetch·EventSource 로 세션 기록(제목·요청·경로)을 읽거나 가짜 이벤트를 보낼 수 있다.
+//  - Host 가 루프백 이름이 아니면 거절 (DNS 리바인딩 차단)
+//  - Origin 이 있으면 AI Office 자신과 데스크톱 앱 창만 허용. 훅(emit.js)·CLI·curl 은 Origin 이 없어 그대로 통과
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);
+function hostAllowed(req) {
+  const host = String(req.headers.host || '').toLowerCase();
+  const name = host.startsWith('[') ? host.slice(0, host.indexOf(']') + 1) : host.replace(/:\d+$/, '');
+  return LOOPBACK.has(name);
+}
+function originAllowed(origin) {
+  if (!origin) return true;
+  let u;
+  try { u = new URL(origin); } catch { return false; }
+  const host = u.hostname.toLowerCase();
+  if (u.protocol === 'tauri:' && host === 'localhost') return true;                       // macOS 앱 창
+  if ((u.protocol === 'http:' || u.protocol === 'https:') && host === 'tauri.localhost') return true; // Windows 앱 창
+  return u.protocol === 'http:' && LOOPBACK.has(host) && Number(u.port || 80) === Number(PORT); // 이 서버가 띄운 웹 화면
+}
+/** 허용된 Origin 이면 그 값을 돌려주는 CORS 헤더 (* 는 쓰지 않는다) */
+function cors(req) {
+  const origin = req.headers.origin;
+  return origin && originAllowed(origin) ? { 'Access-Control-Allow-Origin': origin, Vary: 'Origin' } : {};
+}
+
 const server = http.createServer((req, res) => {
+  if (!hostAllowed(req) || !originAllowed(req.headers.origin)) {
+    res.writeHead(403, { 'Content-Type': 'text/plain; charset=utf-8' });
+    return res.end('forbidden: AI Office 는 이 컴퓨터의 AI Office 화면에서만 접근할 수 있습니다\n');
+  }
   const { pathname } = new URL(req.url, 'http://x');
   if (req.method === 'POST' && pathname === '/hook') return handleHook(req, res);
   if (req.method === 'GET' && pathname === '/events') return handleEvents(req, res);
   if (req.method === 'POST' && pathname === '/api/floors/style') return handleFloorStyle(req, res);
-  if (req.method === 'POST' && pathname === '/api/demo/start') { startDemo(); res.writeHead(200, { 'Content-Type': MIME['.json'], 'Access-Control-Allow-Origin': '*' }); return res.end(JSON.stringify({ demo: true })); }
-  if (req.method === 'POST' && pathname === '/api/demo/stop') { const removed = stopDemo(); res.writeHead(200, { 'Content-Type': MIME['.json'], 'Access-Control-Allow-Origin': '*' }); return res.end(JSON.stringify({ demo: false, removed })); }
+  if (req.method === 'POST' && pathname === '/api/demo/start') { startDemo(); res.writeHead(200, { 'Content-Type': MIME['.json'], ...cors(req) }); return res.end(JSON.stringify({ demo: true })); }
+  if (req.method === 'POST' && pathname === '/api/demo/stop') { const removed = stopDemo(); res.writeHead(200, { 'Content-Type': MIME['.json'], ...cors(req) }); return res.end(JSON.stringify({ demo: false, removed })); }
   // 끝난/자리 비운 세션을 목록에서 치운다 (TTL 을 기다리지 않고). state.remove → SSE 'remove' 로 모든 브라우저에 전파
   const del = /^\/api\/sessions\/([^/]+)$/.exec(pathname);
   if (del && req.method === 'DELETE') {
@@ -168,12 +197,12 @@ const server = http.createServer((req, res) => {
       const s0 = { session_id: id, hook_event_name: 'SessionEnd', reason: 'dismissed' };
       if (!String(id).startsWith('demo')) journal.append(Date.now(), s0);
     }
-    res.writeHead(found ? 200 : 404, { 'Content-Type': MIME['.json'], 'Access-Control-Allow-Origin': '*' });
+    res.writeHead(found ? 200 : 404, { 'Content-Type': MIME['.json'], ...cors(req) });
     return res.end(JSON.stringify({ removed: found, sessionId: id }));
   }
   if (req.method === 'GET' && pathname === '/api/state') {
     // 데스크탑 앱(tauri://) 로더가 서버 준비 여부를 묻는다 — 로컬 전용 서버라 전체 허용
-    res.writeHead(200, { 'Content-Type': MIME['.json'], 'Access-Control-Allow-Origin': '*' });
+    res.writeHead(200, { 'Content-Type': MIME['.json'], ...cors(req) });
     return res.end(JSON.stringify({ ...withPorts(state.snapshot()), installDir: __dirname }));
   }
   if (req.method === 'GET') return serveStatic(req, res);