From 376868d1f51e1b65a378bec5560472df17a6205f Mon Sep 17 00:00:00 2001
From: taskylizard <75871323+taskylizard@users.noreply.github.com>
Date: Thu, 29 Jan 2026 22:18:13 +0100
Subject: [PATCH 1/7] WIP

WIP

fix: detect file modifications using hashes

fix: surface diff fetch failures

fix: handle file-directory transitions in compare

WIP
---
 app/components/diff/Hunk.vue                  |  11 +
 app/components/diff/Line.vue                  | 158 +++++
 app/components/diff/SkipBlock.vue             |  27 +
 app/components/diff/Table.vue                 |  50 ++
 app/components/diff/ViewerPanel.vue           | 637 ++++++++++++++++++
 app/pages/[...package].vue                    |  10 +-
 app/pages/compare/[...path].vue               | 427 ++++++++++++
 app/utils/language-detection.ts               |  75 +++
 app/utils/shiki-client.ts                     |  24 +
 i18n/locales/en.json                          |  24 +
 lunaria/files/en-US.json                      |  24 +
 package.json                                  |   1 +
 pnpm-lock.yaml                                |  46 +-
 .../api/registry/compare-file/[...pkg].get.ts | 248 +++++++
 server/api/registry/compare/[...pkg].get.ts   | 143 ++++
 server/utils/compare.ts                       | 260 +++++++
 server/utils/diff.ts                          |   1 +
 server/utils/file-tree.ts                     |   1 +
 shared/schemas/package.ts                     |  23 +
 shared/types/compare.ts                       | 153 +++++
 shared/types/index.ts                         |   1 +
 shared/types/npm-registry.ts                  |   2 +
 shared/utils/diff.ts                          | 383 +++++++++++
 23 files changed, 2712 insertions(+), 17 deletions(-)
 create mode 100644 app/components/diff/Hunk.vue
 create mode 100644 app/components/diff/Line.vue
 create mode 100644 app/components/diff/SkipBlock.vue
 create mode 100644 app/components/diff/Table.vue
 create mode 100644 app/components/diff/ViewerPanel.vue
 create mode 100644 app/pages/compare/[...path].vue
 create mode 100644 app/utils/language-detection.ts
 create mode 100644 app/utils/shiki-client.ts
 create mode 100644 server/api/registry/compare-file/[...pkg].get.ts
 create mode 100644 server/api/registry/compare/[...pkg].get.ts
 create mode 100644 server/utils/compare.ts
 create mode 100644 server/utils/diff.ts
 create mode 100644 shared/types/compare.ts
 create mode 100644 shared/utils/diff.ts

