Skip to content

feat(artifacts): compare two versions of an artifact side by side - #37657

Merged
javenciu merged 1 commit into
mainfrom
feat/artifact-version-compare
Nov 16, 2026
Merged

javenciu merged 1 commit into
mainfrom
feat/artifact-version-compare

Conversation

@javenciu

@javenciu javenciu commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: from an artifact's page, set any two of its states (Live or a numbered version) side by side with the changed lines marked, so "what did the agent change" is answered by looking, not by flipping the version picker back and forth.

The artifact page lists versions in a picker and can revert to one, but it shows only one state at a time. Comparing two means switching between them and holding the first in memory. Chat file changes already draw a side-by-side diff with the shared diff viewer, and the versions API already returns each version's text, so the pieces exist.

Why it matters

Agents edit saved artifacts repeatedly. A reader who wants to know what changed since version 2 has no way to see it, and a revert is a leap without it.

Not a goal

  • No new route and no change to the versions API or to what is stored.
  • No three-way merge, no per-hunk accept or reject, no comparison of images or web apps.
  • No setting: the control is new and changes nothing until it is used.

What changed (motivation → approach → change)

  • website/src/lib/artifactCompare.ts: pure helpers, including the one stateLabel the select and the view both use. Which states the select offers, whether a request can be drawn, which side is older (Live is newest), and the file name given to the viewer.
  • website/src/components/ArtifactVersionCompare.tsx: the comparison view. It hands the two texts to the existing DiffPanel (the viewer computes the diff), with a heading and a "Stop comparing" button. Round 1: a narrow screen gets the one-column diff, and the two-column view names each column ("v1", "Live"). Round 4: the layout also follows the shared diff layout preference (useDiffSplit, the mc-diff-split setting in Display settings) that the chat diff surfaces read, so a reader who chose unified gets one column (no captions) on a wide screen too.
  • website/src/pages/useArtifactDetailPageDocument.ts: the chosen state, reset when the artifact changes, and a fetch of the other snapshot through the existing artifactVersion call (Live reuses the record already loaded). Round 3: the request is cleared where it stops being drawable (the viewed state becomes the compared one, or an edit starts), so it never returns later while the select shows none.
  • website/src/pages/ArtifactDetailPageHeader.tsx: a "Compare with" select beside the version picker. A select, not a button, so the row keeps its two-action limit.
  • website/src/pages/ArtifactDetailPageBody.tsx: shows the comparison in place of the body while one is active.
  • website/src/i18n/locales/en.json, en-XA.json and the eleven translated catalogs (bn, de, es, fr, hi, it, ja, ko, pt, ru, zh-CN): six strings each. Round 2: the translated catalogs were missing, so catalogParity.test.ts failed; each language now has its own translation.
  • src/kiro_crew/docs/artifacts.md: a paragraph on the feature (round 4: names the Display setting).

Resting header, light
Open option list, light
Compare view, light
Compare view, dark
Round 4 (this head): narrow view, 390 px wide, one column:
Compare view, narrow
Loading the other version, light and dark (loading-light.png, loading-dark.png):
Loading, light
Loading, dark
Other version failed to load, light and dark (error-light.png, error-dark.png):
Error, light
Error, dark

Backwards compatibility

Nothing changes until "Compare with" is used. A request that cannot be drawn (the state already on screen, a version no longer listed, an image or web app, an edit in progress) is dropped: the page shows the document exactly as before, with no refusal. A snapshot that fails to load shows the page's standard error notice and keeps the page.

