@xiaoming_z/dsh-git 0.0.0-stage → 0.3.1

package/test/client.test.mjs

@@ -0,0 +1,1258 @@
+/**
+ * Client-half test.
+ *
+ * The bundle is loaded exactly the way the shell kernel loads it (a classic
+ * script registering a factory with `window.__ModuleLoader__`), then driven
+ * through a real mount → fetch → re-render cycle by a minimal hook-capable
+ * React stand-in. That cycle is where a panel that "flashes a box then goes
+ * blank" fails: the first paint succeeds and the post-load paint throws, so
+ * React unmounts the tree.
+ *
+ * Run: `node test/client.test.mjs`
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { splitHunks as hostSplitHunks } from '../index.js'
+
+const SRC = fileURLToPath(new URL('../client.js', import.meta.url))
+
+let failures = 0
+const check = (label, cond, extra = '') => {
+  console.log(`${cond ? 'PASS' : 'FAIL'}  ${label}${extra ? '  — ' + extra : ''}`)
+  if (!cond) failures += 1
+}
+
+// ---- load the bundle the way the kernel does --------------------------------
+let registration = null
+const window = {
+  __ModuleLoader__: {
+    load: (entry) => {
+      registration = entry
+    },
+  },
+  // Enough of a window for the panel's layout measurement to run in the test.
+  innerHeight: 943,
+  innerWidth: 1280,
+  addEventListener: () => {},
+  removeEventListener: () => {},
+  // `nearestScroller` identifies a scroller by its computed `overflow-y`; a
+  // fixture node opts in by carrying the flag this returns.
+  getComputedStyle: (node) => ({ overflowY: node?.scrolls === true ? 'auto' : 'visible' }),
+}
+
+/**
+ * A hook-capable React stand-in. Not React, but it exercises the contract the
+ * component relies on: stable hook order, state updates that schedule a
+ * re-render, and effects that run once after mount.
+ */
+let currentHooks = []
+let cursor = 0
+let effects = []
+let dirty = false
+
+const React = {
+  createElement(type, props, ...children) {
+    const element = { type, props: props ?? {}, children: children.flat(Infinity) }
+    // Render nested function components eagerly. Without this the harness only
+    // ever executes the top-level GitView and every child (FileRow, LaneGraph,
+    // DiffText) stays an inert object — which is exactly how a crash inside
+    // FileRow slipped past the first version of this test.
+    if (typeof type === 'function') {
+      const outerHooks = currentHooks
+      const outerCursor = cursor
+      // These children hold no state, so their hook slots need not persist
+      // between renders; isolating them keeps GitView's own slots aligned.
+      currentHooks = []
+      cursor = 0
+      try {
+        return type(element.props)
+      } finally {
+        currentHooks = outerHooks
+        cursor = outerCursor
+      }
+    }
+    return element
+  },
+  useState(initial) {
+    const index = cursor++
+    if (!(index in currentHooks)) currentHooks[index] = typeof initial === 'function' ? initial() : initial
+    const set = (next) => {
+      currentHooks[index] = typeof next === 'function' ? next(currentHooks[index]) : next
+      dirty = true
+    }
+    return [currentHooks[index], set]
+  },
+  useEffect(fn) {
+    const index = cursor++
+    if (!(index in currentHooks)) {
+      currentHooks[index] = true
+      effects.push(fn)
+    }
+  },
+  useLayoutEffect(fn) {
+    const index = cursor++
+    if (!(index in currentHooks)) {
+      currentHooks[index] = true
+      effects.push(fn)
+    }
+  },
+  useRef(initial) {
+    const index = cursor++
+    if (!(index in currentHooks)) currentHooks[index] = { current: initial }
+    return currentHooks[index]
+  },
+  useCallback: (fn) => {
+    cursor++
+    return fn
+  },
+  useMemo: (fn) => {
+    cursor++
+    return fn()
+  },
+}
+
+const code = readFileSync(SRC, 'utf8')
+// A syntax error in the bundle would surface here, exactly as it would in the browser.
+new Function('window', code)(window)
+
+check('bundle registers one module factory', registration !== null && typeof registration.factory === 'function')
+check('bundle id matches the package name', registration?.id === '@xiaoming_z/dsh-git', registration?.id)
+
+const requireStub = (spec) => {
+  if (spec === 'react') return React
+  throw new Error(`unexpected external request: ${spec}`)
+}
+const exports = registration.factory(requireStub)
+check('exports apply/inject', typeof exports.apply === 'function' && Array.isArray(exports.inject))
+check(
+  'inject names the services the body uses',
+  JSON.stringify(exports.inject) === JSON.stringify(['slots', 'locale', 'sessions']),
+  JSON.stringify(exports.inject),
+)
+
+// ---- translation seats ------------------------------------------------------
+const { DICTS } = exports
+/**
+ * Build a translate function from a dictionary, mirroring `{name}` substitution.
+ * @param locale - `zh` or `en`.
+ * @returns the translate function the slot would inject.
+ */
+const makeT = (locale) => (key, params) => {
+  const template = DICTS[locale][key] ?? key
+  if (params === undefined) return template
+  return template.replace(/\{(\w+)\}/g, (match, name) => (name in params ? String(params[name]) : match))
+}
+const tZh = makeT('zh')
+const tEn = makeT('en')
+
+check(
+  'both built-in locales define exactly the same keys',
+  JSON.stringify(Object.keys(DICTS.zh).sort()) === JSON.stringify(Object.keys(DICTS.en).sort()),
+  `zh ${Object.keys(DICTS.zh).length} / en ${Object.keys(DICTS.en).length}`,
+)
+check(
+  'no English entry is left as its own key',
+  Object.entries(DICTS.en).every(([key, value]) => value !== key),
+)
+check(
+  'every zh and en value is a string',
+  Object.values(DICTS.zh).every((v) => typeof v === 'string') &&
+    Object.values(DICTS.en).every((v) => typeof v === 'string'),
+)
+
+// ---- apply() wiring ---------------------------------------------------------
+const effectsSeen = []
+const sources = []
+const injectedDeps = []
+const registered = []
+const injected = []
+const ctx = {
+  effect: (fn, label) => {
+    effectsSeen.push(label)
+    return fn()
+  },
+  locale: {
+    register: (ns, dict) => {
+      registered.push(['locale', ns, dict])
+      return () => {}
+    },
+    // `apply` binds once; the fake hands back the zh seat.
+    bind: () => tZh,
+  },
+  slots: {
+    inject: (name, fn) => {
+      injected.push(name)
+      fn()
+    },
+    register: (descriptor, Component) => {
+      registered.push(['slot', descriptor, Component])
+      return () => {}
+    },
+  },
+  // Models the real timing: the service is NOT resolvable through `get` when
+  // the plugin applies, and `inject` is how a plugin waits for it. The earlier
+  // fake handed `get` the service directly, which is why it never caught the
+  // plugin dying on `undefined.registerSource`.
+  get: () => undefined,
+  inject: (deps, callback) => {
+    injectedDeps.push(deps)
+    callback({ ...ctx, inputTriggers: { registerSource: (src) => { sources.push(src); return () => {} } } })
+  },
+  sessions: {
+    list: {
+      getSnapshot: () => ({
+        ids: ['s1'],
+        byId: { s1: { id: 's1', cwd: '/repo/from-session' } },
+      }),
+    },
+  },
+}
+// Guarded: a throw here used to abort the whole file, losing every other
+// assertion's result. It is exactly the failure an eager service read causes.
+let applyError = null
+try {
+  exports.apply(ctx)
+} catch (error) {
+  applyError = error
+}
+check('apply finishes without throwing', applyError === null, applyError?.message ?? '')
+check('registers a locale namespace', registered.some(([kind, ns]) => kind === 'locale' && ns === 'git'))
+check('declares the conversation.view contribution', injected.includes('conversation.view'), injected.join(','))
+check('waits for the trigger service instead of reading it eagerly', JSON.stringify(injectedDeps).includes('inputTriggers'), JSON.stringify(injectedDeps))
+check('registers an @ source for git references', sources.length === 1 && sources[0].trigger === '@' && sources[0].name === 'git', JSON.stringify(sources.map((s) => `${s.trigger}${s.name}`)))
+
+// The regression: an optional service being absent must not take the whole
+// plugin down. Reading it eagerly threw and the panel never loaded at all.
+const sourcesBefore = sources.length
+let survivedWithoutService = true
+try {
+  exports.apply({
+    effect: (fn) => fn(),
+    locale: { register: () => () => {}, bind: () => tZh },
+    slots: { inject: () => {}, register: () => () => {} },
+    sessions: { list: { getSnapshot: () => ({ byId: {} }) } },
+    get: () => undefined,
+    // The service never arrives in this deployment.
+    inject: () => {},
+  })
+} catch (error) {
+  survivedWithoutService = false
+}
+check('a deployment without the trigger service still mounts the panel', survivedWithoutService)
+check('and registers no source in that case', sources.length === sourcesBefore)
+const slot = registered.find(([kind, descriptor]) => kind === 'slot' && descriptor?.name === 'conversation.view')
+check(
+  'slot descriptor is a conversation.view contribution with an id + label',
+  slot?.[1]?.name === 'conversation.view' && slot?.[1]?.id === 'git' && typeof slot?.[1]?.label === 'function',
+  JSON.stringify({ ...slot?.[1], label: slot?.[1]?.label?.() }),
+)
+check('slot contribution passes a component', typeof slot?.[2] === 'function')
+
+// ---- session ↔ repository binding -------------------------------------------
+const { sessionCwd } = exports
+check(
+  'the contribution resolves the active session working directory',
+  typeof slot?.[1]?.inject === 'function' &&
+    slot[1].inject('s1')?.sessionRoot === '/repo/from-session',
+  JSON.stringify(slot?.[1]?.inject?.('s1')),
+)
+check(
+  'an unknown session resolves to no root rather than throwing',
+  sessionCwd(ctx, 'nope') === null && sessionCwd(ctx, '') === null && sessionCwd(ctx, undefined) === null,
+)
+check('a shell without the sessions service degrades to null', sessionCwd({}, 's1') === null)
+check(
+  'a malformed summary degrades to null',
+  sessionCwd({ sessions: { list: { getSnapshot: () => ({ byId: { s1: { cwd: 42 } } }) } } }, 's1') === null,
+)
+check(
+  'a throwing sessions service degrades to null',
+  sessionCwd({ sessions: { list: { getSnapshot: () => { throw new Error('nope') } } } }, 's1') === null,
+)
+
+// ---- lane assignment --------------------------------------------------------
+const c = (hash, ...parents) => ({ hash, parents })
+let rows = exports.computeLanes([c('c', 'b'), c('b', 'a'), c('a')])
+check('linear history stays in one lane', rows.every((row) => row.lane === 0), rows.map((row) => row.lane).join(','))
+
+rows = exports.computeLanes([c('m', 'a', 'b'), c('b', 'base'), c('a', 'base'), c('base')])
+check(
+  'a merge parent claims its own lane',
+  rows[0].lane === 0 && rows[1].lane === 1,
+  rows.map((row) => `${row.commit.hash}@${row.lane}`).join(' '),
+)
+check('the merge row records both active lanes', rows[0].lanesAfter.length >= 1, JSON.stringify(rows[0].lanesAfter))
+
+rows = exports.computeLanes([c('x'), c('y')])
+check('disjoint roots occupy separate lanes', rows[0].lane === 0 && rows[1].lane === 0)
+
+rows = exports.computeLanes([c('a'), c('b')])
+check('lane state is drained at the tail', rows[rows.length - 1].lanesAfter.length === 0)
+
+/** Widest gutter any row needs. */
+const widthOf = (list) =>
+  Math.max(...list.map((row) => Math.max(row.lanesBefore.length, row.lanesAfter.length, row.lane + 1)))
+
+// Regression: the graph used to widen monotonically. A lane freed in the
+// MIDDLE of the table was never reclaimed (only trailing empties were trimmed),
+// so the next branch appended a new column instead of filling the hole.
+rows = exports.computeLanes([c('m', 'x', 'r'), c('x'), c('y', 'r'), c('r')])
+check('a freed interior lane is reused instead of widening the graph', widthOf(rows) === 2, `width=${widthOf(rows)}`)
+
+// Regression: a parent outside the loaded window held its lane open forever.
+rows = exports.computeLanes([{ hash: 'only', parents: ['outside-the-window'] }])
+check('a parent outside the window releases its lane', rows[0].lanesAfter.length === 0, JSON.stringify(rows[0].lanesAfter))
+
+// Regression: several lanes awaiting one merge target only converged for the
+// first, so the rest stayed open.
+rows = exports.computeLanes([c('t', 'a', 'b'), c('b', 't'), c('a', 't'), c('t')])
+check(
+  'every lane converging on one commit collapses',
+  rows[1].lanesAfter.filter((lane) => lane === 't').length <= 1,
+  JSON.stringify(rows[1].lanesAfter),
+)
+
+// A merge-heavy history must not grow a column per commit — the failure a real
+// repository showed, where the gutter squeezed the subject text to nothing.
+const busy = []
+for (let i = 0; i < 120; i += 1) {
+  busy.push({ hash: `c${i}`, parents: i % 3 === 0 && i > 0 ? [`s${i}`, `c${i + 1}`] : [`c${i + 1}`] })
+  if (i % 3 === 0 && i > 0) busy.push({ hash: `s${i}`, parents: [`c${i + 1}`] })
+}
+rows = exports.computeLanes(busy)
+check('a 160-commit merge-heavy history stays narrow', widthOf(rows) <= 3, `width=${widthOf(rows)} over ${rows.length} rows`)
+check(
+  'the gutter does not grow monotonically with depth',
+  widthOf(rows.slice(0, 20)) >= widthOf(rows.slice(-20)),
+  `first20=${widthOf(rows.slice(0, 20))} last20=${widthOf(rows.slice(-20))}`,
+)
+
+// ---- mount → fetch → re-render ----------------------------------------------
+/** Realistic host payloads for the endpoints the panel calls. */
+const HOST = {
+  '/status': {
+    ok: true,
+    data: {
+      root: '/repo',
+      branch: { head: 'main', oid: 'abc', upstream: null, ahead: 2, behind: 1, detached: false, initial: false },
+      staged: [{ path: 'a.txt', index: 'M', worktree: '.', origPath: null }],
+      unstaged: [{ path: 'b.txt', index: '.', worktree: 'M', origPath: null }],
+      untracked: [{ path: 'c.txt', index: '?', worktree: '?', origPath: null }],
+      conflicted: [{ path: 'd.txt', index: 'U', worktree: 'U', origPath: null }],
+    },
+  },
+  '/log': {
+    ok: true,
+    data: {
+      root: '/repo',
+      commits: [
+        {
+          hash: 'a'.repeat(40),
+          parents: ['b'.repeat(40)],
+          author: 'T',
+          email: 't@e.com',
+          at: 1_700_000_000_000,
+          subject: 'merge things',
+        },
+        { hash: 'b'.repeat(40), parents: [], author: 'T', email: 't@e.com', at: 1_699_000_000_000, subject: 'root' },
+      ],
+    },
+  },
+  '/diff': { ok: true, data: { root: '/repo', file: 'a.txt', staged: false, text: '@@ -1 +1 @@\n-old\n+new\n' } },
+  '/branches': {
+    ok: true,
+    data: {
+      root: '/repo',
+      head: 'main',
+      local: [
+        { name: 'main', current: true, upstream: 'origin/main', oid: 'abc1234' },
+        { name: 'feature', current: false, upstream: null, oid: 'def5678' },
+      ],
+      remote: [{ name: 'origin/main', remote: 'origin', branch: 'main', oid: 'abc1234' }],
+    },
+  },
+  '/commit': {
+    ok: true,
+    data: {
+      root: '/repo',
+      commit: { hash: 'a'.repeat(40), author: 'T', at: 1_700_000_000_000, subject: 'merge things' },
+      files: [{ status: 'M', score: null, path: 'a.txt', origPath: null }],
+    },
+  },
+  '/show': { ok: true, data: { root: '/repo', text: 'diff --git a/a.txt b/a.txt\n+a\n' } },
+}
+
+/**
+ * Mount the panel, run its effect, let the fetches settle, and re-render until
+ * quiet — the full cycle a real mount performs.
+ * @param seed - hook slots to pre-set (e.g. the `mode` hook) before mounting.
+ * @param props - the props the component is rendered with.
+ * @param component - the component to render; the panel by default.
+ * @returns the final tree, any crash, and the endpoints requested.
+ */
+async function mount(
+  seed = {},
+  props = { sessionRoot: '/repo/from-session', t: tZh },
+  component = exports.GitView,
+) {
+  const fetched = []
+  globalThis.fetch = async (url) => {
+    const path = String(url).replace('/git-api', '').split('?')[0]
+    fetched.push(path)
+    const payload = HOST[path] ?? { ok: false, error: `mock has no ${path}` }
+    return { status: payload.ok ? 200 : 400, json: async () => payload }
+  }
+
+  currentHooks = []
+  for (const [index, value] of Object.entries(seed)) currentHooks[Number(index)] = value
+  cursor = 0
+  effects = []
+  dirty = false
+
+  let tree = null
+  let crash = null
+  try {
+    tree = component(props)
+  } catch (error) {
+    crash = error
+  }
+
+  for (const fn of effects) {
+    try {
+      fn()
+    } catch (error) {
+      crash = crash ?? error
+    }
+  }
+
+  for (let i = 0; i < 40; i += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    if (!dirty) {
+      if (i > 4) break
+      continue
+    }
+    dirty = false
+    cursor = 0
+    effects = []
+    try {
+      tree = component(props)
+    } catch (error) {
+      crash = error
+      break
+    }
+  }
+
+  return { tree, crash, fetched }
+}
+
+// The worktree pane is the default view; the commit list lives in the history
+// pane, so each mode gets its own mount.
+const worktree = await mount({ 2: 'worktree' })
+check('first paint and post-load render do not throw', worktree.crash === null, worktree.crash?.stack ?? '')
+check(
+  'the panel requested host data',
+  worktree.fetched.includes('/status') && worktree.fetched.includes('/log'),
+  worktree.fetched.join(','),
+)
+
+const worktreeFlat = JSON.stringify(worktree.tree ?? {})
+check('worktree pane shows the branch name', worktreeFlat.includes('main'))
+check('worktree pane shows the changed file', worktreeFlat.includes('a.txt'))
+check('no literal undefined leaked into a file row', !worktreeFlat.includes('undefined'))
+check('both view tabs are present', worktreeFlat.includes('工作区') && worktreeFlat.includes('历史'))
+check('the commit box is present', worktreeFlat.includes('提交 '))
+check(
+  'an empty path box advertises the session workspace it is following',
+  worktreeFlat.includes('跟随会话工作区'),
+  '',
+)
+// The action button is the one place a child component reads its own prop, so
+// it is where a prop-name slip shows up.
+check(
+  'worktree pane renders the stage action for a changed file',
+  worktreeFlat.includes('暂存') && worktreeFlat.includes('git add'),
+)
+
+// Hook order is rootInput, appliedRoot, mode — seeding slot 2 opens the panel
+// straight into the history pane.
+const history = await mount({ 2: 'history' })
+check('history pane renders without throwing', history.crash === null, history.crash?.stack ?? '')
+const historyFlat = JSON.stringify(history.tree ?? {})
+check('history pane shows commit subjects', historyFlat.includes('merge things') && historyFlat.includes('root'))
+check('history pane asks for nothing until a commit is picked', history.fetched.includes('/status'))
+check('no literal undefined leaked into the history pane', !historyFlat.includes('undefined'))
+// Three columns: branches | commits | changes.
+check('history pane fetched the branch list', history.fetched.includes('/branches'))
+check(
+  'branch column lists local and remote branches',
+  historyFlat.includes('本地') && historyFlat.includes('远程') && historyFlat.includes('origin') && historyFlat.includes('feature'),
+  '',
+)
+check(
+  'the details column prompts until a commit is picked',
+  historyFlat.includes('选择中间一栏的提交查看改动'),
+)
+
+// The hunk split exists on both sides, and the indices the browser sends must
+// line up with the ones the host derives from the same text.
+const SAMPLE_DIFF = [
+  'diff --git a/a.txt b/a.txt',
+  'index 111..222 100644',
+  '--- a/a.txt',
+  '+++ b/a.txt',
+  '@@ -1,3 +1,3 @@',
+  ' keep',
+  '-old one',
+  '+new one',
+  '@@ -20,3 +20,3 @@',
+  ' keep two',
+  '-old two',
+  '+new two',
+  '',
+].join('\n')
+const clientSplit = exports.splitHunks(SAMPLE_DIFF)
+const hostSplit = hostSplitHunks(SAMPLE_DIFF)
+check('client and host agree on the hunk split', JSON.stringify(clientSplit) === JSON.stringify(hostSplit), `${clientSplit.hunks.length} vs ${hostSplit.hunks.length}`)
+check('the split separates the file header from the hunks', clientSplit.header.length === 4 && clientSplit.hunks.length === 2, `header=${clientSplit.header.length} hunks=${clientSplit.hunks.length}`)
+
+// Rendering a diff seeds the `file` and `fileDiff` state slots (indices 7 and 8)
+// so the worktree pane paints hunks instead of the empty prompt.
+const withDiff = await mount({
+  2: 'worktree',
+  7: { path: 'a.txt', staged: false, untracked: false },
+  8: SAMPLE_DIFF,
+})
+check('a rendered diff does not throw', withDiff.crash === null, withDiff.crash?.stack ?? '')
+const diffFlat = JSON.stringify(withDiff.tree ?? {})
+check('each hunk gets its own action bar', diffFlat.includes('改动块 1/2') && diffFlat.includes('改动块 2/2'))
+check('an unstaged hunk offers to stage itself', diffFlat.includes('暂存此块'))
+// An untracked file has no index entry to patch, so it must not offer hunks.
+const untrackedDiff = await mount({
+  2: 'worktree',
+  7: { path: 'new.txt', staged: false, untracked: true },
+  8: SAMPLE_DIFF,
+})
+check(
+  'an untracked file offers no hunk action',
+  !JSON.stringify(untrackedDiff.tree ?? {}).includes('暂存此块'),
+)
+
+// ---- resizable columns ------------------------------------------------------
+const { clampWidth, readWidths, COLUMN_LIMITS } = exports
+const fakeStorage = (value) => ({ getItem: () => value, setItem: () => {} })
+const [BRANCH_MIN, BRANCH_MAX] = COLUMN_LIMITS.branches
+
+check(
+  'clampWidth holds a width inside its column bounds',
+  clampWidth('branches', 10) === BRANCH_MIN && clampWidth('branches', 9999) === BRANCH_MAX,
+  `${clampWidth('branches', 10)}..${clampWidth('branches', 9999)}`,
+)
+check(
+  'clampWidth rejects a non-numeric width',
+  clampWidth('branches', 'wide') === null && clampWidth('branches', Number.NaN) === null,
+)
+check(
+  'readWidths keeps a valid stored width',
+  readWidths(fakeStorage(JSON.stringify({ branches: 260, commits: 500, files: 300 }))).branches === 260,
+)
+check('readWidths falls back to the default when nothing is stored', readWidths(fakeStorage(null)).branches === 190)
+check('readWidths survives malformed JSON', readWidths(fakeStorage('{not json')).branches === 190)
+check(
+  'readWidths clamps a stored value instead of trusting it',
+  readWidths(fakeStorage(JSON.stringify({ branches: 99999 }))).branches === BRANCH_MAX,
+)
+check(
+  'readWidths ignores an unknown column and keeps the rest',
+  readWidths(fakeStorage(JSON.stringify({ branches: 300, bogus: 10 }))).commits === 380,
+)
+check(
+  'readWidths tolerates a storage that throws',
+  readWidths({ getItem: () => { throw new Error('denied') } }).files === 380,
+)
+check('readWidths tolerates no storage at all', readWidths(null).files === 380)
+
+const { nextWidth } = exports
+check('a rightward drag widens the column by the pointer travel', nextWidth('branches', 200, 500, 560) === 260)
+check('a leftward drag narrows it by the same amount', nextWidth('branches', 200, 500, 440) === 140)
+check('a drag past the minimum stops at it', nextWidth('branches', 200, 500, 100) === BRANCH_MIN)
+check('a drag past the maximum stops at it', nextWidth('branches', 300, 500, 900) === BRANCH_MAX)
+
+const countSplitters = (mounted) => (JSON.stringify(mounted.tree ?? {}).match(/col-resize/g) ?? []).length
+check('the worktree view renders one column splitter', countSplitters(worktree) === 1, `${countSplitters(worktree)}`)
+check('the history view renders two column splitters', countSplitters(history) === 2, `${countSplitters(history)}`)
+
+// ---- layering against the shell's session-column resize strip ----------------
+// The shell puts an invisible 40px `cursor: col-resize` strip at z-index 8 over
+// this view, so the panel has to paint above it; and because the composer
+// floats at z-index 7, the panel may only take the pointer where it actually
+// has content. Both halves of that contract are easy to break silently.
+const rootStyle = worktree.tree?.props?.style ?? {}
+const innerPanel = worktree.tree?.children?.[0] ?? {}
+const panelStyle = innerPanel.props?.style ?? {}
+
+check('the panel paints above the shell resize strip', Number(rootStyle.zIndex) > 8, `zIndex=${rootStyle.zIndex}`)
+check('the shell box is positioned so its z-index applies', rootStyle.position === 'relative')
+check('the shell box is not hit-testable itself', rootStyle.pointerEvents === 'none')
+check(
+  'the panel does not inset itself for the composer (this view occludes it on purpose)',
+  rootStyle.paddingBottom === undefined,
+  String(rootStyle.paddingBottom),
+)
+check('the shell box paints no background', rootStyle.background === undefined)
+check(
+  'the fallback height leaves the panel room to reach the window bottom',
+  /calc\(100vh - (\d+)px\)/.test(String(rootStyle.height)) &&
+    Number(/calc\(100vh - (\d+)px\)/.exec(String(rootStyle.height))[1]) <= 110,
+  String(rootStyle.height),
+)
+check('the inner panel is the hit-testable one', panelStyle.pointerEvents === 'auto')
+check('the inner panel carries the background', typeof panelStyle.background === 'string')
+check('the inner panel fills the shell box', panelStyle.flex === '1 1 auto' && panelStyle.minHeight === 0)
+
+// ---- filling the view so the composer stays occluded ------------------------
+// A `max-height` alone left a short worktree panel content-sized, which let the
+// composer reappear below it. The panel measures from its own top edge to the
+// window bottom instead. Hook slot 20 is the ref (`fillHeight` is 19).
+const measured = await mount({ 20: { current: { getBoundingClientRect: () => ({ top: 82 }) } } })
+check('the measurement does not throw', measured.crash === null, measured.crash?.stack ?? '')
+check(
+  'the panel is given an explicit height measured from its own top edge',
+  measured.tree?.props?.style?.height === '861px',
+  `height=${measured.tree?.props?.style?.height} (window 943 - top 82)`,
+)
+check(
+  'the viewport estimate remains the fallback when there is nothing to measure',
+  String(worktree.tree?.props?.style?.height).includes('100vh'),
+  String(worktree.tree?.props?.style?.height),
+)
+check(
+  'a definite shell height still wins over the measurement',
+  worktree.tree?.props?.style?.maxHeight === '100%',
+  String(worktree.tree?.props?.style?.maxHeight),
+)
+
+// ---- English rendering ------------------------------------------------------
+const englishMount = await mount({ 2: 'history' }, { sessionRoot: '/repo/from-session', t: tEn })
+check('the history pane renders in English without throwing', englishMount.crash === null, englishMount.crash?.stack ?? '')
+const englishFlat = JSON.stringify(englishMount.tree ?? {})
+check(
+  'the English render uses the git vocabulary rather than transliterations',
+  englishFlat.includes('History') && englishFlat.includes('Branches') && englishFlat.includes('Checkout'),
+  '',
+)
+check(
+  'the English render contains no Chinese at all',
+  !/[\u4e00-\u9fff]/.test(englishFlat),
+  (englishFlat.match(/[\u4e00-\u9fff]+/g) ?? []).slice(0, 5).join(' '),
+)
+const englishWorktree = await mount({ 2: 'worktree' }, { sessionRoot: '/repo/from-session', t: tEn })
+const englishWorktreeFlat = JSON.stringify(englishWorktree.tree ?? {})
+check(
+  'the worktree pane is translated too',
+  englishWorktreeFlat.includes('Changes') &&
+    englishWorktreeFlat.includes('Stage') &&
+    englishWorktreeFlat.includes('Refresh'),
+  '',
+)
+check(
+  'the worktree English render contains no Chinese at all',
+  !/[\u4e00-\u9fff]/.test(englishWorktreeFlat),
+  (englishWorktreeFlat.match(/[\u4e00-\u9fff]+/g) ?? []).slice(0, 5).join(' '),
+)
+check(
+  'the Chinese render still carries Chinese copy',
+  /[\u4e00-\u9fff]/.test(JSON.stringify(worktree.tree ?? {})),
+)
+
+// ---- git references for the model -------------------------------------------
+const { encodeFileRef, encodeCommitRef, decodeRef, refText, gitCandidates } = exports
+
+const fileRef = encodeFileRef({ path: 'src/a b.ts', status: 'M', added: 12, deleted: 3, binary: false }, 'worktree')
+check(
+  'a file reference round-trips',
+  JSON.stringify(decodeRef(fileRef)) ===
+    JSON.stringify({ kind: 'file', mode: 'worktree', status: 'M', added: 12, deleted: 3, binary: false, path: 'src/a b.ts' }),
+  fileRef,
+)
+// The path is the last field, so colons in it must not confuse the decoder.
+const colonRef = encodeFileRef({ path: 'weird:name.txt', status: 'A', added: 1, deleted: 0, binary: false }, 'staged')
+check(
+  'a path containing a colon survives the round trip',
+  decodeRef(colonRef).path === 'weird:name.txt' && decodeRef(colonRef).mode === 'staged',
+  decodeRef(colonRef).path,
+)
+check(
+  'a path with non-ASCII characters survives',
+  decodeRef(encodeFileRef({ path: '中文 文件.txt', status: '?', added: null, deleted: null, binary: false }, 'untracked')).path ===
+    '中文 文件.txt',
+)
+
+// Metadata only: no diff body, but the command that produces one.
+const fileText = refText(fileRef)
+check(
+  'the model gets the change metadata, not the diff',
+  fileText.includes('path="src/a b.ts"') && fileText.includes('added="12"') && fileText.includes('deleted="3"'),
+  fileText,
+)
+check('the model is told how to see it', fileText.includes('git diff -- src/a b.ts'), fileText)
+check('a staged reference names its own command', refText(colonRef).includes('git diff --cached -- weird:name.txt'))
+check(
+  'an untracked reference names the --no-index command',
+  refText(encodeFileRef({ path: 'new.txt', added: null, deleted: null, binary: false }, 'untracked')).includes('--no-index'),
+)
+check(
+  'a binary reference says so instead of inventing line counts',
+  refText(encodeFileRef({ path: 'logo.png', added: null, deleted: null, binary: true }, 'worktree')).includes('binary="true"'),
+)
+
+const commitRef = encodeCommitRef({ hash: 'a'.repeat(40), subject: 'fix: "quoted" thing', files: 3 })
+const commitText = refText(commitRef)
+check(
+  'a commit reference carries its subject and file count',
+  commitText.includes('subject="fix: \'quoted\' thing"') && commitText.includes('files="3"'),
+  commitText,
+)
+check('a commit reference names its command', commitText.includes('git show aaaaaaa'))
+// The worktree view feeds porcelain entries, which carry index/worktree rather
+// than a single status; reading only `status` produced a reference with no
+// metadata at all.
+check(
+  'a porcelain entry reports the side that actually changed',
+  refText(encodeFileRef({ path: 'a.md', index: 'A', worktree: '.' }, 'worktree')).includes('status="A"') &&
+    refText(encodeFileRef({ path: 'b.md', index: '.', worktree: 'M' }, 'worktree')).includes('status="M"') &&
+    refText(encodeFileRef({ path: 'c.md', index: '?', worktree: '?' }, 'worktree')).includes('status="?"'),
+)
+check(
+  'a malformed reference is passed through rather than throwing',
+  refText('dsh-git:file:bogus') === 'dsh-git:file:bogus' && refText('not-ours') === 'not-ours',
+)
+check('an unknown prefix decodes to null', decodeRef('other:thing') === null && decodeRef(null) === null)
+
+// Candidates: the session's repository, narrowed by the query.
+const candidateCtx = {
+  sessions: { list: { getSnapshot: () => ({ byId: { s1: { cwd: '/repo' } } }) } },
+}
+HOST['/status'] = {
+  ok: true,
+  data: {
+    root: '/repo',
+    branch: { head: 'main' },
+    staged: [{ path: 'staged.ts', index: 'M', worktree: '.', origPath: null }],
+    unstaged: [{ path: 'loose.ts', index: '.', worktree: 'M', origPath: null }],
+    untracked: [],
+    conflicted: [],
+  },
+}
+const all = await gitCandidates(candidateCtx, { sessionId: 's1' }, { query: '' }, tEn)
+// Two changed files from /status plus the two commits the /log mock returns.
+check('candidates cover changed files and recent commits', all.length === 4, all.map((c) => c.name).join(' | '))
+check(
+  'files are grouped ahead of commits',
+  all[0].section === 'Changed files' && all[all.length - 1].section === 'Recent commits',
+  all.map((c) => c.section).join(','),
+)
+check(
+  'a file candidate carries a usable reference',
+  decodeRef(all.find((c) => c.name === 'staged.ts')?.value).mode === 'staged',
+)
+check('a commit candidate carries a commit reference', decodeRef(all.find((c) => c.name.startsWith('a')).value).kind === 'commit')
+const filtered = await gitCandidates(candidateCtx, { sessionId: 's1' }, { query: 'loose' }, tEn)
+check('the query narrows the candidates', filtered.length === 1 && filtered[0].name === 'loose.ts', filtered.map((c) => c.name).join(','))
+check(
+  'an unresolvable session yields no candidates',
+  (await gitCandidates(candidateCtx, { sessionId: 'nope' }, { query: '' }, tEn)).length === 0,
+)
+
+// ---- colours come from theme tokens -----------------------------------------
+// A palette picked to read on a dark background is close to invisible on a light
+// one. Every colour the panel renders must therefore be a theme token, which the
+// shell switches with the theme — never a literal that only suits one of them.
+const HEX_COLOUR = /#[0-9a-fA-F]{3}(?:[0-9a-fA-F]{3})?\b/
+const hardcodedColours = (mounted) =>
+  (JSON.stringify(mounted.tree ?? {}).match(/#[0-9a-fA-F]{3,8}\b/g) ?? []).join(' ')
+
+check('the worktree pane hardcodes no colours', !HEX_COLOUR.test(JSON.stringify(worktree.tree ?? {})), hardcodedColours(worktree))
+check('the history pane hardcodes no colours', !HEX_COLOUR.test(JSON.stringify(history.tree ?? {})), hardcodedColours(history))
+check('a rendered diff hardcodes no colours', !HEX_COLOUR.test(JSON.stringify(withDiff.tree ?? {})), hardcodedColours(withDiff))
+check(
+  'diff lines are coloured by the theme success/error tokens',
+  JSON.stringify(withDiff.tree ?? {}).includes('--dsw-alias-state-success-primary') &&
+    JSON.stringify(withDiff.tree ?? {}).includes('--dsw-alias-state-error-primary'),
+)
+
+// ---- review view -------------------------------------------------------------
+const REVIEW_SAMPLE = {
+  root: '/repo',
+  marker: 'a'.repeat(40),
+  head: 'abc1234',
+  commits: [{ hash: 'a'.repeat(40), parents: [], author: 'T', email: 't@e.com', at: Date.now() - 60_000, subject: 'agent work' }],
+  files: [
+    { path: 'small.js', origPath: null, added: 2, deleted: 1, binary: false, status: 'M' },
+    { path: 'big.js', origPath: null, added: 300, deleted: 4, binary: false, status: 'M' },
+    { path: 'logo.png', origPath: null, added: null, deleted: null, binary: true, status: 'M' },
+    { path: 'gone.txt', origPath: null, added: 0, deleted: 40, binary: false, status: 'D' },
+    { path: 'clash.txt', origPath: null, added: 3, deleted: 3, binary: false, status: 'U' },
+  ],
+  totals: { files: 5, added: 305, deleted: 48, binary: 1 },
+}
+
+const { rankReviewFiles, readMarkers, MARKER_KEY } = exports
+check(
+  'ranking puts conflicts, deletions, binaries and large changes first',
+  rankReviewFiles(REVIEW_SAMPLE.files)
+    .map((entry) => entry.file.path)
+    .join(',') === 'clash.txt,gone.txt,logo.png,big.js,small.js',
+  rankReviewFiles(REVIEW_SAMPLE.files).map((entry) => entry.file.path).join(','),
+)
+check(
+  'within a tier the bigger change comes first',
+  rankReviewFiles([
+    { path: 'a.js', added: 1, deleted: 0, binary: false, status: 'M' },
+    { path: 'b.js', added: 50, deleted: 0, binary: false, status: 'M' },
+  ])[0].file.path === 'b.js',
+)
+check(
+  'a file with no risk marker carries no reason',
+  rankReviewFiles([{ path: 'plain.js', added: 1, deleted: 1, binary: false, status: 'M' }])[0].reason === null,
+)
+
+const markerStorage = (value) => ({ getItem: () => value, setItem: () => {} })
+check(
+  'markers round-trip',
+  readMarkers(markerStorage(JSON.stringify({ '/repo': { hash: 'abc', at: 123 } })))['/repo'].hash === 'abc',
+)
+check('markers survive malformed JSON', Object.keys(readMarkers(markerStorage('{oops'))).length === 0)
+check(
+  'a marker without a hash is dropped',
+  Object.keys(readMarkers(markerStorage(JSON.stringify({ '/repo': { at: 1 }, '/ok': { hash: 'h' } })))).join(',') === '/ok',
+)
+check('markers tolerate no storage', Object.keys(readMarkers(null)).length === 0)
+
+// Rendering: seed the marker (slot 24) and a status payload (slot 5) so the
+// review effect's condition holds on the first render — the shim runs effects
+// once, so a null status there would blank the pane before the fetch could
+// happen. `/review` is served from the mock, so this exercises the real path:
+// marker -> effect -> request -> render.
+HOST['/review'] = { ok: true, data: REVIEW_SAMPLE }
+const reviewMount = await mount({
+  5: {
+    root: '/repo',
+    branch: { head: 'main', oid: 'a'.repeat(40) },
+    staged: [],
+    unstaged: [],
+    untracked: [],
+    conflicted: [],
+  },
+  24: { '/repo': { hash: 'a'.repeat(40), at: Date.now() - 3_600_000 } },
+})
+check('the review pane renders without throwing', reviewMount.crash === null, reviewMount.crash?.stack ?? '')
+check('the pane asked the host for the review', reviewMount.fetched.includes('/review'), reviewMount.fetched.join(','))
+const reviewFlat = JSON.stringify(reviewMount.tree ?? {})
+check(
+  'the review pane leads with the net effect',
+  reviewFlat.includes('5 个文件') && reviewFlat.includes('+305') && reviewFlat.includes('−48'),
+  '',
+)
+check(
+  'every ranked file is listed',
+  ['clash.txt', 'gone.txt', 'logo.png', 'big.js', 'small.js'].every((path) => reviewFlat.includes(path)),
+)
+check(
+  'the ranking is explained rather than implied',
+  reviewFlat.includes('冲突') && reviewFlat.includes('删除') && reviewFlat.includes('二进制') && reviewFlat.includes('大改动'),
+)
+check(
+  'the list is rendered in ranked order',
+  (() => {
+    const order = ['clash.txt', 'gone.txt', 'logo.png', 'big.js', 'small.js'].map((path) => reviewFlat.indexOf(path))
+    return order.every((at, index) => at > 0 && (index === 0 || at > order[index - 1]))
+  })(),
+)
+
+// No marker yet: the pane asks for one instead of showing an empty list.
+const noMarker = await mount({})
+const noMarkerFlat = JSON.stringify(noMarker.tree ?? {})
+check('the review tab is the default view', noMarkerFlat.includes('审查') && noMarkerFlat.includes('还没有审查点'))
+check('the empty review pane offers to set a marker', noMarkerFlat.includes('标记为已审查'))
+
+// ---- branch actions ---------------------------------------------------------
+/** Depth-first search for the first element whose children include `text`. */
+function findByText(node, text) {
+  if (node === null || typeof node !== 'object') return undefined
+  if (Array.isArray(node.children) && node.children.includes(text)) return node
+  for (const child of node.children ?? []) {
+    const hit = findByText(child, text)
+    if (hit !== undefined) return hit
+  }
+  return undefined
+}
+
+check('the branch column offers a new-branch action', findByText(history.tree, '新建') !== undefined)
+check('the branch column offers a pull button', findByText(history.tree, '拉取') !== undefined)
+check('the branch column offers a push button', findByText(history.tree, '推送') !== undefined)
+
+// ---- the composer's branch chip ---------------------------------------------
+// The chip says which branch the session's workspace is on. It is display only,
+// and a directory that is not a repository has no chip at all.
+const { BranchChip } = exports
+
+const chipSlot = registered.find(
+  ([kind, descriptor]) => kind === 'slot' && descriptor?.name === 'conversation.input.left',
+)
+check('the chip is registered in the composer accessory row', chipSlot !== undefined)
+check('the chip is registered under its own id', chipSlot?.[1]?.id === 'git-branch', String(chipSlot?.[1]?.id))
+check(
+  'the chip follows the session workspace',
+  chipSlot?.[1]?.inject?.('s1')?.root === '/repo/from-session',
+  JSON.stringify(chipSlot?.[1]?.inject?.('s1')),
+)
+check(
+  'a session with no workspace gives the chip nothing to report',
+  chipSlot?.[1]?.inject?.('nope')?.root === '',
+  JSON.stringify(chipSlot?.[1]?.inject?.('nope')),
+)
+
+const chipMount = await mount({}, { root: '/repo/from-session' }, BranchChip)
+check('the chip renders without throwing', chipMount.crash === null, chipMount.crash?.stack ?? '')
+const chipFlat = JSON.stringify(chipMount.tree ?? {})
+check('the chip shows the current branch', chipFlat.includes('main'), chipFlat)
+check('the chip names the branch it shows', chipMount.tree?.props?.['data-dsh-git-branch'] === 'main')
+check('the chip carries a branch icon', chipFlat.includes('svg'), '')
+check('the chip is not a button', chipMount.tree?.type === 'span', String(chipMount.tree?.type))
+check(
+  'the chip asks the host for the branch, not for the whole status',
+  chipMount.fetched.includes('/branches') && !chipMount.fetched.includes('/status'),
+  chipMount.fetched.join(','),
+)
+
+// A directory that is not a repository: the host refuses, and the chip is
+// silent. A composer is not the place to complain about a repository.
+const savedBranches = HOST['/branches']
+HOST['/branches'] = { ok: false, error: 'not a git repository' }
+const noRepoChip = await mount({}, { root: '/tmp/not-a-repo' }, BranchChip)
+check('a directory that is not a repository shows no chip', noRepoChip.tree === null, JSON.stringify(noRepoChip.tree))
+check('a failed read does not crash the chip', noRepoChip.crash === null, noRepoChip.crash?.stack ?? '')
+
+// No workspace at all: nothing to report.
+const noRootChip = await mount({}, { root: '' }, BranchChip)
+check('no workspace shows no chip', noRootChip.tree === null, JSON.stringify(noRootChip.tree))
+HOST['/branches'] = savedBranches
+
+// All three strategies must be reachable, not just the two the first cut
+// exposed: the host enumerated three and the client has to offer three.
+const strategySelect = (() => {
+  const walk = (node) => {
+    if (node === null || typeof node !== 'object') return undefined
+    if (node.type === 'select') return node
+    for (const child of node.children ?? []) {
+      const hit = walk(child)
+      if (hit !== undefined) return hit
+    }
+    return undefined
+  }
+  return walk(history.tree)
+})()
+const optionValues = (strategySelect?.children ?? []).map((option) => option?.props?.value)
+check(
+  'the pull strategy selector lists every strategy the host accepts',
+  JSON.stringify(optionValues) === JSON.stringify(['ff-only', 'merge', 'rebase']),
+  JSON.stringify(optionValues),
+)
+check('the pull strategy defaults to the safe one', strategySelect?.props?.value === 'ff-only', strategySelect?.props?.value)
+check(
+  'the selected strategy is explained rather than just named',
+  typeof strategySelect?.props?.title === 'string' && strategySelect.props.title.includes('不改历史'),
+  strategySelect?.props?.title,
+)
+check('the current branch is marked instead of offering a checkout', historyFlat.includes('当前'))
+check(
+  'other local and remote branches offer a checkout',
+  (historyFlat.match(/检出/g) ?? []).length >= 2,
+  `${(historyFlat.match(/检出/g) ?? []).length} occurrences`,
+)
+
+// Clicking "新建" must reveal the inline name input. This is the one interaction
+// the harness can drive end to end: call the handler, re-render, look again.
+//
+// The click has to happen against the hook state of the mount that produced the
+// tree, so this re-mounts rather than reusing `history` — an intervening mount
+// would have replaced the state slots the button's handler writes into.
+const branchMount = await mount({ 2: 'history' })
+const newBranchButton = findByText(branchMount.tree, '新建')
+check('the new-branch button carries a handler', typeof newBranchButton?.props?.onClick === 'function')
+newBranchButton.props.onClick()
+// The shim reads hooks positionally, so cursor must be reset for a manual render.
+cursor = 0
+effects = []
+const opened = exports.GitView({ sessionRoot: '/repo/from-session', t: tZh })
+check('clicking it opens the inline name input', JSON.stringify(opened).includes('新分支名'))
+check('the input names the start point it will branch from', JSON.stringify(opened).includes('基于 HEAD'))
+
+// ---- sizing to the scroll container, not to the window ----------------------
+// The composer seat is an in-flow sibling, so a window-sized panel made the
+// scroller exactly one composer taller than its scrollport — scrollable, which
+// is how the composer could be scrolled back into view.
+const { fillHeightFor } = exports
+// A physically consistent fixture: a real scroller's `scrollHeight` tracks the
+// panel's height, because the panel is part of the flow. Fixing `scrollHeight`
+// at a constant would test arithmetic on an impossible container.
+const FLOW_BESIDES_PANEL = 160 // headers above + the composer seat below
+const scrollerNode = { clientHeight: 860, parentElement: null, panelHeight: 0, scrolls: true }
+Object.defineProperty(scrollerNode, 'scrollHeight', {
+  get: () => scrollerNode.panelHeight + FLOW_BESIDES_PANEL,
+})
+const panelOf = (height) => {
+  scrollerNode.panelHeight = height
+  return { getBoundingClientRect: () => ({ top: 82, height }), parentElement: scrollerNode }
+}
+
+check(
+  'the panel is sized to leave no slack in the scroll container',
+  fillHeightFor(panelOf(860), 861) === 700,
+  `scrollport 860 - ${FLOW_BESIDES_PANEL} of other flow = ${fillHeightFor(panelOf(860), 861)}`,
+)
+// The target must not depend on the height the panel happened to have when it
+// was measured — that is what makes a single pass exact and a re-measure safe.
+check(
+  'an oversized panel converges on the same target',
+  fillHeightFor(panelOf(1013), 861) === 700,
+  String(fillHeightFor(panelOf(1013), 861)),
+)
+check(
+  'an undersized panel grows to the same target',
+  fillHeightFor(panelOf(300), 861) === 700,
+  String(fillHeightFor(panelOf(300), 861)),
+)
+
+// No scroller (a definite-height shell, or a bare test frame): the window
+// estimate is the only thing available.
+const noScroller = { getBoundingClientRect: () => ({ top: 82, height: 400 }), parentElement: null }
+check('without a scroller the window estimate is used', fillHeightFor(noScroller, 861) === 861)
+
+check(
+  'a collapsed measurement is rejected instead of collapsing the panel',
+  fillHeightFor({ getBoundingClientRect: () => ({ top: 0, height: 0 }), parentElement: null }, 12) === null,
+)
+
+// A malformed payload must produce a visible message, not a blank panel: the
+// throw has to happen before render, or React unmounts the tree with no trace.
+const savedStatus = HOST['/status']
+HOST['/status'] = { ok: true, data: { root: '/repo', branch: { head: 'main' } } }
+const malformed = await mount()
+check('a status payload missing its arrays does not crash the render', malformed.crash === null, malformed.crash?.stack ?? '')
+const malformedFlat = JSON.stringify(malformed.tree ?? {})
+check(
+  'the missing field is reported to the user instead of blanking the panel',
+  malformedFlat.includes('缺少字段') && malformedFlat.includes('conflicted'),
+  malformedFlat.slice(0, 160),
+)
+HOST['/status'] = savedStatus
+
+// ---- the hover bubble --------------------------------------------------------
+// A name that does not fit is cut to an ellipsis, and the reader has no way to
+// see the rest of it. The bubble is the answer, and it has three rules worth
+// asserting: it appears only for a label that is actually cut off, it lands
+// where the reader can see it, and it is styled from the shell's own tooltip
+// tokens rather than from a palette of this plugin's own.
+
+const { bubblePosition, isTruncated, BUBBLE_STYLE, BUBBLE_DELAY_MS } = exports
+
+// Placement: below the label when there is room, above it when there is not,
+// and never past the edge of the window.
+const anchorBox = { left: 100, top: 200, width: 120, height: 18, bottom: 218, right: 220 }
+const bubbleSize = { width: 200, height: 40 }
+const screen = { width: 1280, height: 943 }
+
+const below = bubblePosition(anchorBox, bubbleSize, screen)
+check('the bubble sits below the label when there is room', below.top === 226, JSON.stringify(below))
+check(
+  'a bubble wider than the label lines up with its start edge',
+  below.left === 100,
+  JSON.stringify(below),
+)
+check(
+  'a bubble narrower than the label is centred on it',
+  bubblePosition(anchorBox, { width: 80, height: 40 }, screen).left === 120,
+  JSON.stringify(bubblePosition(anchorBox, { width: 80, height: 40 }, screen)),
+)
+
+const above = bubblePosition({ left: 100, top: 900, width: 120, height: 18, bottom: 918 }, bubbleSize, screen)
+check('the bubble flips above the label when the bottom is full', above.top === 852, JSON.stringify(above))
+
+const leftEdge = bubblePosition({ left: 0, top: 200, width: 20, height: 18, bottom: 218 }, bubbleSize, screen)
+check('the bubble never runs off the left edge', leftEdge.left === 8, JSON.stringify(leftEdge))
+
+const rightEdge = bubblePosition({ left: 1200, top: 200, width: 70, height: 18, bottom: 218 }, bubbleSize, screen)
+check('the bubble never runs off the right edge', rightEdge.left === 1072, JSON.stringify(rightEdge))
+
+// The gate: a bubble that repeats text the reader can already see is noise.
+check('a label that fits is not truncated', isTruncated({ scrollWidth: 100, clientWidth: 100 }) === false)
+check('a label that overflows is truncated', isTruncated({ scrollWidth: 140, clientWidth: 100 }) === true)
+check('an element that was never measured is not truncated', isTruncated(null) === false)
+check(
+  'the bubble is styled from the shell tooltip tokens, not from literals',
+  BUBBLE_STYLE.background === 'var(--dsw-alias-tooltip-bg)' &&
+    BUBBLE_STYLE.color === 'var(--dsw-static-neutral-bluish-00)' &&
+    BUBBLE_STYLE.borderRadius === 'var(--dsw-radius-sm)' &&
+    BUBBLE_STYLE.pointerEvents === 'none',
+  JSON.stringify(BUBBLE_STYLE),
+)
+check(
+  'the bubble hardcodes no colour',
+  !HEX_COLOUR.test(JSON.stringify(BUBBLE_STYLE)),
+  (JSON.stringify(BUBBLE_STYLE).match(/#[0-9a-fA-F]{3,8}\b/g) ?? []).join(' '),
+)
+
+// The bubble lives in the document body, so the panel's `overflow: hidden`
+// columns cannot clip it. This is the fake document it lives in.
+const fakeDocument = {
+  body: {
+    children: [],
+    appendChild(element) {
+      this.children.push(element)
+      return element
+    },
+  },
+  createElement(tag) {
+    return {
+      tagName: tag,
+      nodeType: 1,
+      style: {},
+      textContent: '',
+      children: [],
+      offsetWidth: 200,
+      offsetHeight: 40,
+      setAttribute(name, value) {
+        this.attributes = { ...(this.attributes ?? {}), [name]: value }
+      },
+      // The bubble is filled with text nodes and `<wbr>` break hints, the way
+      // a path should break at its slashes. A text node adds to the text; a
+      // `<wbr>` does not, which is the whole point of it.
+      appendChild(child) {
+        this.children.push(child)
+        if (child.nodeType === 3) this.textContent += child.data
+        return child
+      },
+      getBoundingClientRect: () => anchorBox,
+    }
+  },
+  createTextNode(data) {
+    return { nodeType: 3, data }
+  },
+}
+globalThis.document = fakeDocument
+
+/** A label that is (or is not) cut off. */
+const fakeLabel = (scrollWidth, clientWidth) => ({
+  scrollWidth,
+  clientWidth,
+  getBoundingClientRect: () => anchorBox,
+})
+
+/** Wait for the bubble's delay to elapse. */
+const settle = () => new Promise((resolve) => setTimeout(resolve, BUBBLE_DELAY_MS + 60))
+
+// A label that fits must not produce a bubble at all.
+exports.reveal('src/deep/nested/file.ts').onPointerEnter({
+  currentTarget: fakeLabel(120, 120),
+})
+await settle()
+check('a label that fits produces no bubble', fakeDocument.body.children.length === 0)
+
+// A label that is cut off must produce one, carrying the whole name.
+exports.reveal('src/deep/nested/file.ts').onPointerEnter({
+  currentTarget: fakeLabel(400, 120),
+})
+await settle()
+const bubble = fakeDocument.body.children[0]
+check('a cut-off label produces a bubble', bubble !== undefined)
+check('the bubble is on screen', bubble?.style?.display === 'block', String(bubble?.style?.display))
+check('the bubble carries the full name', bubble?.textContent === 'src/deep/nested/file.ts', String(bubble?.textContent))
+check('the bubble is placed next to the label', bubble?.style?.left === '100px' && bubble?.style?.top === '226px', `${bubble?.style?.left} / ${bubble?.style?.top}`)
+
+// Leaving the label takes it away again.
+exports.reveal('src/deep/nested/file.ts').onPointerLeave()
+check('the bubble goes away when the pointer leaves', bubble?.style?.display === 'none', String(bubble?.style?.display))
+
+// The rows themselves must carry the reveal handlers, and must not keep the
+// native tooltip: both answer the same hover, and the native one paints over
+// the bubble a second later.
+
+/** Every node in a rendered tree, depth first. */
+function walk(node, visit) {
+  if (node === null || typeof node !== 'object') return
+  visit(node)
+  for (const child of node.children ?? []) walk(child, visit)
+}
+
+/** The node that renders `text` and reacts to the pointer. */
+function labelledNode(tree, text) {
+  let hit
+  walk(tree, (node) => {
+    if (hit !== undefined) return
+    if (!Array.isArray(node.children) || !node.children.includes(text)) return
+    if (typeof node.props?.onPointerEnter !== 'function') return
+    hit = node
+  })
+  return hit
+}
+
+/** The row that holds a node. */
+function rowOf(tree, node) {
+  let hit
+  walk(tree, (candidate) => {
+    if (hit !== undefined) return
+    if ((candidate.children ?? []).includes(node)) hit = candidate
+  })
+  return hit
+}
+
+// A file with a directory: the row shows the name and the directory as two
+// pieces, and the bubble shows the whole path.
+const savedStatusForBubble = HOST['/status']
+HOST['/status'] = {
+  ok: true,
+  data: {
+    root: '/repo',
+    branch: { head: 'main', oid: 'abc' },
+    staged: [],
+    unstaged: [{ path: 'src/deep/nested/file.ts', index: '.', worktree: 'M', origPath: null }],
+    untracked: [],
+    conflicted: [],
+  },
+}
+const bubbleMount = await mount({ 2: 'worktree' })
+const fileNameNode = labelledNode(bubbleMount.tree, 'file.ts')
+check('a file name reveals its full path on hover', fileNameNode !== undefined)
+check(
+  'the file row no longer leans on a native tooltip',
+  rowOf(bubbleMount.tree, fileNameNode)?.props?.title === undefined,
+  String(rowOf(bubbleMount.tree, fileNameNode)?.props?.title),
+)
+check(
+  'the file name can dismiss the bubble again',
+  typeof fileNameNode?.props?.onPointerLeave === 'function',
+)
+
+// The branch tree: a long branch name is the case the panel is worst at.
+const branchBubbleMount = await mount({ 2: 'history' })
+const branchNode = labelledNode(branchBubbleMount.tree, 'feature')
+check('a branch name reveals itself on hover', branchNode !== undefined)
+check(
+  'the branch row no longer leans on a native tooltip',
+  rowOf(branchBubbleMount.tree, branchNode)?.props?.title === undefined,
+  String(rowOf(branchBubbleMount.tree, branchNode)?.props?.title),
+)
+
+// The commit subject is the other name the panel cuts short — and it never had
+// a tooltip at all, so this is the case the bubble actually adds.
+const subjectNode = labelledNode(branchBubbleMount.tree, 'merge things')
+check('a commit subject reveals itself on hover', subjectNode !== undefined)
+const hashNode = labelledNode(branchBubbleMount.tree, 'aaaaaaa')
+check('a commit hash reveals the whole hash and its author', hashNode !== undefined)
+
+HOST['/status'] = savedStatusForBubble
+delete globalThis.document
+
+console.log(failures === 0 ? '\nALL PASS' : `\n${failures} FAILURE(S)`)
+process.exit(failures === 0 ? 0 : 1)