diff --git a/app/components/diff/Hunk.vue b/app/components/diff/Hunk.vue
new file mode 100644
index 00000000..741689f0
--- /dev/null
+++ b/app/components/diff/Hunk.vue
@@ -0,0 +1,11 @@
+<script setup lang="ts">
+import type { DiffHunk as DiffHunkType } from '#shared/types'
+
+defineProps<{
+  hunk: DiffHunkType
+}>()
+</script>
+
+<template>
+  <DiffLine v-for="(line, index) in hunk.lines" :key="index" :line="line" />
+</template>
diff --git a/app/components/diff/Line.vue b/app/components/diff/Line.vue
new file mode 100644
index 00000000..2c890635
--- /dev/null
+++ b/app/components/diff/Line.vue
@@ -0,0 +1,158 @@
+<script setup lang="ts">
+import type { DiffLine as DiffLineType } from '#shared/types'
+import { getClientHighlighter } from '~/utils/shiki-client'
+
+const props = defineProps<{
+  line: DiffLineType
+}>()
+
+const diffContext = inject<{
+  fileStatus: ComputedRef<'add' | 'delete' | 'modify'>
+  language?: ComputedRef<string>
+  enableShiki?: ComputedRef<boolean>
+  wordWrap?: ComputedRef<boolean>
+}>('diffContext')
+
+const colorMode = useColorMode()
+
+const lineNumberNew = computed(() => {
+  if (props.line.type === 'normal') {
+    return props.line.newLineNumber
+  }
+  return props.line.lineNumber ?? props.line.newLineNumber
+})
+
+const lineNumberOld = computed(() => {
+  if (props.line.type === 'normal') {
+    return props.line.oldLineNumber
+  }
+  return props.line.type === 'delete'
+    ? (props.line.lineNumber ?? props.line.oldLineNumber)
+    : undefined
+})
+
+const rowClasses = computed(() => {
+  const shouldWrap = diffContext?.wordWrap?.value ?? false
+  const classes = ['whitespace-pre-wrap', 'box-border', 'border-none']
+  if (shouldWrap) classes.push('min-h-6')
+  else classes.push('h-6', 'min-h-6')
+  const fileStatus = diffContext?.fileStatus.value
+
+  if (props.line.type === 'insert' && fileStatus !== 'add') {
+    classes.push('bg-[var(--code-added)]/10')
+  }
+  if (props.line.type === 'delete' && fileStatus !== 'delete') {
+    classes.push('bg-[var(--code-removed)]/10')
+  }
+
+  return classes
+})
+
+const borderClasses = computed(() => {
+  const classes = ['border-transparent', 'w-1', 'border-l-3']
+
+  if (props.line.type === 'insert') {
+    classes.push('border-[color:var(--code-added)]/60')
+  }
+  if (props.line.type === 'delete') {
+    classes.push('border-[color:var(--code-removed)]/80')
+  }
+
+  return classes
+})
+
+const contentClasses = computed(() => {
+  const shouldWrap = diffContext?.wordWrap?.value ?? false
+  return ['pr-6', shouldWrap ? 'whitespace-pre-wrap break-words' : 'text-nowrap']
+})
+
+type RenderedSegment = { html: string; type: 'insert' | 'delete' | 'normal' }
+const renderedSegments = shallowRef<RenderedSegment[]>(
+  props.line.content.map(seg => ({ html: escapeHtml(seg.value), type: seg.type })),
+)
+
+function normalizeLanguage(raw?: string): 'javascript' | 'typescript' | 'json' | 'plaintext' {
+  if (!raw) return 'plaintext'
+  const lang = raw.toLowerCase()
+  if (lang.includes('json')) return 'json'
+  if (lang === 'ts' || lang.includes('typescript') || lang.includes('tsx')) return 'typescript'
+  if (lang === 'js' || lang.includes('javascript') || lang.includes('mjs') || lang.includes('cjs'))
+    return 'javascript'
+  return 'plaintext'
+}
+
+function escapeHtml(str: string): string {
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+async function highlightSegments() {
+  if (!import.meta.client) return
+
+  const lang = normalizeLanguage(diffContext?.language?.value)
+  // If language unsupported, keep escaped plain text
+  if (lang === 'plaintext') {
+    renderedSegments.value = props.line.content.map(seg => ({
+      html: escapeHtml(seg.value),
+      type: seg.type,
+    }))
+    return
+  }
+
+  const theme = colorMode.value === 'light' ? 'github-light' : 'github-dark'
+  const highlighter = await getClientHighlighter()
+
+  renderedSegments.value = props.line.content.map(seg => {
+    const code = seg.value.length ? seg.value : ' '
+    const html = highlighter.codeToHtml(code, { lang, theme })
+    const inner = html.match(/<code[^>]*>([\s\S]*?)<\/code>/)?.[1] ?? escapeHtml(code)
+    return { html: inner, type: seg.type }
+  })
+}
+
+watch(
+  () => [props.line, diffContext?.language?.value, colorMode.value],
+  () => {
+    highlightSegments()
+  },
+  { immediate: true, deep: true },
+)
+</script>
+
+<template>
+  <tr
+    :data-line-new="lineNumberNew"
+    :data-line-old="lineNumberOld"
+    :data-line-kind="line.type"
+    :class="rowClasses"
+  >
+    <!-- Border indicator -->
+    <td :class="borderClasses" />
+
+    <!-- Line number -->
+    <td class="tabular-nums text-center opacity-50 px-2 text-xs select-none w-12 shrink-0">
+      {{ line.type === 'delete' ? '–' : lineNumberNew }}
+    </td>
+
+    <!-- Line content -->
+    <td :class="contentClasses">
+      <component :is="line.type === 'insert' ? 'ins' : line.type === 'delete' ? 'del' : 'span'">
+        <span
+          v-for="(seg, i) in renderedSegments"
+          :key="i"
+          :class="{
+            'bg-[var(--code-added)]/20': seg.type === 'insert',
+            'bg-[var(--code-removed)]/20': seg.type === 'delete',
+          }"
+          v-html="seg.html"
+        />
+      </component>
+    </td>
+  </tr>
+</template>
+
+<style scoped>
+ins,
+del {
+  text-decoration: none;
+}
+</style>
diff --git a/app/components/diff/SkipBlock.vue b/app/components/diff/SkipBlock.vue
new file mode 100644
index 00000000..6200903e
--- /dev/null
+++ b/app/components/diff/SkipBlock.vue
@@ -0,0 +1,27 @@
+<script setup lang="ts">
+defineProps<{
+  count: number
+  content?: string
+}>()
+</script>
+
+<template>
+  <!-- Spacer row -->
+  <tr class="h-2" />
+
+  <!-- Skip block row -->
+  <tr class="h-10 font-mono bg-bg-muted text-fg-muted">
+    <td />
+    <td class="opacity-50 select-none text-center">
+      <span class="i-lucide-chevrons-up-down w-4 h-4" />
+    </td>
+    <td>
+      <span class="px-0 sticky left-2 italic opacity-50">
+        {{ content || `${count} lines hidden` }}
+      </span>
+    </td>
+  </tr>
+
+  <!-- Spacer row -->
+  <tr class="h-2" />
+</template>
diff --git a/app/components/diff/Table.vue b/app/components/diff/Table.vue
new file mode 100644
index 00000000..e207d798
--- /dev/null
+++ b/app/components/diff/Table.vue
@@ -0,0 +1,50 @@
+<script setup lang="ts">
+import type { DiffHunk, DiffSkipBlock } from '#shared/types'
+import { guessLanguageFromPath } from '~/utils/language-detection'
+
+const props = defineProps<{
+  hunks: (DiffHunk | DiffSkipBlock)[]
+  type: 'add' | 'delete' | 'modify'
+  fileName?: string
+  enableShiki?: boolean
+  wordWrap?: boolean
+}>()
+
+const language = computed(() => {
+  if (!props.fileName) return 'text'
+  return guessLanguageFromPath(props.fileName)
+})
+
+// provide diff context into child components
+provide('diffContext', {
+  fileStatus: computed(() => props.type),
+  language: computed(() => language.value),
+  enableShiki: computed(() => props.enableShiki ?? false),
+  wordWrap: computed(() => props.wordWrap ?? false),
+})
+</script>
+
+<template>
+  <table
+    class="diff-table font-mono text-sm w-full m-0 border-separate border-0 outline-none overflow-x-auto border-spacing-0"
+  >
+    <tbody class="w-full box-border">
+      <template v-for="(hunk, index) in hunks" :key="index">
+        <DiffHunk v-if="hunk.type === 'hunk'" :hunk="hunk" />
+        <DiffSkipBlock v-else :count="hunk.count" :content="hunk.content" />
+      </template>
+    </tbody>
+  </table>
+</template>
+
+<style scoped>
+.diff-table {
+  --code-added: oklch(0.723 0.219 149.579);
+  --code-removed: oklch(0.704 0.191 22.216);
+}
+
+:root[data-theme='light'] .diff-table {
+  --code-added: oklch(0.527 0.154 150.069);
+  --code-removed: oklch(0.577 0.184 27.325);
+}
+</style>
diff --git a/app/components/diff/ViewerPanel.vue b/app/components/diff/ViewerPanel.vue
new file mode 100644
index 00000000..5d2f9244
--- /dev/null
+++ b/app/components/diff/ViewerPanel.vue
@@ -0,0 +1,637 @@
+<script setup lang="ts">
+import type { FileDiffResponse, FileChange } from '#shared/types'
+import { createDiff, insertSkipBlocks, countDiffStats } from '#shared/utils/diff'
+// @ts-expect-error: (tasky): idk why this is type-erroring even if it has types? /shrug
+import { motion } from 'motion-v'
+
+const props = defineProps<{
+  packageName: string
+  fromVersion: string
+  toVersion: string
+  file: FileChange
+}>()
+
+const mergeModifiedLines = ref(true)
+const maxChangeRatio = ref(0.45)
+const maxDiffDistance = ref(30)
+const inlineMaxCharEdits = ref(2)
+const wordWrap = ref(false)
+const showOptions = ref(false)
+const loading = ref(true)
+const loadError = ref<Error | null>(null)
+const diff = ref<FileDiffResponse | null>(null)
+const fromContent = ref<string | null>(null)
+const toContent = ref<string | null>(null)
+const loadToken = ref(0)
+
+const DIFF_TIMEOUT = 15000
+const MAX_DIFF_FILE_SIZE = 250 * 1024
+
+const optionsParams = computed(() => ({
+  mergeModifiedLines: mergeModifiedLines.value,
+  maxChangeRatio: maxChangeRatio.value,
+  maxDiffDistance: maxDiffDistance.value,
+  inlineMaxCharEdits: inlineMaxCharEdits.value,
+}))
+
+const status = computed(() => {
+  if (loadError.value) return 'error'
+  if (loading.value) return 'pending'
+  return 'success'
+})
+
+async function fetchFileContent(version: string): Promise<string | null> {
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort(), DIFF_TIMEOUT)
+  const url = `https://cdn.jsdelivr.net/npm/${props.packageName}@${version}/${props.file.path}`
+  try {
+    const res = await fetch(url, { signal: controller.signal })
+    if (res.status === 404) return null
+    if (!res.ok) throw new Error(`Failed to fetch file (status ${res.status})`)
+
+    const length = res.headers.get('content-length')
+    if (length && parseInt(length, 10) > MAX_DIFF_FILE_SIZE) {
+      throw new Error(
+        `File too large to diff (${(parseInt(length, 10) / 1024).toFixed(0)}KB). Maximum is ${
+          MAX_DIFF_FILE_SIZE / 1024
+        }KB.`,
+      )
+    }
+
+    const text = await res.text()
+    if (text.length > MAX_DIFF_FILE_SIZE) {
+      throw new Error(
+        `File too large to diff (${(text.length / 1024).toFixed(0)}KB). Maximum is ${
+          MAX_DIFF_FILE_SIZE / 1024
+        }KB.`,
+      )
+    }
+
+    return text
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+function computeDiff() {
+  if (loadError.value) return
+  if (loading.value && fromContent.value === null && toContent.value === null) return
+
+  const oldContent = fromContent.value ?? ''
+  const newContent = toContent.value ?? ''
+
+  // Determine type
+  let type: FileDiffResponse['type'] = 'modify'
+  if (fromContent.value === null && toContent.value !== null) type = 'add'
+  else if (fromContent.value !== null && toContent.value === null) type = 'delete'
+
+  const parsed = createDiff(oldContent, newContent, props.file.path, optionsParams.value)
+
+  if (!parsed) {
+    diff.value = {
+      package: props.packageName,
+      from: props.fromVersion,
+      to: props.toVersion,
+      path: props.file.path,
+      type,
+      hunks: [],
+      stats: { additions: 0, deletions: 0 },
+      meta: {},
+    }
+    return
+  }
+
+  const hunksWithSkips = insertSkipBlocks(
+    parsed.hunks.filter(
+      (h): h is (typeof parsed.hunks)[number] & { type: 'hunk' } => h.type === 'hunk',
+    ),
+  )
+  const stats = countDiffStats(hunksWithSkips)
+
+  diff.value = {
+    package: props.packageName,
+    from: props.fromVersion,
+    to: props.toVersion,
+    path: props.file.path,
+    type: parsed.type,
+    hunks: hunksWithSkips,
+    stats,
+    meta: {},
+  }
+}
+
+async function loadContents() {
+  const token = ++loadToken.value
+  loading.value = true
+  loadError.value = null
+  try {
+    const [from, to] = await Promise.all([
+      fetchFileContent(props.fromVersion),
+      fetchFileContent(props.toVersion),
+    ])
+
+    if (token !== loadToken.value) return
+
+    fromContent.value = from
+    toContent.value = to
+
+    if (from === null && to === null) {
+      throw new Error('File not found in either version')
+    }
+
+    computeDiff()
+  } catch (err) {
+    if (token !== loadToken.value) return
+    loadError.value = err as Error
+    diff.value = null
+  } finally {
+    if (token === loadToken.value) loading.value = false
+  }
+}
+
+watch(
+  [() => props.file.path, () => props.fromVersion, () => props.toVersion],
+  () => {
+    loadContents()
+  },
+  { immediate: true },
+)
+
+watch([mergeModifiedLines, maxChangeRatio, maxDiffDistance, inlineMaxCharEdits], () => {
+  computeDiff()
+})
+
+function calcPercent(value: number, min: number, max: number): number {
+  if (max === min) return 0
+  const percent = ((value - min) / (max - min)) * 100
+  return Math.min(100, Math.max(0, percent))
+}
+
+function getStepMarks(min: number, max: number, step: number): number[] {
+  const marks: number[] = []
+  const range = max - min
+  const stepCount = Math.floor(range / step)
+
+  if (stepCount <= 10) {
+    for (let i = 1; i <= stepCount; i++) {
+      const positionPercent = ((i * step) / range) * 100
+      marks.push(positionPercent)
+    }
+  }
+
+  return marks
+}
+
+const changeRatioMarks = computed(() => getStepMarks(0, 1, 0.01))
+const diffDistanceMarks = computed(() => getStepMarks(1, 60, 1))
+const charEditMarks = computed(() => [] as number[]) // no dots for char edits slider
+const changeRatioPercent = computed(() => calcPercent(maxChangeRatio.value, 0, 1))
+const diffDistancePercent = computed(() => calcPercent(maxDiffDistance.value, 1, 60))
+const charEditPercent = computed(() => calcPercent(inlineMaxCharEdits.value, 0, 10))
+
+function formatBytes(bytes: number | undefined): string {
+  if (bytes === undefined) return ''
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+// Build code browser URL
+function getCodeUrl(version: string): string {
+  return `/code/${props.packageName}/v/${version}/${props.file.path}`
+}
+</script>
+
+<template>
+  <div class="h-full flex flex-col bg-bg">
+    <!-- Header -->
+    <div
+      class="flex items-center justify-between px-4 py-3 bg-bg-subtle border-b border-border shrink-0"
+    >
+      <div class="flex items-center gap-3 min-w-0">
+        <!-- File icon based on type -->
+        <span
+          :class="[
+            'w-4 h-4 shrink-0',
+            file.type === 'added'
+              ? 'i-carbon-add-alt text-green-500'
+              : file.type === 'removed'
+                ? 'i-carbon-subtract-alt text-red-500'
+                : 'i-carbon-edit text-yellow-500',
+          ]"
+        />
+
+        <!-- File path -->
+        <span class="font-mono text-sm truncate">{{ file.path }}</span>
+
+        <!-- Stats -->
+        <template v-if="diff?.stats">
+          <span v-if="diff.stats.additions > 0" class="text-xs text-green-500 font-mono shrink-0">
+            +{{ diff.stats.additions }}
+          </span>
+          <span v-if="diff.stats.deletions > 0" class="text-xs text-red-500 font-mono shrink-0">
+            -{{ diff.stats.deletions }}
+          </span>
+        </template>
+
+        <!-- File sizes -->
+        <span v-if="file.oldSize || file.newSize" class="text-xs text-fg-subtle shrink-0">
+          <template v-if="file.type === 'modified'">
+            {{ formatBytes(file.oldSize) }} → {{ formatBytes(file.newSize) }}
+          </template>
+          <template v-else-if="file.type === 'added'">
+            {{ formatBytes(file.newSize) }}
+          </template>
+          <template v-else>
+            {{ formatBytes(file.oldSize) }}
+          </template>
+        </span>
+      </div>
+
+      <div class="flex items-center gap-2 shrink-0">
+        <!-- Options dropdown -->
+        <div class="relative">
+          <button
+            type="button"
+            class="px-2 py-1 text-xs text-fg-muted hover:text-fg bg-bg-muted border border-border rounded transition-colors flex items-center gap-1.5"
+            :class="{ 'bg-bg-elevated text-fg': showOptions }"
+            @click="showOptions = !showOptions"
+          >
+            <span class="i-carbon-settings w-3.5 h-3.5" />
+            Options
+            <span
+              class="i-carbon-chevron-down w-3 h-3 transition-transform"
+              :class="{ 'rotate-180': showOptions }"
+            />
+          </button>
+
+          <!-- Dropdown menu -->
+          <motion.div
+            v-if="showOptions"
+            class="absolute right-0 top-full mt-2 z-20 p-4 bg-bg-elevated/40 backdrop-blur-sm border border-border shadow-2xl overflow-hidden"
+            :initial="{ width: 220, height: 110, borderRadius: 20 }"
+            :animate="{
+              width: mergeModifiedLines ? 400 : 220,
+              height: mergeModifiedLines ? 260 : 110,
+              borderRadius: mergeModifiedLines ? 14 : 20,
+            }"
+            :transition="{
+              type: 'spring',
+              stiffness: 550,
+              damping: 45,
+              mass: 0.7,
+              delay: mergeModifiedLines ? 0 : 0.08,
+            }"
+          >
+            <div class="flex flex-col gap-2">
+              <!-- Merge modified lines checkbox -->
+              <div class="flex items-center gap-2">
+                <input
+                  id="merge-modified-lines"
+                  v-model="mergeModifiedLines"
+                  type="checkbox"
+                  class="w-4 h-4 rounded border-border bg-bg text-blue-500 focus:ring-2 focus:ring-blue-500/50 cursor-pointer"
+                />
+                <label
+                  for="merge-modified-lines"
+                  class="text-sm cursor-pointer select-none whitespace-nowrap w-full"
+                >
+                  Merge modified lines
+                </label>
+              </div>
+
+              <!-- Word wrap checkbox -->
+              <div class="flex items-center gap-2">
+                <input
+                  id="word-wrap"
+                  v-model="wordWrap"
+                  type="checkbox"
+                  class="w-4 h-4 rounded border-border bg-bg text-blue-500 focus:ring-2 focus:ring-blue-500/50 cursor-pointer"
+                />
+                <label
+                  for="word-wrap"
+                  class="text-sm cursor-pointer select-none whitespace-nowrap w-full"
+                >
+                  Word wrap
+                </label>
+              </div>
+
+              <!-- Sliders -->
+              <motion.div
+                class="flex flex-col gap-2"
+                :animate="{ opacity: mergeModifiedLines ? 1 : 0 }"
+              >
+                <!-- Change ratio slider -->
+                <div class="sr-only">
+                  <label for="change-ratio">Change ratio</label>
+                </div>
+                <div
+                  class="slider-shell min-w-[360px]"
+                  :class="{ 'is-disabled': !mergeModifiedLines }"
+                >
+                  <div class="slider-labels">
+                    <span class="slider-label">Change ratio</span>
+                    <span class="slider-value tabular-nums">{{ maxChangeRatio.toFixed(2) }}</span>
+                  </div>
+                  <div class="slider-track">
+                    <div
+                      v-for="mark in changeRatioMarks"
+                      :key="`cr-${mark}`"
+                      class="slider-mark"
+                      :style="{ left: `calc(${mark}% - 11px)` }"
+                    />
+                    <div class="slider-range" :style="{ width: `${changeRatioPercent}%` }" />
+                  </div>
+                  <input
+                    id="change-ratio"
+                    v-model.number="maxChangeRatio"
+                    type="range"
+                    min="0"
+                    max="1"
+                    step="0.01"
+                    :disabled="!mergeModifiedLines"
+                    class="slider-input"
+                  />
+                </div>
+
+                <!-- Diff distance slider -->
+                <div class="sr-only">
+                  <label for="diff-distance">Diff distance</label>
+                </div>
+                <div
+                  class="slider-shell min-w-[360px]"
+                  :class="{ 'is-disabled': !mergeModifiedLines }"
+                >
+                  <div class="slider-labels">
+                    <span class="slider-label">Diff distance</span>
+                    <span class="slider-value tabular-nums">{{ maxDiffDistance }}</span>
+                  </div>
+                  <div class="slider-track">
+                    <div
+                      v-for="mark in diffDistanceMarks"
+                      :key="`dd-${mark}`"
+                      class="slider-mark"
+                      :style="{ left: `calc(${mark}% - 11px)` }"
+                    />
+                    <div class="slider-range" :style="{ width: `${diffDistancePercent}%` }" />
+                  </div>
+                  <input
+                    id="diff-distance"
+                    v-model.number="maxDiffDistance"
+                    type="range"
+                    min="1"
+                    max="60"
+                    step="1"
+                    :disabled="!mergeModifiedLines"
+                    class="slider-input"
+                  />
+                </div>
+
+                <!-- Char edits slider -->
+                <div class="sr-only">
+                  <label for="char-edits">Char edits</label>
+                </div>
+                <div
+                  class="slider-shell min-w-[360px]"
+                  :class="{ 'is-disabled': !mergeModifiedLines }"
+                >
+                  <div class="slider-labels">
+                    <span class="slider-label">Char edits</span>
+                    <span class="slider-value tabular-nums">{{ inlineMaxCharEdits }}</span>
+                  </div>
+                  <div class="slider-track">
+                    <div
+                      v-for="mark in charEditMarks"
+                      :key="`ce-${mark}`"
+                      class="slider-mark"
+                      :style="{ left: `calc(${mark}% - 11px)` }"
+                    />
+                    <div class="slider-range" :style="{ width: `${charEditPercent}%` }" />
+                  </div>
+                  <input
+                    id="char-edits"
+                    v-model.number="inlineMaxCharEdits"
+                    type="range"
+                    min="0"
+                    max="10"
+                    step="1"
+                    :disabled="!mergeModifiedLines"
+                    class="slider-input"
+                  />
+                </div>
+              </motion.div>
+            </div>
+          </motion.div>
+        </div>
+
+        <!-- View in code browser -->
+        <NuxtLink
+          v-if="file.type !== 'removed'"
+          :to="getCodeUrl(toVersion)"
+          class="px-2 py-1 text-xs text-fg-muted hover:text-fg bg-bg-muted border border-border rounded transition-colors"
+          target="_blank"
+        >
+          View file
+        </NuxtLink>
+      </div>
+    </div>
+
+    <!-- Content -->
+    <div class="flex-1 overflow-auto relative">
+      <!-- Loading state -->
+      <div v-if="status === 'pending'" class="py-12 text-center">
+        <div class="i-svg-spinners-ring-resize w-6 h-6 mx-auto text-fg-muted" />
+        <p class="mt-2 text-sm text-fg-muted">Loading diff...</p>
+      </div>
+
+      <!-- Error state -->
+      <div v-else-if="status === 'error'" class="py-8 text-center">
+        <span class="i-carbon-warning-alt w-8 h-8 mx-auto text-fg-subtle mb-2 block" />
+        <p class="text-fg-muted text-sm mb-2">
+          {{ loadError?.message || 'Failed to load diff' }}
+        </p>
+        <div class="flex items-center justify-center gap-2">
+          <NuxtLink
+            v-if="file.type !== 'removed'"
+            :to="getCodeUrl(toVersion)"
+            class="text-xs text-fg-muted hover:text-fg underline"
+          >
+            View in code browser
+          </NuxtLink>
+        </div>
+      </div>
+
+      <!-- No changes -->
+      <div
+        v-else-if="diff && diff.hunks.length === 0"
+        class="py-8 text-center text-fg-muted text-sm"
+      >
+        No content changes detected
+      </div>
+
+      <!-- Diff content -->
+      <DiffTable
+        v-else-if="diff"
+        :hunks="diff.hunks"
+        :type="diff.type"
+        :file-name="file.path"
+        :enable-shiki="true"
+        :word-wrap="wordWrap"
+      />
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.slider-shell {
+  position: relative;
+  display: flex;
+  align-items: center;
+  height: 48px;
+  width: 100%;
+  border: 1px solid var(--border);
+  background: var(--bg-subtle);
+  border-radius: 12px;
+  overflow: hidden;
+  cursor: grab;
+  transition:
+    background-color 150ms ease,
+    border-color 150ms ease,
+    opacity 150ms ease;
+}
+
+.slider-shell:hover {
+  background: var(--bg-muted);
+  border-color: var(--border-hover);
+}
+
+.slider-shell:active {
+  cursor: grabbing;
+}
+
+.slider-shell.is-disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.slider-labels {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0 16px;
+  pointer-events: none;
+  z-index: 3;
+}
+
+.slider-label {
+  font-size: 0.875rem;
+  font-weight: 400;
+  color: color-mix(in srgb, var(--fg) 30%, transparent);
+  letter-spacing: -0.01em;
+  transition: color 150ms ease;
+}
+
+.slider-shell:hover .slider-label {
+  color: var(--fg);
+}
+
+.slider-value {
+  min-width: 32px;
+  text-align: right;
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: var(--fg);
+}
+
+.slider-track {
+  position: absolute;
+  inset: 0;
+  background: var(--bg-muted);
+  border-radius: 10px;
+  overflow: hidden;
+  z-index: 1;
+  pointer-events: none;
+}
+
+.slider-mark {
+  position: absolute;
+  top: 50%;
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: color-mix(in srgb, var(--fg) 20%, transparent);
+  transform: translateY(-50%);
+  pointer-events: none;
+  opacity: 0.9;
+}
+
+.slider-range {
+  position: absolute;
+  inset: 0 auto 0 0;
+  background: var(--bg-subtle);
+  border-radius: 10px;
+  transition:
+    width 150ms ease-out,
+    background-color 150ms ease-out;
+  z-index: 2;
+  pointer-events: none;
+}
+
+.slider-range::after {
+  content: '';
+  position: absolute;
+  right: 8px;
+  top: 50%;
+  width: 2px;
+  height: 28px;
+  border-radius: 12px;
+  background: color-mix(in srgb, var(--fg) 20%, transparent);
+  transform: translateY(-50%);
+  transition: background-color 150ms ease;
+}
+
+.slider-shell:hover .slider-range::after {
+  background: color-mix(in srgb, var(--fg) 50%, transparent);
+}
+
+.slider-input {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  opacity: 0;
+  cursor: inherit;
+  -webkit-appearance: none;
+  background: transparent;
+  z-index: 4;
+  pointer-events: auto;
+  -webkit-tap-highlight-color: transparent;
+}
+
+.slider-input::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  height: 32px;
+  width: 16px;
+}
+
+.slider-input::-moz-range-thumb {
+  height: 32px;
+  width: 16px;
+  border: none;
+  background: transparent;
+}
+</style>
diff --git a/app/pages/[...package].vue b/app/pages/[...package].vue
index ff18b953..6113450b 100644
--- a/app/pages/[...package].vue
+++ b/app/pages/[...package].vue
@@ -518,7 +518,7 @@ defineOgImageComponent('Package', {
               </template>
             </ClientOnly>
 
-            <!-- Internal navigation: Docs + Code (hidden on mobile, shown in external links instead) -->
+            <!-- Internal navigation: Docs + Code + Compare (hidden on mobile, shown in external links instead) -->
             <nav
               v-if="displayVersion"
               :aria-label="$t('package.navigation')"
@@ -556,6 +556,14 @@ defineOgImageComponent('Package', {
                   .
                 </kbd>
               </NuxtLink>
+              <NuxtLink
+                v-if="latestVersion && displayVersion.version !== latestVersion.version"
+                :to="`/compare/${pkg.name}/v/${displayVersion.version}...${latestVersion.version}`"
+                class="px-2 py-1.5 font-mono text-xs rounded transition-colors duration-150 border border-transparent text-fg-subtle hover:text-fg hover:bg-bg hover:shadow hover:border-border focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fg/50 inline-flex items-center gap-1.5"
+              >
+                <span class="i-carbon-compare w-3 h-3" aria-hidden="true" />
+                {{ $t('compare.compare_versions') }}
+              </NuxtLink>
             </nav>
           </div>
 
diff --git a/app/pages/compare/[...path].vue b/app/pages/compare/[...path].vue
new file mode 100644
index 00000000..e9b95d41
--- /dev/null
+++ b/app/pages/compare/[...path].vue
@@ -0,0 +1,427 @@
+<script setup lang="ts">
+import type { CompareResponse, FileChange } from '#shared/types'
+import { getFileIcon } from '~/utils/file-icons'
+
+definePageMeta({
+  name: 'compare',
+})
+
+const route = useRoute('compare')
+const { t } = useI18n()
+
+// Parse package name and version range from URL
+// Patterns:
+// -  /compare/nuxt/v/4.0.0...4.2.0
+// -  /compare/@nuxt/kit/v/1.0.0...2.0.0
+const parsedRoute = computed(() => {
+  const segments = route.params.path || []
+
+  // Find the /v/ separator
+  const vIndex = segments.indexOf('v')
+  if (vIndex === -1 || vIndex >= segments.length - 1) {
+    return { packageName: segments.join('/'), range: null }
+  }
+
+  const packageName = segments.slice(0, vIndex).join('/')
+  const rangeStr = segments[vIndex + 1] ?? ''
+
+  // Parse version range (from...to)
+  const parts = rangeStr.split('...')
+  if (parts.length !== 2) {
+    return { packageName, range: null }
+  }
+
+  return {
+    packageName,
+    range: { from: parts[0]!, to: parts[1]! },
+  }
+})
+
+const packageName = computed(() => parsedRoute.value.packageName)
+const fromVersion = computed(() => parsedRoute.value.range?.from ?? '')
+const toVersion = computed(() => parsedRoute.value.range?.to ?? '')
+
+const { data: pkg } = usePackage(packageName)
+
+const { data: compare, status: compareStatus } = useFetch<CompareResponse>(
+  () => `/api/registry/compare/${packageName.value}/v/${fromVersion.value}...${toVersion.value}`,
+  {
+    immediate: !!parsedRoute.value.range,
+    timeout: 15000,
+  },
+)
+
+const selectedFile = ref<FileChange | null>(null)
+const fileFilter = ref<'all' | 'added' | 'removed' | 'modified'>('all')
+
+const allChanges = computed(() => {
+  if (!compare.value) return []
+  return [
+    ...compare.value.files.added,
+    ...compare.value.files.removed,
+    ...compare.value.files.modified,
+  ].sort((a, b) => a.path.localeCompare(b.path))
+})
+
+const filteredChanges = computed(() => {
+  if (fileFilter.value === 'all') return allChanges.value
+  return allChanges.value.filter(f => f.type === fileFilter.value)
+})
+
+const groupedDeps = computed(() => {
+  if (!compare.value?.dependencyChanges) return new Map()
+
+  const groups = new Map<string, typeof compare.value.dependencyChanges>()
+  for (const change of compare.value.dependencyChanges) {
+    const existing = groups.get(change.section) ?? []
+    existing.push(change)
+    groups.set(change.section, existing)
+  }
+  return groups
+})
+
+function formatSection(section: string): string {
+  switch (section) {
+    case 'dependencies':
+      return 'Dependencies'
+    case 'devDependencies':
+      return 'Dev Dependencies'
+    case 'peerDependencies':
+      return 'Peer Dependencies'
+    case 'optionalDependencies':
+      return 'Optional Dependencies'
+    default:
+      return section
+  }
+}
+
+function getSemverBadgeClass(semverDiff: string | null | undefined): string {
+  switch (semverDiff) {
+    case 'major':
+      return 'bg-red-500/10 text-red-500'
+    case 'minor':
+      return 'bg-yellow-500/10 text-yellow-500'
+    case 'patch':
+      return 'bg-green-500/10 text-green-500'
+    case 'prerelease':
+      return 'bg-purple-500/10 text-purple-500'
+    default:
+      return 'bg-bg-muted text-fg-subtle'
+  }
+}
+
+function getChangeIcon(type: FileChange['type']): string {
+  switch (type) {
+    case 'added':
+      return 'i-carbon-add-alt text-green-500'
+    case 'removed':
+      return 'i-carbon-subtract-alt text-red-500'
+    case 'modified':
+      return 'i-carbon-edit text-yellow-500'
+  }
+}
+
+const fromVersionUrlPattern = computed(() => {
+  return `/compare/${packageName.value}/v/{version}...${toVersion.value}`
+})
+const toVersionUrlPattern = computed(() => {
+  return `/compare/${packageName.value}/v/${fromVersion.value}...{version}`
+})
+
+function getCodeUrl(version: string, path?: string): string {
+  const base = `/code/${packageName.value}/v/${version}`
+  return path ? `${base}/${path}` : base
+}
+
+function packageRoute(ver?: string | null) {
+  const segments = packageName.value.split('/')
+  if (ver) segments.push('v', ver)
+  return { name: 'package' as const, params: { package: segments } }
+}
+
+useSeoMeta({
+  title: () => {
+    if (fromVersion.value && toVersion.value) {
+      return `Compare ${packageName.value} ${fromVersion.value}...${toVersion.value} - npmx`
+    }
+    return `Compare - ${packageName.value} - npmx`
+  },
+  description: () =>
+    `Compare changes between ${packageName.value} versions ${fromVersion.value} and ${toVersion.value}`,
+})
+</script>
+
+<template>
+  <main class="flex-1 flex flex-col min-h-0">
+    <!-- Header -->
+    <header class="border-b border-border bg-bg sticky top-14 z-20">
+      <div class="container py-4">
+        <!-- Package info -->
+        <div class="flex items-center gap-2 mb-3 flex-wrap min-w-0">
+          <NuxtLink
+            :to="packageRoute()"
+            class="font-mono text-lg font-medium hover:text-fg transition-colors min-w-0 truncate"
+          >
+            {{ packageName }}
+          </NuxtLink>
+          <span class="text-fg-subtle">/</span>
+          <span class="font-mono text-sm text-fg-muted">compare</span>
+        </div>
+
+        <!-- Version selectors -->
+        <div class="flex items-center gap-3 flex-wrap">
+          <div class="flex items-center gap-2">
+            <span class="text-xs text-fg-subtle uppercase tracking-wide">From</span>
+            <VersionSelector
+              v-if="pkg?.versions && pkg?.['dist-tags']"
+              :package-name="packageName"
+              :current-version="fromVersion"
+              :versions="pkg.versions"
+              :dist-tags="pkg['dist-tags']"
+              :url-pattern="fromVersionUrlPattern"
+            />
+            <span v-else class="font-mono text-sm text-fg-muted">{{ fromVersion }}</span>
+          </div>
+
+          <span class="i-carbon-arrow-right w-4 h-4 text-fg-subtle" />
+
+          <div class="flex items-center gap-2">
+            <span class="text-xs text-fg-subtle uppercase tracking-wide">To</span>
+            <VersionSelector
+              v-if="pkg?.versions && pkg?.['dist-tags']"
+              :package-name="packageName"
+              :current-version="toVersion"
+              :versions="pkg.versions"
+              :dist-tags="pkg['dist-tags']"
+              :url-pattern="toVersionUrlPattern"
+            />
+            <span v-else class="font-mono text-sm text-fg-muted">{{ toVersion }}</span>
+          </div>
+        </div>
+      </div>
+    </header>
+
+    <!-- Error: invalid route -->
+    <div v-if="!parsedRoute.range" class="container py-20 text-center">
+      <p class="text-fg-muted mb-4">
+        Invalid comparison URL. Use format: /compare/package/v/from...to
+      </p>
+      <NuxtLink :to="packageRoute()" class="btn">Go to package</NuxtLink>
+    </div>
+
+    <!-- Loading state -->
+    <div v-else-if="compareStatus === 'pending'" class="container py-20 text-center">
+      <div class="i-svg-spinners-ring-resize w-8 h-8 mx-auto text-fg-muted" />
+      <p class="mt-4 text-fg-muted">Comparing versions...</p>
+    </div>
+
+    <!-- Error state -->
+    <div v-else-if="compareStatus === 'error'" class="container py-20 text-center" role="alert">
+      <p class="text-fg-muted mb-4">Failed to compare versions</p>
+      <NuxtLink :to="packageRoute()" class="btn">Back to package</NuxtLink>
+    </div>
+
+    <!-- Comparison content - 2 column layout -->
+    <div v-else-if="compare" class="flex-1 flex min-h-0 overflow-hidden">
+      <!-- Left sidebar: Summary + File browser -->
+      <aside class="w-80 border-r border-border bg-bg-subtle flex flex-col shrink-0">
+        <!-- Summary section -->
+        <div class="border-b border-border shrink-0">
+          <!-- Header with stats -->
+          <div class="px-3 py-2.5 border-b border-border">
+            <div class="flex items-center justify-between">
+              <h2 class="text-xs font-medium">Summary</h2>
+              <div class="flex items-center gap-3 font-mono text-[10px]">
+                <span class="flex items-center gap-1">
+                  <span class="text-green-500">+{{ compare.stats.filesAdded }}</span>
+                  <span class="text-fg-subtle">/</span>
+                  <span class="text-red-500">-{{ compare.stats.filesRemoved }}</span>
+                  <span class="text-fg-subtle">/</span>
+                  <span class="text-yellow-500">~{{ compare.stats.filesModified }}</span>
+                </span>
+                <span v-if="compare.dependencyChanges.length > 0" class="text-fg-muted">
+                  {{ compare.dependencyChanges.length }} dep{{
+                    compare.dependencyChanges.length !== 1 ? 's' : ''
+                  }}
+                </span>
+              </div>
+            </div>
+          </div>
+
+          <!-- Warnings -->
+          <div
+            v-if="compare.meta.warnings?.length"
+            class="px-3 py-2 bg-yellow-500/5 border-b border-border"
+          >
+            <div class="flex items-start gap-2">
+              <span class="i-carbon-warning w-3.5 h-3.5 text-yellow-500 shrink-0 mt-0.5" />
+              <div class="text-[10px] text-fg-muted">
+                <p v-for="warning in compare.meta.warnings" :key="warning">{{ warning }}</p>
+              </div>
+            </div>
+          </div>
+
+          <!-- Dependency changes -->
+          <div v-if="compare.dependencyChanges.length > 0" class="px-3 py-2.5">
+            <details class="group">
+              <summary
+                class="cursor-pointer list-none flex items-center gap-2 text-xs font-medium mb-2 hover:text-fg transition-colors"
+              >
+                <span
+                  class="i-carbon-chevron-right w-3.5 h-3.5 transition-transform group-open:rotate-90"
+                />
+                <span class="i-carbon-cube w-3.5 h-3.5" />
+                Dependencies ({{ compare.dependencyChanges.length }})
+              </summary>
+
+              <div class="space-y-2 ml-5 max-h-40 overflow-y-auto">
+                <div v-for="[section, changes] in groupedDeps" :key="section">
+                  <div
+                    class="text-[10px] font-medium text-fg-subtle uppercase tracking-wide mb-1.5"
+                  >
+                    {{ formatSection(section) }}
+                  </div>
+                  <div class="space-y-1">
+                    <div
+                      v-for="dep in changes"
+                      :key="dep.name"
+                      class="flex items-center gap-2 text-xs py-0.5"
+                    >
+                      <!-- Change type icon -->
+                      <span
+                        :class="[
+                          'w-3 h-3 shrink-0',
+                          dep.type === 'added'
+                            ? 'i-carbon-add-alt text-green-500'
+                            : dep.type === 'removed'
+                              ? 'i-carbon-subtract-alt text-red-500'
+                              : 'i-carbon-arrows-horizontal text-yellow-500',
+                        ]"
+                      />
+
+                      <!-- Package name -->
+                      <NuxtLink
+                        :to="`/${dep.name}`"
+                        class="font-mono hover:text-fg transition-colors truncate min-w-0"
+                      >
+                        {{ dep.name }}
+                      </NuxtLink>
+
+                      <!-- Version change -->
+                      <div
+                        class="flex items-center gap-1.5 text-fg-muted font-mono text-[10px] ml-auto shrink-0"
+                      >
+                        <span
+                          v-if="dep.from"
+                          :class="{ 'line-through opacity-50': dep.type === 'updated' }"
+                        >
+                          {{ dep.from }}
+                        </span>
+                        <span
+                          v-if="dep.type === 'updated'"
+                          class="i-carbon-arrow-right w-2.5 h-2.5"
+                        />
+                        <span v-if="dep.to">{{ dep.to }}</span>
+                      </div>
+
+                      <!-- Semver badge -->
+                      <span
+                        v-if="dep.semverDiff"
+                        class="text-[9px] px-1.5 py-0.5 rounded font-medium shrink-0"
+                        :class="getSemverBadgeClass(dep.semverDiff)"
+                      >
+                        {{ dep.semverDiff }}
+                      </span>
+                    </div>
+                  </div>
+                </div>
+              </div>
+            </details>
+          </div>
+
+          <!-- Empty state -->
+          <div
+            v-if="compare.dependencyChanges.length === 0 && !compare.meta.warnings?.length"
+            class="px-3 py-2 text-[10px] text-fg-muted text-center"
+          >
+            No dependency changes
+          </div>
+        </div>
+
+        <!-- File browser header with dropdown filter -->
+        <div class="border-b border-border px-3 py-2 shrink-0 bg-bg-muted">
+          <div class="flex items-center justify-between gap-2">
+            <h2 class="text-xs font-medium flex items-center gap-1.5">
+              <span class="i-carbon-document w-3.5 h-3.5" />
+              Changed Files
+            </h2>
+
+            <!-- Filter dropdown -->
+            <select
+              v-model="fileFilter"
+              class="text-[10px] px-2 py-1 bg-bg-subtle border border-border rounded font-mono cursor-pointer hover:border-border-hover transition-colors"
+            >
+              <option value="all">All ({{ allChanges.length }})</option>
+              <option value="added">Added ({{ compare.stats.filesAdded }})</option>
+              <option value="removed">Removed ({{ compare.stats.filesRemoved }})</option>
+              <option value="modified">Modified ({{ compare.stats.filesModified }})</option>
+            </select>
+          </div>
+        </div>
+
+        <!-- File list (scrollable) -->
+        <div class="flex-1 overflow-y-auto min-h-0">
+          <div v-if="filteredChanges.length === 0" class="p-8 text-center text-xs text-fg-muted">
+            No {{ fileFilter === 'all' ? '' : fileFilter }} files
+          </div>
+
+          <nav v-else class="divide-y divide-border">
+            <button
+              v-for="file in filteredChanges"
+              :key="file.path"
+              type="button"
+              class="w-full px-3 py-2 flex items-center gap-2 text-sm text-left hover:bg-bg-muted transition-colors group"
+              :class="{
+                'bg-bg-muted border-l-3 border-l-blue-500': selectedFile?.path === file.path,
+              }"
+              @click="selectedFile = file"
+            >
+              <!-- File icon -->
+              <span :class="[getFileIcon(file.path), 'w-3.5 h-3.5 shrink-0']" />
+
+              <!-- Change type indicator -->
+              <span :class="[getChangeIcon(file.type), 'w-3 h-3 shrink-0']" />
+
+              <!-- File path -->
+              <span class="font-mono text-[10px] truncate min-w-0 group-hover:text-fg">
+                {{ file.path }}
+              </span>
+            </button>
+          </nav>
+        </div>
+      </aside>
+
+      <!-- Right side: Diff viewer -->
+      <div class="flex-1 flex flex-col min-w-0 overflow-hidden">
+        <!-- Diff viewer panel -->
+        <div class="flex-1 overflow-hidden bg-bg-subtle">
+          <DiffViewerPanel
+            v-if="selectedFile"
+            :package-name="packageName"
+            :from-version="fromVersion"
+            :to-version="toVersion"
+            :file="selectedFile"
+          />
+          <div v-else class="h-full flex items-center justify-center text-center p-8">
+            <div>
+              <span
+                class="i-carbon-document-blank w-16 h-16 mx-auto text-fg-subtle/50 block mb-4"
+              />
+              <p class="text-fg-muted">Select a file from the sidebar to view its diff</p>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </main>
+</template>
diff --git a/app/utils/language-detection.ts b/app/utils/language-detection.ts
new file mode 100644
index 00000000..5848a9c8
--- /dev/null
+++ b/app/utils/language-detection.ts
@@ -0,0 +1,75 @@
+/**
+ * Guess the programming language from a file path for syntax highlighting.
+ * NOTE: We aren't using this for any other language besides JS/TS/JSON.
+ */
+export function guessLanguageFromPath(filePath: string): string {
+  const fileName = filePath.split('/').pop() || ''
+  const ext = fileName.split('.').pop()?.toLowerCase() || ''
+
+  // Extension-based mapping
+  const extMap: Record<string, string> = {
+    // JavaScript/TypeScript
+    js: 'javascript',
+    mjs: 'javascript',
+    cjs: 'javascript',
+    jsx: 'jsx',
+    ts: 'typescript',
+    mts: 'typescript',
+    cts: 'typescript',
+    tsx: 'tsx',
+
+    // Web
+    html: 'html',
+    htm: 'html',
+    css: 'css',
+    scss: 'scss',
+    sass: 'scss',
+    less: 'less',
+    vue: 'vue',
+    svelte: 'svelte',
+    astro: 'astro',
+
+    // Data/Config
+    json: 'json',
+    jsonc: 'jsonc',
+    json5: 'json',
+    yaml: 'yaml',
+    yml: 'yaml',
+    toml: 'toml',
+    xml: 'xml',
+    svg: 'xml',
+
+    // Documentation
+    md: 'markdown',
+    mdx: 'markdown',
+    txt: 'text',
+
+    // Shell
+    sh: 'bash',
+    bash: 'bash',
+    zsh: 'bash',
+    fish: 'bash',
+
+    // Other languages
+    py: 'python',
+    rs: 'rust',
+    go: 'go',
+    sql: 'sql',
+    graphql: 'graphql',
+    gql: 'graphql',
+    diff: 'diff',
+    patch: 'diff',
+  }
+
+  // Special filename mapping
+  const filenameMap: Record<string, string> = {
+    Dockerfile: 'dockerfile',
+    Makefile: 'makefile',
+  }
+
+  if (filenameMap[fileName]) {
+    return filenameMap[fileName]
+  }
+
+  return extMap[ext] || 'text'
+}
diff --git a/app/utils/shiki-client.ts b/app/utils/shiki-client.ts
new file mode 100644
index 00000000..62974580
--- /dev/null
+++ b/app/utils/shiki-client.ts
@@ -0,0 +1,24 @@
+import { createHighlighterCore, type HighlighterCore } from 'shiki/core'
+import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
+import githubDark from '@shikijs/themes/github-dark'
+import githubLight from '@shikijs/themes/github-light'
+import javascript from '@shikijs/langs/javascript'
+import typescript from '@shikijs/langs/typescript'
+import json from '@shikijs/langs/json'
+
+let highlighterPromise: Promise<HighlighterCore> | null = null
+
+/**
+ * Lightweight client-side Shiki highlighter (JS/TS/JSON only).
+ */
+export function getClientHighlighter(): Promise<HighlighterCore> {
+  if (highlighterPromise) return highlighterPromise
+
+  highlighterPromise = createHighlighterCore({
+    themes: [githubDark, githubLight],
+    langs: [javascript, typescript, json],
+    engine: createJavaScriptRegexEngine(),
+  })
+
+  return highlighterPromise
+}
diff --git a/i18n/locales/en.json b/i18n/locales/en.json
index e6b85967..850e1048 100644
--- a/i18n/locales/en.json
+++ b/i18n/locales/en.json
@@ -617,5 +617,29 @@
       "empty": "No organizations found",
       "view_all": "View all"
     }
+  },
+  "compare": {
+    "title": "Compare Versions",
+    "from": "From",
+    "to": "To",
+    "comparing": "Comparing versions...",
+    "invalid_url": "Invalid comparison URL. Use format: /compare/package/v/from...to",
+    "failed": "Failed to compare versions",
+    "files_added": "Files added",
+    "files_removed": "Files removed",
+    "files_modified": "Files modified",
+    "deps_changed": "Deps changed",
+    "dependency_changes": "Dependency Changes",
+    "file_changes": "File Changes",
+    "files_count": "{count} files",
+    "no_file_changes": "No file changes detected",
+    "no_content_changes": "No content changes detected",
+    "loading_diff": "Loading diff...",
+    "failed_to_load_diff": "Failed to load diff",
+    "view_file": "View file",
+    "view_in_browser": "View in code browser",
+    "close_diff": "Close diff",
+    "lines_hidden": "{count} lines hidden",
+    "compare_versions": "Compare versions"
   }
 }
