issue-map 0.3.1 → 0.5.0

package/{scripts → src}/issue-map-model.ts

@@ -3,8 +3,7 @@
  * 那一側（`issue-map-page.ts`）都 import 它，所以它不能碰任何一邊的專屬 API。
  *
  * 這裡住的是「同一份定義只有一份」的東西：狀態的五個值、一張票的形狀、分群規則、關鍵路徑，
- * 以及線路圖的排版。畫面那一側曾經把狀態的五個值再抄一次，兩邊沒有東西保證同步；現在型別
- * 是共用的，抄錯編不過。
+ * 以及線路圖的排版。兩側共用同一份型別，任何一邊自己抄一份都編不過。
  */
 
 /** 一張票現在的處境。同時是頁面的顏色與篩選分頁。 */
@@ -73,15 +72,36 @@ export type Group = {
 export type Snapshot = {
   readonly generatedAt: string
   readonly repo: string
-  /** 這一次實際生效的標籤字彙。圖例照它寫，不然改了設定圖例就會說謊。 */
-  readonly labels: { readonly ready: readonly string[]; readonly unready: readonly string[] }
-  /** 一張圖一群。 */
+  /**
+   * 這一次實際生效的標籤字彙與閘門。圖例照它寫，不然改了設定圖例就會說謊。
+   *
+   * `gated` 是**狀態機當下真的有沒有把這些標籤當閘門**。字彙本身一律有預設值、永遠非空，拿
+   * 它的長度去推閘門開著沒有的話，repo 還沒導入標籤時票會判成可動，頁尾卻說沒掛標籤等於未定案。
+   */
+  readonly labels: {
+    readonly ready: readonly string[]
+    readonly unready: readonly string[]
+    readonly gated: boolean
+  }
   readonly groups: readonly Group[]
   /** 最長的一條依序未完成鏈，也就是最少要幾輪。 */
   readonly criticalPath: number
   readonly issues: readonly MapIssue[]
 }
 
+/**
+ * 什麼都還沒有的快照。畫面那一側解析行內 JSON 時用它補齊缺的欄位——**缺欄位只在那一個邊界
+ * 成立**，收在這裡的話下游拿到的一律是完整的 `Snapshot`，不必每個欄位各自決定「缺了算什麼」。
+ */
+export const EMPTY_SNAPSHOT: Snapshot = {
+  generatedAt: '',
+  repo: '',
+  labels: { ready: [], unready: [], gated: false },
+  groups: [],
+  criticalPath: 0,
+  issues: [],
+}
+
 /**
  * 分群：同一張主票底下的子票一群；沒有主票但跟別人有前置關係的合成一群；完全孤立的合成一群。
  * 一張圖畫一群。
@@ -175,16 +195,36 @@ export type Edge = { readonly from: number; readonly to: number }
 export type Layout = {
   /** 每一條線由前到後的站。只有一站的線不標線名。 */
   readonly tracks: readonly (readonly number[])[]
-  /** 孤立的票排成幾列月台。 */
+  /** 孤立的票排成幾列月台。月台接在最後一條線下面，起點就是 `tracks.length`。 */
   readonly islandRows: number
-  /** 月台從第幾列開始。 */
-  readonly islandFrom: number
   readonly xy: ReadonlyMap<number, Point>
   readonly edges: readonly Edge[]
   readonly width: number
   readonly height: number
 }
 
+/** 月台一列至少幾站。票很少時不要排成細細一條。 */
+const ISLAND_MIN_PER_ROW = 4
+/**
+ * 月台一列最多幾站。再寬下去橫向要捲很遠，而月台上的左右位置本來就不帶意義——寧可多幾列。
+ */
+const ISLAND_MAX_PER_ROW = 12
+
+/**
+ * 一組票內部的阻擋邊。**什麼算一條邊只有這一份定義**——排版照它畫線，頁面也照它判斷這一組畫
+ * 出來到底有沒有線；各算一次的話會出現「說要畫圖、畫出來卻沒有線」。
+ */
+export function edgesWithin(members: readonly MapIssue[]): Edge[] {
+  const inGroup = new Set(members.map((m) => m.number))
+  const edges: Edge[] = []
+  for (const m of members) {
+    for (const from of m.blockedBy) {
+      if (inGroup.has(from)) edges.push({ from, to: m.number })
+    }
+  }
+  return edges
+}
+
 /**
  * 把一組票排成線路圖。
  *
@@ -196,19 +236,12 @@ export type Layout = {
  * 會變成十二條單站線。
  */
 export function layoutOf(members: readonly MapIssue[]): Layout {
-  const inGroup = new Set(members.map((m) => m.number))
-  const preds = new Map(
-    members.map((m) => [m.number, m.blockedBy.filter((n) => inGroup.has(n))] as const),
-  )
+  const edges = edgesWithin(members)
+  const preds = new Map<number, number[]>(members.map((m) => [m.number, []]))
+  for (const edge of edges) preds.get(edge.to)?.push(edge.from)
   const predsOf = (n: number): readonly number[] => preds.get(n) ?? []
 
-  const hasEdge = new Set<number>()
-  for (const m of members) {
-    for (const from of predsOf(m.number)) {
-      hasEdge.add(m.number)
-      hasEdge.add(from)
-    }
-  }
+  const hasEdge = new Set(edges.flatMap((edge) => [edge.from, edge.to]))
   const wired = members.filter((m) => hasEdge.has(m.number))
   const island = members.filter((m) => !hasEdge.has(m.number))
 
@@ -235,7 +268,9 @@ export function layoutOf(members: readonly MapIssue[]): Layout {
   }
 
   const depth = wired.length ? Math.max(...wired.map((m) => levelOf(m.number))) : 1
-  const perRow = Math.max(depth, 4)
+  // 月台排成接近正方形，不然沒有阻擋關係的 repo 會把整批票疊成一條幾千 px 高的直條。
+  const squarish = Math.ceil(Math.sqrt(island.length))
+  const perRow = Math.max(depth, Math.min(squarish, ISLAND_MAX_PER_ROW), ISLAND_MIN_PER_ROW)
   const xy = new Map<number, Point>()
   tracks.forEach((chain, index) => {
     for (const n of chain) {
@@ -250,15 +285,9 @@ export function layoutOf(members: readonly MapIssue[]): Layout {
   })
   const islandRows = Math.ceil(island.length / perRow)
 
-  const edges: Edge[] = []
-  for (const m of members) {
-    for (const from of predsOf(m.number)) edges.push({ from, to: m.number })
-  }
-
   return {
     tracks,
     islandRows,
-    islandFrom: tracks.length,
     xy,
     edges,
     width: MAP.gutter + perRow * MAP.step + MAP.rightPad,

package/src/issue-map-page.ts

@@ -0,0 +1,411 @@
+/**
+ * 開發地圖的畫面。`issue-map.ts` 用 `Bun.build` 把這支打包成一段 script 塞進樣板，所以它
+ * **只能碰瀏覽器的東西**，不能 import Bun 的 API。
+ *
+ * 標記全部在 `issue-map-view.ts`，而且建置時就已經用同一批函式畫過一次寫進檔案了——這一支只在
+ * 換語言、換篩選、選取、收合時重畫。所以沒有 JS 的環境看到的是同一份頁面，只是不能互動。
+ *
+ * 這裡剩下的是 DOM 與事件：讀寫 localStorage 的兩個偏好（語言、收合）、事件代理、選取狀態。
+ */
+
+import { DEFAULT_LOCALE, isLocale, type Locale, locale, setLocale, t } from './issue-map-i18n.ts'
+import { EMPTY_SNAPSHOT, type Snapshot } from './issue-map-model.ts'
+import { type Filter, langOptionsHTML, viewOf } from './issue-map-view.ts'
+
+/** 樣板保證這些節點存在。找不到就是樣板被改壞了，早點喊比畫出半張圖好。 */
+function pick(id: string): HTMLElement {
+  const node = document.getElementById(id)
+  if (!node) throw new Error(`樣板缺少 #${id}`)
+  return node
+}
+
+/**
+ * 行內 JSON 是整份快照唯一可能殘缺的地方（沒有資料、被截斷）。缺的欄位在這裡一次補齊，下游
+ * 拿到的一律是完整的 `Snapshot`——不然每個用到快照的地方都要自己決定「缺了算什麼」。
+ */
+function readSnapshot(): Snapshot {
+  const parsed = JSON.parse(pick('issue-map-data').textContent || '{}') as Partial<Snapshot>
+  return { ...EMPTY_SNAPSHOT, ...parsed }
+}
+
+const snapshot = readSnapshot()
+const view = viewOf(snapshot)
+const repo = snapshot.repo
+
+const detail = pick('detail')
+const rowsEl = pick('rows')
+const groupsEl = pick('groups')
+const tabsEl = pick('tabs')
+
+let selected: number | null = null
+let filter: Filter = 'all'
+
+// ---- 偏好 ----
+
+/**
+ * 偏好記在瀏覽器。**讀不到、寫不進都不是錯誤**：無痕視窗與擋掉儲存的設定裡 `localStorage` 會
+ * 直接丟例外，那時偏好只在這一次有效，畫面照樣是完整的——所以存取一律收在這兩支裡。
+ */
+function readStored(key: string): string | null {
+  try {
+    return localStorage.getItem(key)
+  } catch {
+    return null
+  }
+}
+
+function writeStored(key: string, value: string): void {
+  try {
+    localStorage.setItem(key, value)
+  } catch {
+    // 存不了就只在這一次有效。
+  }
+}
+
+// ---- 語言 ----
+
+/**
+ * 語言記在瀏覽器、而且不分 repo——同一個人看好幾個 repo 的地圖，語言是他的偏好，不是某個專案
+ * 的設定。讀不到（無痕、封鎖）或存的是舊值就用預設的英文。
+ *
+ * 刻意不看 `navigator.language`：這一頁的預設語言是英文，猜錯了反而要每次進來都改回去。
+ */
+const LOCALE_KEY = 'issue-map:locale'
+
+function readLocale(): Locale {
+  const saved = readStored(LOCALE_KEY)
+  return isLocale(saved) ? saved : DEFAULT_LOCALE
+}
+
+/** 語言選單只做一次；換語言是整頁重畫，選單自己不重建，不然焦點會掉。 */
+function mountLangPicker(): void {
+  const picker = pick('lang')
+  if (!(picker instanceof HTMLSelectElement)) throw new Error('#lang 不是 select')
+  picker.innerHTML = langOptionsHTML()
+  picker.value = locale()
+  picker.addEventListener('change', () => {
+    if (!isLocale(picker.value)) return
+    setLocale(picker.value)
+    writeStored(LOCALE_KEY, picker.value)
+    render()
+  })
+}
+
+// ---- 收合狀態 ----
+
+/**
+ * 收合狀態只有一份，地圖與清單都讀它、都能改它。每個瀏覽器記自己的；讀不到（無痕、封鎖）
+ * 就當成全部展開。
+ */
+const COLLAPSE_KEY = `issue-map:collapsed:${repo}`
+
+function readFolded(): Set<string> {
+  try {
+    return new Set(JSON.parse(readStored(COLLAPSE_KEY) || '[]') as string[])
+  } catch {
+    return new Set()
+  }
+}
+
+const folded = readFolded()
+
+function isFolded(parent: number): boolean {
+  return folded.has(String(parent))
+}
+
+/**
+ * 掛在某張票底下的東西該不該藏起來。
+ *
+ * 看的是**整條祖先鏈**，不只直屬主票——三層的鏈收起最上面那張時，第三層的 `data-parent` 指的
+ * 是第二層，只比對直屬的話它會單獨留在畫面上。
+ */
+function foldedAnywhere(parent: number): boolean {
+  const seen = new Set<number>()
+  for (let at: number | null = parent; at !== null && !seen.has(at);) {
+    if (isFolded(at)) return true
+    seen.add(at)
+    at = view.issueAt(at)?.parent ?? null
+  }
+  return false
+}
+
+function setFolded(parent: number, shut: boolean): void {
+  if (shut) folded.add(String(parent))
+  else folded.delete(String(parent))
+  writeStored(COLLAPSE_KEY, JSON.stringify([...folded]))
+  paintFolded()
+}
+
+/**
+ * 收合只在這裡畫一次：列、就地展開的細節、地圖本體，凡是掛了 data-parent 的都聽它。收合鈕的
+ * 樣子也在這裡補上——建置時畫出來的鈕是空的，因為那時還不知道這個瀏覽器記了什麼。
+ */
+function paintFolded(): void {
+  for (const node of document.querySelectorAll<HTMLElement>('[data-parent]')) {
+    node.hidden = foldedAnywhere(Number(node.dataset.parent))
+  }
+  for (const section of document.querySelectorAll<HTMLElement>('section.group[data-fold]')) {
+    section.dataset.folded = String(isFolded(Number(section.dataset.fold)))
+  }
+  for (const button of document.querySelectorAll<HTMLElement>('.fold[data-fold-for]')) {
+    const parent = Number(button.dataset.foldFor)
+    const open = !isFolded(parent)
+    button.setAttribute('aria-expanded', String(open))
+    button.setAttribute(
+      'aria-label',
+      open ? t('fold.collapse', { n: parent }) : t('fold.expand', { n: parent }),
+    )
+    button.textContent = open ? '−' : '+'
+  }
+}
+
+// ---- 選取 ----
+
+/**
+ * 選一張票。再點同一張不會取消——在清單上你往往只是想再看一次，取消掉反而要重新找。要清掉
+ * 按 Esc。
+ */
+function select(number: number): void {
+  selected = number
+  paintSelection()
+}
+
+function clearSelection(): void {
+  selected = null
+  closeExpander()
+  paintSelection()
+}
+
+function paintSelection(): void {
+  const lit = selected === null ? null : view.chainOf(selected)
+  for (const svg of document.querySelectorAll<SVGSVGElement>('svg')) {
+    svg.classList.toggle('has-selection', selected !== null)
+    for (const node of svg.querySelectorAll<SVGElement>('.node')) {
+      const number = Number(node.dataset.number)
+      node.classList.toggle('lit', lit !== null && lit.has(number))
+      node.classList.toggle('selected', number === selected)
+    }
+    for (const edge of svg.querySelectorAll<SVGElement>('.edge')) {
+      const from = Number(edge.dataset.from)
+      const to = Number(edge.dataset.to)
+      edge.classList.toggle('lit', lit !== null && lit.has(from) && lit.has(to))
+    }
+  }
+  for (const row of rowsEl.querySelectorAll<HTMLElement>('.row[data-number]')) {
+    row.classList.toggle('selected', Number(row.dataset.number) === selected)
+  }
+  renderDetail(selected ?? view.defaultPick())
+}
+
+function renderDetail(number: number | undefined): void {
+  const panel = view.detailPanelHTML(number)
+  detail.dataset.status = panel.status
+  detail.innerHTML = panel.html
+}
+
+// ---- 就地展開 ----
+
+/**
+ * 清單的細節就在被點的那一列底下展開，不把畫面捲到上面的面板——連著看三張票時，視線不用
+ * 來回跑。
+ */
+function closeExpander(): void {
+  rowsEl.querySelector('.detail.expand')?.remove()
+}
+
+function openExpander(row: HTMLElement, number: number): void {
+  closeExpander()
+  const issue = view.issueAt(number)
+  if (!issue) return
+  const panel = document.createElement('div')
+  panel.className = 'detail expand'
+  panel.dataset.status = issue.status
+  panel.dataset.forNumber = String(number)
+  // 掛上 data-parent，主票收起來時 paintFolded 會一起把它藏掉。
+  if (row.dataset.parent) panel.dataset.parent = row.dataset.parent
+  panel.innerHTML = view.detailHTML(number)
+  row.insertAdjacentElement('afterend', panel)
+  paintFolded()
+}
+
+function pickRow(row: HTMLElement): void {
+  const number = Number(row.dataset.number)
+  const already = rowsEl.querySelector(`.detail.expand[data-for-number="${number}"]`)
+  // 上面的面板換一張票會改變自己的高度，把清單整段推走。先記下這一列在畫面上的位置，改完
+  // 再補回去，手指底下的那一列就不會跑。
+  const before = row.getBoundingClientRect().top
+  select(number)
+  if (already) closeExpander()
+  else openExpander(row, number)
+  const shift = row.getBoundingClientRect().top - before
+  if (shift) window.scrollBy({ top: shift, behavior: 'instant' })
+}
+
+// ---- 複製 ----
+
+/**
+ * 複製到剪貼簿。`navigator.clipboard` 在非安全來源沒有，而就算有也可能被權限擋掉（沒有使用者
+ * 手勢、或瀏覽器設定），所以失敗一律退回選取再 execCommand。
+ */
+function legacyCopy(text: string): Promise<void> {
+  const box = document.createElement('textarea')
+  box.value = text
+  box.setAttribute('readonly', '')
+  box.style.cssText = 'position:fixed;top:-100px;opacity:0'
+  document.body.appendChild(box)
+  box.select()
+  const ok = document.execCommand('copy')
+  box.remove()
+  return ok ? Promise.resolve() : Promise.reject(new Error('execCommand copy failed'))
+}
+
+function copyText(text: string): Promise<void> {
+  if (!navigator.clipboard || !window.isSecureContext) return legacyCopy(text)
+  return navigator.clipboard.writeText(text).catch(() => legacyCopy(text))
+}
+
+function flash(label: HTMLElement, text: string, ms: number, then: () => void): void {
+  label.textContent = text
+  setTimeout(then, ms)
+}
+
+function handleCopy(button: HTMLElement): void {
+  const label = button.querySelector<HTMLElement>('.copy-text')
+  const command = button.dataset.copy
+  if (!label || !command) return
+  const was = label.textContent ?? ''
+  copyText(command).then(
+    () => {
+      button.dataset.copied = 'true'
+      flash(label, t('copy.done'), 1200, () => {
+        delete button.dataset.copied
+        label.textContent = was
+      })
+    },
+    () => flash(label, t('copy.fail'), 1600, () => (label.textContent = was)),
+  )
+}
+
+// ---- 事件 ----
+
+function elementAt(ev: Event): Element | null {
+  return ev.target instanceof Element ? ev.target : null
+}
+
+// 全部走委派：標記是建置時畫好的，重畫也只是換 innerHTML，沒有可以逐一掛監聽的時機。
+document.addEventListener('click', (ev) => {
+  const target = elementAt(ev)
+  if (!target) return
+
+  const fold = target.closest<HTMLElement>('.fold[data-fold-for]')
+  if (fold) {
+    const parent = Number(fold.dataset.foldFor)
+    setFolded(parent, !isFolded(parent))
+    return
+  }
+
+  const copy = target.closest<HTMLElement>('.copy')
+  if (copy) {
+    // 複製是自己一件事，不要順手把那一列也選起來。
+    ev.stopPropagation()
+    handleCopy(copy)
+    return
+  }
+
+  const tab = target.closest<HTMLElement>('.tab[data-filter]')
+  if (tab) {
+    filter = (tab.dataset.filter ?? 'all') as Filter
+    renderRows()
+    paintSelection()
+    const back =
+      selected === null
+        ? null
+        : rowsEl.querySelector<HTMLElement>(`.row[data-number="${selected}"]`)
+    if (back && selected !== null) openExpander(back, selected)
+    return
+  }
+
+  // 點站看詳細；要開 GitHub 用 ⌘／Ctrl 點，或詳細面板裡的連結。
+  const node = target.closest<HTMLElement>('.node[data-number]')
+  if (node) {
+    if (ev.metaKey || ev.ctrlKey || ev.shiftKey) return
+    ev.preventDefault()
+    const number = Number(node.dataset.number)
+    // 再點同一站就取消，跟點空白處一樣——不然亮起來之後只剩 Esc 能收，那沒人找得到。
+    if (selected === number) clearSelection()
+    else select(number)
+    return
+  }
+
+  // 點圖上的空白處就取消亮線。
+  if (target.closest('.map-wrap')) {
+    clearSelection()
+    return
+  }
+
+  if (target.closest('a')) return
+  const row = target.closest<HTMLElement>('.row[data-number]')
+  if (row) pickRow(row)
+})
+
+rowsEl.addEventListener('keydown', (ev) => {
+  const target = elementAt(ev)
+  const row = target?.closest<HTMLElement>('.row[data-number]')
+  if (!row) return
+  if (ev.key === 'Enter' || ev.key === ' ') {
+    ev.preventDefault()
+    pickRow(row)
+    return
+  }
+  if (ev.key !== 'ArrowDown' && ev.key !== 'ArrowUp') return
+  ev.preventDefault()
+  const rows = [...rowsEl.querySelectorAll<HTMLElement>('.row[data-number]:not([hidden])')]
+  const next = rows[rows.indexOf(row) + (ev.key === 'ArrowDown' ? 1 : -1)]
+  next?.focus()
+})
+
+document.addEventListener('keydown', (ev) => {
+  if (ev.key === 'Escape') clearSelection()
+})
+
+// ---- 重畫 ----
+
+function renderRows(): void {
+  const rows = view.rowsHTML(filter)
+  pick('list-title').textContent = t('list.title')
+  pick('list-sub').textContent = t('list.count', { n: rows.shown })
+  rowsEl.innerHTML = rows.html
+  tabsEl.innerHTML = view.tabsHTML(filter)
+  paintFolded()
+}
+
+/**
+ * 整頁重畫。換語言就是走這裡——每一段都會先清掉自己那一塊，所以重畫一次不會留下上一種語言的
+ * 殘骸。選取與收合是狀態不是文字，重畫時保留。
+ */
+function render(): void {
+  const heading = view.title()
+  pick('page-title').textContent = heading
+  document.title = heading
+  document.documentElement.lang = locale()
+  pick('lang').setAttribute('aria-label', t('lang.label'))
+  pick('eyebrow').textContent = view.eyebrow()
+  pick('lede').innerHTML = view.lede()
+  pick('stats').innerHTML = view.statsHTML()
+
+  // 三段都是逃脫過的 HTML，跟建置時填進樣板的是同一批字串——用 textContent 塞會把逃脫顯示出來。
+  const foot = view.footerHTML()
+  pick('foot-truth').innerHTML = foot.truth
+  pick('foot-refresh').innerHTML = foot.refresh
+  pick('foot-config').innerHTML = foot.config
+
+  groupsEl.innerHTML = view.groupsHTML()
+  tabsEl.setAttribute('aria-label', t('tabs.aria'))
+  renderRows()
+  // paintSelection 收尾會畫詳細，沒有選取時它自己退回預設那一張。
+  paintSelection()
+}
+
+setLocale(readLocale())
+mountLangPicker()
+render()

package/{scripts → src}/issue-map-serve.ts

@@ -6,26 +6,28 @@
  * 這是 package.json 的預設 bin，所以在**要看的那個 repo** 裡直接跑就會畫那個 repo：
  *   bunx issue-map@latest
  *
- * 起來之後直接開瀏覽器。不要的話設 `ISSUE_MAP_OPEN=0`——`bun --watch` 的開發模式就是這樣關掉
- * 的，否則每存一次檔就多一個分頁。
+ * 起來之後直接開瀏覽器，`ISSUE_MAP_OPEN=0` 可以關掉（`--watch` 的開發模式靠它，否則每存一次
+ * 檔就多一個分頁）。
+ *
+ * 預設不綁固定 port（`port: 0`，交給 OS 挑），所以在好幾個 repo 裡同時跑不會互相撞；實際網址
+ * 跟正在畫的目錄一起印在啟動訊息裡。設 `ISSUE_MAP_PORT` 可以固定，那時撞到就直接失敗而不偷
+ * 偷換一個——指定了還被換掉，書籤和反向代理都會對不上。
  *
  * 在這個 repo 裡開發時：
- *   bun run issue-map:serve                       # http://localhost:4747，不自動開
- *   ISSUE_MAP_PORT=5000 bun run issue-map:serve
+ *   bun run issue-map:serve                       # 隨機 port，不自動開
+ *   ISSUE_MAP_PORT=4747 bun run issue-map:serve   # 固定網址，--watch 重啟後還是同一個
  */
 
 import { spawnSync } from 'bun'
 
-import { describe, renderFragment, takeSnapshot } from './issue-map.ts'
+import { describe, renderDocument, takeSnapshot } from './issue-map.ts'
 
-// `PORT` 是 Claude 桌面 app 的 launch.json 在 autoPort 換 port 時塞進來的。
-const PORT = Number(process.env.ISSUE_MAP_PORT ?? process.env.PORT ?? 4747)
+// `PORT` 是 Claude 桌面 app 的 launch.json 在 autoPort 換 port 時塞進來的。都沒設就是 0：
+// 由 OS 指派，`server.port` 才是真的在聽的那個。
+const PORT = Number(process.env.ISSUE_MAP_PORT ?? process.env.PORT ?? 0)
 const OPEN = process.env.ISSUE_MAP_OPEN !== '0'
 
-/**
- * 開系統預設瀏覽器。**打不開不算失敗**：server 已經起來了，印出網址讓人自己開就好——把它
- * 當錯誤收掉會讓「地圖其實好好地跑著」這件事被一個無關的問題蓋掉。
- */
+/** 開系統預設瀏覽器。**打不開不算失敗**：server 已經起來了，印出網址讓人自己開就好。 */
 function openInBrowser(url: string): void {
   const command =
     process.platform === 'darwin'
@@ -41,14 +43,25 @@ function openInBrowser(url: string): void {
   }
 }
 
+/**
+ * 同時抵達的請求共用同一次抓取。
+ *
+ * 一次重新整理按兩下、或開著兩個分頁，本來會各自跑一趟完整的 GitHub 抓取；它們要的是同一刻的
+ * 狀態，讓後到的等前一趟就好。抓完就清掉，所以「每次重新整理都是最新的」沒有變。
+ */
+let inFlight: Promise<string> | null = null
+
 async function page(): Promise<string> {
-  const snapshot = takeSnapshot()
+  const snapshot = await takeSnapshot()
   console.log(describe(snapshot))
-  // 樣板是 artifact 用的片段；本機直接看要補上完整文件與 charset。
-  const head =
-    '<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">'
-  // `lang` 是預設語言；頁面上換語言時畫面那一支會改掉 `documentElement.lang`。
-  return `<!doctype html><html lang="en"><head>${head}</head><body>${await renderFragment(snapshot)}</body></html>`
+  return renderDocument(snapshot)
+}
+
+function pageShared(): Promise<string> {
+  inFlight ??= page().finally(() => {
+    inFlight = null
+  })
+  return inFlight
 }
 
 const server = Bun.serve({
@@ -57,7 +70,7 @@ const server = Bun.serve({
     const { pathname } = new URL(request.url)
     if (pathname !== '/') return new Response(null, { status: 404 })
     try {
-      return new Response(await page(), {
+      return new Response(await pageShared(), {
         headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' },
       })
     } catch (error) {
@@ -72,5 +85,6 @@ const server = Bun.serve({
 })
 
 const url = `http://localhost:${server.port}`
-console.log(`Dev map: ${url} (every refresh re-fetches from GitHub)`)
+console.log(`Dev map for ${process.cwd()}`)
+console.log(`  ${url} (every refresh re-fetches from GitHub)`)
 if (OPEN) openInBrowser(url)