@pghoya2956/livemap 1.0.0 → 1.1.0

package/docs/view-budget.md

@@ -6,35 +6,57 @@
 - 산출물은 프로젝트 `map/.out/overview-1440.png`와 `map/.out/budget-results/`다.
 - 대상은 엔진 `serve`(포트 `MAP_PORT`, 기본 4181)다. `LIVEMAP_BUDGET_STATIC=<export 폴더>`면 `serve --static`을 잰다.
 
+## 첫 화면이 답하는 질문
+
+개요는 처음 보는 동료·외부 독자가 30초 안에 읽는 화면이다. 읽는 순서대로 다음 네 질문에 답하고, 답하지 않는 패널은 첫 화면에 못 들어온다.
+
+1. 지금 어느 마일스톤이고 얼마나 왔나: 진척 계기(화면에서 가장 큰 글자)와 마일스톤 패널.
+2. 무엇이 동작하고 무엇이 남았나: 기능 지도(가장 넓은 패널)와 기능 현황.
+3. 무엇을 기다리고, 이상은 없나: 특보와 상단 바 알약.
+4. 최근 얼마나 바뀌었나: 최근 변경, 기능별 변경, 전광판.
+
+운영자 신호(계획 항목 수, 열린 질문, 등급, 미분류, 어댑터 상태)는 전광판 숫자와 더보기에 둔다.
+
 ## 규칙과 이유
 
 | 규칙 | 값(`config.budget`) | 이유 |
 |---|---|---|
-| 첫 화면은 세 질문만 | 어디까지 됐나 · 지금 무엇을 하나 · 무엇이 바뀌었나 | 이 셋에 답하지 않는 패널은 첫 화면에 못 들어온다 |
-| 스크롤 0 | viewport 1440×900 | 한 눈에 전체 상태. 한국 상황판 문법 |
-| 패널 수 | ≤ 8 | 지금 5. 더하려면 하나를 뺀다 |
-| 목록 패널 행 수 | ≤ 6 (목록이 둘이면 각각) | 훑어 읽을 수 있는 한계 |
-| 여정 매트릭스 행 | ≤ 12 | 여정이 그보다 많으면 레인을 합친다 |
-| 시스템 식별자 | 0 | 첫 화면은 사용자 어휘만. 경로·파일명·sha는 상세 층 |
-| 내비 | ≤ 5 | 개요·여정·작업·변화·더보기 |
-| 깊이 | 3 | 개요 → 목록 → 상세. 화면·API·DB 표는 장면 상세에서만 도달 |
-| CSP 아래 렌더 | 콘솔 오류 0, 사이드바 배경 적용 | 인라인 의존 회귀 방지 |
+| 스크롤 0 | `viewport` 1440×900 | 한 눈에 전체 상태. 한국 상황판 문법 |
+| 숨은 스크롤 0 | 모든 `.panel`, 그 안의 `.pb`·`.rows`, `overflow-y`가 `auto`·`scroll`인 자손에서 `scrollHeight − clientHeight ≤ 1`. 줄 수 제한(`-webkit-line-clamp`) 글자와 기능 지도(`.mapwrap`)·캡처(`.live`) 상자는 뺀다 | 패널 안 스크롤은 행 수 검사가 볼 수 없는 곳에서 행을 자르고 공유 스크린샷에 잘린 행이 실린다. 목록은 들어가는 행만 그리고 나머지는 머리줄 "외 n →" 링크로 보낸다 |
+| 패널 수 | ≤ 8 (`maxPanels`) | 지금 8. 더하려면 하나를 뺀다 |
+| 목록 패널 행 수 | ≤ 6 (`maxRowsPerPanel`, 목록 묶음 `.rows`마다) | 훑어 읽을 수 있는 한계 |
+| 기능 지도 행 | ≤ 12 (`.jrow`) | 기능이 13개부터는 완성 기능이 지도에서 접히고 바닥 칩 "완성 기능 n 접힘"이 기능 화면으로 이어진다. 기능 화면에는 전부 보인다 |
+| 시스템 식별자 | 0 (`#root` 글자 전체) | 첫 화면은 사용자 어휘만. 경로·파일명·sha는 상세 층 |
+| 내비 | ≤ 5 (`navItems`), 모두 보임 | 개요·기능·로드맵·작업·더보기 |
+| 깊이 | 3 | 기능 지도 기능 선택 → 기능 현황의 "기능 화면 →" → 단계 카드 → 단계 상세. 화면·API·DB 표는 단계 상세에서만 도달 |
+| CSP 아래 렌더 | 콘솔 오류·CSP 위반 0, `body` 배경이 `--bg`(`rgb(5, 7, 10)`) | 인라인 의존 회귀 방지(`hosting-and-csp.md`) |
+| 모션 줄임 | `reducedMotion: 'reduce'`에서 `document.getAnimations()` 0 | 전광판·캡처 회전·연결선 흐름이 멈추는지 |
+| 상태 모양 | 기능 지도 범례(레이어 버튼) 표식 4종이 각각 동작 = 채운 원, 목업 = 반원 채움 + 실선, 계획 = 채움 없음 + 실선, 구상 = 채움 없음 + 점선. 기능이 없어 범례가 없으면 건너뛴다 | 다크 상태 색끼리는 휘도 차가 작아 색을 못 보는 독자에게 모양이 구분을 맡는다 |
+
+스크린샷은 모션 줄임 컨텍스트에서 `document.fonts.ready` 뒤에 찍는다. 새로 더한 숨은 스크롤·모션 줄임·상태 모양 검사는 엔진 화면 요소만 보므로, 프로젝트 자료가 달라서 새로 실패하지 않는다. 내부 용어·글자 대비·글자 크기 집합은 프로젝트 문구와 브라우저에 따라 달라져 예산 검사에 넣지 않는다.
 
 ## 개요 조각
 