diff --git a/lunaria/files/en-US.json b/lunaria/files/en-US.json
index 21ad0964..5ea20d7d 100644
--- a/lunaria/files/en-US.json
+++ b/lunaria/files/en-US.json
@@ -617,5 +617,29 @@
       "empty": "No organizations found",
       "view_all": "View all"
     }
+  },
+  "compare": {
+    "title": "Compare Versions",
+    "from": "From",
+    "to": "To",
+    "comparing": "Comparing versions...",
+    "invalid_url": "Invalid comparison URL. Use format: /compare/package/v/from...to",
+    "failed": "Failed to compare versions",
+    "files_added": "Files added",
+    "files_removed": "Files removed",
+    "files_modified": "Files modified",
+    "deps_changed": "Deps changed",
+    "dependency_changes": "Dependency Changes",
+    "file_changes": "File Changes",
+    "files_count": "{count} files",
+    "no_file_changes": "No file changes detected",
+    "no_content_changes": "No content changes detected",
+    "loading_diff": "Loading diff...",
+    "failed_to_load_diff": "Failed to load diff",
+    "view_file": "View file",
+    "view_in_browser": "View in code browser",
+    "close_diff": "Close diff",
+    "lines_hidden": "{count} lines hidden",
+    "compare_versions": "Compare versions"
   }
 }