Tests

  • Before: on main, six of the nine tests in website/src/test/ArtifactDetailPage.compare.test.tsx fail (no "Compare with" control); the three that pin today's behavior pass. website/src/lib/artifactCompare.test.ts needs the new module.
  • Round 4: one new test (the compare view follows the stored diff layout: mc-diff-split off gives the unified diff with no captions, on gives split with captions) fails on the previous source (ArtifactVersionCompare.tsx as of 3437a05, forced split) and passes now. The artifact page and diff panel suites: 20 files, 385 tests pass; ArtifactDetailPage.compare.test.tsx 14 tests.
  • Rebased onto current main for its test fix (test(wakatime): start the read-audit cache cold so the status load count is exact #37726); no code change.
  • Round 3: two new tests (viewed state returns to Live after being set to the compared one; an edit starts and ends) fail on the previous head with the select reading "Compare with v2" and pass now. The artifact page's suites: 19 files, 376 tests pass.
  • Round 2: vitest run src/i18n/ with I18N_BASE_REF set to the merge base: 81 files, 1,261 tests passed (the 11 has no key missing relative to en failures are gone).
  • Round 1: two new tests (unified diff on a narrow screen; captions over the columns) fail on the previous head and pass now.
  • After: all pass. The earlier suites still pass.
  • eslint, tsc -p tsconfig.app.json, i18n:check (RC=0) and the theme, class and string lints pass.
  • Reproduce: cd website && npx vitest run src/test/ArtifactDetailPage.compare.test.tsx src/lib/artifactCompare.test.ts
  • Proof: PROVEN website/src/test/ArtifactDetailPage.compare.test.tsx::ArtifactDetailPage — compare with another version > puts the older snapshot on the left and Live on the right (head 2e01fdb)

Manual verification

Rendered the real artifact page on loopback with three versions of a markdown file and Live, chose "Compare with v1", and captured the resting header, the open option list, and the comparison in light and dark, plus the narrow, loading and error views (above; also shots/resting-light.png, shots/resting-dark.png, shots/options-light.png, shots/options-dark.png). The older text is on the left, removed lines are red, added lines green, with the changed words marked inside each line.

Sibling sweep

Sibling: website/src/components/ArtifactBody.tsx -- not affected -- the normal body renders unchanged when no comparison is active
Sibling: website/src/pages/RemoteArtifactDetailPage.tsx -- not affected -- a remote listing has no local versions

Pattern harvest

Rule candidate: review-prompt
Pattern: a picker that swaps the whole view gives no way to see a change; offer a diff against the other states.

Related Issues

None.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

@javenciu
javenciu requested review from a team and KiroCrewCaptain as code owners November 15, 2026 18:25
@javenciu
javenciu enabled auto-merge (squash) November 15, 2026 18:25
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 15, 2026
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 2e01fdb3e4c38ff1636d6ebe79ef2c7c9ec0ec10 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the change only adds things, reuses the existing DiffPanel and versions API, and the description includes screenshots of this revision.

[DESIGN-REVIEWED] 2e01fdb

Description read

[DESCRIPTION-READ] deb28a64c3c7b181c0e22a73dfbc40e063734fafbf2a8cc07754c9059e3d96dd

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 2e01fdb3e4c38ff1636d6ebe79ef2c7c9ec0ec10 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

This adds a comparison you have to choose to use. It builds on the existing DiffPanel and artifactVersion call and leaves every default as it was. The only finding is a second spelling of the version label.

Notes

  • Item 1 — duplicate of website/src/pages/ArtifactDetailPageHeader.tsx:326-327: stateLabel says it is "how the version picker words a state, so every place that names one reads the same". The picker still builds the same string inline (i18nT('pages.artifactDetailPage.live') / version_label + fmtNumber(v, { useGrouping: false })). That leaves 2 spellings (grepped version_label outside i18n and tests: 2 sites). Subtraction: change the picker's inline versionOptions labels to stateLabel(stateKey(v)) so only one spelling remains.

What this change ships

Inventory (6 items) — 5 justified

Intent: let a reader see what changed between two states of an artifact without flipping the version picker back and forth. ADDITION.

  1. A "Compare with" select appears next to the version picker on text artifacts — justified
  2. Picking a state replaces the body with an older-left, newer-right diff with "Stop comparing" — justified
  3. Two-column mode labels each column ("v1", "Live") — justified
  4. The diff follows the Display setting's split/unified preference and goes to one column on narrow screens — justified
  5. The comparison clears itself when the viewed state becomes the compared one, or when an edit starts — justified
  6. New stateLabel helper names states, duplicating the picker's inline label — duplicate of ArtifactDetailPageHeader.tsx:326

[FIRST-PRINCIPLES-REVIEWED] 2e01fdb

Description read

[DESCRIPTION-READ] 7e3674e34a9927fd65246a9ea52f5fbc4231c0c32af0693c73473b46982baf56

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 2e01fdb3e4c38ff1636d6ebe79ef2c7c9ec0ec10 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks. The blind reader read "Compare with" and "Stop comparing" correctly and would use both. Screenshots cover every state the diff adds: the menu, split, narrow, loading, error, and light and dark themes.

Notes

  • The "Compare with" list offers "Compare with v3" while the footer says "Showing Live (v3)". When nothing has changed since v3, that comparison shows only "identical". The blind reader called it "compare the document with itself… seems pointless". Hide the newest snapshot when Live matches it, or label that row "v3 (same as Live)".
  • The first menu row, "Compare with ✓", means "not comparing", but it uses the same words as the menu's own label. The reader saw it as an action rather than an off setting. Rename the COMPARE_NONE option label to "Don't compare" or "No comparison".
  • The failure notice puts raw error text under "Could not load v1 to compare". The reader asked "is v1 lost for good?" and found no next step. Say what happened in plain words (the version could not be read, and the current document is unaffected) and add a Retry button.

[UX-REVIEWED] 2e01fdb

Description read

[DESCRIPTION-READ] 72fa0da4f5590a637be8c33c7d903448f747769c85726ebf97ffad20c8d89a36

That sha256 names everything this verdict read: the PR description, plus the 12 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 2e01fdb3e4c38ff1636d6ebe79ef2c7c9ec0ec10 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 2e01fdb

Verdict parsed from the review's SHA-scoped output markers for commit 2e01fdb3e4c38ff1636d6ebe79ef2c7c9ec0ec10.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 2e01fdb3e4c38ff1636d6ebe79ef2c7c9ec0ec10 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 2e01fdb3e4c38ff1636d6ebe79ef2c7c9ec0ec10 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2e01fdb

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 2e01fdb3e4c38ff1636d6ebe79ef2c7c9ec0ec10 false-positive: <reason, 20 to 500 characters>

@KiroCrewCaptain

KiroCrewCaptain commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates a 12% chance that this change introduces a defect, within the 12% limit for approving on its own, but it changes 633 lines, more than the 400 it may approve on its own.

This PR adds an opt-in, front-end-only view that compares two states of an artifact. It reuses DiffPanel and the existing artifactVersion query. State lifecycle checks out: the compare state resets when the slug changes, clears when an edit starts or the viewed version becomes the compared one, and is ignored for images, web apps and edit mode. A version that can't be drawn falls back to the normal body. The older state always goes on the left. The view follows the shared mft-diff-split layout setting and drops to one column on a narrow screen. Strings were added to every catalog, and there are tests for each behaviour (page-level and pure helpers). CI and all review lanes are green. The one sibling-path concern was that the Compare select skips the comment-draft guard. It turned out not to lose anything, because the composer draft store keeps the text through an unguarded teardown. Nothing blocks.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 2e01fdb3e4 · 633 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@javenciu
javenciu force-pushed the feat/artifact-version-compare branch from c585b04 to d7dfd99 Compare November 15, 2026 18:56
@javenciu

Copy link
Copy Markdown
Contributor Author

Blocking, ArtifactVersionCompare.tsx:86 (always two columns, nothing for a narrow screen). Fixed in d7dfd99. The view reads useIsMobile() and passes sideBySide={!isMobile} to DiffPanel, so a phone gets the one-column diff the chat diff already offers. The test draws two columns on a wide screen and one unified column on a narrow one in website/src/test/ArtifactDetailPage.compare.test.tsx fails on the previous head (expected 'split' to be 'unified') and passes now.

First principles, the "Live / vN" label was spelled twice. Fixed in d7dfd99. stateLabel now lives in website/src/lib/artifactCompare.ts; the "Compare with" select in ArtifactDetailPageHeader.tsx and the comparison view both call it, and the inline ternary is gone.

UX, the two panes have no labels. Fixed in d7dfd99. In two-column mode a caption row names the older state over the left column and the newer over the right ("v1", "Live"), using the existing state labels (no new string). Test names the older state over the left column and the newer over the right in two-column mode fails on the previous head (no caption element) and passes now.

UX, missing resting and open-list screenshots. Added resting-light.png and options-light.png to the body (kept in the build folder, not committed); the light and dark comparison shots were retaken with the captions.

UX, "Stop comparing" scrolls away. Not changed. The page header is already sticky and holds the "Compare with" select; its first row ("Compare with") returns to the document, so a way back stays on screen while the diff scrolls. A second sticky row would sit under the page header (both are top-0), and a second stop button in the header would break max-two-buttons-per-row.

UX, "Version Live" and "Compare with v1" look alike; loading and error states unseen. The column captions answer the first. The loading and error states are pinned by tests (says so, and keeps the page, when the other snapshot cannot be read) and use the page's standard ErrorNotice; no change.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 15, 2026
@javenciu
javenciu force-pushed the feat/artifact-version-compare branch from d7dfd99 to 6982e7b Compare November 15, 2026 22:19
@javenciu

Copy link
Copy Markdown
Contributor Author

CI, src/i18n/catalogParity.test.ts (11 failures, "has no key missing relative to en"). Fixed in 6982e7b04743. The six new strings (pages.artifactDetailPage.compare_*, comparing_older_with_newer, stop_comparing) had only been added to en and en-XA. They are now in all eleven translated catalogs (bn, de, es, fr, hi, it, ja, ko, pt, ru, zh-CN), each with a real translation, placed next to send_to_session_failed in the same block. In Russian and Korean the state label sits after a colon, so the grammatical case or particle cannot clash with the label ("Текущая", "라이브"). With I18N_BASE_REF set to the merge base, vitest run src/i18n/ passes (81 files, 1,261 tests, including every per-language style test), and npm run i18n:check exits 0 with no FAIL line.

CI, "Render Benchmark (counter budgets)". Not changed. The job fails with "Playwright does not support chromium on ubuntu26.04-x64", which is the runner image; it does not run any code from this PR.

The branch is rebased onto the current main as a single commit.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 15, 2026
@javenciu
javenciu force-pushed the feat/artifact-version-compare branch from 6982e7b to 3437a05 Compare November 15, 2026 22:55
@javenciu

Copy link
Copy Markdown
Contributor Author

BLOCKING, useArtifactDetailPageDocument.ts:278: a comparison the page dropped stays stored in compareWith and comes back later. Fixed in 3437a05, as suggested: the request is cleared where it stops being drawable. Setting the viewed version to the state that was to be compared now runs setCompareWith(COMPARE_NONE) for that value, and starting an edit clears it too. Both live in the page state hook (one place, not each caller), so the version picker, "Back to live" and the post-revert reset are all covered, and the stored state always matches what the select shows. Two new tests fail on the previous head and pass now: "does not bring a dropped comparison back when the viewed state returns to Live" (Compare with v2, set the picker to v2, then Live: the select still read "Compare with v2" and the diff returned) and "does not bring a comparison back after an edit starts and ends". No string or layout changed, so the screenshots stand.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 15, 2026
@javenciu
javenciu force-pushed the feat/artifact-version-compare branch from 3437a05 to 29e0fa9 Compare November 16, 2026 00:23
@javenciu

Copy link
Copy Markdown
Contributor Author

UX lane (screenshots of the narrow, loading and error views): captured on this head from the real artifact page on loopback with the version fetch mocked. Narrow view: 390 px viewport at 2x, clipped to the compare region so the changed lines and their text are readable (shots/compare-narrow.png). Loading state, with the version fetch held pending: shots/loading-light.png, shots/loading-dark.png. Error state, with the fetch failing: shots/error-light.png, shots/error-dark.png. The wide light and dark comparison shots, the resting header and the option list from earlier rounds still match this head and are kept. The three notes (a label for the "no comparison" option, hiding a version equal to Live, saying what the select compares against) were marked not blocking and are left for a follow-up, to keep this PR one mechanism.

Code change approver, item 2 (unified layout ignored): it did. On the previous head ArtifactVersionCompare forced sideBySide = !useIsMobile(), while the chat diff surfaces read useDiffSplit() (DiffBlock.tsx:207, FileChangeChips.tsx:589, MarkdownPanel.tsx:264, SidePanel.tsx:680). Fixed in 29e0fa945681: sideBySide = preferSplit && !narrow, so a stored unified preference gives one column and no captions, and a phone still gets one column. Test follows the shared diff layout preference from Display settings in website/src/test/ArtifactDetailPage.compare.test.tsx fails on the previous source (red-r4.log: 1 failed, 13 passed) and passes now (14 passed). The docs paragraph names the Display setting.

Code change approver, item 1 (no narrow branch): fixed in round 1; the test is draws two columns on a wide screen and one unified column on a narrow one (same file), and useIsMobile still gates the layout at ArtifactVersionCompare.tsx:38-39.

CI: gh pr checks 37657 on head 3437a05 shows 86 SUCCESS and 11 SKIPPED, nothing failing, so there is no job log to attribute.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Nov 16, 2026
@javenciu
javenciu force-pushed the feat/artifact-version-compare branch from 29e0fa9 to 2e01fdb Compare November 16, 2026 01:57
@javenciu

Copy link
Copy Markdown
Contributor Author

Rebased onto current main (c2f1b329a3) as 2e01fdb3e4, with no code change, to pick up #37726: backend shard 1 failed here on test_wakatime_handlers.py::test_status_loads_config_off_the_event_loop, which was red on main before that fix, and this PR changes no Python. On the new head the compare, diff panel and i18n suites give 125 passed and the lane CI checks pass.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 16, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. On this head the review checked these points. The compare query shares the version picker's cache key and stays off for Live. Revert, Back to live, the version picker, an edit start and a slug change all clear a comparison that can no longer be shown. Images and web apps get no Compare control. The narrow view falls back to one column. Artifact text reaches the diff viewer as plain text, and the diff adds no new endpoint and no raw HTML path. Each fix round added a page test that pins its change.

Done well: the feature is built from what already exists (the artifact version API, DiffPanel and the shared diff layout preference), and the choice logic lives in small pure helpers with their own unit tests.

Optional:

  • src/kiro_crew/docs/artifacts.md:35 sends readers to Display settings, but the diff layout toggle ("Split (side-by-side) diffs") is in Settings > Chat. The comment at ArtifactVersionCompare.tsx:35 names the same wrong tab.
  • ArtifactDetailPageHeader.tsx:326 still builds the picker's "Live" / "vN" labels inline. Mapping them through stateLabel would make its doc comment true.
  • The Compare select's onChange (ArtifactDetailPageHeader.tsx:540) could go through guardCommentDraft, the same way the Version picker's does, so an open anchored-comment box is not closed without asking.

@javenciu
javenciu merged commit 8f4b6b6 into main Nov 16, 2026
99 checks passed
@javenciu
javenciu deleted the feat/artifact-version-compare branch November 16, 2026 03:34
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants