From 2d8ede51c20289540e0da1a29f8dc3e6f540f7d6 Mon Sep 17 00:00:00 2001
From: Martin Donadieu <martindonadieu@gmail.com>
Date: Wed, 29 Apr 2026 11:44:31 +0200
Subject: [PATCH 1/2] feat(preview): add channel preview support

---
 src/components/BundlePreviewFrame.vue         |  17 +-
 .../app/[app].channel.[channel].preview.vue   | 195 ++++++++++++++++++
 src/pages/app/[app].channel.[channel].vue     |  15 ++
 supabase/functions/_backend/files/preview.ts  | 105 ++++++++--
 .../functions/shared/preview-subdomain.ts     |  59 +++++-
 tests/preview-response-headers.unit.test.ts   |  29 +++
 tests/preview-subdomain.unit.test.ts          |  24 ++-
 7 files changed, 414 insertions(+), 30 deletions(-)
 create mode 100644 src/pages/app/[app].channel.[channel].preview.vue
 create mode 100644 tests/preview-response-headers.unit.test.ts

diff --git a/src/components/BundlePreviewFrame.vue b/src/components/BundlePreviewFrame.vue
index 66c1d1ebe0..e35e5cb152 100644
--- a/src/components/BundlePreviewFrame.vue
+++ b/src/components/BundlePreviewFrame.vue
@@ -4,11 +4,12 @@ import { computed, onMounted, onUnmounted, ref, watch } from 'vue'
 import { useI18n } from 'vue-i18n'
 import IconExternalLink from '~icons/lucide/external-link'
 import IconSmartphone from '~icons/lucide/smartphone'
-import { buildPreviewSubdomain } from '../../shared/preview-subdomain.ts'
+import { buildChannelPreviewSubdomain, buildPreviewSubdomain } from '../../shared/preview-subdomain.ts'
 
 const props = defineProps<{
   appId: string
-  versionId: number
+  versionId?: number
+  channelId?: number
 }>()
 
 const { t } = useI18n()
@@ -53,7 +54,17 @@ const currentDevice = computed(() => devices[selectedDevice.value])
 // Build the preview URL using a reversible preview subdomain format.
 const previewUrl = computed<string | null>(() => {
   try {
-    const subdomain = buildPreviewSubdomain(props.appId, props.versionId)
+    const hasVersionId = typeof props.versionId === 'number'
+    const hasChannelId = typeof props.channelId === 'number'
+
+    if (hasVersionId === hasChannelId) {
+      console.error('BundlePreviewFrame requires exactly one preview target')
+      return null
+    }
+
+    const subdomain = hasChannelId
+      ? buildChannelPreviewSubdomain(props.appId, props.channelId as number)
+      : buildPreviewSubdomain(props.appId, props.versionId as number)
     // Extract base domain from current host, default to capgo.app for localhost
     // Preserve environment segments (e.g., 'dev' in console.dev.capgo.app)
     const hostname = window.location.hostname
diff --git a/src/pages/app/[app].channel.[channel].preview.vue b/src/pages/app/[app].channel.[channel].preview.vue
new file mode 100644
index 0000000000..d4cfe9c08e
--- /dev/null
+++ b/src/pages/app/[app].channel.[channel].preview.vue
@@ -0,0 +1,195 @@
+<script setup lang="ts">
+import type { Database } from '~/types/supabase.types'
+import { ref, watchEffect } from 'vue'
+import { useI18n } from 'vue-i18n'
+import { useRoute, useRouter } from 'vue-router'
+import IconAlertCircle from '~icons/lucide/alert-circle'
+import IconLock from '~icons/lucide/lock'
+import IconSettings from '~icons/lucide/settings'
+import { useSupabase } from '~/services/supabase'
+import { useDisplayStore } from '~/stores/display'
+
+interface ChannelPreview {
+  version: Pick<Database['public']['Tables']['app_versions']['Row'], 'id' | 'manifest_count' | 'name' | 'session_key'> | null
+}
+
+const route = useRoute()
+const router = useRouter()
+const displayStore = useDisplayStore()
+const { t } = useI18n()
+const supabase = useSupabase()
+const packageId = ref<string>('')
+const id = ref<number>(0)
+const loading = ref(true)
+const channel = ref<Database['public']['Tables']['channels']['Row'] & ChannelPreview>()
+const app = ref<Database['public']['Tables']['apps']['Row']>()
+
+type PreviewState = 'loading' | 'no-manifest' | 'preview-disabled' | 'encrypted' | 'ready'
+const previewState = ref<PreviewState>('loading')
+
+async function getChannel() {
+  if (!id.value)
+    return
+
+  try {
+    const { data, error } = await supabase
+      .from('channels')
+      .select(`
+        id,
+        app_id,
+        name,
+        version (
+          id,
+          name,
+          manifest_count,
+          session_key
+        )
+      `)
+      .eq('app_id', packageId.value)
+      .eq('id', id.value)
+      .single()
+
+    if (error) {
+      console.error('no channel', error)
+      return
+    }
+
+    channel.value = data as unknown as Database['public']['Tables']['channels']['Row'] & ChannelPreview
+
+    if (channel.value?.name)
+      displayStore.setChannelName(String(channel.value.id), channel.value.name)
+    displayStore.NavTitle = channel.value?.name ?? t('channel')
+  }
+  catch (error) {
+    console.error(error)
+  }
+}
+
+async function getApp() {
+  try {
+    const { data, error } = await supabase
+      .from('apps')
+      .select()
+      .eq('app_id', packageId.value)
+      .single()
+
+    if (error) {
+      console.error('no app', error)
+      return
+    }
+
+    app.value = data
+  }
+  catch (error) {
+    console.error(error)
+  }
+}
+
+function determinePreviewState() {
+  if (!channel.value || !app.value) {
+    previewState.value = 'loading'
+    return
+  }
+
+  if (!app.value.allow_preview) {
+    previewState.value = 'preview-disabled'
+    return
+  }
+
+  if (!channel.value.version?.manifest_count) {
+    previewState.value = 'no-manifest'
+    return
+  }
+
+  if (channel.value.version.session_key) {
+    previewState.value = 'encrypted'
+    return
+  }
+
+  previewState.value = 'ready'
+}
+
+function goToAppSettings() {
+  router.push(`/app/${packageId.value}/info`)
+}
+
+watchEffect(async () => {
+  const match = route.path.match(/^\/app\/([^/]+)\/channel\/([^/]+)\/preview$/)
+  if (match) {
+    loading.value = true
+    previewState.value = 'loading'
+    packageId.value = decodeURIComponent(match[1] ?? '')
+    id.value = Number(decodeURIComponent(match[2] ?? '0'))
+    await Promise.all([getChannel(), getApp()])
+    determinePreviewState()
+    loading.value = false
+    displayStore.defaultBack = `/app/${packageId.value}/channel/${id.value}`
+  }
+})
+</script>
+
+<template>
+  <div>
+    <div v-if="loading" class="flex flex-col justify-center items-center min-h-[50vh]">
+      <Spinner size="w-40 h-40" />
+    </div>
+
+    <div v-else-if="!channel" class="flex flex-col justify-center items-center min-h-[50vh]">
+      <IconAlertCircle class="w-16 h-16 mb-4 text-destructive" />
+      <h2 class="text-xl font-semibold text-foreground">
+        {{ t('channel-not-found') }}
+      </h2>
+      <p class="mt-2 text-muted-foreground">
+        {{ t('channel-not-found-description') }}
+      </p>
+      <button class="mt-4 text-white d-btn d-btn-primary" @click="router.push(`/app/${packageId}/channels`)">
+        {{ t('back-to-channels') }}
+      </button>
+    </div>
+
+    <div v-else-if="previewState === 'preview-disabled'" class="flex flex-col justify-center items-center min-h-[50vh]">
+      <IconSettings class="w-16 h-16 mb-4 text-muted-foreground" />
+      <h2 class="text-xl font-semibold text-foreground">
+        {{ t('preview-disabled') }}
+      </h2>
+      <p class="mt-2 text-center text-muted-foreground max-w-md">
+        {{ t('preview-disabled-description') }}
+      </p>
+      <button class="mt-4 text-white d-btn d-btn-primary" @click="goToAppSettings">
+        {{ t('preview-enable-settings') }}
+      </button>
+    </div>
+
+    <div v-else-if="previewState === 'no-manifest'" class="flex flex-col justify-center items-center min-h-[50vh]">
+      <IconAlertCircle class="w-16 h-16 mb-4 text-amber-500" />
+      <h2 class="text-xl font-semibold text-foreground">
+        {{ t('preview-not-available') }}
+      </h2>
+      <p class="mt-2 text-center text-muted-foreground max-w-md">
+        {{ t('preview-no-manifest') }}
+      </p>
+    </div>
+
+    <div v-else-if="previewState === 'encrypted'" class="flex flex-col justify-center items-center min-h-[50vh]">
+      <IconLock class="w-16 h-16 mb-4 text-amber-500" />
+      <h2 class="text-xl font-semibold text-foreground">
+        {{ t('preview-encrypted') }}
+      </h2>
+      <p class="mt-2 text-center text-muted-foreground max-w-md">
+        {{ t('preview-encrypted-description') }}
+      </p>
+    </div>
+
+    <div v-else-if="previewState === 'ready'" class="w-full h-full">
+      <BundlePreviewFrame
+        :app-id="packageId"
+        :channel-id="id"
+      />
+    </div>
+  </div>
+</template>
+
+<route lang="yaml">
+meta:
+  layout: app
+</route>
diff --git a/src/pages/app/[app].channel.[channel].vue b/src/pages/app/[app].channel.[channel].vue
index 62c93ef1e8..c6100916b1 100644
--- a/src/pages/app/[app].channel.[channel].vue
+++ b/src/pages/app/[app].channel.[channel].vue
@@ -10,6 +10,7 @@ import { toast } from 'vue-sonner'
 import IconCopy from '~icons/heroicons/clipboard-document-check'
 import IconCode from '~icons/heroicons/code-bracket'
 import Settings from '~icons/heroicons/cog-8-tooth'
+import IconEye from '~icons/heroicons/eye'
 import IconInformation from '~icons/heroicons/information-circle'
 import IconSearch from '~icons/ic/round-search?raw'
 import IconAlertCircle from '~icons/lucide/alert-circle'
@@ -83,6 +84,12 @@ function openBundle() {
   router.push(`/app/${route.params.app}/bundle/${channel.value.version.id}`)
 }
 
+function openPreview() {
+  if (!channel.value)
+    return
+  router.push(`/app/${route.params.app}/channel/${id.value}/preview`)
+}
+
 async function getChannel(force = false) {
   if (!id.value)
     return
@@ -669,6 +676,14 @@ async function copyCurlCommand() {
             <InfoRow :label="t('bundle-number')" :is-link="channel && !isInternalVersionName((channel.version.name))">
               <div class="flex items-center gap-2">
                 <span class="cursor-pointer" @click="openBundle()">{{ channel.version.name }}</span>
+                <button
+                  v-if="channel"
+                  class="p-1 transition-colors border border-gray-200 rounded-md dark:border-gray-700 hover:bg-gray-50 hover:border-gray-300 dark:hover:border-gray-600 dark:hover:bg-gray-800"
+                  :title="t('preview')"
+                  @click="openPreview()"
+                >
+                  <IconEye class="w-4 h-4 text-gray-500 dark:text-gray-400 hover:text-blue-500 dark:hover:text-blue-400" />
+                </button>
                 <button
                   v-if="channel"
                   class="p-1 transition-colors border border-gray-200 rounded-md dark:border-gray-700 hover:bg-gray-50 hover:border-gray-300 dark:hover:border-gray-600 dark:hover:bg-gray-800 disabled:opacity-50 disabled:cursor-not-allowed disabled:hover:bg-transparent disabled:hover:border-gray-200 dark:disabled:hover:border-gray-700"
diff --git a/supabase/functions/_backend/files/preview.ts b/supabase/functions/_backend/files/preview.ts
index 00970b8a50..49d6e66fe6 100644
--- a/supabase/functions/_backend/files/preview.ts
+++ b/supabase/functions/_backend/files/preview.ts
@@ -1,9 +1,10 @@
 import type { Context } from 'hono'
+import type { ParsedPreviewSubdomain } from '../../shared/preview-subdomain.ts'
 import type { MiddlewareKeyVariables } from '../utils/hono.ts'
 import { Buffer } from 'node:buffer'
 import { brotliDecompressSync } from 'node:zlib'
 import { getRuntimeKey } from 'hono/adapter'
-import { buildPreviewSubdomain, parsePreviewHostname } from '../../shared/preview-subdomain.ts'
+import { buildChannelPreviewSubdomain, buildPreviewSubdomain, parsePreviewHostname } from '../../shared/preview-subdomain.ts'
 import { CacheHelper } from '../utils/cache.ts'
 import { simpleError } from '../utils/hono.ts'
 import { cloudlog } from '../utils/logging.ts'
@@ -112,12 +113,33 @@ const MIME_TYPES: Record<string, string> = {
   wasm: 'application/wasm',
 }
 
+const BUNDLE_PREVIEW_CACHE_CONTROL = 'public, max-age=31536000, immutable'
+const CHANNEL_PREVIEW_CACHE_CONTROL = 'no-store, no-cache, must-revalidate, max-age=0'
+
 function getContentType(filePath: string): string {
   const ext = filePath.split('.').pop()?.toLowerCase() || ''
   return MIME_TYPES[ext] || 'application/octet-stream'
 }
 
-function parsePreviewSubdomain(hostname: string): { appId: string, versionId: number } | null {
+export function buildPreviewResponseHeaders(contentType: string, options: { disableCache?: boolean, httpEtag?: string } = {}): Headers {
+  const headers = new Headers()
+  headers.set('Content-Type', contentType)
+  headers.set('X-Content-Type-Options', 'nosniff')
+
+  if (options.disableCache) {
+    headers.set('Cache-Control', CHANNEL_PREVIEW_CACHE_CONTROL)
+    headers.set('Pragma', 'no-cache')
+    headers.set('Expires', '0')
+    return headers
+  }
+
+  if (options.httpEtag)
+    headers.set('etag', options.httpEtag)
+  headers.set('Cache-Control', BUNDLE_PREVIEW_CACHE_CONTROL)
+  return headers
+}
+
+function parsePreviewSubdomain(hostname: string): ParsedPreviewSubdomain | null {
   const parsed = parsePreviewHostname(hostname)
   if (!parsed || !isValidAppId(parsed.appId))
     return null
@@ -125,6 +147,26 @@ function parsePreviewSubdomain(hostname: string): { appId: string, versionId: nu
   return parsed
 }
 
+async function getChannelPreviewVersionId(c: Context<MiddlewareKeyVariables>, appId: string, channelId: number): Promise<number> {
+  const supabase = supabaseAdmin(c)
+  const { data: channel, error } = await supabase
+    .from('channels')
+    .select('version')
+    .eq('app_id', appId)
+    .eq('id', channelId)
+    .single()
+
+  if (error || !channel) {
+    throw simpleError('channel_not_found', 'Channel not found', { channelId })
+  }
+
+  if (!Number.isSafeInteger(channel.version) || channel.version <= 0) {
+    throw simpleError('bundle_not_found', 'Bundle not found', { channelId })
+  }
+
+  return channel.version
+}
+
 // Export the handler directly for use in the main app
 // This preserves the context (requestId, env bindings, etc.) from the parent app
 export async function handlePreviewRequest(c: Context<MiddlewareKeyVariables>): Promise<Response> {
@@ -133,10 +175,11 @@ export async function handlePreviewRequest(c: Context<MiddlewareKeyVariables>):
 
   if (!parsed) {
     cloudlog({ requestId: c.get('requestId'), message: 'invalid preview subdomain', hostname })
-    throw simpleError('invalid_subdomain', 'Invalid preview subdomain format. Expected: {version_id}-{preview_app_id}.preview.capgo.app')
+    throw simpleError('invalid_subdomain', 'Invalid preview subdomain format. Expected: {version_id}-{preview_app_id}.preview.capgo.app or c{channel_id}-{preview_app_id}.preview.capgo.app')
   }
 
-  const { appId, versionId } = parsed
+  const { appId } = parsed
+  const isChannelPreview = 'channelId' in parsed
 
   // Get the file path from the request path - default to index.html
   let filePath = c.req.path.slice(1) || 'index.html' // Remove leading slash
@@ -145,7 +188,15 @@ export async function handlePreviewRequest(c: Context<MiddlewareKeyVariables>):
   if (filePath.includes('?'))
     filePath = filePath.split('?')[0]
 
-  cloudlog({ requestId: c.get('requestId'), message: 'preview subdomain request', hostname, appId, versionId, filePath })
+  cloudlog({
+    requestId: c.get('requestId'),
+    message: 'preview subdomain request',
+    hostname,
+    appId,
+    channelId: isChannelPreview ? parsed.channelId : undefined,
+    versionId: 'versionId' in parsed ? parsed.versionId : undefined,
+    filePath,
+  })
 
   // Check cache for app preview authorization first
   let actualAppId: string
@@ -208,8 +259,12 @@ export async function handlePreviewRequest(c: Context<MiddlewareKeyVariables>):
     actualAppId = appData.app_id
   }
 
+  const previewVersionId = isChannelPreview
+    ? await getChannelPreviewVersionId(c, actualAppId, parsed.channelId)
+    : parsed.versionId
+
   // Check cache for bundle info
-  let bundleInfo = await getBundleInfo(c, versionId)
+  let bundleInfo = await getBundleInfo(c, previewVersionId)
 
   if (!bundleInfo) {
     const supabase = supabaseAdmin(c)
@@ -219,11 +274,11 @@ export async function handlePreviewRequest(c: Context<MiddlewareKeyVariables>):
       .from('app_versions')
       .select('id, session_key, manifest_count')
       .eq('app_id', actualAppId)
-      .eq('id', versionId)
+      .eq('id', previewVersionId)
       .single()
 
     if (bundleError || !bundle) {
-      throw simpleError('bundle_not_found', 'Bundle not found', { versionId })
+      throw simpleError('bundle_not_found', 'Bundle not found', { versionId: previewVersionId })
     }
 
     bundleInfo = {
@@ -232,7 +287,7 @@ export async function handlePreviewRequest(c: Context<MiddlewareKeyVariables>):
     }
 
     // Cache the bundle info
-    setBundleInfo(c, versionId, bundleInfo)
+    setBundleInfo(c, previewVersionId, bundleInfo)
   }
 
   // Check if bundle is encrypted
@@ -276,12 +331,12 @@ export async function handlePreviewRequest(c: Context<MiddlewareKeyVariables>):
   const { data: manifestEntries, error: manifestError } = await supabase
     .from('manifest')
     .select('s3_path, file_name')
-    .eq('app_version_id', versionId)
+    .eq('app_version_id', previewVersionId)
     .in('file_name', possiblePaths)
     .limit(1)
 
   if (manifestError || !manifestEntries || manifestEntries.length === 0) {
-    cloudlog({ requestId: c.get('requestId'), message: 'file not found in manifest', filePath, versionId, possiblePaths })
+    cloudlog({ requestId: c.get('requestId'), message: 'file not found in manifest', filePath, versionId: previewVersionId, possiblePaths })
     throw simpleError('file_not_found', 'File not found in bundle', { filePath })
   }
 
@@ -303,13 +358,19 @@ export async function handlePreviewRequest(c: Context<MiddlewareKeyVariables>):
 
     // Use our own MIME type detection - R2 rewrites text/html to text/plain without custom domains
     const contentType = getContentType(actualFileName)
-    const headers = new Headers()
-    headers.set('Content-Type', contentType)
-    headers.set('etag', object.httpEtag)
-    headers.set('Cache-Control', 'public, max-age=31536000, immutable') // Assets are immutable, cache forever
-    headers.set('X-Content-Type-Options', 'nosniff')
+    const headers = buildPreviewResponseHeaders(contentType, {
+      disableCache: isChannelPreview,
+      httpEtag: object.httpEtag,
+    })
 
-    cloudlog({ requestId: c.get('requestId'), message: 'serving preview file from R2 (subdomain)', filePath: manifestEntry.file_name, contentType, isBrotli })
+    cloudlog({
+      requestId: c.get('requestId'),
+      message: 'serving preview file from R2 (subdomain)',
+      filePath: manifestEntry.file_name,
+      contentType,
+      isBrotli,
+      cacheMode: isChannelPreview ? 'no-store' : 'immutable',
+    })
 
     // If the file is brotli compressed, decompress it before serving
     // CLI compresses with node:zlib createBrotliCompress(), we decompress with brotliDecompressSync
@@ -338,3 +399,13 @@ export function generatePreviewUrl(appId: string, versionId: number, env: 'prod'
     return null
   }
 }
+
+export function generateChannelPreviewUrl(appId: string, channelId: number, env: 'prod' | 'preprod' | 'dev' = 'prod'): string | null {
+  const envPrefix = env === 'prod' ? '' : `.${env}`
+  try {
+    return `https://${buildChannelPreviewSubdomain(appId, channelId)}.preview${envPrefix}.capgo.app`
+  }
+  catch {
+    return null
+  }
+}
diff --git a/supabase/functions/shared/preview-subdomain.ts b/supabase/functions/shared/preview-subdomain.ts
index bcf0ecdc35..172c3c4f89 100644
--- a/supabase/functions/shared/preview-subdomain.ts
+++ b/supabase/functions/shared/preview-subdomain.ts
@@ -1,15 +1,23 @@
 const PREVIEW_HOSTNAME_REGEX = /^([^.]+)\.preview(?:\.[^.]+)?\.(?:capgo\.app|usecapgo\.com)$/
 const PREVIEW_VERSION_SEPARATOR = '-'
+const PREVIEW_CHANNEL_PREFIX = 'c'
 const DNS_LABEL_MAX_LENGTH = 63
 
 /**
  * Parsed preview hostname information after the preview subdomain is decoded.
  */
-export interface ParsedPreviewSubdomain {
+export interface ParsedBundlePreviewSubdomain {
   appId: string
   versionId: number
 }
 
+export interface ParsedChannelPreviewSubdomain {
+  appId: string
+  channelId: number
+}
+
+export type ParsedPreviewSubdomain = ParsedBundlePreviewSubdomain | ParsedChannelPreviewSubdomain
+
 /**
  * Returns whether a character can be emitted directly inside the DNS-safe label.
  */
@@ -45,6 +53,11 @@ function assertValidPreviewVersionId(versionId: number): void {
     throw new Error(`Invalid preview version id: ${versionId}`)
 }
 
+function assertValidPreviewChannelId(channelId: number): void {
+  if (!Number.isSafeInteger(channelId) || channelId <= 0)
+    throw new Error(`Invalid preview channel id: ${channelId}`)
+}
+
 /**
  * Encodes an app ID into a reversible DNS-safe preview subdomain label.
  */
@@ -52,15 +65,27 @@ export function encodePreviewAppId(appId: string): string {
   return Array.from(appId).map(char => isDirectPreviewCharacter(char) ? char : encodeEscapedByte(char)).join('')
 }
 
+function buildEncodedPreviewSubdomain(target: string, appId: string): string {
+  const label = `${target}${PREVIEW_VERSION_SEPARATOR}${encodePreviewAppId(appId)}`
+  if (label.length > DNS_LABEL_MAX_LENGTH)
+    throw new Error(`Preview subdomain exceeds DNS label limit: "${label}" (${label.length} characters)`)
+  return label
+}
+
 /**
  * Builds the preview subdomain label used before `.preview.capgo.app`.
  */
 export function buildPreviewSubdomain(appId: string, versionId: number): string {
   assertValidPreviewVersionId(versionId)
-  const label = `${versionId}${PREVIEW_VERSION_SEPARATOR}${encodePreviewAppId(appId)}`
-  if (label.length > DNS_LABEL_MAX_LENGTH)
-    throw new Error(`Preview subdomain exceeds DNS label limit: "${label}" (${label.length} characters)`)
-  return label
+  return buildEncodedPreviewSubdomain(String(versionId), appId)
+}
+
+/**
+ * Builds the preview subdomain label for stable channel previews.
+ */
+export function buildChannelPreviewSubdomain(appId: string, channelId: number): string {
+  assertValidPreviewChannelId(channelId)
+  return buildEncodedPreviewSubdomain(`${PREVIEW_CHANNEL_PREFIX}${channelId}`, appId)
 }
 
 /**
@@ -117,6 +142,13 @@ function parseVersionId(value: string): number | null {
   return Number.isSafeInteger(versionId) ? versionId : null
 }
 
+function parseChannelId(value: string): number | null {
+  const channelId = parseVersionId(value)
+  if (channelId === null || channelId <= 0)
+    return null
+  return channelId
+}
+
 /**
  * Parses the new reversible preview subdomain format.
  */
@@ -125,15 +157,24 @@ function parseEncodedPreviewSubdomain(subdomain: string): ParsedPreviewSubdomain
   if (separatorIndex <= 0)
     return null
 
-  const versionId = parseVersionId(subdomain.slice(0, separatorIndex))
-  if (versionId === null)
-    return null
-
+  const target = subdomain.slice(0, separatorIndex)
   const encodedAppId = subdomain.slice(separatorIndex + PREVIEW_VERSION_SEPARATOR.length)
   const appId = decodePreviewAppId(encodedAppId)
   if (!appId)
     return null
 
+  if (target.startsWith(PREVIEW_CHANNEL_PREFIX)) {
+    const channelId = parseChannelId(target.slice(PREVIEW_CHANNEL_PREFIX.length))
+    if (channelId === null)
+      return null
+
+    return { appId, channelId }
+  }
+
+  const versionId = parseVersionId(target)
+  if (versionId === null)
+    return null
+
   return { appId, versionId }
 }
 
diff --git a/tests/preview-response-headers.unit.test.ts b/tests/preview-response-headers.unit.test.ts
new file mode 100644
index 0000000000..51d7164d59
--- /dev/null
+++ b/tests/preview-response-headers.unit.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest'
+import { buildPreviewResponseHeaders } from '../supabase/functions/_backend/files/preview.ts'
+
+describe('preview response headers', () => {
+  it.concurrent('keeps bundle preview responses immutable', () => {
+    const headers = buildPreviewResponseHeaders('text/html', {
+      httpEtag: '"bundle-etag"',
+    })
+
+    expect(headers.get('content-type')).toBe('text/html')
+    expect(headers.get('cache-control')).toBe('public, max-age=31536000, immutable')
+    expect(headers.get('etag')).toBe('"bundle-etag"')
+    expect(headers.get('pragma')).toBeNull()
+    expect(headers.get('expires')).toBeNull()
+  })
+
+  it.concurrent('disables caching for channel preview responses', () => {
+    const headers = buildPreviewResponseHeaders('text/html', {
+      disableCache: true,
+      httpEtag: '"channel-etag"',
+    })
+
+    expect(headers.get('content-type')).toBe('text/html')
+    expect(headers.get('cache-control')).toBe('no-store, no-cache, must-revalidate, max-age=0')
+    expect(headers.get('etag')).toBeNull()
+    expect(headers.get('pragma')).toBe('no-cache')
+    expect(headers.get('expires')).toBe('0')
+  })
+})
diff --git a/tests/preview-subdomain.unit.test.ts b/tests/preview-subdomain.unit.test.ts
index 7a8ea00ac8..cb4af55760 100644
--- a/tests/preview-subdomain.unit.test.ts
+++ b/tests/preview-subdomain.unit.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { buildPreviewSubdomain, encodePreviewAppId, parsePreviewHostname } from '../shared/preview-subdomain.ts'
+import { buildChannelPreviewSubdomain, buildPreviewSubdomain, encodePreviewAppId, parsePreviewHostname } from '../shared/preview-subdomain.ts'
 
 describe('preview subdomain encoding', () => {
   it.concurrent('round-trips app IDs with reserved hostname characters', () => {
@@ -35,6 +35,15 @@ describe('preview subdomain encoding', () => {
     })
   })
 
+  it.concurrent('round-trips stable channel preview hostnames', () => {
+    const appId = 'Com.Example_app-name'
+    const channelId = 123456
+    const subdomain = buildChannelPreviewSubdomain(appId, channelId)
+
+    expect(subdomain).not.toMatch(/[.A-Z]/)
+    expect(parsePreviewHostname(`${subdomain}.preview.capgo.app`)).toEqual({ appId, channelId })
+  })
+
   it.concurrent('returns null for malformed hostnames', () => {
     expect(parsePreviewHostname('invalid.domain.com')).toBeNull()
     expect(parsePreviewHostname('')).toBeNull()
@@ -82,7 +91,20 @@ describe('preview subdomain encoding', () => {
     )
   })
 
+  it.concurrent('rejects invalid preview channel ids before building labels', () => {
+    expect(() => buildChannelPreviewSubdomain('com.example', 0)).toThrow('Invalid preview channel id: 0')
+    expect(() => buildChannelPreviewSubdomain('com.example', 1.5)).toThrow('Invalid preview channel id: 1.5')
+    expect(() => buildChannelPreviewSubdomain('com.example', Number.MAX_SAFE_INTEGER + 1)).toThrow(
+      `Invalid preview channel id: ${Number.MAX_SAFE_INTEGER + 1}`,
+    )
+  })
+
   it.concurrent('rejects preview hostnames whose version id exceeds the safe integer range', () => {
     expect(parsePreviewHostname('9007199254740992-com-0example.preview.capgo.app')).toBeNull()
   })
+
+  it.concurrent('rejects preview hostnames whose channel id is not a positive safe integer', () => {
+    expect(parsePreviewHostname('c0-com-0example.preview.capgo.app')).toBeNull()
+    expect(parsePreviewHostname('c9007199254740992-com-0example.preview.capgo.app')).toBeNull()
+  })
 })

From 2a307fa2dea3c3b483792190163ab47ac491bbec Mon Sep 17 00:00:00 2001
From: Martin Donadieu <martindonadieu@gmail.com>
Date: Thu, 30 Apr 2026 11:15:27 +0200
Subject: [PATCH 2/2] fix(preview): address channel preview review feedback

---
 .../app/[app].channel.[channel].preview.vue   | 52 ++++++++++++++-----
 src/pages/app/[app].channel.[channel].vue     |  5 +-
 src/route-map.d.ts                            | 13 +++++
 3 files changed, 54 insertions(+), 16 deletions(-)

diff --git a/src/pages/app/[app].channel.[channel].preview.vue b/src/pages/app/[app].channel.[channel].preview.vue
index d4cfe9c08e..4d807358f0 100644
--- a/src/pages/app/[app].channel.[channel].preview.vue
+++ b/src/pages/app/[app].channel.[channel].preview.vue
@@ -13,7 +13,7 @@ interface ChannelPreview {
   version: Pick<Database['public']['Tables']['app_versions']['Row'], 'id' | 'manifest_count' | 'name' | 'session_key'> | null
 }
 
-const route = useRoute()
+const route = useRoute('/app/[app].channel.[channel].preview')
 const router = useRouter()
 const displayStore = useDisplayStore()
 const { t } = useI18n()
@@ -24,7 +24,7 @@ const loading = ref(true)
 const channel = ref<Database['public']['Tables']['channels']['Row'] & ChannelPreview>()
 const app = ref<Database['public']['Tables']['apps']['Row']>()
 
-type PreviewState = 'loading' | 'no-manifest' | 'preview-disabled' | 'encrypted' | 'ready'
+type PreviewState = 'loading' | 'no-app' | 'no-manifest' | 'preview-disabled' | 'encrypted' | 'ready'
 const previewState = ref<PreviewState>('loading')
 
 async function getChannel() {
@@ -51,6 +51,8 @@ async function getChannel() {
 
     if (error) {
       console.error('no channel', error)
+      channel.value = undefined
+      displayStore.NavTitle = t('channel')
       return
     }
 
@@ -61,6 +63,8 @@ async function getChannel() {
     displayStore.NavTitle = channel.value?.name ?? t('channel')
   }
   catch (error) {
+    channel.value = undefined
+    displayStore.NavTitle = t('channel')
     console.error(error)
   }
 }
@@ -75,22 +79,29 @@ async function getApp() {
 
     if (error) {
       console.error('no app', error)
+      app.value = undefined
       return
     }
 
     app.value = data
   }
   catch (error) {
+    app.value = undefined
     console.error(error)
   }
 }
 
 function determinePreviewState() {
-  if (!channel.value || !app.value) {
+  if (!channel.value) {
     previewState.value = 'loading'
     return
   }
 
+  if (!app.value) {
+    previewState.value = 'no-app'
+    return
+  }
+
   if (!app.value.allow_preview) {
     previewState.value = 'preview-disabled'
     return
@@ -114,17 +125,17 @@ function goToAppSettings() {
 }
 
 watchEffect(async () => {
-  const match = route.path.match(/^\/app\/([^/]+)\/channel\/([^/]+)\/preview$/)
-  if (match) {
-    loading.value = true
-    previewState.value = 'loading'
-    packageId.value = decodeURIComponent(match[1] ?? '')
-    id.value = Number(decodeURIComponent(match[2] ?? '0'))
-    await Promise.all([getChannel(), getApp()])
-    determinePreviewState()
-    loading.value = false
-    displayStore.defaultBack = `/app/${packageId.value}/channel/${id.value}`
-  }
+  loading.value = true
+  previewState.value = 'loading'
+  channel.value = undefined
+  app.value = undefined
+  displayStore.NavTitle = t('channel')
+  packageId.value = route.params.app as string
+  id.value = Number(route.params.channel as string)
+  await Promise.all([getChannel(), getApp()])
+  determinePreviewState()
+  loading.value = false
+  displayStore.defaultBack = `/app/${packageId.value}/channel/${id.value}`
 })
 </script>
 
@@ -147,6 +158,19 @@ watchEffect(async () => {
       </button>
     </div>
 
+    <div v-else-if="previewState === 'no-app'" class="flex flex-col justify-center items-center min-h-[50vh]">
+      <IconAlertCircle class="w-16 h-16 mb-4 text-destructive" />
+      <h2 class="text-xl font-semibold text-foreground">
+        {{ t('app-not-found') }}
+      </h2>
+      <p class="mt-2 text-center text-muted-foreground max-w-md">
+        {{ t('app-not-found-description') }}
+      </p>
+      <button class="mt-4 text-white d-btn d-btn-primary" @click="router.push('/apps')">
+        {{ t('back-to-apps') }}
+      </button>
+    </div>
+
     <div v-else-if="previewState === 'preview-disabled'" class="flex flex-col justify-center items-center min-h-[50vh]">
       <IconSettings class="w-16 h-16 mb-4 text-muted-foreground" />
       <h2 class="text-xl font-semibold text-foreground">
diff --git a/src/pages/app/[app].channel.[channel].vue b/src/pages/app/[app].channel.[channel].vue
index c6100916b1..b3d4e0b4df 100644
--- a/src/pages/app/[app].channel.[channel].vue
+++ b/src/pages/app/[app].channel.[channel].vue
@@ -678,11 +678,12 @@ async function copyCurlCommand() {
                 <span class="cursor-pointer" @click="openBundle()">{{ channel.version.name }}</span>
                 <button
                   v-if="channel"
-                  class="p-1 transition-colors border border-gray-200 rounded-md dark:border-gray-700 hover:bg-gray-50 hover:border-gray-300 dark:hover:border-gray-600 dark:hover:bg-gray-800"
+                  class="border border-gray-200 dark:border-gray-700 d-btn d-btn-ghost d-btn-square d-btn-sm"
                   :title="t('preview')"
+                  :aria-label="t('preview')"
                   @click="openPreview()"
                 >
-                  <IconEye class="w-4 h-4 text-gray-500 dark:text-gray-400 hover:text-blue-500 dark:hover:text-blue-400" />
+                  <IconEye class="w-4 h-4 text-gray-500 dark:text-gray-400" />
                 </button>
                 <button
                   v-if="channel"
diff --git a/src/route-map.d.ts b/src/route-map.d.ts
index d7fdeea644..b21c28adb0 100644
--- a/src/route-map.d.ts
+++ b/src/route-map.d.ts
@@ -195,6 +195,13 @@ declare module 'vue-router/auto-routes' {
       { app: ParamValue<false>, channel: ParamValue<false> },
       | never
     >,
+    '/app/[app].channel.[channel].preview': RouteRecordInfo<
+      '/app/[app].channel.[channel].preview',
+      '/app/:app/channel/:channel/preview',
+      { app: ParamValue<true>, channel: ParamValue<true> },
+      { app: ParamValue<false>, channel: ParamValue<false> },
+      | never
+    >,
     '/app/[app].channel.[channel].statistics': RouteRecordInfo<
       '/app/[app].channel.[channel].statistics',
       '/app/:app/channel/:channel/statistics',
@@ -667,6 +674,12 @@ declare module 'vue-router/auto-routes' {
       views:
         | never
     }
+    'src/pages/app/[app].channel.[channel].preview.vue': {
+      routes:
+        | '/app/[app].channel.[channel].preview'
+      views:
+        | never
+    }
     'src/pages/app/[app].channel.[channel].statistics.vue': {
       routes:
         | '/app/[app].channel.[channel].statistics'