@ihyeon/flow-qa 0.2.9 → 0.3.0

package/README.ko.md

@@ -16,7 +16,7 @@ CLI와 `127.0.0.1` 전용 웹 UI를 제공합니다. UI는 영어로 시작하
 Node.js 24.x(24.22.1 이상) 또는 26.12.1 이상이 필요합니다. 브라우저는 첫 웹 실행 전에 설치합니다.
 
 ```sh
-npm install -g @ihyeon/flow-qa@0.2.9
+npm install -g @ihyeon/flow-qa@0.3.0
 flow-qa browser install
 flow-qa ui --demo
 ```
@@ -62,6 +62,10 @@ flow-qa plan flows/my-flow.md --workspace my-qa
 
 `flow-qa doctor --workspace my-qa`로 로컬 의존성과 모델 인증용 환경 변수의 설정 여부를 확인할 수 있습니다. 키 값은 출력하지 않고 모델 서버도 호출하지 않습니다. 환경 변수가 있어도 실제 인증 성공을 확인한 것은 아닙니다.
 
+## 실행 결과 비교
+
+**실행 기록 → 실행 2건 비교**에서 같은 스위트와 대상의 두 기록을 선택하면 통과→실패, 실패→통과, 그 외 상태 변경, 동일 상태, 추가·누락 케이스를 확인할 수 있습니다. 분류별로 보거나 전체 비교를 Markdown·JSON으로 내려받으세요. 테스트 내용 변경과 불완전한 실행은 별도로 표시하며, 상태 변화만으로 제품 버그의 발생·해결을 확정하지 않습니다. 자세한 동작은 [UI 가이드](docs/ui.md#compare-two-runs)를 참고하세요.
+
 ## 모바일 대상
 
 `0.2.0`부터 사용자가 직접 설정하는 iOS·Android 대상을 지원합니다. 시나리오 화면에서 **모바일**을 선택하면 앱을 정하기 전에도 케이스를 준비할 수 있습니다. 이후 **연결 설정**에서 플랫폼·설치된 앱의 번들/패키지 ID·기기를 등록하고 실행할 때 선택합니다. 설정 저장은 앱 설치나 테스트 실행을 시작하지 않습니다.

package/README.md

@@ -16,7 +16,7 @@ Flow QA is available as a CLI and a web UI bound to `127.0.0.1`. Provide a targe
 Node.js 24.x (24.22.1 or later) or 26.12.1 or later is required. Install Chromium before the first web run:
 
 ```sh
-npm install -g @ihyeon/flow-qa@0.2.9
+npm install -g @ihyeon/flow-qa@0.3.0
 flow-qa browser install
 flow-qa ui --demo
 ```
@@ -62,6 +62,10 @@ For authenticated models, add `--key-env FLOW_QA_API_KEY` to the model command a
 
 `flow-qa doctor --workspace my-qa` checks local dependencies and whether configured model-key environment variables are present. It does not print key values or call the model server; a present key does not confirm remote authentication.
 
+## Compare recorded runs
+
+In **Run history → Compare two runs**, select two reports from the same suite and target to see passed-to-failed, failed-to-passed, other status changes, unchanged, added, and missing cases. Filter the comparison or download all results as Markdown/JSON. Changed test definitions and incomplete runs carry explicit warnings; observed status changes do not prove a product defect was introduced or fixed. See the [UI guide](docs/ui.md#compare-two-runs).
+
 ## Mobile targets
 
 Version `0.2.0` adds user-configured iOS and Android targets. Choose **Mobile** in the scenario screen to prepare cases before choosing an app. Later, register the platform, installed app's bundle/package ID, and device in **Connections**, then select that target for execution. Saving settings does not install an app or start a test.

package/dist/src/i18n.js

@@ -62,6 +62,12 @@ const koreanMessages = {
     'Invalid request origin.': '요청 출처가 올바르지 않습니다.',
     'A case file name is required.': '케이스 파일 이름이 필요합니다.',
     'A run ID is required.': '실행 ID가 필요합니다.',
+    'Both run IDs are required.': '비교할 두 실행 ID가 필요합니다.',
+    'A comparison needs two different runs.': '서로 다른 두 실행을 선택해야 합니다.',
+    'Both reports must belong to the same suite.': '두 리포트의 케이스 모음이 같아야 합니다.',
+    'Both reports must use the same target.': '두 리포트의 실행 대상이 같아야 합니다.',
+    'Both reports need a non-empty suite hash.': '두 리포트에 비어 있지 않은 케이스 모음 해시가 있어야 합니다.',
+    'Both reports need unique, non-empty case IDs.': '두 리포트의 케이스 ID는 비어 있지 않고 중복되지 않아야 합니다.',
     'Invalid evidence selection.': '증거 파일 선택이 올바르지 않습니다.',
     'The request is not allowed.': '허용되지 않은 요청입니다.',
     'Invalid request token.': '요청 토큰이 올바르지 않습니다.',

package/dist/src/run-comparison.js

@@ -0,0 +1,152 @@
+import { localized } from "./i18n.js";
+import { targetFingerprint, targetLabel } from "./targets.js";
+export const comparisonCategories = ['newly-failed', 'now-passed', 'changed', 'unchanged', 'added', 'missing'];
+export class ComparisonError extends Error {
+    status;
+    constructor(status, message) { super(message); this.status = status; }
+}
+function validateCaseIds(report) {
+    const cases = new Map();
+    for (const item of report.cases) {
+        if (!item.id.trim() || cases.has(item.id)) {
+            throw new ComparisonError(409, 'Both reports need unique, non-empty case IDs.');
+        }
+        cases.set(item.id, item);
+    }
+    return cases;
+}
+function runSummary(report) {
+    return {
+        runId: report.runId, suiteId: report.suiteId, suiteHash: report.suiteHash,
+        target: { ...report.target }, startedAt: report.startedAt,
+        finishedAt: report.finishedAt, status: report.status,
+    };
+}
+function caseSnapshot(item) {
+    if (!item)
+        return null;
+    return {
+        title: item.title, status: item.status, expected: [...item.expected],
+        ...(item.reason === undefined ? {} : { reason: item.reason }),
+    };
+}
+function category(baseline, current) {
+    if (!baseline)
+        return 'added';
+    if (!current)
+        return 'missing';
+    if (baseline.status === current.status)
+        return 'unchanged';
+    if (baseline.status === 'passed' && current.status === 'failed')
+        return 'newly-failed';
+    if (baseline.status === 'failed' && current.status === 'passed')
+        return 'now-passed';
+    return 'changed';
+}
+/** Compare only recorded final case statuses and report metadata. Never inspect attempts or artifacts. */
+export function compareReports(baseline, current) {
+    if (baseline.runId === current.runId)
+        throw new ComparisonError(400, 'A comparison needs two different runs.');
+    if (baseline.suiteId !== current.suiteId)
+        throw new ComparisonError(409, 'Both reports must belong to the same suite.');
+    if (targetFingerprint(baseline.target) !== targetFingerprint(current.target)) {
+        throw new ComparisonError(409, 'Both reports must use the same target.');
+    }
+    if (!baseline.suiteHash.trim() || !current.suiteHash.trim()) {
+        throw new ComparisonError(409, 'Both reports need a non-empty suite hash.');
+    }
+    const before = validateCaseIds(baseline);
+    const after = validateCaseIds(current);
+    const warnings = [];
+    if (baseline.suiteHash !== current.suiteHash)
+        warnings.push('suite-changed');
+    if (Date.parse(current.startedAt) < Date.parse(baseline.startedAt))
+        warnings.push('reverse-order');
+    if (baseline.status === 'interrupted' || baseline.status === 'error' || current.status === 'interrupted' || current.status === 'error') {
+        warnings.push('incomplete-run');
+    }
+    if (baseline.target.kind === 'mobile')
+        warnings.push('mobile-identity-unverified');
+    const counts = Object.fromEntries(comparisonCategories.map((value) => [value, 0]));
+    const cases = [...new Set([...before.keys(), ...after.keys()])].sort().map((id) => {
+        const baselineCase = before.get(id);
+        const currentCase = after.get(id);
+        const transition = category(baselineCase, currentCase);
+        counts[transition]++;
+        return { id, category: transition, baseline: caseSnapshot(baselineCase), current: caseSnapshot(currentCase) };
+    });
+    return { schemaVersion: 'flow-qa/comparison-1', baseline: runSummary(baseline), current: runSummary(current), warnings, counts, cases };
+}
+function safeInline(value, locale) {
+    return value.replace(/(?:https?:\/\/|file:\/\/)[^\s<>"'\])}]+/gi, localized(locale, '[URL hidden]', '[URL 숨김]'))
+        .replace(/\[[^\]]*\]\([^)]*\)/g, localized(locale, '[link hidden]', '[링크 숨김]'))
+        .replace(/[\x00-\x1f\x7f\u0085\u2028\u2029]/g, (character) => {
+        if (character === '\n')
+            return '\\n';
+        if (character === '\r')
+            return '\\r';
+        if (character === '\t')
+            return '\\t';
+        return `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`;
+    }).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+        .replace(/([\\`*_{}\[\]()#+.!|~:])/g, '\\$1');
+}
+export function renderComparisonMarkdown(comparison, locale = 'en') {
+    const label = (english, korean) => localized(locale, english, korean);
+    const safe = (value) => safeInline(value, locale);
+    const run = (name, item) => [
+        `## ${name}`,
+        '',
+        `- ${label('Run ID', '실행 ID')}: ${safe(item.runId)}`,
+        `- ${label('Suite ID', '케이스 모음 ID')}: ${safe(item.suiteId)}`,
+        `- ${label('Suite hash', '케이스 모음 해시')}: ${safe(item.suiteHash)}`,
+        `- ${label('Target', '대상')}: ${safe(item.target.name)} ${item.target.kind === 'mobile'
+            ? safe(targetLabel(item.target))
+            : label('(URL available in the local JSON comparison)', '(주소는 로컬 JSON 비교 결과에서 확인)')}`,
+        `- ${label('Started', '시작')}: ${safe(item.startedAt)}`,
+        `- ${label('Finished', '종료')}: ${safe(item.finishedAt)}`,
+        `- ${label('Status', '상태')}: ${safe(item.status)}`,
+        '',
+    ];
+    const warningText = {
+        'suite-changed': label('Steps or expectations may differ because the suite changed; these outcomes do not prove a regression or fix.', '케이스 모음이 변경되어 단계나 기대 결과가 다를 수 있습니다. 이 결과만으로 회귀나 수정이 입증되지는 않습니다.'),
+        'reverse-order': label('The selected current run started before the baseline run.', '선택한 현재 실행이 기준 실행보다 먼저 시작됐습니다.'),
+        'incomplete-run': label('At least one run ended with error or interruption; case results may be incomplete.', '하나 이상의 실행이 오류 또는 중단으로 끝나 케이스 결과가 불완전할 수 있습니다.'),
+        'mobile-identity-unverified': label('The recorded app and device settings match, but these reports do not verify that both runs used the same physical device.', '기록된 앱과 기기 설정은 같지만, 두 실행이 같은 실제 기기에서 진행됐는지는 이 리포트로 확인할 수 없습니다.'),
+    };
+    const lines = [
+        `# ${label('QA run comparison', 'QA 실행 비교')}`,
+        '',
+        ...run(label('Baseline', '기준 실행'), comparison.baseline),
+        ...run(label('Current', '현재 실행'), comparison.current),
+        `## ${label('Transition counts', '상태 전이 개수')}`,
+        '',
+        ...comparisonCategories.map((category) => `- ${category}: ${comparison.counts[category]}`),
+        '',
+        `## ${label('Warnings', '주의 사항')}`,
+        '',
+        ...(comparison.warnings.length
+            ? comparison.warnings.map((warning) => `- ${warning}: ${warningText[warning]}`)
+            : [`- ${label('None', '없음')}`]),
+        '',
+        label('These categories describe observed status transitions only. They do not establish the cause of a failure or prove that a defect was fixed.', '이 분류는 관찰된 상태 전이만 나타냅니다. 실패 원인이나 결함 수정 여부를 입증하지 않습니다.'),
+        '',
+        `## ${label('Cases', '케이스')}`,
+        '',
+    ];
+    for (const item of comparison.cases) {
+        lines.push(`### ${safe(item.id)} — ${item.category}`, '');
+        for (const [name, entry] of [[label('Baseline', '기준 실행'), item.baseline], [label('Current', '현재 실행'), item.current]]) {
+            if (!entry) {
+                lines.push(`- ${name}: ${label('Absent', '없음')}`);
+                continue;
+            }
+            lines.push(`- ${name}: ${safe(entry.status)} · ${safe(entry.title)}`);
+            lines.push(`  - ${label('Expected', '기대 결과')}: ${entry.expected.length ? entry.expected.map(safe).join('; ') : label('None', '없음')}`);
+            if (entry.reason !== undefined)
+                lines.push(`  - ${label('Reason', '실행 상태 근거')}: ${safe(entry.reason)}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/src/ui/public/app.js

@@ -4,7 +4,7 @@
   const i18n = window.FlowQAI18n;
   const t = i18n.t;
   const names = { scenario: 'nav.scenario', library: 'nav.library', history: 'nav.history', settings: 'nav.settings' };
-  const app = { state: null, connected: false, displayTargets: [], draft: null, script: '', savedFile: '', savedHash: '', origin: 'none', sourceFlow: '', boundSource: null, stale: false, dirty: false, busy: false, planning: false, planRequest: 0, stopping: false, report: null, reportMarkdown: '', selectedRun: '', view: 'scenario' };
+  const app = { state: null, connected: false, displayTargets: [], draft: null, script: '', savedFile: '', savedHash: '', origin: 'none', sourceFlow: '', boundSource: null, stale: false, dirty: false, busy: false, planning: false, planRequest: 0, stopping: false, report: null, reportMarkdown: '', selectedRun: '', comparison: null, comparisonRequest: 0, comparisonBusy: false, comparisonStatus: 'comparison.selectBoth', view: 'scenario' };
 
   function el(tag, className, value) {
     const node = document.createElement(tag);
@@ -53,7 +53,7 @@
     });
     $('breadcrumb').textContent = t('app.breadcrumb', { name: t(names[name]) });
     $('sidebar').classList.remove('nav-open'); $('nav-toggle').setAttribute('aria-expanded', 'false');
-    if (name === 'history') renderHistory();
+    if (name === 'history') { renderHistory(); renderComparisonOptions(); }
   }
   function suitePlatform() { return app.draft?.platform || 'web'; }
   function targetPlatform(target) { return target?.kind === 'mobile' ? 'mobile' : 'web'; }
@@ -239,6 +239,98 @@
       const button = el('button', 'button', t('app.viewReport')); button.type = 'button'; button.disabled = run.status === 'running' || run.status === 'stopping'; button.addEventListener('click', () => loadReport(run.runId)); row.append(copy, button); host.append(row);
     }
   }
+  const comparisonCategories = ['newly-failed', 'now-passed', 'changed', 'unchanged', 'added', 'missing'];
+  const comparisonCategoryKeys = { 'newly-failed': 'comparison.newlyFailed', 'now-passed': 'comparison.nowPassed', changed: 'comparison.changed', unchanged: 'comparison.unchanged', added: 'comparison.added', missing: 'comparison.missing' };
+  const comparisonWarningKeys = { 'suite-changed': 'comparison.warningSuite', 'reverse-order': 'comparison.warningReverse', 'incomplete-run': 'comparison.warningIncomplete', 'mobile-identity-unverified': 'comparison.warningMobileIdentity' };
+  function comparisonPair() { return { baseline: $('compare-baseline').value, current: $('compare-current').value }; }
+  function comparisonValid() { const { baseline, current } = comparisonPair(); return !!baseline && !!current && baseline !== current; }
+  function comparisonStatus(key, params = {}, error = false) {
+    app.comparisonStatus = key; app.comparisonStatusParams = params;
+    const node = $('comparison-status'); node.textContent = t(key, params); node.classList.toggle('report-errors', error);
+  }
+  function comparisonControls() {
+    const { baseline, current } = comparisonPair();
+    $('compare-btn').disabled = !comparisonValid() || app.comparisonBusy;
+    $('compare-swap').disabled = !baseline || !current || baseline === current;
+    const ready = !!app.comparison && comparisonValid() && app.comparison.baseline.runId === baseline && app.comparison.current.runId === current;
+    for (const id of ['comparison-md', 'comparison-json', 'compare-open-baseline', 'compare-open-current']) $(id).disabled = !ready;
+    $('comparison-results').hidden = !ready;
+  }
+  function clearComparison() {
+    app.comparisonRequest += 1; app.comparisonBusy = false; app.comparison = null; app.comparisonMarkdown = '';
+    $('comparison-summary').replaceChildren(); $('comparison-warnings').replaceChildren(); $('comparison-content').replaceChildren();
+    comparisonStatus('comparison.selectBoth'); comparisonControls();
+  }
+  function renderComparisonOptions() {
+    const runs = (app.state?.runs || []).slice(0, 50);
+    let missing = false;
+    for (const id of ['compare-baseline', 'compare-current']) {
+      const select = $(id); const selected = select.value;
+      select.replaceChildren(el('option', '', t('comparison.choose'))); select.firstChild.value = '';
+      for (const run of runs) {
+        const option = el('option', '', t('comparison.runLabel', { id: run.runId, shortId: run.runId.slice(-8), date: formatDate(run.startedAt), suite: run.suiteId, target: targetDisplay(run.target), status: i18n.status(run.status) }));
+        option.value = run.runId; select.append(option);
+      }
+      select.value = runs.some((run) => run.runId === selected) ? selected : '';
+      if (selected && !select.value) missing = true;
+    }
+    if (missing) clearComparison();
+    if (!runs.length && !app.comparison) comparisonStatus('comparison.noRuns');
+    comparisonControls();
+  }
+  async function compareRuns() {
+    if (!comparisonValid()) return;
+    const { baseline, current } = comparisonPair(); const locale = i18n.locale(); const request = ++app.comparisonRequest;
+    app.comparisonBusy = true; app.comparison = null; app.comparisonMarkdown = '';
+    comparisonStatus('comparison.loading'); comparisonControls();
+    try {
+      const result = await api(`/api/comparison?baseline=${encodeURIComponent(baseline)}&current=${encodeURIComponent(current)}`);
+      if (request !== app.comparisonRequest || locale !== i18n.locale() || baseline !== $('compare-baseline').value || current !== $('compare-current').value) return;
+      app.comparison = result.comparison; app.comparisonMarkdown = result.markdown;
+      comparisonStatus('comparison.ready'); renderComparison();
+    } catch (error) {
+      if (request === app.comparisonRequest && locale === i18n.locale() && baseline === $('compare-baseline').value && current === $('compare-current').value) comparisonStatus('comparison.error', { message: error instanceof Error ? error.message : String(error) }, true);
+    } finally { if (request === app.comparisonRequest) { app.comparisonBusy = false; comparisonControls(); } }
+  }
+  function renderComparison() {
+    const result = app.comparison; if (!result) { comparisonControls(); return; }
+    const warnings = $('comparison-warnings'); replace(warnings);
+    for (const code of result.warnings || []) warnings.append(el('p', 'comparison-warning', t(comparisonWarningKeys[code] || 'comparison.warningUnknown', { code })));
+    const summary = $('comparison-summary'); replace(summary);
+    const meta = el('p', 'comparison-meta', `${result.baseline.runId} · ${formatDate(result.baseline.startedAt)} → ${result.current.runId} · ${formatDate(result.current.startedAt)}`); summary.append(meta);
+    const counts = el('div', 'comparison-counts');
+    for (const category of comparisonCategories) {
+      const item = el('div', 'comparison-count');
+      item.append(el('strong', '', String(result.counts?.[category] ?? 0)), el('span', '', t(comparisonCategoryKeys[category]))); counts.append(item);
+    }
+    summary.append(counts);
+    const host = $('comparison-content'); replace(host);
+    const selected = $('comparison-filter').value;
+    const cases = (result.cases || []).filter((item) => !selected || item.category === selected);
+    if (!cases.length) host.append(el('p', 'empty', t('comparison.noCases')));
+    for (const item of cases) {
+      const section = el('section', 'case-report comparison-case'); section.dataset.category = item.category;
+      section.append(el('h3', '', `${item.id} · ${t(comparisonCategoryKeys[item.category] || 'comparison.changed')} · ${t('comparison.pair', { baseline: item.baseline ? i18n.status(item.baseline.status) : t('comparison.notPresent'), current: item.current ? i18n.status(item.current.status) : t('comparison.notPresent') })}`));
+      for (const [side, entry] of [['baseline', item.baseline], ['current', item.current]]) {
+        if (!entry) continue;
+        section.append(el('p', '', t(side === 'baseline' ? 'comparison.baselineCase' : 'comparison.currentCase', { title: entry.title, status: i18n.status(entry.status) })));
+        if (entry.expected?.length) { const list = el('ul', 'compact-list'); for (const value of entry.expected) list.append(el('li', '', String(value))); section.append(el('p', '', t('app.expected')), list); }
+        if (entry.reason) section.append(el('p', '', t('comparison.reason', { value: entry.reason })));
+      }
+      host.append(section);
+    }
+    comparisonControls();
+  }
+  async function downloadComparisonMarkdown() {
+    if (!app.comparison || !comparisonValid()) return;
+    const { baseline, current } = comparisonPair(); const locale = i18n.locale(); const request = app.comparisonRequest;
+    try {
+      const result = await api(`/api/comparison?baseline=${encodeURIComponent(baseline)}&current=${encodeURIComponent(current)}`);
+      if (request !== app.comparisonRequest || locale !== i18n.locale() || baseline !== $('compare-baseline').value || current !== $('compare-current').value || !app.comparison) return;
+      app.comparisonMarkdown = result.markdown;
+      download(`${baseline}-to-${current}.md`, result.markdown, 'text/markdown');
+    } catch (error) { if (request === app.comparisonRequest && locale === i18n.locale()) comparisonStatus('comparison.error', { message: error instanceof Error ? error.message : String(error) }, true); }
+  }
   function renderActive() {
     const active = app.state?.active;
     $('active-indicator').textContent = !app.connected ? t('app.disconnected') : active ? `${t(active.status === 'stopping' ? 'app.activeStopping' : active.kind === 'plan' ? 'app.activePlanning' : 'app.activeRunning')}${active.kind === 'run' ? ` · ${active.title}` : ''}` : t(app.planning ? 'app.requestingPlan' : 'top.waiting');
@@ -258,7 +350,7 @@
     const libraryChanged = JSON.stringify(app.state?.suites) !== JSON.stringify(state.suites);
     const historyChanged = JSON.stringify(app.state?.runs) !== JSON.stringify(state.runs);
     app.state = state; app.connected = true;
-    renderActive(); if (libraryChanged) renderLibrary(); if (historyChanged) renderHistory();
+    renderActive(); if (libraryChanged) renderLibrary(); if (historyChanged) { renderHistory(); renderComparisonOptions(); }
     if (full || initialize) { targetOptions(); modelForms(); }
     if (previousActive?.kind === 'run' && !state.active) { if (state.lastError) notice(state.lastError, true); else noticeKey('app.runEnded'); }
     if (state.lastError && state.lastError !== app.lastError) { app.lastError = state.lastError; notice(state.lastError, true); }
@@ -406,7 +498,8 @@
       if (input) { input.focus(); if (Number.isInteger(focus.start)) input.setSelectionRange(focus.start, focus.end); }
     }
     summarize(app.draft, true);
-    renderActive(); targetDescription(); renderLibrary(); renderHistory(); renderReport();
+    renderActive(); targetDescription(); renderLibrary(); renderHistory(); renderComparisonOptions(); renderComparison(); renderReport();
+    if (app.comparisonStatus) comparisonStatus(app.comparisonStatus, app.comparisonStatusParams || {}, app.comparisonStatus === 'comparison.error');
     app.reportMarkdown = '';
     if (app.notice) $('notice').textContent = t(app.notice.key, app.notice.params);
     else if (!$('notice').hidden) notice(''); // A server error has no stable code to translate; the next request uses the selected language.
@@ -417,6 +510,14 @@
     $('library-search').addEventListener('input', renderLibrary);
     $('history-search').addEventListener('input', renderHistory);
     $('history-status-filter').addEventListener('change', renderHistory);
+    for (const id of ['compare-baseline', 'compare-current']) $(id).addEventListener('change', clearComparison);
+    $('compare-btn').addEventListener('click', compareRuns);
+    $('compare-swap').addEventListener('click', () => { const pair = comparisonPair(); $('compare-baseline').value = pair.current; $('compare-current').value = pair.baseline; clearComparison(); });
+    $('comparison-filter').addEventListener('change', renderComparison);
+    $('comparison-md').addEventListener('click', downloadComparisonMarkdown);
+    $('comparison-json').addEventListener('click', () => { if (app.comparison && comparisonValid()) { const { baseline, current } = comparisonPair(); download(`${baseline}-to-${current}.json`, JSON.stringify(app.comparison, null, 2), 'application/json'); } });
+    $('compare-open-baseline').addEventListener('click', () => { if (app.comparison && comparisonValid()) loadReport(app.comparison.baseline.runId); });
+    $('compare-open-current').addEventListener('click', () => { if (app.comparison && comparisonValid()) loadReport(app.comparison.current.runId); });
     $('nav-toggle').addEventListener('click', () => { const open = $('sidebar').classList.toggle('nav-open'); $('nav-toggle').setAttribute('aria-expanded', String(open)); });
     $('library-shortcut').addEventListener('click', () => view('library'));
     $('new-draft-btn').addEventListener('click', () => {
@@ -447,7 +548,7 @@
     $('target-form').addEventListener('submit', saveTarget);
     $('target-kind').addEventListener('change', targetFields); targetFields();
     $('language-select').addEventListener('change', (event) => i18n.setLocale(event.currentTarget.value));
-    i18n.onChange(renderLanguage);
+    i18n.onChange(() => { app.comparisonRequest += 1; if (app.comparisonBusy || app.comparisonStatus === 'comparison.error') comparisonStatus(app.comparison ? 'comparison.ready' : 'comparison.selectBoth'); app.comparisonBusy = false; renderLanguage(); comparisonControls(); });
     let refreshing = false;
     const poll = async () => { if (document.hidden || refreshing) return; refreshing = true; try { await refresh(false); } catch { /* Connection state offers explicit retry; avoid repeated alerts. */ } finally { refreshing = false; } };
     document.addEventListener('visibilitychange', poll);

package/dist/src/ui/public/i18n.js

@@ -83,6 +83,45 @@
     'history.searchPlaceholder': ['Suite ID, run ID, or target name', '스위트 ID, 실행 ID 또는 대상 이름'],
     'history.statusFilter': ['Run status', '실행 상태'],
     'history.statusAll': ['All statuses', '전체 상태'],
+    'comparison.title': ['Compare two runs', '실행 2건 비교'],
+    'comparison.help': ['Choose a baseline and current run to compare case outcomes. Inspect detailed reports for evidence.', '기준 실행과 현재 실행을 선택해 케이스 결과를 비교하세요. 증거는 상세 보고서에서 확인하세요.'],
+    'comparison.baseline': ['Baseline run', '기준 실행'],
+    'comparison.current': ['Current run', '현재 실행'],
+    'comparison.choose': ['Choose a run', '실행 선택'],
+    'comparison.compare': ['Compare', '비교하기'],
+    'comparison.swap': ['Swap runs', '실행 순서 바꾸기'],
+    'comparison.filter': ['Show cases', '케이스 표시'],
+    'comparison.all': ['All categories', '전체 분류'],
+    'comparison.newlyFailed': ['Newly failed', '새로 실패'],
+    'comparison.nowPassed': ['Now passed', '이제 통과'],
+    'comparison.changed': ['Changed status', '상태 변경'],
+    'comparison.unchanged': ['Same status', '상태 동일'],
+    'comparison.added': ['Added to current', '현재에만 있음'],
+    'comparison.missing': ['Missing from current', '현재 기록에 없음'],
+    'comparison.downloadMarkdown': ['Download comparison Markdown', '비교 Markdown 다운로드'],
+    'comparison.downloadJson': ['Download comparison JSON', '비교 JSON 다운로드'],
+    'comparison.openBaseline': ['View baseline report', '기준 실행 보고서 보기'],
+    'comparison.openCurrent': ['View current report', '현재 실행 보고서 보기'],
+    'comparison.selectBoth': ['Select two different runs to compare.', '서로 다른 실행 2건을 선택하세요.'],
+    'comparison.noRuns': ['No recent runs available to compare.', '비교할 최근 실행이 없습니다.'],
+    'comparison.loading': ['Comparing selected runs…', '선택한 실행을 비교하고 있습니다…'],
+    'comparison.limit': ['Choose from the 50 most recent runs. Comparison counts describe observed statuses; they do not establish failure cause or prove a defect was fixed.', '최근 실행 50건에서 선택하세요. 비교 수치는 관찰된 상태만 나타내며 실패 원인이나 결함 수정 여부를 입증하지 않습니다.'],
+    'comparison.ready': ['Comparison ready. Categories describe observed case status changes.', '비교 결과가 준비됐습니다. 분류는 관찰된 케이스 상태 차이입니다.'],
+    'comparison.noCases': ['No cases in this category.', '이 분류에 해당하는 케이스가 없습니다.'],
+    'comparison.warningSuite': ['Suite content changed. Steps or expectations may differ, so these counts do not establish equivalent regressions or fixes.', '스위트 내용이 바뀌었습니다. 단계나 기대 결과가 다를 수 있으므로 이 수치만으로 같은 조건의 회귀나 수정이라고 판단할 수 없습니다.'],
+    'comparison.warningReverse': ['The selected current run started before the baseline run.', '선택한 현재 실행이 기준 실행보다 먼저 시작됐습니다.'],
+    'comparison.warningIncomplete': ['At least one run is incomplete. Interpret case outcomes with its detailed report.', '완료되지 않은 실행이 있습니다. 상세 보고서와 함께 결과를 해석하세요.'],
+    'comparison.warningMobileIdentity': ['Mobile comparison matches recorded app and device settings. It does not verify that both runs used the same physical device.', '모바일 비교는 기록된 앱과 기기 설정을 기준으로 합니다. 두 실행이 같은 실제 기기를 사용했는지는 확인하지 않습니다.'],
+    'comparison.warningUnknown': ['Comparison warning: {code}', '비교 주의: {code}'],
+    'comparison.pair': ['{baseline} → {current}', '{baseline} → {current}'],
+    'comparison.notPresent': ['not present', '없음'],
+    'comparison.baselineCase': ['Baseline: {title} · {status}', '기준: {title} · {status}'],
+    'comparison.currentCase': ['Current: {title} · {status}', '현재: {title} · {status}'],
+    'comparison.expected': ['Expected: {value}', '기대 결과: {value}'],
+    'comparison.reason': ['Reason: {value}', '사유: {value}'],
+    'comparison.count': ['{category}: {count}', '{category}: {count}'],
+    'comparison.error': ['Comparison failed: {message}', '비교 실패: {message}'],
+    'comparison.runLabel': ['{date} · {suite} · {shortId} · {target} · {status} · {id}', '{date} · {suite} · {shortId} · {target} · {status} · {id}'],
     'history.report': ['Detailed report', '상세 보고서'],
     'history.downloadMarkdown': ['Download Markdown', 'Markdown 다운로드'],
     'history.downloadJson': ['Download JSON', 'JSON 다운로드'],

package/dist/src/ui/public/index.html

@@ -93,7 +93,17 @@
         <section id="view-history" class="view" hidden>
           <div class="page-heading"><p class="eyebrow" data-i18n="history.eyebrow">03 / RUNS</p><h1 data-i18n="nav.history">Run history</h1><p data-i18n="history.intro">Only runs that actually started appear here. Once results are saved, you can view the detailed report.</p></div>
           <section class="list-section"><div class="section-head"><span class="section-number">01</span><div><h2 data-i18n="history.title">Runs</h2><p data-i18n="history.help">Check the completed report for the final status.</p></div></div><div class="section-body form-stack"><label for="history-search" data-i18n="history.searchLabel">Search runs</label><input id="history-search" type="search" aria-controls="history-list" placeholder="Suite ID, run ID, or target name" data-i18n-placeholder="history.searchPlaceholder"><label for="history-status-filter" data-i18n="history.statusFilter">Run status</label><select id="history-status-filter" aria-controls="history-list"><option value="" data-i18n="history.statusAll">All statuses</option><option value="passed" data-i18n="status.passed">passed</option><option value="failed" data-i18n="status.failed">failed</option><option value="blocked" data-i18n="status.blocked">blocked</option><option value="error" data-i18n="status.error">error</option><option value="interrupted" data-i18n="status.interrupted">interrupted</option></select><div id="history-list" class="list-body"></div></div></section>
-          <section id="report-panel" class="report-panel" hidden><div class="section-head"><span class="section-number">02</span><div><h2 data-i18n="history.report">Detailed report</h2><p id="report-heading"></p></div></div><div class="section-body"><div class="actions"><button type="button" id="report-md" class="button" data-i18n="history.downloadMarkdown">Download Markdown</button><button type="button" id="report-json" class="button quiet" data-i18n="history.downloadJson">Download JSON</button></div><p class="hint" data-i18n="history.evidenceHint">The report summarizes results. Open or download screenshots and recordings from each attempt. Evidence files are not included in report downloads.</p><div id="report-content"></div></div></section>
+          <section id="comparison-panel" class="comparison-panel" aria-labelledby="comparison-title">
+            <div class="section-head"><span class="section-number">02</span><div><h2 id="comparison-title" data-i18n="comparison.title">Compare two runs</h2><p data-i18n="comparison.help">Choose a baseline and current run to compare case outcomes. This does not replace either detailed report.</p></div></div>
+            <div class="section-body">
+              <p class="hint" data-i18n="comparison.limit">Choose from the 50 most recent runs. Comparison counts describe observed statuses; they do not establish failure cause or prove a defect was fixed.</p>
+              <div class="comparison-selects"><div><label for="compare-baseline" data-i18n="comparison.baseline">Baseline run</label><select id="compare-baseline" aria-controls="comparison-content"><option value="" data-i18n="comparison.choose">Choose a run</option></select></div><div><label for="compare-current" data-i18n="comparison.current">Current run</label><select id="compare-current" aria-controls="comparison-content"><option value="" data-i18n="comparison.choose">Choose a run</option></select></div></div>
+              <div class="actions comparison-actions"><button type="button" id="compare-btn" class="button primary" data-i18n="comparison.compare" disabled>Compare</button><button type="button" id="compare-swap" class="button quiet" data-i18n="comparison.swap" disabled>Swap runs</button></div>
+              <p id="comparison-status" class="hint" role="status" aria-live="polite"></p>
+              <div id="comparison-results" hidden><div id="comparison-warnings"></div><div id="comparison-summary"></div><div class="comparison-filter-row"><label for="comparison-filter" data-i18n="comparison.filter">Show cases</label><select id="comparison-filter" aria-controls="comparison-content"><option value="" data-i18n="comparison.all">All categories</option><option value="newly-failed" data-i18n="comparison.newlyFailed">Newly failed</option><option value="now-passed" data-i18n="comparison.nowPassed">Now passed</option><option value="changed" data-i18n="comparison.changed">Changed status</option><option value="unchanged" data-i18n="comparison.unchanged">Same status</option><option value="added" data-i18n="comparison.added">Added to current</option><option value="missing" data-i18n="comparison.missing">Missing from current</option></select></div><div class="actions comparison-actions"><button type="button" id="comparison-md" class="button" data-i18n="comparison.downloadMarkdown" disabled>Download comparison Markdown</button><button type="button" id="comparison-json" class="button quiet" data-i18n="comparison.downloadJson" disabled>Download comparison JSON</button><button type="button" id="compare-open-baseline" class="button quiet" data-i18n="comparison.openBaseline" disabled>View baseline report</button><button type="button" id="compare-open-current" class="button quiet" data-i18n="comparison.openCurrent" disabled>View current report</button></div><div id="comparison-content"></div></div>
+            </div>
+          </section>
+          <section id="report-panel" class="report-panel" hidden><div class="section-head"><span class="section-number">03</span><div><h2 data-i18n="history.report">Detailed report</h2><p id="report-heading"></p></div></div><div class="section-body"><div class="actions"><button type="button" id="report-md" class="button" data-i18n="history.downloadMarkdown">Download Markdown</button><button type="button" id="report-json" class="button quiet" data-i18n="history.downloadJson">Download JSON</button></div><p class="hint" data-i18n="history.evidenceHint">The report summarizes results. Open or download screenshots and recordings from each attempt. Evidence files are not included in report downloads.</p><div id="report-content"></div></div></section>
         </section>
         <section id="view-settings" class="view" hidden>
           <div class="page-heading"><p class="eyebrow" data-i18n="settings.eyebrow">04 / CONNECTIONS</p><h1 data-i18n="nav.settings">Connections</h1><p data-i18n="settings.intro">Configure run targets and models separately. Key values are read only from server environment variables.</p></div>

package/dist/src/ui/public/style.css

@@ -52,7 +52,7 @@ button:focus-visible, input:focus-visible, select:focus-visible, textarea:focus-
 .page-heading h1 em { color: var(--accent-text); font-style: normal; }
 .page-heading > p:last-child { max-width: 56ch; margin: 0; color: var(--muted); font-size: 15px; line-height: 1.7; }
 .workflow { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); column-gap: clamp(26px, 3vw, 46px); row-gap: calc(var(--space-factor) * 34px); }
-.work-section, .execution-section, .list-section, .report-panel, .settings-section { min-width: 0; border-top: 2px solid var(--ink); }
+.work-section, .execution-section, .list-section, .report-panel, .comparison-panel, .settings-section { min-width: 0; border-top: 2px solid var(--ink); }
 .section-head { display: flex; align-items: flex-start; gap: 13px; min-width: 0; padding: calc(var(--space-factor) * 19px) 0 calc(var(--space-factor) * 18px); border-bottom: 1px solid var(--line); }
 .section-head > div { min-width: 0; }
 .section-number { flex: none; min-width: 26px; padding-top: 4px; color: var(--accent-text); font-family: 'DM Sans', monospace; font-size: 11px; font-weight: 800; }
@@ -130,13 +130,31 @@ button:focus-visible, input:focus-visible, select:focus-visible, textarea:focus-
 .review-line input { width: 18px; height: 18px; flex: none; margin: 2px 0 0; accent-color: var(--accent-solid); }
 .run-bar { display: flex; align-items: end; justify-content: space-between; flex-wrap: wrap; gap: 12px; margin-top: auto; padding-top: 18px; }
 .run-bar > span { max-width: 37ch; color: var(--muted); font-size: 12px; line-height: 1.5; }
-.list-section, .report-panel { margin-top: calc(var(--space-factor) * 28px); }
+.list-section, .report-panel, .comparison-panel { margin-top: calc(var(--space-factor) * 28px); }
 .list-body { min-width: 0; }
 .list-row { display: flex; align-items: center; justify-content: space-between; gap: 20px; padding: calc(var(--space-factor) * 19px) 0; border-bottom: 1px solid var(--line); }
 .list-row > div { min-width: 0; }
 .list-row strong { display: block; font-size: 15px; overflow-wrap: anywhere; }
 .list-row small { display: block; margin-top: 6px; color: var(--muted); font-size: 12px; line-height: 1.55; overflow-wrap: anywhere; }
 .empty { max-width: 50ch; margin: 0; padding: 32px 0; color: var(--muted); line-height: 1.7; }
+
+.comparison-selects { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 18px; }
+.comparison-selects > div { min-width: 0; }
+.comparison-selects label, .comparison-filter-row label { display: block; margin-bottom: 8px; font-size: 13px; font-weight: 750; }
+.comparison-selects select, .comparison-filter-row select { display: block; width: 100%; min-width: 0; padding: 12px 14px; border: 1px solid var(--line); border-radius: var(--radius-control); background: var(--paper); color: var(--ink); }
+.comparison-actions { margin: 18px 0; }
+#comparison-status { min-height: 20px; }
+.comparison-warning { padding: 12px 14px; border-left: 3px solid var(--accent-solid); background: var(--surface); font-size: 13px; line-height: 1.6; overflow-wrap: anywhere; }
+.comparison-meta { font-size: 13px; overflow-wrap: anywhere; }
+.comparison-counts { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); border-block: 1px solid var(--line); margin: 18px 0; }
+.comparison-count { min-width: 0; padding: 12px; border-right: 1px solid var(--line); overflow-wrap: anywhere; }
+.comparison-count:nth-child(3n) { border-right: 0; }
+.comparison-count:nth-child(n+4) { border-top: 1px solid var(--line); }
+.comparison-count strong, .comparison-count span { display: block; }
+.comparison-count strong { font-size: 22px; }
+.comparison-count span { color: var(--muted); font-size: 12px; }
+.comparison-filter-row { max-width: 320px; }
+#comparison-content, .comparison-panel { min-width: 0; }
 .report-panel .actions { margin-bottom: 25px; }
 .report-meta { display: flex; flex-wrap: wrap; gap: 9px; margin: 0 0 23px; }
 .report-meta span { padding: 5px 9px; border: 1px solid var(--line); border-radius: var(--radius-control); font-size: 12px; }
@@ -189,6 +207,9 @@ button:focus-visible, input:focus-visible, select:focus-visible, textarea:focus-
   .execution-grid { grid-template-columns: 1fr; gap: 16px; }
   .run-bar { align-items: start; flex-direction: column; }
   .list-row { align-items: start; flex-direction: column; gap: 12px; }
+  .comparison-selects { grid-template-columns: 1fr; }
+  .comparison-count { padding: 9px 5px; }
+  .comparison-count strong { font-size: 19px; }
   .draft-topline { align-items: start; flex-direction: column; }
   .summary { padding: 17px; }
   .summary-stat { padding-inline: 5px; }

package/dist/src/ui/server.js

@@ -13,6 +13,7 @@ import { localeFromAcceptLanguage, localizeProductMessage } from "../i18n.js";
 import { EvidenceError, readEvidence } from "./evidence.js";
 import { buildPlanningPrompt, planFlow, PlannerError } from "../planner.js";
 import { renderMarkdown } from "../report.js";
+import { compareReports, ComparisonError, renderComparisonMarkdown } from "../run-comparison.js";
 import { configSchema, idSchema, modelSchema, suiteSchema, targetSchema } from "../schema.js";
 import { targetFingerprint } from "../targets.js";
 import { CONFIG_FILE, sha256 } from "../workspace.js";
@@ -468,6 +469,25 @@ export async function startUIServer(options) {
                 sendJSON(response, 200, await report(runId, true, locale));
                 return;
             }
+            if (url.pathname === '/api/comparison') {
+                const baseline = url.searchParams.get('baseline');
+                const current = url.searchParams.get('current');
+                if (!baseline || !current)
+                    invalid('Both run IDs are required.');
+                const baselineReport = (await report(baseline, false)).report;
+                const currentReport = (await report(current, false)).report;
+                let comparison;
+                try {
+                    comparison = compareReports(baselineReport, currentReport);
+                }
+                catch (error) {
+                    if (error instanceof ComparisonError)
+                        throw new HTTPError(error.status, error.message);
+                    throw error;
+                }
+                sendJSON(response, 200, { comparison, markdown: renderComparisonMarkdown(comparison, locale) });
+                return;
+            }
             if (url.pathname === '/api/artifact') {
                 const runId = url.searchParams.get('runId');
                 const caseId = url.searchParams.get('caseId');

package/docs/mobile.md

@@ -9,7 +9,7 @@ Choose **Mobile** on the scenario screen, describe the flow, and generate or dow
 With the installed CLI:
 
 ```sh
-npm install -g @ihyeon/flow-qa@0.2.9
+npm install -g @ihyeon/flow-qa@0.3.0
 flow-qa init ./my-qa
 # Write your mobile flow in my-qa/flows/my-flow.md first.
 flow-qa plan flows/my-flow.md --platform mobile --prompt-only --workspace ./my-qa

package/docs/releases.md

@@ -2,6 +2,17 @@
 
 The alpha entries below are historical release records. They document earlier package versions and checks.
 
+## 0.3.0: compare recorded runs
+
+Adds a two-run comparison workspace to Run history. Select a baseline and current report, swap their direction, filter by case transition, open either detailed report, and export the complete comparison as Markdown or JSON. Cases are matched by ID, with distinct categories for passed-to-failed, failed-to-passed, other changes, equal statuses, added, and missing. Flaky, blocked, skipped, and execution-error results retain their meaning.
+
+The read-only comparison endpoint requires the same suite ID and recorded target settings, rejects ambiguous case IDs, and uses the existing safe report loader. Suite changes, reversed dates, and interrupted/error runs are explicitly flagged. Mobile comparisons also warn that recorded device selectors do not establish physical device identity. Comparisons describe saved outcomes, not proof of a regression or fixed defect. Shared Markdown hides URLs and links under the existing report policy; JSON retains recorded metadata. Selections remain across navigation, language changes, and history updates; selection changes or disappeared runs invalidate old exports, and late responses cannot replace a newer comparison. The existing report format is unchanged.
+
+Locally verified on macOS with Node.js 24.22.1 on 2026-11-02: 101 tests, type checking, UI syntax and design-system audit, existing browser/demo checks, and comparison UI checks using synthetic report fixtures. All 36 terminal-status combinations, compatibility gates, URL/link hiding, English/Korean exports, filtering, polling, navigation, 390px layout, late responses, and stale downloads were covered. A fresh tarball installation ran two real Chromium demo runs (six passing cases) and compared their saved reports. No model calls or native-device execution were used.
+
+- Package: [`@ihyeon/flow-qa@0.3.0`](https://www.npmjs.com/package/@ihyeon/flow-qa/v/0.3.0)
+- Release: [GitHub 0.3.0](https://github.com/hyeonse-swing/flow-qa/releases/tag/v0.3.0)
+
 ## 0.2.9: search run history
 
 Adds Search runs to run history, matching suite IDs, run IDs, and target names with case-insensitive partial search. Surrounding whitespace is ignored, and the search combines with the existing status filter. Clearing the query preserves the selected status. The current query stays through navigation, language changes, and automatic history updates; open reports and downloads remain available. Search covers only the most recent 50 reports already loaded by the UI.
@@ -100,7 +111,7 @@ Locally verified on macOS with Node.js 24.14.1 on 2026-10-12: 89 tests, type che
 
 A push to `main` publishes only when `package.json` changes to a new plain `X.Y.Z` version. Pull requests and pushes without a version change run verification without publishing. The package and lockfile versions must agree; the version must increase, and registry errors stop the release. Rerunning a successful publication skips the existing immutable npm version.
 
-The `publish` job in [ci.yml](../.github/workflows/ci.yml) waits for the full verification matrix on Ubuntu and macOS, then publishes through npm trusted publishing (OIDC). It uses the `latest` tag, requires the registry's `gitHead` to match the workflow commit, and checks the published package with a fresh consumer installation and three real Chromium demo cases. The commit check also applies when retrying an already published version. No npm token is stored in GitHub secrets. After the published package passes its consumer smoke check, a separate job creates the matching GitHub tag and release at the exact verified commit. It preserves existing releases and rejects a tag pointing to another commit. Rerunning an older release does not replace a newer latest release.
+The `publish` job in [ci.yml](../.github/workflows/ci.yml) waits for the full verification matrix on Ubuntu and macOS, then publishes through npm trusted publishing (OIDC). It uses the `latest` tag, requires the registry's `gitHead` to match the workflow commit, and checks the published package with a fresh consumer installation, two real Chromium demo runs (six cases), and comparison of their saved reports. The commit check also applies when retrying an already published version. No npm token is stored in GitHub secrets. After the published package passes its consumer smoke check, a separate job creates the matching GitHub tag and release at the exact verified commit. It preserves existing releases and rejects a tag pointing to another commit. Rerunning an older release does not replace a newer latest release.
 
 For the next release, update the release notes and current installation examples, then bump the version before committing and pushing:
 

package/docs/ui.md

@@ -7,7 +7,7 @@ Describe a user flow, review cases, and configure a target when ready to run. We
 Node.js 24.x (24.22.1 or later) or 26.12.1 or later is required. Node 25 is unsupported. Upgrade the Node runtime and restart any running UI process; updating Flow QA alone does not patch Node. Install Flow QA and start the web demo:
 
 ```sh
-npm install -g @ihyeon/flow-qa@0.2.9
+npm install -g @ihyeon/flow-qa@0.3.0
 flow-qa browser install
 flow-qa ui --demo
 ```
@@ -62,6 +62,16 @@ From version `0.2.7`, **Run history → Run status** filters the loaded reports
 
 From version `0.2.9`, **Run history → Search runs** matches part of a suite ID, run ID, or target name. Matching ignores letter case and surrounding whitespace, and supports Korean target names. Search combines with **Run status**; clear the search to return to the selected status. The query stays through navigation, language changes, and automatic report updates, and resets on page reload. Search covers the most recent 50 reports loaded by the UI, not older records, target URLs, or individual case content. Changing the query keeps the open report and its downloads available.
 
+### Compare two runs
+
+From version `0.3.0`, open **Run history → Compare two runs**, choose a **Baseline run** and **Current run**, then compare. Both selectors use the most recent 50 loaded reports, independently of the history search and status filter. The reports must belong to the same suite ID and recorded target settings: a matching web URL, or mobile platform, app ID, and device. Target display names may differ. Mobile reports record the configured device selector, which can be a name; all mobile comparisons warn that matching selectors do not establish that the same physical device was used. Comparing does not run tests, call a model, or change case review.
+
+Cases are matched by ID. **Newly failed** means only `passed → failed`; **Now passed** means only `failed → passed`. Other status transitions, including flaky, blocked, skipped, and execution errors, appear under **Changed status**. Equal statuses are **Same status**. **Added to current** and **Missing from current** mean present in only one selected report; missing does not mean passed or deleted from the suite. Filter the visible rows by category, open either detailed report for its evidence, or download the complete comparison as Markdown or JSON. Downloads include every category, regardless of the display filter, and do not include evidence files. Markdown follows the existing report URL/link hiding policy; JSON retains the recorded target settings and case text.
+
+When suite hashes differ, the UI and exports warn that steps or expectations may have changed. These are recorded outcomes, not proof of equivalent tests, a product regression, or a fixed defect. Additional warnings identify reversed chronological order and interrupted/error runs. The comparison never treats a flaky pass as a clean pass. The existing report format remains unchanged; comparison JSON uses `flow-qa/comparison-1`.
+
+Swap reverses the baseline and current selections. Changing either selection clears the old result and downloads until a new comparison succeeds. Navigation, language changes, and history updates preserve valid selections and results; a selected run disappearing from the loaded list invalidates the comparison. Choices reset on page reload. Markdown product labels follow the selected language, while user-written case content and status codes are preserved.
+
 ### Import existing case files
 
 From version `0.2.1`, select a `flow-qa/suite-1` JSON file and, when it declares a source, its Markdown file in case review, then choose **Import case files**. The two file controls let you select files from different folders. For an error-to-test export, select `cases/error-to-test.json` and `flows/error-to-test.md`. A JSON file without a source can be imported alone or with a Markdown file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ihyeon/flow-qa",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "license": "MIT",
   "author": "Hyeonse Im",
   "repository": {
@@ -57,7 +57,7 @@
     "check:ui": "node --check src/ui/public/app.js && node --check src/ui/public/display.js && node --check src/ui/public/i18n.js && hds-audit .",
     "demo:serve": "node examples/demo/server.ts",
     "demo:smoke": "node scripts/demo-smoke.ts",
-    "smoke:ui": "node scripts/ui-i18n-smoke.mjs"
+    "smoke:ui": "node scripts/ui-i18n-smoke.mjs && node scripts/ui-comparison-smoke.mjs"
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "3.0.53",