diff --git a/package.json b/package.json
index 4c4f55fc..0b0ee75a 100644
--- a/package.json
+++ b/package.json
@@ -46,6 +46,7 @@
     "@shikijs/themes": "^3.21.0",
     "@vueuse/core": "^14.1.0",
     "@vueuse/nuxt": "14.1.0",
+    "diff": "^8.0.3",
     "nuxt": "^4.3.0",
     "nuxt-og-image": "^5.1.13",
     "ohash": "^2.0.11",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index cd8092b9..007d73e6 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -65,6 +65,9 @@ importers:
       '@vueuse/nuxt':
         specifier: 14.1.0
         version: 14.1.0(magicast@0.5.1)(nuxt@4.3.0(@parcel/watcher@2.5.6)(@types/node@24.10.9)(@vue/compiler-sfc@3.5.27)(better-sqlite3@12.5.0)(cac@6.7.14)(db0@0.3.4(better-sqlite3@12.5.0))(eslint@9.39.2(jiti@2.6.1))(ioredis@5.9.2)(magicast@0.5.1)(optionator@0.9.4)(oxlint@1.42.0(oxlint-tsgolint@0.11.2))(rolldown@1.0.0-rc.1)(rollup@4.57.0)(terser@5.46.0)(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.9)(jiti@2.6.1)(lightningcss@1.31.1)(terser@5.46.0)(yaml@2.8.2))(vue-tsc@3.2.2(typescript@5.9.3))(yaml@2.8.2))(vue@3.5.27(typescript@5.9.3))
+      diff:
+        specifier: ^8.0.3
+        version: 8.0.3
       nuxt:
         specifier: ^4.3.0
         version: 4.3.0(@parcel/watcher@2.5.6)(@types/node@24.10.9)(@vue/compiler-sfc@3.5.27)(better-sqlite3@12.5.0)(cac@6.7.14)(db0@0.3.4(better-sqlite3@12.5.0))(eslint@9.39.2(jiti@2.6.1))(ioredis@5.9.2)(magicast@0.5.1)(optionator@0.9.4)(oxlint@1.42.0(oxlint-tsgolint@0.11.2))(rolldown@1.0.0-rc.1)(rollup@4.57.0)(terser@5.46.0)(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.9)(jiti@2.6.1)(lightningcss@1.31.1)(terser@5.46.0)(yaml@2.8.2))(vue-tsc@3.2.2(typescript@5.9.3))(yaml@2.8.2)
@@ -2238,9 +2241,16 @@ packages:
     resolution: {integrity: sha512-4t5lYmPneAGKGN7zDhK2iQrn+Ax3DXLCNqVr3z6K2VqemKWfQTlLyzjgjilxZmwFAKe65qI4WG7Bsj05UgUHaA==}
     engines: {node: ^20.19.0 || >=22.12.0}
 
+  '@oxc-project/runtime@0.111.0':
+    resolution: {integrity: sha512-Hssa3lXfhczG0Qx0XB6NXLQTKrKeWSPDxcHqddCmBVnOQnlgE8Z+omcPHiewvvvZjSw8RgUPQCU5a+rx/vZ1YA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+
   '@oxc-project/types@0.110.0':
     resolution: {integrity: sha512-6Ct21OIlrEnFEJk5LT4e63pk3btsI6/TusD/GStLi7wYlGJNOl1GI9qvXAnRAxQU9zqA2Oz+UwhfTOU2rPZVow==}
 
+  '@oxc-project/types@0.111.0':
+    resolution: {integrity: sha512-bh54LJMafgRGl2cPQ/QM+tI5rWaShm/wK9KywEj/w36MhiPKXYM67H2y3q+9pr4YO7ufwg2AKdBAZkhHBD8ClA==}
+
   '@oxc-project/types@0.95.0':
     resolution: {integrity: sha512-vACy7vhpMPhjEJhULNxrdR0D943TkA/MigMpJCHmBHvMXxRStRi/dPtTlfQ3uDwWSzRpT8z+7ImjZVf8JWBocQ==}
 
@@ -3869,8 +3879,8 @@ packages:
   '@vitest/utils@4.0.18':
     resolution: {integrity: sha512-msMRKLMVLWygpK3u2Hybgi4MNjcYJvwTb0Ru09+fOyCXIgT5raYP041DRRdiJiI3k/2U6SEbAETB3YtBrUkCFA==}
 
-  '@voidzero-dev/vite-plus-core@0.0.0-dfd5c99899261c54d5b19dceaa831fab310d6171':
-    resolution: {integrity: sha512-tNNx5L88Wzd5ABY/fggYsu1h4iK8u9zqSAby9DH/p6dP+FgFD/WgI3Uxnqymik1Zg7I/7x+pQ+819fUkG0EpyQ==}
+  '@voidzero-dev/vite-plus-core@0.0.0-40918e094cfc5866505c7c99ca8187c4793b88f6':
+    resolution: {integrity: sha512-fa6obN+CTIyk2lr+nIoM2urKyo9AvHnrp716rHqPid3ESHyTL7KJCf7NNPTcRaEhXo2Lss++vRaz2Hh9Jb+pVA==}
     engines: {node: ^20.19.0 || >=22.12.0}
     peerDependencies:
       '@arethetypeswrong/core': ^0.18.1
@@ -11280,8 +11290,8 @@ snapshots:
     dependencies:
       '@nuxt/kit': 4.3.0(magicast@0.5.1)
       '@rollup/plugin-replace': 6.0.3(rollup@4.57.0)
-      '@vitejs/plugin-vue': 6.0.3(@voidzero-dev/vite-plus-core@0.0.0-dfd5c99899261c54d5b19dceaa831fab310d6171(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2))(vue@3.5.27(typescript@5.9.3))
-      '@vitejs/plugin-vue-jsx': 5.1.3(@voidzero-dev/vite-plus-core@0.0.0-dfd5c99899261c54d5b19dceaa831fab310d6171(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2))(vue@3.5.27(typescript@5.9.3))
+      '@vitejs/plugin-vue': 6.0.3(@voidzero-dev/vite-plus-core@0.0.0-40918e094cfc5866505c7c99ca8187c4793b88f6(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2))(vue@3.5.27(typescript@5.9.3))
+      '@vitejs/plugin-vue-jsx': 5.1.3(@voidzero-dev/vite-plus-core@0.0.0-40918e094cfc5866505c7c99ca8187c4793b88f6(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2))(vue@3.5.27(typescript@5.9.3))
       autoprefixer: 10.4.23(postcss@8.5.6)
       consola: 3.4.2
       cssnano: 7.1.2(postcss@8.5.6)
@@ -11304,9 +11314,9 @@ snapshots:
       std-env: 3.10.0
       ufo: 1.6.3
       unenv: 2.0.0-rc.24
-      vite: '@voidzero-dev/vite-plus-core@0.0.0-dfd5c99899261c54d5b19dceaa831fab310d6171(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2)'
+      vite: '@voidzero-dev/vite-plus-core@0.0.0-40918e094cfc5866505c7c99ca8187c4793b88f6(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2)'
       vite-node: 5.3.0(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2)
-      vite-plugin-checker: 0.12.0(@voidzero-dev/vite-plus-core@0.0.0-dfd5c99899261c54d5b19dceaa831fab310d6171(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2))(eslint@9.39.2(jiti@2.6.1))(optionator@0.9.4)(oxlint@1.42.0(oxlint-tsgolint@0.11.2))(typescript@5.9.3)(vue-tsc@3.2.2(typescript@5.9.3))
+      vite-plugin-checker: 0.12.0(@voidzero-dev/vite-plus-core@0.0.0-40918e094cfc5866505c7c99ca8187c4793b88f6(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2))(eslint@9.39.2(jiti@2.6.1))(optionator@0.9.4)(oxlint@1.42.0(oxlint-tsgolint@0.11.2))(typescript@5.9.3)(vue-tsc@3.2.2(typescript@5.9.3))
       vue: 3.5.27(typescript@5.9.3)
       vue-bundle-renderer: 2.2.0
     optionalDependencies:
@@ -11695,8 +11705,12 @@ snapshots:
 
   '@oxc-project/runtime@0.110.0': {}
 
+  '@oxc-project/runtime@0.111.0': {}
+
   '@oxc-project/types@0.110.0': {}
 
+  '@oxc-project/types@0.111.0': {}
+
   '@oxc-project/types@0.95.0': {}
 
   '@oxc-resolver/binding-android-arm-eabi@11.16.4':
@@ -13081,22 +13095,22 @@ snapshots:
       - workbox-build
       - workbox-window
 
-  '@vitejs/plugin-vue-jsx@5.1.3(@voidzero-dev/vite-plus-core@0.0.0-dfd5c99899261c54d5b19dceaa831fab310d6171(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2))(vue@3.5.27(typescript@5.9.3))':
+  '@vitejs/plugin-vue-jsx@5.1.3(@voidzero-dev/vite-plus-core@0.0.0-40918e094cfc5866505c7c99ca8187c4793b88f6(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2))(vue@3.5.27(typescript@5.9.3))':
     dependencies:
       '@babel/core': 7.28.6
       '@babel/plugin-syntax-typescript': 7.28.6(@babel/core@7.28.6)
       '@babel/plugin-transform-typescript': 7.28.6(@babel/core@7.28.6)
       '@rolldown/pluginutils': 1.0.0-rc.1
       '@vue/babel-plugin-jsx': 2.0.1(@babel/core@7.28.6)
-      vite: '@voidzero-dev/vite-plus-core@0.0.0-dfd5c99899261c54d5b19dceaa831fab310d6171(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2)'
+      vite: '@voidzero-dev/vite-plus-core@0.0.0-40918e094cfc5866505c7c99ca8187c4793b88f6(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2)'
       vue: 3.5.27(typescript@5.9.3)
     transitivePeerDependencies:
       - supports-color
 
-  '@vitejs/plugin-vue@6.0.3(@voidzero-dev/vite-plus-core@0.0.0-dfd5c99899261c54d5b19dceaa831fab310d6171(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2))(vue@3.5.27(typescript@5.9.3))':
+  '@vitejs/plugin-vue@6.0.3(@voidzero-dev/vite-plus-core@0.0.0-40918e094cfc5866505c7c99ca8187c4793b88f6(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2))(vue@3.5.27(typescript@5.9.3))':
     dependencies:
       '@rolldown/pluginutils': 1.0.0-beta.53
-      vite: '@voidzero-dev/vite-plus-core@0.0.0-dfd5c99899261c54d5b19dceaa831fab310d6171(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2)'
+      vite: '@voidzero-dev/vite-plus-core@0.0.0-40918e094cfc5866505c7c99ca8187c4793b88f6(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2)'
       vue: 3.5.27(typescript@5.9.3)
 
   '@vitest/browser-playwright@4.0.18(@voidzero-dev/vite-plus-test@0.0.0-ffb4d08a8edafe855c59736c0a38ee85a2373ebb(@types/node@24.10.9)(esbuild@0.27.2)(happy-dom@20.3.5)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2))(playwright@1.57.0)(vite@7.3.1(@types/node@24.10.9)(jiti@2.6.1)(lightningcss@1.31.1)(terser@5.46.0)(yaml@2.8.2))':
@@ -13164,10 +13178,10 @@ snapshots:
       '@vitest/pretty-format': 4.0.18
       tinyrainbow: 3.0.3
 
-  '@voidzero-dev/vite-plus-core@0.0.0-dfd5c99899261c54d5b19dceaa831fab310d6171(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2)':
+  '@voidzero-dev/vite-plus-core@0.0.0-40918e094cfc5866505c7c99ca8187c4793b88f6(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2)':
     dependencies:
-      '@oxc-project/runtime': 0.110.0
-      '@oxc-project/types': 0.110.0
+      '@oxc-project/runtime': 0.111.0
+      '@oxc-project/types': 0.111.0
       lightningcss: 1.31.1
       postcss: 8.5.6
     optionalDependencies:
@@ -19169,7 +19183,7 @@ snapshots:
       es-module-lexer: 2.0.0
       obug: 2.1.1
       pathe: 2.0.3
-      vite: '@voidzero-dev/vite-plus-core@0.0.0-dfd5c99899261c54d5b19dceaa831fab310d6171(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2)'
+      vite: '@voidzero-dev/vite-plus-core@0.0.0-40918e094cfc5866505c7c99ca8187c4793b88f6(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2)'
     transitivePeerDependencies:
       - '@arethetypeswrong/core'
       - '@types/node'
@@ -19189,7 +19203,7 @@ snapshots:
       - unplugin-unused
       - yaml
 
-  vite-plugin-checker@0.12.0(@voidzero-dev/vite-plus-core@0.0.0-dfd5c99899261c54d5b19dceaa831fab310d6171(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2))(eslint@9.39.2(jiti@2.6.1))(optionator@0.9.4)(oxlint@1.42.0(oxlint-tsgolint@0.11.2))(typescript@5.9.3)(vue-tsc@3.2.2(typescript@5.9.3)):
+  vite-plugin-checker@0.12.0(@voidzero-dev/vite-plus-core@0.0.0-40918e094cfc5866505c7c99ca8187c4793b88f6(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2))(eslint@9.39.2(jiti@2.6.1))(optionator@0.9.4)(oxlint@1.42.0(oxlint-tsgolint@0.11.2))(typescript@5.9.3)(vue-tsc@3.2.2(typescript@5.9.3)):
     dependencies:
       '@babel/code-frame': 7.28.6
       chokidar: 4.0.3
@@ -19198,7 +19212,7 @@ snapshots:
       picomatch: 4.0.3
       tiny-invariant: 1.3.3
       tinyglobby: 0.2.15
-      vite: '@voidzero-dev/vite-plus-core@0.0.0-dfd5c99899261c54d5b19dceaa831fab310d6171(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2)'
+      vite: '@voidzero-dev/vite-plus-core@0.0.0-40918e094cfc5866505c7c99ca8187c4793b88f6(@types/node@24.10.9)(esbuild@0.27.2)(jiti@2.6.1)(terser@5.46.0)(typescript@5.9.3)(yaml@2.8.2)'
       vscode-uri: 3.1.0
     optionalDependencies:
       eslint: 9.39.2(jiti@2.6.1)
diff --git a/server/api/registry/compare-file/[...pkg].get.ts b/server/api/registry/compare-file/[...pkg].get.ts
new file mode 100644
index 00000000..b7fdacca
--- /dev/null
+++ b/server/api/registry/compare-file/[...pkg].get.ts
@@ -0,0 +1,248 @@
+import * as v from 'valibot'
+import { PackageFileDiffQuerySchema } from '#shared/schemas/package'
+import type { FileDiffResponse, DiffHunk } from '#shared/types'
+import { CACHE_MAX_AGE_ONE_YEAR } from '#shared/utils/constants'
+import { createDiff, insertSkipBlocks, countDiffStats } from '#server/utils/diff'
+
+const CACHE_VERSION = 1
+const DIFF_TIMEOUT = 15000 // 15 sec
+
+/** Maximum file size for diffing (250KB - smaller than viewing since we diff two files) */
+const MAX_DIFF_FILE_SIZE = 250 * 1024
+
+/**
+ * Parse the version range from the URL.
+ * Supports formats like: "1.0.0...2.0.0" or "1.0.0..2.0.0"
+ */
+function parseVersionRange(versionRange: string): { from: string; to: string } | null {
+  // Try triple dot first (GitHub style)
+  let parts = versionRange.split('...')
+  if (parts.length === 2) {
+    return { from: parts[0]!, to: parts[1]! }
+  }
+
+  // Try double dot
+  parts = versionRange.split('..')
+  if (parts.length === 2) {
+    return { from: parts[0]!, to: parts[1]! }
+  }
+
+  return null
+}
+
+/**
+ * Fetch file content from jsDelivr with size check
+ */
+async function fetchFileContentForDiff(
+  packageName: string,
+  version: string,
+  filePath: string,
+  signal?: AbortSignal,
+): Promise<string | null> {
+  const url = `https://cdn.jsdelivr.net/npm/${packageName}@${version}/${filePath}`
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort(), DIFF_TIMEOUT)
+  if (signal) {
+    signal.addEventListener('abort', () => controller.abort(signal.reason as any), { once: true })
+  }
+
+  try {
+    const response = await fetch(url, { signal: controller.signal })
+
+    if (!response.ok) {
+      if (response.status === 404) return null
+      throw createError({
+        statusCode: response.status >= 500 ? 502 : response.status,
+        message: `Failed to fetch file (${response.status})`,
+      })
+    }
+
+    const contentLength = response.headers.get('content-length')
+    if (contentLength && parseInt(contentLength, 10) > MAX_DIFF_FILE_SIZE) {
+      throw createError({
+        statusCode: 413,
+        message: `File too large to diff (${(parseInt(contentLength, 10) / 1024).toFixed(0)}KB). Maximum is ${MAX_DIFF_FILE_SIZE / 1024}KB.`,
+      })
+    }
+
+    const content = await response.text()
+
+    if (content.length > MAX_DIFF_FILE_SIZE) {
+      throw createError({
+        statusCode: 413,
+        message: `File too large to diff (${(content.length / 1024).toFixed(0)}KB). Maximum is ${MAX_DIFF_FILE_SIZE / 1024}KB.`,
+      })
+    }
+
+    return content
+  } catch (error) {
+    if (error && typeof error === 'object' && 'statusCode' in error) {
+      throw error
+    }
+    if ((error as Error)?.name === 'AbortError') {
+      throw createError({
+        statusCode: 504,
+        message: 'Diff request timed out while fetching file',
+      })
+    }
+    throw createError({
+      statusCode: 502,
+      message: 'Failed to fetch file for diff',
+    })
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+/**
+ * Get diff for a specific file between two versions.
+ *
+ * URL patterns:
+ * - /api/registry/compare-file/packageName/v/1.0.0...2.0.0/path/to/file.ts
+ * - /api/registry/compare-file/@scope/packageName/v/1.0.0...2.0.0/path/to/file.ts
+ */
+export default defineCachedEventHandler(
+  async event => {
+    const startTime = Date.now()
+
+    // Parse package segments
+    const pkgParamSegments = getRouterParam(event, 'pkg')?.split('/') ?? []
+    const { rawPackageName, rawVersion: fullPathAfterV } = parsePackageParams(pkgParamSegments)
+
+    // Split version range and file path
+    // fullPathAfterV => "1.0.0...2.0.0/dist/index.mjs"
+    const versionSegments = fullPathAfterV?.split('/') ?? []
+
+    if (versionSegments.length < 2) {
+      throw createError({
+        statusCode: 400,
+        message: 'Version range and file path are required',
+      })
+    }
+
+    // First segment contains the version range
+    const rawVersionRange = versionSegments[0]!
+    const rawFilePath = versionSegments.slice(1).join('/')
+
+    // Parse version range
+    const range = parseVersionRange(rawVersionRange)
+    if (!range) {
+      throw createError({
+        statusCode: 400,
+        message: 'Invalid version range format. Use from...to (e.g., 1.0.0...2.0.0)',
+      })
+    }
+
+    try {
+      // Validate inputs
+      const { packageName, fromVersion, toVersion, filePath } = v.parse(
+        PackageFileDiffQuerySchema,
+        {
+          packageName: rawPackageName,
+          fromVersion: range.from,
+          toVersion: range.to,
+          filePath: rawFilePath,
+        },
+      )
+
+      // Set up abort controller for timeout
+      const controller = new AbortController()
+      const timeoutId = setTimeout(() => controller.abort(), DIFF_TIMEOUT)
+
+      try {
+        // Get diff options from query params
+        const query = getQuery(event)
+        const diffOptions = {
+          mergeModifiedLines: query.mergeModifiedLines !== 'false',
+          maxChangeRatio: parseFloat(query.maxChangeRatio as string) || 0.45,
+          maxDiffDistance: parseInt(query.maxDiffDistance as string, 10) || 30,
+          inlineMaxCharEdits: parseInt(query.inlineMaxCharEdits as string, 10) || 2,
+        }
+
+        // Fetch file contents in parallel
+        const [fromContent, toContent] = await Promise.all([
+          fetchFileContentForDiff(packageName, fromVersion, filePath, controller.signal),
+          fetchFileContentForDiff(packageName, toVersion, filePath, controller.signal),
+        ])
+
+        clearTimeout(timeoutId)
+
+        // Determine file type
+        let type: 'add' | 'delete' | 'modify'
+        if (fromContent === null && toContent === null) {
+          throw createError({
+            statusCode: 404,
+            message: 'File not found in either version',
+          })
+        } else if (fromContent === null) {
+          type = 'add'
+        } else if (toContent === null) {
+          type = 'delete'
+        } else {
+          type = 'modify'
+        }
+
+        // Create diff with options
+        const diff = createDiff(fromContent ?? '', toContent ?? '', filePath, diffOptions)
+
+        if (!diff) {
+          // No changes (shouldn't happen but handle it)
+          return {
+            package: packageName,
+            from: fromVersion,
+            to: toVersion,
+            path: filePath,
+            type,
+            hunks: [],
+            stats: { additions: 0, deletions: 0 },
+            meta: { computeTime: Date.now() - startTime },
+          } satisfies FileDiffResponse
+        }
+
+        // Insert skip blocks and count stats
+        const hunkOnly = diff.hunks.filter((h): h is DiffHunk => h.type === 'hunk')
+        const hunksWithSkips = insertSkipBlocks(hunkOnly)
+        const stats = countDiffStats(hunksWithSkips)
+
+        return {
+          package: packageName,
+          from: fromVersion,
+          to: toVersion,
+          path: filePath,
+          type,
+          hunks: hunksWithSkips,
+          stats,
+          meta: { computeTime: Date.now() - startTime },
+        } satisfies FileDiffResponse
+      } catch (error) {
+        clearTimeout(timeoutId)
+
+        // Check if it was a timeout
+        if (error instanceof Error && error.name === 'AbortError') {
+          throw createError({
+            statusCode: 504,
+            message: 'Diff computation timed out',
+          })
+        }
+
+        throw error
+      }
+    } catch (error: unknown) {
+      handleApiError(error, {
+        statusCode: 502,
+        message: 'Failed to compute file diff',
+      })
+    }
+  },
+  {
+    // Diff between specific versions never changes - cache permanently
+    maxAge: CACHE_MAX_AGE_ONE_YEAR,
+    swr: true,
+    getKey: event => {
+      const pkg = getRouterParam(event, 'pkg') ?? ''
+      const query = getQuery(event)
+      const optionsKey = `${query.mergeModifiedLines}:${query.maxChangeRatio}:${query.maxDiffDistance}:${query.inlineMaxCharEdits}`
+      return `compare-file:v${CACHE_VERSION}:${pkg.replace(/\/+$/, '').trim()}:${optionsKey}`
+    },
+  },
+)
diff --git a/server/api/registry/compare/[...pkg].get.ts b/server/api/registry/compare/[...pkg].get.ts
new file mode 100644
index 00000000..71ba004e
--- /dev/null
+++ b/server/api/registry/compare/[...pkg].get.ts
@@ -0,0 +1,143 @@
+import * as v from 'valibot'
+import { PackageCompareQuerySchema } from '#shared/schemas/package'
+import type { CompareResponse } from '#shared/types'
+import { CACHE_MAX_AGE_ONE_YEAR } from '#shared/utils/constants'
+import { buildCompareResponse } from '#server/utils/compare'
+
+const CACHE_VERSION = 1
+const COMPARE_TIMEOUT = 8000 // 8 seconds
+
+/**
+ * Fetch package.json from jsDelivr
+ */
+async function fetchPackageJson(
+  packageName: string,
+  version: string,
+  signal?: AbortSignal,
+): Promise<Record<string, unknown> | null> {
+  try {
+    const url = `https://cdn.jsdelivr.net/npm/${packageName}@${version}/package.json`
+    const response = await fetch(url, { signal })
+    if (!response.ok) return null
+    return (await response.json()) as Record<string, unknown>
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Parse the version range from the URL.
+ * Supports formats like: "1.0.0...2.0.0" or "1.0.0..2.0.0"
+ */
+function parseVersionRange(versionRange: string): { from: string; to: string } | null {
+  // Try triple dot first (GitHub style)
+  let parts = versionRange.split('...')
+  if (parts.length === 2) {
+    return { from: parts[0]!, to: parts[1]! }
+  }
+
+  // Try double dot
+  parts = versionRange.split('..')
+  if (parts.length === 2) {
+    return { from: parts[0]!, to: parts[1]! }
+  }
+
+  return null
+}
+
+/**
+ * Compare two package versions and return differences.
+ *
+ * URL patterns:
+ * - /api/registry/compare/packageName/v/1.0.0...2.0.0
+ * - /api/registry/compare/@scope/packageName/v/1.0.0...2.0.0
+ */
+export default defineCachedEventHandler(
+  async event => {
+    const startTime = Date.now()
+
+    // Parse package segments
+    const pkgParamSegments = getRouterParam(event, 'pkg')?.split('/') ?? []
+    const { rawPackageName, rawVersion: rawVersionRange } = parsePackageParams(pkgParamSegments)
+
+    if (!rawVersionRange) {
+      throw createError({
+        statusCode: 400,
+        message: 'Version range is required (e.g., 1.0.0...2.0.0)',
+      })
+    }
+
+    // Parse version range
+    const range = parseVersionRange(rawVersionRange)
+    if (!range) {
+      throw createError({
+        statusCode: 400,
+        message: 'Invalid version range format. Use from...to (e.g., 1.0.0...2.0.0)',
+      })
+    }
+
+    try {
+      // Validate inputs
+      const { packageName, fromVersion, toVersion } = v.parse(PackageCompareQuerySchema, {
+        packageName: rawPackageName,
+        fromVersion: range.from,
+        toVersion: range.to,
+      })
+
+      // Set up abort controller for timeout
+      const controller = new AbortController()
+      const timeoutId = setTimeout(() => controller.abort(), COMPARE_TIMEOUT)
+
+      try {
+        // Fetch file trees and package.json for both versions in parallel
+        const [fromTree, toTree, fromPkg, toPkg] = await Promise.all([
+          getPackageFileTree(packageName, fromVersion),
+          getPackageFileTree(packageName, toVersion),
+          fetchPackageJson(packageName, fromVersion, controller.signal),
+          fetchPackageJson(packageName, toVersion, controller.signal),
+        ])
+
+        clearTimeout(timeoutId)
+
+        const computeTime = Date.now() - startTime
+
+        return buildCompareResponse(
+          packageName,
+          fromVersion,
+          toVersion,
+          fromTree.tree,
+          toTree.tree,
+          fromPkg,
+          toPkg,
+          computeTime,
+        ) satisfies CompareResponse
+      } catch (error) {
+        clearTimeout(timeoutId)
+
+        // Check if it was a timeout
+        if (error instanceof Error && error.name === 'AbortError') {
+          throw createError({
+            statusCode: 504,
+            message: 'Comparison timed out. Try comparing fewer files.',
+          })
+        }
+
+        throw error
+      }
+    } catch (error: unknown) {
+      handleApiError(error, {
+        statusCode: 502,
+        message: 'Failed to compare package versions',
+      })
+    }
+  },
+  {
+    // Comparison between specific versions never changes hence cache permanently
+    maxAge: CACHE_MAX_AGE_ONE_YEAR,
+    swr: true,
+    getKey: event => {
+      const pkg = getRouterParam(event, 'pkg') ?? ''
+      return `compare:v${CACHE_VERSION}:${pkg.replace(/\/+$/, '').trim()}`
+    },
+  },
+)
diff --git a/server/utils/compare.ts b/server/utils/compare.ts
new file mode 100644
index 00000000..71bfec1e
--- /dev/null
+++ b/server/utils/compare.ts
@@ -0,0 +1,260 @@
+import { diff as semverDiff } from 'semver'
+import type { PackageFileTree, DependencyChange, FileChange, CompareResponse } from '#shared/types'
+
+/** Maximum number of files to include in comparison */
+const MAX_FILES_COMPARE = 1000
+
+/** Flatten a file tree into a map of path -> node */
+export function flattenTree(tree: PackageFileTree[]): Map<string, PackageFileTree> {
+  const result = new Map<string, PackageFileTree>()
+
+  function traverse(nodes: PackageFileTree[]) {
+    for (const node of nodes) {
+      result.set(node.path, node)
+      if (node.children) {
+        traverse(node.children)
+      }
+    }
+  }
+
+  traverse(tree)
+  return result
+}
+
+/** Compare two file trees and return changes */
+export function compareFileTrees(
+  fromTree: PackageFileTree[],
+  toTree: PackageFileTree[],
+): { added: FileChange[]; removed: FileChange[]; modified: FileChange[]; truncated: boolean } {
+  const fromFiles = flattenTree(fromTree)
+  const toFiles = flattenTree(toTree)
+
+  const hasChanged = (fromNode: PackageFileTree, toNode: PackageFileTree): boolean => {
+    // Prefer strong hash comparison when both hashes are available
+    if (fromNode.hash && toNode.hash) return fromNode.hash !== toNode.hash
+    // Fallback to size comparison if hashes are missing
+    if (typeof fromNode.size === 'number' && typeof toNode.size === 'number') {
+      return fromNode.size !== toNode.size
+    }
+    // If we lack comparable signals, assume unchanged
+    return false
+  }
+
+  const added: FileChange[] = []
+  const removed: FileChange[] = []
+  const modified: FileChange[] = []
+  let truncated = false
+  const overLimit = () => added.length + removed.length + modified.length >= MAX_FILES_COMPARE
+
+  // Find added and modified files
+  for (const [path, toNode] of toFiles) {
+    if (overLimit()) {
+      truncated = true
+      break
+    }
+
+    const fromNode = fromFiles.get(path)
+
+    // Handle directory -> file / file -> directory transitions
+    if (toNode.type === 'directory') {
+      if (fromNode?.type === 'file') {
+        removed.push({
+          path,
+          type: 'removed',
+          oldSize: fromNode.size,
+        })
+      }
+      continue
+    }
+
+    // toNode is file
+    if (!fromNode) {
+      // New file
+      added.push({
+        path,
+        type: 'added',
+        newSize: toNode.size,
+      })
+    } else if (fromNode.type === 'directory') {
+      // Path was a directory, now a file -> treat as added file
+      added.push({
+        path,
+        type: 'added',
+        newSize: toNode.size,
+      })
+    } else if (fromNode.type === 'file') {
+      if (hasChanged(fromNode, toNode)) {
+        modified.push({
+          path,
+          type: 'modified',
+          oldSize: fromNode.size,
+          newSize: toNode.size,
+        })
+      }
+    }
+  }
+
+  // Find removed files
+  for (const [path, fromNode] of fromFiles) {
+    if (fromNode.type === 'directory') continue
+
+    if (added.length + removed.length + modified.length >= MAX_FILES_COMPARE) {
+      truncated = true
+      break
+    }
+
+    if (!toFiles.has(path)) {
+      removed.push({
+        path,
+        type: 'removed',
+        oldSize: fromNode.size,
+      })
+    }
+  }
+
+  // Sort by path
+  added.sort((a, b) => a.path.localeCompare(b.path))
+  removed.sort((a, b) => a.path.localeCompare(b.path))
+  modified.sort((a, b) => a.path.localeCompare(b.path))
+
+  return { added, removed, modified, truncated }
+}
+
+/** Compare dependencies between two package.json files */
+export function compareDependencies(
+  fromPkg: Record<string, unknown> | null,
+  toPkg: Record<string, unknown> | null,
+): DependencyChange[] {
+  const changes: DependencyChange[] = []
+  const sections = [
+    'dependencies',
+    'devDependencies',
+    'peerDependencies',
+    'optionalDependencies',
+  ] as const
+
+  for (const section of sections) {
+    const fromDeps = (fromPkg?.[section] as Record<string, string>) ?? {}
+    const toDeps = (toPkg?.[section] as Record<string, string>) ?? {}
+
+    const allNames = new Set([...Object.keys(fromDeps), ...Object.keys(toDeps)])
+
+    for (const name of allNames) {
+      const fromVersion = fromDeps[name] ?? null
+      const toVersion = toDeps[name] ?? null
+
+      if (fromVersion === toVersion) continue
+
+      let type: 'added' | 'removed' | 'updated'
+      if (!fromVersion) type = 'added'
+      else if (!toVersion) type = 'removed'
+      else type = 'updated'
+
+      let semverDiffType: DependencyChange['semverDiff'] = null
+      if (type === 'updated' && fromVersion && toVersion) {
+        // Try to compute semver diff
+        try {
+          // Strip ^ ~ >= etc for comparison
+          const cleanFrom = fromVersion.replace(/^[\^~>=<]+/, '')
+          const cleanTo = toVersion.replace(/^[\^~>=<]+/, '')
+          const diffResult = semverDiff(cleanFrom, cleanTo)
+          if (diffResult) {
+            if (
+              diffResult === 'premajor' ||
+              diffResult === 'preminor' ||
+              diffResult === 'prepatch'
+            ) {
+              semverDiffType = 'prerelease'
+            } else if (['major', 'minor', 'patch', 'prerelease'].includes(diffResult)) {
+              semverDiffType = diffResult as 'major' | 'minor' | 'patch' | 'prerelease'
+            }
+          }
+        } catch {
+          // Invalid semver, ignore
+        }
+      }
+
+      changes.push({
+        name,
+        section,
+        from: fromVersion,
+        to: toVersion,
+        type,
+        semverDiff: semverDiffType,
+      })
+    }
+  }
+
+  // Sort: by section, then by name
+  changes.sort((a, b) => {
+    if (a.section !== b.section) {
+      return sections.indexOf(a.section) - sections.indexOf(b.section)
+    }
+    return a.name.localeCompare(b.name)
+  })
+
+  return changes
+}
+
+/** Count total files in a tree */
+export function countFiles(tree: PackageFileTree[]): number {
+  let count = 0
+
+  function traverse(nodes: PackageFileTree[]) {
+    for (const node of nodes) {
+      if (node.type === 'file') count++
+      if (node.children) traverse(node.children)
+    }
+  }
+
+  traverse(tree)
+  return count
+}
+
+/** Build the full compare response */
+export function buildCompareResponse(
+  packageName: string,
+  from: string,
+  to: string,
+  fromTree: PackageFileTree[],
+  toTree: PackageFileTree[],
+  fromPkg: Record<string, unknown> | null,
+  toPkg: Record<string, unknown> | null,
+  computeTime: number,
+): CompareResponse {
+  const fileChanges = compareFileTrees(fromTree, toTree)
+  const dependencyChanges = compareDependencies(fromPkg, toPkg)
+
+  const warnings: string[] = []
+  if (fileChanges.truncated) {
+    warnings.push(`File list truncated to ${MAX_FILES_COMPARE} files`)
+  }
+
+  return {
+    package: packageName,
+    from,
+    to,
+    packageJson: {
+      from: fromPkg,
+      to: toPkg,
+    },
+    files: {
+      added: fileChanges.added,
+      removed: fileChanges.removed,
+      modified: fileChanges.modified,
+    },
+    dependencyChanges,
+    stats: {
+      totalFilesFrom: countFiles(fromTree),
+      totalFilesTo: countFiles(toTree),
+      filesAdded: fileChanges.added.length,
+      filesRemoved: fileChanges.removed.length,
+      filesModified: fileChanges.modified.length,
+    },
+    meta: {
+      truncated: fileChanges.truncated,
+      warnings: warnings.length > 0 ? warnings : undefined,
+      computeTime,
+    },
+  }
+}
diff --git a/server/utils/diff.ts b/server/utils/diff.ts
new file mode 100644
index 00000000..45e695a4
--- /dev/null
+++ b/server/utils/diff.ts
@@ -0,0 +1 @@
+export * from '../../shared/utils/diff'
diff --git a/server/utils/file-tree.ts b/server/utils/file-tree.ts
index 9d2556e0..2f2fe599 100644
--- a/server/utils/file-tree.ts
+++ b/server/utils/file-tree.ts
@@ -50,6 +50,7 @@ export function convertToFileTree(
         name: node.name,
         path,
         type: 'file',
+        hash: node.hash,
         size: node.size,
       })
     }
diff --git a/shared/schemas/package.ts b/shared/schemas/package.ts
index 49543ece..bc4b10af 100644
--- a/shared/schemas/package.ts
+++ b/shared/schemas/package.ts
@@ -70,6 +70,25 @@ export const PackageFileQuerySchema = v.object({
   filePath: FilePathSchema,
 })
 
+/**
+ * Schema for version comparison (from...to range)
+ */
+export const PackageCompareQuerySchema = v.object({
+  packageName: PackageNameSchema,
+  fromVersion: VersionSchema,
+  toVersion: VersionSchema,
+})
+
+/**
+ * Schema for file diff between versions
+ */
+export const PackageFileDiffQuerySchema = v.object({
+  packageName: PackageNameSchema,
+  fromVersion: VersionSchema,
+  toVersion: VersionSchema,
+  filePath: FilePathSchema,
+})
+
 /**
  * Automatically infer types for routes
  * Usage - prefer this over manually defining interfaces
@@ -80,3 +99,7 @@ export type PackageRouteParams = v.InferOutput<typeof PackageRouteParamsSchema>
 export type PackageVersionQuery = v.InferOutput<typeof PackageVersionQuerySchema>
 /** @public */
 export type PackageFileQuery = v.InferOutput<typeof PackageFileQuerySchema>
+/** @public */
+export type PackageCompareQuery = v.InferOutput<typeof PackageCompareQuerySchema>
+/** @public */
+export type PackageFileDiffQuery = v.InferOutput<typeof PackageFileDiffQuerySchema>
diff --git a/shared/types/compare.ts b/shared/types/compare.ts
new file mode 100644
index 00000000..9d0d3ea5
--- /dev/null
+++ b/shared/types/compare.ts
@@ -0,0 +1,153 @@
+/** A change in a dependency between versions */
+export interface DependencyChange {
+  /** Package name */
+  name: string
+  /** Which dependency section it belongs to */
+  section: 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies'
+  /** Version in the "from" version (null if newly added) */
+  from: string | null
+  /** Version in the "to" version (null if removed) */
+  to: string | null
+  /** Type of change */
+  type: 'added' | 'removed' | 'updated'
+  /** Best-effort semver diff type */
+  semverDiff?: 'major' | 'minor' | 'patch' | 'prerelease' | null
+}
+
+/** File change info in the comparison */
+export interface FileChange {
+  /** File path */
+  path: string
+  /** Type of change */
+  type: 'added' | 'removed' | 'modified'
+  /** Old file size (for removed/modified) */
+  oldSize?: number
+  /** New file size (for added/modified) */
+  newSize?: number
+}
+
+/** Comparison summary response from the API */
+export interface CompareResponse {
+  /** Package name */
+  package: string
+  /** Source version */
+  from: string
+  /** Target version */
+  to: string
+  /** package.json content for both versions */
+  packageJson: {
+    from: Record<string, unknown> | null
+    to: Record<string, unknown> | null
+  }
+  /** File changes between versions */
+  files: {
+    added: FileChange[]
+    removed: FileChange[]
+    modified: FileChange[]
+  }
+  /** Dependency changes */
+  dependencyChanges: DependencyChange[]
+  /** Stats summary */
+  stats: {
+    totalFilesFrom: number
+    totalFilesTo: number
+    filesAdded: number
+    filesRemoved: number
+    filesModified: number
+  }
+  /** Metadata about the comparison */
+  meta: {
+    /** Whether file list was truncated due to size */
+    truncated?: boolean
+    /** Any warnings during comparison */
+    warnings?: string[]
+    /** Time taken to compute (ms) */
+    computeTime?: number
+  }
+}
+
+/** A line segment in a diff (for inline word-level diffs) */
+export interface DiffLineSegment {
+  value: string
+  type: 'insert' | 'delete' | 'normal'
+}
+
+/** A single line in the diff */
+export interface DiffLine {
+  /** Line type */
+  type: 'insert' | 'delete' | 'normal'
+  /** Old line number (for normal/delete) */
+  oldLineNumber?: number
+  /** New line number (for normal/insert) */
+  newLineNumber?: number
+  /** Line number (for insert/delete) */
+  lineNumber?: number
+  /** Line content segments */
+  content: DiffLineSegment[]
+}
+
+/** A hunk in the diff */
+export interface DiffHunk {
+  type: 'hunk'
+  /** Original hunk header content */
+  content: string
+  /** Old file start line */
+  oldStart: number
+  /** Number of lines in old file */
+  oldLines: number
+  /** New file start line */
+  newStart: number
+  /** Number of lines in new file */
+  newLines: number
+  /** Lines in this hunk */
+  lines: DiffLine[]
+}
+
+/** A skip block (collapsed unchanged lines) */
+export interface DiffSkipBlock {
+  type: 'skip'
+  /** Number of lines skipped */
+  count: number
+  /** Context message */
+  content: string
+}
+
+/** Parsed file diff */
+export interface FileDiff {
+  /** Old file path */
+  oldPath: string
+  /** New file path */
+  newPath: string
+  /** File change type */
+  type: 'add' | 'delete' | 'modify'
+  /** Hunks in the diff */
+  hunks: (DiffHunk | DiffSkipBlock)[]
+}
+
+/** Per-file diff response from the API */
+export interface FileDiffResponse {
+  /** Package name */
+  package: string
+  /** Source version */
+  from: string
+  /** Target version */
+  to: string
+  /** File path */
+  path: string
+  /** File change type */
+  type: 'add' | 'delete' | 'modify'
+  /** Parsed diff hunks */
+  hunks: (DiffHunk | DiffSkipBlock)[]
+  /** Diff stats */
+  stats: {
+    additions: number
+    deletions: number
+  }
+  /** Metadata */
+  meta: {
+    /** Whether diff was truncated */
+    truncated?: boolean
+    /** Time taken to compute (ms) */
+    computeTime?: number
+  }
+}
diff --git a/shared/types/index.ts b/shared/types/index.ts
index 228f6e85..cf537404 100644
--- a/shared/types/index.ts
+++ b/shared/types/index.ts
@@ -5,3 +5,4 @@ export * from './readme'
 export * from './docs'
 export * from './deno-doc'
 export * from './i18n-status'
+export * from './compare'
diff --git a/shared/types/npm-registry.ts b/shared/types/npm-registry.ts
index 624acc5e..49ea6d4e 100644
--- a/shared/types/npm-registry.ts
+++ b/shared/types/npm-registry.ts
@@ -298,6 +298,8 @@ export interface PackageFileTree {
   path: string
   /** Node type */
   type: 'file' | 'directory'
+  /** File hash (only for files) */
+  hash?: string
   /** File size in bytes (only for files) */
   size?: number
   /** Child nodes (only for directories) */
diff --git a/shared/utils/diff.ts b/shared/utils/diff.ts
new file mode 100644
index 00000000..e409f613
--- /dev/null
+++ b/shared/utils/diff.ts
@@ -0,0 +1,383 @@
+import { createTwoFilesPatch } from 'diff'
+import type {
+  DiffLine,
+  DiffLineSegment,
+  DiffHunk,
+  DiffSkipBlock,
+  FileDiff,
+} from '#shared/types/compare'
+
+/** Options for parsing diffs */
+export interface ParseOptions {
+  maxDiffDistance: number
+  maxChangeRatio: number
+  mergeModifiedLines: boolean
+  inlineMaxCharEdits: number
+}
+
+const defaultOptions: ParseOptions = {
+  maxDiffDistance: 30,
+  maxChangeRatio: 0.45,
+  mergeModifiedLines: true,
+  inlineMaxCharEdits: 2,
+}
+
+interface RawChange {
+  type: 'insert' | 'delete' | 'normal'
+  content: string
+  lineNumber?: number
+  oldLineNumber?: number
+  newLineNumber?: number
+  isNormal?: boolean
+}
+
+function calculateChangeRatio(a: string, b: string): number {
+  const totalChars = a.length + b.length
+  if (totalChars === 0) return 1
+  let changedChars = 0
+  const maxLen = Math.max(a.length, b.length)
+  for (let i = 0; i < maxLen; i++) {
+    if (a[i] !== b[i]) changedChars++
+  }
+  changedChars += Math.abs(a.length - b.length)
+  return changedChars / totalChars
+}
+
+function isSimilarEnough(a: string, b: string, maxChangeRatio: number): boolean {
+  if (maxChangeRatio <= 0) return a === b
+  if (maxChangeRatio >= 1) return true
+  return calculateChangeRatio(a, b) <= maxChangeRatio
+}
+
+function buildInlineDiffSegments(
+  oldContent: string,
+  newContent: string,
+  _options: ParseOptions,
+): DiffLineSegment[] {
+  const oldWords = oldContent.split(/(\s+)/)
+  const newWords = newContent.split(/(\s+)/)
+
+  const segments: DiffLineSegment[] = []
+  let oi = 0
+  let ni = 0
+
+  while (oi < oldWords.length || ni < newWords.length) {
+    if (oi >= oldWords.length) {
+      segments.push({ value: newWords.slice(ni).join(''), type: 'insert' })
+      break
+    }
+    if (ni >= newWords.length) {
+      segments.push({ value: oldWords.slice(oi).join(''), type: 'delete' })
+      break
+    }
+
+    if (oldWords[oi] === newWords[ni]) {
+      const last = segments[segments.length - 1]
+      if (last?.type === 'normal') {
+        last.value += oldWords[oi]!
+      } else {
+        segments.push({ value: oldWords[oi]!, type: 'normal' })
+      }
+      oi++
+      ni++
+    } else {
+      let foundSync = false
+
+      for (let look = 1; look <= 3 && ni + look < newWords.length; look++) {
+        if (newWords[ni + look] === oldWords[oi]) {
+          segments.push({ value: newWords.slice(ni, ni + look).join(''), type: 'insert' })
+          ni += look
+          foundSync = true
+          break
+        }
+      }
+
+      if (!foundSync) {
+        for (let look = 1; look <= 3 && oi + look < oldWords.length; look++) {
+          if (oldWords[oi + look] === newWords[ni]) {
+            segments.push({ value: oldWords.slice(oi, oi + look).join(''), type: 'delete' })
+            oi += look
+            foundSync = true
+            break
+          }
+        }
+      }
+
+      if (!foundSync) {
+        segments.push({ value: oldWords[oi]!, type: 'delete' })
+        segments.push({ value: newWords[ni]!, type: 'insert' })
+        oi++
+        ni++
+      }
+    }
+  }
+
+  const merged: DiffLineSegment[] = []
+  for (const seg of segments) {
+    const last = merged[merged.length - 1]
+    if (last?.type === seg.type) {
+      last.value += seg.value
+    } else {
+      merged.push({ ...seg })
+    }
+  }
+
+  return merged
+}
+
+function changeToLine(change: RawChange): DiffLine {
+  return {
+    type: change.type,
+    oldLineNumber: change.oldLineNumber,
+    newLineNumber: change.newLineNumber,
+    lineNumber: change.lineNumber,
+    content: [{ value: change.content, type: 'normal' }],
+  }
+}
+
+function mergeAdjacentLines(changes: RawChange[], options: ParseOptions): DiffLine[] {
+  const out: DiffLine[] = []
+
+  for (let i = 0; i < changes.length; i++) {
+    const current = changes[i]!
+    const next = changes[i + 1]
+
+    if (
+      next &&
+      current.type === 'delete' &&
+      next.type === 'insert' &&
+      isSimilarEnough(current.content, next.content, options.maxChangeRatio)
+    ) {
+      out.push({
+        type: 'normal',
+        oldLineNumber: current.lineNumber,
+        newLineNumber: next.lineNumber,
+        content: buildInlineDiffSegments(current.content, next.content, options),
+      })
+      i++
+    } else {
+      out.push(changeToLine(current))
+    }
+  }
+
+  return out
+}
+
+export function parseUnifiedDiff(
+  diffText: string,
+  options: Partial<ParseOptions> = {},
+): FileDiff[] {
+  const opts = { ...defaultOptions, ...options }
+  const files: FileDiff[] = []
+
+  const lines = diffText.split('\n')
+  let currentFile: FileDiff | null = null
+  let currentHunk: {
+    changes: RawChange[]
+    oldStart: number
+    oldLines: number
+    newStart: number
+    newLines: number
+    content: string
+  } | null = null
+  let oldLine = 0
+  let newLine = 0
+
+  for (const line of lines) {
+    if (line.startsWith('---')) {
+      if (currentHunk && currentFile) {
+        const hunk = processHunk(currentHunk, opts)
+        currentFile.hunks.push(hunk)
+      }
+      currentHunk = null
+      continue
+    }
+
+    if (line.startsWith('+++')) {
+      const match = line.match(/^\+\+\+ (?:b\/)?(.*)/)
+      const path = match?.[1] ?? ''
+
+      if (currentFile && currentHunk) {
+        const hunk = processHunk(currentHunk, opts)
+        currentFile.hunks.push(hunk)
+        files.push(currentFile)
+      } else if (currentFile) {
+        files.push(currentFile)
+      }
+
+      currentFile = {
+        oldPath: path,
+        newPath: path,
+        type: 'modify',
+        hunks: [],
+      }
+      currentHunk = null
+      continue
+    }
+
+    const hunkMatch = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(.*)/)
+    if (hunkMatch) {
+      if (currentHunk && currentFile) {
+        const hunk = processHunk(currentHunk, opts)
+        currentFile.hunks.push(hunk)
+      }
+
+      oldLine = parseInt(hunkMatch[1]!, 10)
+      newLine = parseInt(hunkMatch[3]!, 10)
+
+      currentHunk = {
+        changes: [],
+        oldStart: oldLine,
+        oldLines: parseInt(hunkMatch[2] ?? '1', 10),
+        newStart: newLine,
+        newLines: parseInt(hunkMatch[4] ?? '1', 10),
+        content: line,
+      }
+      continue
+    }
+
+    if (line.startsWith('diff ') || line.startsWith('index ') || line.startsWith('\\')) {
+      continue
+    }
+
+    if (currentHunk) {
+      if (line.startsWith('+')) {
+        currentHunk.changes.push({
+          type: 'insert',
+          content: line.slice(1),
+          lineNumber: newLine,
+          newLineNumber: newLine,
+        })
+        newLine++
+      } else if (line.startsWith('-')) {
+        currentHunk.changes.push({
+          type: 'delete',
+          content: line.slice(1),
+          lineNumber: oldLine,
+          oldLineNumber: oldLine,
+        })
+        oldLine++
+      } else if (line.startsWith(' ') || line === '') {
+        currentHunk.changes.push({
+          type: 'normal',
+          content: line.slice(1) || '',
+          oldLineNumber: oldLine,
+          newLineNumber: newLine,
+          isNormal: true,
+        })
+        oldLine++
+        newLine++
+      }
+    }
+  }
+
+  if (currentHunk && currentFile) {
+    const hunk = processHunk(currentHunk, opts)
+    currentFile.hunks.push(hunk)
+  }
+  if (currentFile) {
+    files.push(currentFile)
+  }
+
+  for (const file of files) {
+    const hasAdds = file.hunks.some(
+      h => h.type === 'hunk' && h.lines.some(l => l.type === 'insert'),
+    )
+    const hasDels = file.hunks.some(
+      h => h.type === 'hunk' && h.lines.some(l => l.type === 'delete'),
+    )
+
+    if (hasAdds && !hasDels) file.type = 'add'
+    else if (hasDels && !hasAdds) file.type = 'delete'
+    else file.type = 'modify'
+  }
+
+  return files
+}
+
+function processHunk(
+  raw: {
+    changes: RawChange[]
+    oldStart: number
+    oldLines: number
+    newStart: number
+    newLines: number
+    content: string
+  },
+  options: ParseOptions,
+): DiffHunk {
+  const lines = options.mergeModifiedLines
+    ? mergeAdjacentLines(raw.changes, options)
+    : raw.changes.map(changeToLine)
+
+  return {
+    type: 'hunk',
+    content: raw.content,
+    oldStart: raw.oldStart,
+    oldLines: raw.oldLines,
+    newStart: raw.newStart,
+    newLines: raw.newLines,
+    lines,
+  }
+}
+
+export function insertSkipBlocks(hunks: DiffHunk[]): (DiffHunk | DiffSkipBlock)[] {
+  const result: (DiffHunk | DiffSkipBlock)[] = []
+  let lastHunkLine = 1
+
+  for (const hunk of hunks) {
+    const distanceToLastHunk = hunk.oldStart - lastHunkLine
+
+    if (distanceToLastHunk > 0) {
+      result.push({
+        type: 'skip',
+        count: distanceToLastHunk,
+        content: `${distanceToLastHunk} lines hidden`,
+      })
+    }
+
+    lastHunkLine = Math.max(hunk.oldStart + hunk.oldLines, lastHunkLine)
+    result.push(hunk)
+  }
+
+  return result
+}
+
+export function createDiff(
+  oldContent: string,
+  newContent: string,
+  filePath: string,
+  options: Partial<ParseOptions> = {},
+): FileDiff | null {
+  const diffText = createTwoFilesPatch(
+    `a/${filePath}`,
+    `b/${filePath}`,
+    oldContent,
+    newContent,
+    '',
+    '',
+    { context: 3 },
+  )
+
+  const files = parseUnifiedDiff(diffText, options)
+  return files[0] ?? null
+}
+
+export function countDiffStats(hunks: (DiffHunk | DiffSkipBlock)[]): {
+  additions: number
+  deletions: number
+} {
+  let additions = 0
+  let deletions = 0
+
+  for (const hunk of hunks) {
+    if (hunk.type === 'hunk') {
+      for (const line of hunk.lines) {
+        if (line.type === 'insert') additions++
+        else if (line.type === 'delete') deletions++
+      }
+    }
+  }
+
+  return { additions, deletions }
+}

From 8447763146daa23ce1da5c6bb362526e6457f30a Mon Sep 17 00:00:00 2001
From: taskylizard <75871323+taskylizard@users.noreply.github.com>
Date: Thu, 29 Jan 2026 22:50:11 +0100
Subject: [PATCH 2/7] feat: collapsible file browser in compare

---
 app/pages/compare/[...path].vue | 97 +++++++++++++++++----------------
 1 file changed, 50 insertions(+), 47 deletions(-)

diff --git a/app/pages/compare/[...path].vue b/app/pages/compare/[...path].vue
index e9b95d41..d79f3ca1 100644
--- a/app/pages/compare/[...path].vue
+++ b/app/pages/compare/[...path].vue
@@ -348,57 +348,60 @@ useSeoMeta({
           </div>
         </div>
 
-        <!-- File browser header with dropdown filter -->
-        <div class="border-b border-border px-3 py-2 shrink-0 bg-bg-muted">
-          <div class="flex items-center justify-between gap-2">
-            <h2 class="text-xs font-medium flex items-center gap-1.5">
+        <!-- File browser collapsible -->
+        <details class="flex-1 flex flex-col open:flex-1 group" open>
+          <summary
+            class="border-b border-border px-3 py-2 shrink-0 bg-bg-muted cursor-pointer list-none flex items-center justify-between gap-2"
+          >
+            <span class="text-xs font-medium flex items-center gap-1.5">
               <span class="i-carbon-document w-3.5 h-3.5" />
               Changed Files
-            </h2>
-
-            <!-- Filter dropdown -->
-            <select
-              v-model="fileFilter"
-              class="text-[10px] px-2 py-1 bg-bg-subtle border border-border rounded font-mono cursor-pointer hover:border-border-hover transition-colors"
-            >
-              <option value="all">All ({{ allChanges.length }})</option>
-              <option value="added">Added ({{ compare.stats.filesAdded }})</option>
-              <option value="removed">Removed ({{ compare.stats.filesRemoved }})</option>
-              <option value="modified">Modified ({{ compare.stats.filesModified }})</option>
-            </select>
-          </div>
-        </div>
+            </span>
+            <span class="flex items-center gap-2">
+              <select
+                v-model="fileFilter"
+                class="text-[10px] px-2 py-1 bg-bg-subtle border border-border rounded font-mono cursor-pointer hover:border-border-hover transition-colors"
+              >
+                <option value="all">All ({{ allChanges.length }})</option>
+                <option value="added">Added ({{ compare.stats.filesAdded }})</option>
+                <option value="removed">Removed ({{ compare.stats.filesRemoved }})</option>
+                <option value="modified">Modified ({{ compare.stats.filesModified }})</option>
+              </select>
+              <span class="i-carbon-chevron-right w-3.5 h-3.5 transition-transform group-open:rotate-90" />
+            </span>
+          </summary>
+
+          <!-- File list (scrollable) -->
+          <div class="flex-1 overflow-y-auto min-h-0">
+            <div v-if="filteredChanges.length === 0" class="p-8 text-center text-xs text-fg-muted">
+              No {{ fileFilter === 'all' ? '' : fileFilter }} files
+            </div>
 
-        <!-- File list (scrollable) -->
-        <div class="flex-1 overflow-y-auto min-h-0">
-          <div v-if="filteredChanges.length === 0" class="p-8 text-center text-xs text-fg-muted">
-            No {{ fileFilter === 'all' ? '' : fileFilter }} files
-          </div>
+            <nav v-else class="divide-y divide-border">
+              <button
+                v-for="file in filteredChanges"
+                :key="file.path"
+                type="button"
+                class="w-full px-3 py-2 flex items-center gap-2 text-sm text-left hover:bg-bg-muted transition-colors group"
+                :class="{
+                  'bg-bg-muted border-l-3 border-l-blue-500': selectedFile?.path === file.path,
+                }"
+                @click="selectedFile = file"
+              >
+                <!-- File icon -->
+                <span :class="[getFileIcon(file.path), 'w-3.5 h-3.5 shrink-0']" />
 
-          <nav v-else class="divide-y divide-border">
-            <button
-              v-for="file in filteredChanges"
-              :key="file.path"
-              type="button"
-              class="w-full px-3 py-2 flex items-center gap-2 text-sm text-left hover:bg-bg-muted transition-colors group"
-              :class="{
-                'bg-bg-muted border-l-3 border-l-blue-500': selectedFile?.path === file.path,
-              }"
-              @click="selectedFile = file"
-            >
-              <!-- File icon -->
-              <span :class="[getFileIcon(file.path), 'w-3.5 h-3.5 shrink-0']" />
-
-              <!-- Change type indicator -->
-              <span :class="[getChangeIcon(file.type), 'w-3 h-3 shrink-0']" />
-
-              <!-- File path -->
-              <span class="font-mono text-[10px] truncate min-w-0 group-hover:text-fg">
-                {{ file.path }}
-              </span>
-            </button>
-          </nav>
-        </div>
+                <!-- Change type indicator -->
+                <span :class="[getChangeIcon(file.type), 'w-3 h-3 shrink-0']" />
+
+                <!-- File path -->
+                <span class="font-mono text-[10px] truncate min-w-0 group-hover:text-fg">
+                  {{ file.path }}
+                </span>
+              </button>
+            </nav>
+          </div>
+        </details>
       </aside>
 
       <!-- Right side: Diff viewer -->

From 56b5ced781abce3d36396c8eba63c4a38a99b06b Mon Sep 17 00:00:00 2001
From: taskylizard <75871323+taskylizard@users.noreply.github.com>
Date: Thu, 29 Jan 2026 22:50:34 +0100
Subject: [PATCH 3/7] feat: shareable compare file links

---
 app/pages/compare/[...path].vue | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/app/pages/compare/[...path].vue b/app/pages/compare/[...path].vue
index d79f3ca1..075c1594 100644
--- a/app/pages/compare/[...path].vue
+++ b/app/pages/compare/[...path].vue
@@ -41,6 +41,8 @@ const packageName = computed(() => parsedRoute.value.packageName)
 const fromVersion = computed(() => parsedRoute.value.range?.from ?? '')
 const toVersion = computed(() => parsedRoute.value.range?.to ?? '')
 
+const router = useRouter()
+const initializedFromQuery = ref(false)
 const { data: pkg } = usePackage(packageName)
 
 const { data: compare, status: compareStatus } = useFetch<CompareResponse>(
@@ -68,6 +70,31 @@ const filteredChanges = computed(() => {
   return allChanges.value.filter(f => f.type === fileFilter.value)
 })
 
+// Sync selection with ?file= query for shareable links
+watch(
+  () => route.query.file,
+  filePath => {
+    if (initializedFromQuery.value || !filePath || !compare.value) return
+    const match = allChanges.value.find(f => f.path === filePath)
+    if (match) {
+      selectedFile.value = match
+      initializedFromQuery.value = true
+    }
+  },
+  { immediate: true },
+)
+
+watch(
+  selectedFile,
+  file => {
+    const query = { ...route.query }
+    if (file?.path) query.file = file.path
+    else delete query.file
+    router.replace({ query })
+  },
+  { deep: false },
+)
+
 const groupedDeps = computed(() => {
   if (!compare.value?.dependencyChanges) return new Map()
 

From 7124b6d6878f1221929c8b2f204245b74b999bc1 Mon Sep 17 00:00:00 2001
From: taskylizard <75871323+taskylizard@users.noreply.github.com>
Date: Thu, 29 Jan 2026 22:54:46 +0100
Subject: [PATCH 4/7] chore: set word wrap to true

---
 app/components/diff/ViewerPanel.vue | 2 +-
 app/pages/compare/[...path].vue     | 4 +++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/app/components/diff/ViewerPanel.vue b/app/components/diff/ViewerPanel.vue
index 5d2f9244..f9236cff 100644
--- a/app/components/diff/ViewerPanel.vue
+++ b/app/components/diff/ViewerPanel.vue
@@ -15,7 +15,7 @@ const mergeModifiedLines = ref(true)
 const maxChangeRatio = ref(0.45)
 const maxDiffDistance = ref(30)
 const inlineMaxCharEdits = ref(2)
-const wordWrap = ref(false)
+const wordWrap = ref(true)
 const showOptions = ref(false)
 const loading = ref(true)
 const loadError = ref<Error | null>(null)
diff --git a/app/pages/compare/[...path].vue b/app/pages/compare/[...path].vue
index 075c1594..07bb451b 100644
--- a/app/pages/compare/[...path].vue
+++ b/app/pages/compare/[...path].vue
@@ -394,7 +394,9 @@ useSeoMeta({
                 <option value="removed">Removed ({{ compare.stats.filesRemoved }})</option>
                 <option value="modified">Modified ({{ compare.stats.filesModified }})</option>
               </select>
-              <span class="i-carbon-chevron-right w-3.5 h-3.5 transition-transform group-open:rotate-90" />
+              <span
+                class="i-carbon-chevron-right w-3.5 h-3.5 transition-transform group-open:rotate-90"
+              />
             </span>
           </summary>
 

From 8b37e444915fbd09acf802c6aca2bccd16643ac3 Mon Sep 17 00:00:00 2001
From: taskylizard <75871323+taskylizard@users.noreply.github.com>
Date: Fri, 30 Jan 2026 09:00:20 +0100
Subject: [PATCH 5/7] oops

---
 package.json   | 1 +
 pnpm-lock.yaml | 3 +++
 2 files changed, 4 insertions(+)

diff --git a/package.json b/package.json
index 0b0ee75a..a067bbd6 100644
--- a/package.json
+++ b/package.json
@@ -47,6 +47,7 @@
     "@vueuse/core": "^14.1.0",
     "@vueuse/nuxt": "14.1.0",
     "diff": "^8.0.3",
+    "motion-v": "^1.10.2",
     "nuxt": "^4.3.0",
     "nuxt-og-image": "^5.1.13",
     "ohash": "^2.0.11",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 007d73e6..0fbadd64 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -68,6 +68,9 @@ importers:
       diff:
         specifier: ^8.0.3
         version: 8.0.3
+      motion-v:
+        specifier: ^1.10.2
+        version: 1.10.2(@vueuse/core@14.1.0(vue@3.5.27(typescript@5.9.3)))(vue@3.5.27(typescript@5.9.3))
       nuxt:
         specifier: ^4.3.0
         version: 4.3.0(@parcel/watcher@2.5.6)(@types/node@24.10.9)(@vue/compiler-sfc@3.5.27)(better-sqlite3@12.5.0)(cac@6.7.14)(db0@0.3.4(better-sqlite3@12.5.0))(eslint@9.39.2(jiti@2.6.1))(ioredis@5.9.2)(magicast@0.5.1)(optionator@0.9.4)(oxlint@1.42.0(oxlint-tsgolint@0.11.2))(rolldown@1.0.0-rc.1)(rollup@4.57.0)(terser@5.46.0)(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.9)(jiti@2.6.1)(lightningcss@1.31.1)(terser@5.46.0)(yaml@2.8.2))(vue-tsc@3.2.2(typescript@5.9.3))(yaml@2.8.2)

From 3d91ad18f312711623a0f79fa2c6170d7ce63344 Mon Sep 17 00:00:00 2001
From: taskylizard <75871323+taskylizard@users.noreply.github.com>
Date: Fri, 30 Jan 2026 09:16:24 +0100
Subject: [PATCH 6/7] fix: sync file selection from query param after compare
 data loads

---
 app/pages/compare/[...path].vue | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/app/pages/compare/[...path].vue b/app/pages/compare/[...path].vue
index 07bb451b..5210a78b 100644
--- a/app/pages/compare/[...path].vue
+++ b/app/pages/compare/[...path].vue
@@ -72,8 +72,8 @@ const filteredChanges = computed(() => {
 
 // Sync selection with ?file= query for shareable links
 watch(
-  () => route.query.file,
-  filePath => {
+  [() => route.query.file, compare],
+  ([filePath]) => {
     if (initializedFromQuery.value || !filePath || !compare.value) return
     const match = allChanges.value.find(f => f.path === filePath)
     if (match) {

From 1259bc3ce6a2b1b114f832e13c73956ecc4d19b2 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Fri, 30 Jan 2026 22:17:47 +0000
Subject: [PATCH 7/7] chore: cleanup

---
 app/components/diff/ViewerPanel.vue | 12 ++++++++++--
 app/pages/compare/[...path].vue     |  6 ------
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/app/components/diff/ViewerPanel.vue b/app/components/diff/ViewerPanel.vue
index f9236cff..0f7a3568 100644
--- a/app/components/diff/ViewerPanel.vue
+++ b/app/components/diff/ViewerPanel.vue
@@ -1,7 +1,6 @@
 <script setup lang="ts">
 import type { FileDiffResponse, FileChange } from '#shared/types'
 import { createDiff, insertSkipBlocks, countDiffStats } from '#shared/utils/diff'
-// @ts-expect-error: (tasky): idk why this is type-erroring even if it has types? /shrug
 import { motion } from 'motion-v'
 
 const props = defineProps<{
@@ -68,6 +67,12 @@ async function fetchFileContent(version: string): Promise<string | null> {
     }
 
     return text
+  } catch (err) {
+    // Provide specific error message for timeout
+    if (err instanceof Error && err.name === 'AbortError') {
+      throw new Error(`Request timed out after ${DIFF_TIMEOUT / 1000}s`, { cause: err })
+    }
+    throw err
   } finally {
     clearTimeout(timeoutId)
   }
@@ -80,7 +85,10 @@ function computeDiff() {
   const oldContent = fromContent.value ?? ''
   const newContent = toContent.value ?? ''
 
-  // Determine type
+  // Determine diff type based on content availability
+  // Note: FileDiffResponse uses 'add'/'delete'/'modify' while FileChange uses
+  // 'added'/'removed'/'modified' - this is intentional to distinguish between
+  // the file-level change info (FileChange) and the diff content type (FileDiff)
   let type: FileDiffResponse['type'] = 'modify'
   if (fromContent.value === null && toContent.value !== null) type = 'add'
   else if (fromContent.value !== null && toContent.value === null) type = 'delete'
diff --git a/app/pages/compare/[...path].vue b/app/pages/compare/[...path].vue
index 5210a78b..8f147456 100644
--- a/app/pages/compare/[...path].vue
+++ b/app/pages/compare/[...path].vue
@@ -7,7 +7,6 @@ definePageMeta({
 })
 
 const route = useRoute('compare')
-const { t } = useI18n()
 
 // Parse package name and version range from URL
 // Patterns:
@@ -155,11 +154,6 @@ const toVersionUrlPattern = computed(() => {
   return `/compare/${packageName.value}/v/${fromVersion.value}...{version}`
 })
 
-function getCodeUrl(version: string, path?: string): string {
-  const base = `/code/${packageName.value}/v/${version}`
-  return path ? `${base}/${path}` : base
-}
-
 function packageRoute(ver?: string | null) {
   const segments = packageName.value.split('/')
   if (ver) segments.push('v', ver)