-개요는 `overview.json`만 읽는다. `derive.mjs`의 `overviewSlice()`가 경로·파일명·sha를 뺀 조각을 만들고, 검사는 개요 본문에서 `/api/`·`.tsx`·`.mjs`·`.sql`·`web/src`·7자 이상 16진수를 찾아 하나라도 있으면 실패한다. 개요에 무언가를 더할 때 이 조각을 거치지 않으면 식별자가 새어 들어온다.
+개요는 `overview.json`만 읽고 다시 계산하지 않는다. `derive.mjs`의 `overviewSlice(d, opts)`가 경로·파일명·sha를 뺀 조각을 만들고, 검사는 개요 본문에서 `/api/`·`.tsx`·`.mjs`·`.sql`·`web/src`·7자 이상 16진수를 찾아 하나라도 있으면 실패한다. 개요에 무언가를 더할 때 이 조각을 거치지 않으면 식별자가 새어 들어온다.
+
+프로젝트가 적은 문구도 개요에 나온다. 커밋 제목은 `overviewSlice`가 관례 접두어·내부 ID·식별자를 지우고 사람 커밋만 싣는다(작성자가 `[bot]`으로 끝나면 자동 커밋으로 따로 센다). 로드맵 항목·마일스톤의 목표와 결정 대기, 작업 제목, 기능·단계 이름은 엔진이 고치지 않는다. 여기에 경로나 7자 이상 16진수를 적으면 식별자 검사가 실패하므로 그 문구를 고친다.
+
+`overview.json` 크기는 기능 수와 커밋 수에 따라 1.0.1보다 커진다. 엔진 픽스처는 3,697B이고, 기능 9개·14일 커밋 200여 건인 실제 프로젝트 하나에서 25,637B였다.
 
 ## 다시 보게 만드는 것
 
-- 마지막 방문 시각을 브라우저 안에 기억해(밖으로 보내지 않는다) 그 뒤 바뀐 커밋·장면에 빨간 점을 찍는다.
-- 상단 띠 한 줄: 동작 장면 수·실데이터 화면 수·14일 커밋·미배포·경고·다음 한 걸음. 들어오자마자 읽을 한 문장.
+- 마지막 방문 시각을 브라우저 안에 기억해(`localStorage` `map:lastVisit`, 밖으로 보내지 않는다) 그 뒤 생긴 커밋 행에 점을 찍는다.
+- 전광판 한 줄: 동작 단계·완성 기능·로드맵 완료·14일 변경·규모 숫자·기능별 변경. 들어오자마자 읽는 줄이고, 정지 버튼과 모션 줄임으로 멈춘다.
 - 2주 뒤 실제로 연 뷰만 남긴다. 안 연 패널은 지운다.
 
 ## 패널을 바꾸는 절차
 
-화면 파일은 엔진 소유다. 패널을 바꾸는 일은 엔진 저장소에서 하고 릴리스로 내보낸다.
+화면 원본은 엔진 저장소 `ui/`(React)이고 `site/`의 `index.html`·`map.css`·`map.js`는 그 번들 산출물이다. 패널을 바꾸는 일은 엔진 저장소에서 하고 릴리스로 내보낸다.
 
-1. 답하려는 질문이 세 질문 중 무엇인지 적는다. 없으면 상세 층으로 간다.
+1. 답하려는 질문이 위 네 질문 중 무엇인지 적는다. 없으면 하위 화면으로 간다.
 2. 뺄 패널을 정한다.
-3. 엔진 저장소 `site/map.js`의 `overview()`에서 `<section class="panel" data-budget="list|matrix">`로 만든다. 인라인 style 금지, 폭은 `data-w`.
-4. 엔진 CI의 tarball 스모크(픽스처)와, 쓰는 프로젝트에 `npm install --no-save --install-links <엔진 저장소>`로 끼운 `npm run map:budget`으로 스크롤·행·식별자를 잰다. 스크린샷 `map/.out/overview-1440.png`을 사용자에게 보인다.
+3. `ui/components/panels.jsx`에 컴포넌트를 만들고 `ui/Overview.jsx` 격자에 놓는다. 틀은 `ui/components/primitives.jsx`의 `Panel`이고, 목록 패널은 `budget="list"`와 `.rows > .row`, 행 수는 `ui/lib/fit.js`의 `useFitRows`로 정한다. 마크업의 `style` 속성·`<style>` 주입은 쓰지 않고 크기·위치만 React `style` prop으로 준다. 프로젝트가 적은 문구를 담는 요소에는 `data-text="project"`, 커밋 제목에는 `data-text="commit"`을 단다.
+4. 자료가 더 필요하면 `overviewSlice`에 필드를 더한다(추가만 한다. 1.0.1 필드의 이름·형·값은 바꾸지 않는다).
+5. `node scripts/build-ui.mjs`로 `site/`를 다시 만들어 함께 커밋한다. CI는 다시 빌드한 결과가 커밋과 같은지 본다.
+6. 누르거나 이동하는 요소를 더하거나 바꿨으면 `scripts/click-targets.json`에 행을 맞춘다. 표에 없는 대화형 요소가 있으면 클릭 경로 크롤이 실패한다. 엔진 저장소에서 `node scripts/route-crawl.mjs --url http://127.0.0.1:<포트>/map/ --targets scripts/click-targets.json`(한 화면만 `--only <overview|journeys|roadmap|tasks|more>`, 이동 없이 개요만 `--overview-only`)로 확인한다. 크롤러는 팩에 없어 엔진 저장소에서만 돈다.
+7. 엔진 CI의 스모크(픽스처: 예산, 하위 화면 콘솔 0, 설정 경로를 바꾼 복사본의 화면 문구, 클릭 경로)와, 쓰는 프로젝트에 `npm install --no-save --install-links <엔진 저장소>`로 끼운 `npm run map:budget`으로 스크롤·숨은 스크롤·행·식별자를 잰다. 스크린샷 `map/.out/overview-1440.png`을 사용자에게 보인다.

package/package.json

@@ -1,19 +1,49 @@
 {
   "name": "@pghoya2956/livemap",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Project status board engine: scans a repository into a graph and serves a one-screen map of journeys, screens, APIs, tests and work.",
   "license": "MIT",
   "type": "module",
-  "bin": { "livemap": "bin/livemap.mjs" },
-  "files": ["bin/", "src/", "site/", "budget/", "templates/", "docs/", "CHANGELOG.md"],
-  "engines": { "node": ">=22" },
+  "bin": {
+    "livemap": "bin/livemap.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "site/",
+    "budget/",
+    "templates/",
+    "docs/",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "build:ui": "node scripts/build-ui.mjs"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.63.0 <2"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "1.63.0",
+    "@types/react": "19.3.0",
+    "esbuild": "0.28.2",
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pghoya2956/livemap.git"
   },
-  "peerDependencies": { "@playwright/test": ">=1.63.0 <2" },
-  "peerDependenciesMeta": { "@playwright/test": { "optional": true } },
-  "devDependencies": { "@playwright/test": "1.63.0" },
-  "repository": { "type": "git", "url": "git+https://github.com/pghoya2956/livemap.git" },
   "homepage": "https://github.com/pghoya2956/livemap#readme",
-  "publishConfig": { "access": "public" }
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/site/index.html

@@ -4,22 +4,10 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>상황판</title>
-<!-- 서빙 CSP(default-src 'self')에 맞춰 스타일·스크립트·서체는 같은 출처의 /map/ 아래 파일만 쓴다. 인라인은 넣지 않는다. -->
-<link rel="stylesheet" href="/map/map.css">
+<link rel="stylesheet" href="map.css">
 </head>
 <body>
-
-<div class="app">
-  <aside class="side">
-    <div class="brand"><span id="brandName">상황판</span><small id="brandSha"></small></div>
-    <nav class="nav" id="nav"></nav>
-    <div class="foot" id="sideFoot"></div>
-  </aside>
-  <main class="main">
-    <div class="head"><h1 id="title"></h1><span class="sub" id="subtitle"></span><div class="meta" id="meta"></div></div>
-    <div id="view"><p class="empty">불러오는 중…</p></div>
-  </main>
-</div>
-<script src="/map/map.js"></script>
+<div id="root"></div>
+<script src="map.js"></script>
 </body>
 </html>