@duffcloudservices/cms 0.3.12 → 0.3.14

package/src/components/PreviewRibbon.vue

@@ -1,613 +1,613 @@
-<template>
-  <Teleport to="body">
-    <div v-if="isVisible" :class="['dcs-ribbon-container', `dcs-ribbon-container--${side}`]">
-      <svg
-        :viewBox="`0 0 ${SVG_SIZE} ${SVG_SIZE}`"
-        class="dcs-ribbon-svg"
-      >
-        <defs>
-          <path id="dcs-ribbon-text-path" :d="textPath" />
-          <linearGradient
-            id="dcs-ribbon-grad"
-            :x1="side === 'left' ? '0%' : '100%'"
-            y1="100%"
-            :x2="side === 'left' ? '100%' : '0%'"
-            y2="0%"
-          >
-            <stop offset="0%" stop-color="#1a1a2e" />
-            <stop offset="40%" stop-color="#16213e" />
-            <stop offset="100%" stop-color="#0f3460" />
-          </linearGradient>
-          <filter id="dcs-ribbon-ts">
-            <feDropShadow dx="0" dy="1" stdDeviation="0.8" flood-color="rgba(0,0,0,0.5)" />
-          </filter>
-        </defs>
-
-        <!-- Drop shadow (offset copy of band) -->
-        <path
-          :d="bandPath"
-          fill="rgba(0,0,0,0.2)"
-          :transform="side === 'left' ? 'translate(2,3)' : 'translate(-2,3)'"
-        />
-
-        <!-- Main ribbon band -->
-        <path
-          :d="bandPath"
-          fill="url(#dcs-ribbon-grad)"
-          stroke="rgba(255,255,255,0.08)"
-          stroke-width="1"
-          class="dcs-ribbon-band"
-        />
-
-        <!-- Decorative stitched borders -->
-        <path :d="outerStitchPath" class="dcs-ribbon-stitch" />
-        <path :d="innerStitchPath" class="dcs-ribbon-stitch" />
-
-        <!-- Text: full (wide screens) -->
-        <text
-          class="dcs-ribbon-text dcs-ribbon-text--full"
-          dominant-baseline="central"
-          filter="url(#dcs-ribbon-ts)"
-        >
-          <textPath href="#dcs-ribbon-text-path" startOffset="50%" text-anchor="middle">
-            Duff Cloud Services Preview Site{{ displayVersion }}
-          </textPath>
-        </text>
-
-        <!-- Text: compact (narrow screens) -->
-        <text
-          class="dcs-ribbon-text dcs-ribbon-text--compact"
-          dominant-baseline="central"
-          filter="url(#dcs-ribbon-ts)"
-        >
-          <textPath href="#dcs-ribbon-text-path" startOffset="50%" text-anchor="middle">
-            DCS Preview{{ displayVersion }}
-          </textPath>
-        </text>
-      </svg>
-
-      <!--
-        Touch overlay: transparent HTML <div> sitting on top of the SVG.
-        Android Chrome ignores touch-action: none on SVG <path> elements
-        because the compositor only checks HTML elements in the hit chain.
-        This HTML div with clip-path creates a reliable touch-action: none
-        hit area over the ribbon band that works on all mobile browsers.
-      -->
-      <div
-        ref="touchOverlayRef"
-        :class="['dcs-ribbon-touch', { 'dcs-ribbon-touch--dragging': isDragging }]"
-        :style="touchClipStyle"
-        @pointerdown.stop.prevent="onPointerDown"
-      />
-    </div>
-  </Teleport>
-</template>
-
-<script setup lang="ts">
-import { ref, computed, onMounted, onBeforeUnmount, watch } from 'vue'
-
-/* ------------------------------------------------------------------ */
-/*  Props                                                              */
-/* ------------------------------------------------------------------ */
-const props = withDefaults(
-  defineProps<{
-    /** Override the auto-detected version string (e.g. "1.2.3"). */
-    version?: string | null
-  }>(),
-  {
-    version: null,
-  },
-)
-
-/* ------------------------------------------------------------------ */
-/*  Geometry constants                                                 */
-/* ------------------------------------------------------------------ */
-
-/** SVG viewBox size (square, covers the ribbon corner area) */
-const SVG_SIZE = 260
-
-/** Where the ribbon center-line meets each viewport edge */
-const EP = 220
-
-/** Half the ribbon band width (perpendicular to curve) */
-const HW = 20
-
-/** Default bezier control-point position (x = y → symmetric 45° curve) */
-const CP0 = 90
-
-/**
- * Perpendicular offset for band edges relative to center control point.
- * HW / √2 because the perpendicular to a 45° diagonal has (1/√2, 1/√2)
- * components.
- */
-const CPO = Math.round(HW / Math.SQRT2) // ≈ 14
-
-/** Stitch-line inset from band edges (px in SVG space) */
-const STI = 4
-
-/* ------------------------------------------------------------------ */
-/*  Constants                                                          */
-/* ------------------------------------------------------------------ */
-
-/** The preview domain where the ribbon should be displayed */
-const PREVIEW_DOMAIN = 'preview.duffcloudservices.com'
-
-/**
- * Query string parameter that suppresses the preview ribbon.
- * Used by GitHub Actions snapshot capture so screenshots don't include the ribbon overlay.
- * Example: https://preview.duffcloudservices.com/kept/?dcs-hide-ribbon
- */
-const HIDE_RIBBON_PARAM = 'dcs-hide-ribbon'
-
-/** localStorage key for persisting which corner the ribbon is docked to */
-const STORAGE_KEY = 'dcs-preview-ribbon-side'
-
-/* ------------------------------------------------------------------ */
-/*  Visibility gate                                                    */
-/* ------------------------------------------------------------------ */
-const isVisible = ref(false)
-
-function shouldShow(): boolean {
-  if (globalThis.window === undefined) return false
-
-  const host = globalThis.location.hostname
-
-  // Only show on the preview domain
-  if (host !== PREVIEW_DOMAIN) return false
-
-  // Never show in the visual page editor (iframe inside portal)
-  try {
-    if (globalThis.self !== globalThis.top) return false
-  } catch {
-    // cross-origin – inside an iframe → editor context
-    return false
-  }
-
-  // Allow suppression via query parameter (for automated screenshot capture)
-  const params = new URLSearchParams(globalThis.location.search)
-  if (params.has(HIDE_RIBBON_PARAM)) return false
-
-  return true
-}
-
-/* ------------------------------------------------------------------ */
-/*  Side state (which corner the ribbon is docked to, persisted)       */
-/* ------------------------------------------------------------------ */
-const side = ref<'left' | 'right'>('left')
-
-function loadSide(): 'left' | 'right' {
-  try {
-    const s = localStorage.getItem(STORAGE_KEY)
-    if (s === 'left' || s === 'right') return s
-  } catch { /* noop */ }
-  return 'left'
-}
-
-function saveSide(s: 'left' | 'right') {
-  try { localStorage.setItem(STORAGE_KEY, s) } catch { /* noop */ }
-}
-
-/* ------------------------------------------------------------------ */
-/*  Version display                                                    */
-/* ------------------------------------------------------------------ */
-const resolvedVersion = ref<string | null>(props.version ?? null)
-
-const displayVersion = computed(() =>
-  resolvedVersion.value ? ` v${resolvedVersion.value}` : '',
-)
-
-// Sync prop changes
-watch(
-  () => props.version,
-  (v) => {
-    if (v !== null && v !== undefined) resolvedVersion.value = v
-  },
-)
-
-/* ------------------------------------------------------------------ */
-/*  Lifecycle                                                          */
-/* ------------------------------------------------------------------ */
-onMounted(async () => {
-  isVisible.value = shouldShow()
-  if (!isVisible.value) return
-
-  side.value = loadSide()
-
-  // Resolve version
-  if (resolvedVersion.value) return
-
-  try {
-    const envVersion = (import.meta.env as Record<string, string | undefined>)
-      .VITE_SITE_VERSION
-    if (envVersion) {
-      resolvedVersion.value = envVersion
-      return
-    }
-  } catch {
-    /* noop */
-  }
-
-  try {
-    const slug =
-      (import.meta.env as Record<string, string | undefined>).VITE_SITE_SLUG ??
-      ''
-    if (!slug) return
-    const base =
-      (import.meta.env as Record<string, string | undefined>)
-        .VITE_API_BASE_URL ?? 'https://portal.duffcloudservices.com'
-    const res = await fetch(
-      `${base}/api/v1/sites/${slug}/release-notes/latest`,
-      { headers: { Accept: 'application/json' } },
-    )
-    if (res.ok) {
-      const data = await res.json()
-      if (data.version) resolvedVersion.value = data.version
-    }
-  } catch {
-    /* non-critical */
-  }
-})
-
-/* ------------------------------------------------------------------ */
-/*  Elastic stretch state (control-point displacement)                 */
-/* ------------------------------------------------------------------ */
-const stretchX = ref(0)
-const stretchY = ref(0)
-const isDragging = ref(false)
-
-/**
- * Absolute SVG-space control point for the band center-line.
- * Left side default: (CP0, CP0) = (90, 90)
- * Right side default: (SVG_SIZE - CP0, CP0) = (170, 90)
- * stretchX/Y displace the control point in screen-mapped SVG units.
- */
-const cx = computed(() =>
-  side.value === 'left'
-    ? CP0 + stretchX.value
-    : SVG_SIZE - CP0 + stretchX.value,
-)
-const cy = computed(() => CP0 + stretchY.value)
-
-/**
- * Perpendicular sign: for left-side ribbon the outward perpendicular
- * direction is (+1, +1); for right-side it is (-1, +1).
- * This determines how CPO is applied to get outer/inner band edges.
- */
-const ps = computed(() => (side.value === 'left' ? 1 : -1))
-
-/* ------------------------------------------------------------------ */
-/*  SVG path computation (side-aware, with elastic control-point)      */
-/* ------------------------------------------------------------------ */
-
-/**
- * Text center-line. On the right side the path direction is reversed
- * so that textPath renders left-to-right (readable).
- */
-const textPath = computed(() => {
-  if (side.value === 'left') {
-    return `M 0,${EP} Q ${cx.value},${cy.value} ${EP},0`
-  }
-  return `M ${SVG_SIZE - EP},0 Q ${cx.value},${cy.value} ${SVG_SIZE},${EP}`
-})
-
-const bandPath = computed(() => {
-  const p = ps.value
-  // Outer edge control point (further from corner)
-  const ocx = cx.value + p * CPO
-  const ocy = cy.value + CPO
-  // Inner edge control point (closer to corner)
-  const icx = cx.value - p * CPO
-  const icy = cy.value - CPO
-
-  if (side.value === 'left') {
-    return [
-      `M 0,${EP + HW} Q ${ocx},${ocy} ${EP + HW},0`,
-      `L ${EP - HW},0`,
-      `Q ${icx},${icy} 0,${EP - HW}`,
-      `Z`,
-    ].join(' ')
-  }
-
-  return [
-    `M ${SVG_SIZE},${EP + HW} Q ${ocx},${ocy} ${SVG_SIZE - EP - HW},0`,
-    `L ${SVG_SIZE - EP + HW},0`,
-    `Q ${icx},${icy} ${SVG_SIZE},${EP - HW}`,
-    `Z`,
-  ].join(' ')
-})
-
-const outerStitchPath = computed(() => {
-  const p = ps.value
-  const scx = cx.value + p * (CPO - 3)
-  const scy = cy.value + (CPO - 3)
-  const d = EP + HW - STI
-
-  if (side.value === 'left') {
-    return `M 0,${d} Q ${scx},${scy} ${d},0`
-  }
-  return `M ${SVG_SIZE},${d} Q ${scx},${scy} ${SVG_SIZE - d},0`
-})
-
-const innerStitchPath = computed(() => {
-  const p = ps.value
-  const scx = cx.value - p * (CPO - 3)
-  const scy = cy.value - (CPO - 3)
-  const d = EP - HW + STI
-
-  if (side.value === 'left') {
-    return `M 0,${d} Q ${scx},${scy} ${d},0`
-  }
-  return `M ${SVG_SIZE},${d} Q ${scx},${scy} ${SVG_SIZE - d},0`
-})
-
-/* ------------------------------------------------------------------ */
-/*  Touch overlay clip-path                                            */
-/* ------------------------------------------------------------------ */
-
-/**
- * Clip-path polygon that creates an invisible hit area over the ribbon
- * band, wider than the visible band for comfortable touch targeting.
- * This is on an HTML <div>, so touch-action: none is guaranteed to work
- * on Android Chrome (unlike SVG <path> elements).
- */
-const touchClipStyle = computed(() => {
-  if (side.value === 'left') {
-    // Quadrilateral covering the band diagonal: bottom-left → top-right
-    return { clipPath: 'polygon(0% 100%, 100% 0%, 65% 0%, 0% 65%)' }
-  }
-  // Right side: mirrored
-  return { clipPath: 'polygon(100% 100%, 0% 0%, 35% 0%, 100% 65%)' }
-})
-
-/* ------------------------------------------------------------------ */
-/*  Drag: elastic control-point stretch + flip on midpoint crossing    */
-/* ------------------------------------------------------------------ */
-const touchOverlayRef = ref<HTMLDivElement | null>(null)
-let dragStart: { x: number; y: number } | null = null
-let springRaf = 0
-
-/**
- * Get the rendered pixel size of the SVG element.
- * Used to convert screen-space drag deltas to SVG-space units.
- */
-function getSvgPixelSize(): number {
-  return window.innerWidth <= 640 ? 200 : 260
-}
-
-function onPointerDown(e: PointerEvent) {
-  // Cancel any in-progress spring animation
-  if (springRaf) {
-    cancelAnimationFrame(springRaf)
-    springRaf = 0
-  }
-
-  // Capture the pointer on the HTML overlay div.
-  // Unlike SVG <path> elements, HTML elements reliably support
-  // setPointerCapture on Android Chrome, ensuring all subsequent
-  // pointer events are delivered even when the finger moves outside.
-  const target = e.currentTarget as HTMLElement
-  target.setPointerCapture(e.pointerId)
-
-  isDragging.value = true
-  dragStart = { x: e.clientX, y: e.clientY }
-
-  globalThis.addEventListener('pointermove', onPointerMove)
-  globalThis.addEventListener('pointerup', onPointerUp)
-  globalThis.addEventListener('pointercancel', onPointerUp)
-}
-
-function onPointerMove(e: PointerEvent) {
-  if (!dragStart) return
-
-  // Convert screen-space drag delta to SVG-space units
-  const scale = SVG_SIZE / getSvgPixelSize()
-  stretchX.value = (e.clientX - dragStart.x) * scale
-  stretchY.value = (e.clientY - dragStart.y) * scale
-
-  // Flip when the pointer crosses the viewport midpoint
-  const mid = window.innerWidth / 2
-  if (side.value === 'left' && e.clientX > mid) {
-    triggerFlip('right', e)
-  } else if (side.value === 'right' && e.clientX < mid) {
-    triggerFlip('left', e)
-  }
-}
-
-function onPointerUp(e: PointerEvent) {
-  if (touchOverlayRef.value) {
-    try { touchOverlayRef.value.releasePointerCapture(e.pointerId) } catch { /* already released */ }
-  }
-  isDragging.value = false
-  dragStart = null
-  removeListeners()
-  animateSnapBack()
-}
-
-function removeListeners() {
-  globalThis.removeEventListener('pointermove', onPointerMove)
-  globalThis.removeEventListener('pointerup', onPointerUp)
-  globalThis.removeEventListener('pointercancel', onPointerUp)
-}
-
-/**
- * Snap the ribbon to the opposite corner when the pointer crosses
- * the viewport midpoint. Resets the elastic stretch, switches side,
- * and persists the user's preference.
- */
-function triggerFlip(newSide: 'left' | 'right', e: PointerEvent) {
-  // Reset stretch to default shape
-  stretchX.value = 0
-  stretchY.value = 0
-
-  // End drag
-  isDragging.value = false
-  dragStart = null
-  removeListeners()
-
-  // Release pointer capture
-  if (touchOverlayRef.value) {
-    try { touchOverlayRef.value.releasePointerCapture(e.pointerId) } catch { /* noop */ }
-  }
-
-  // Switch to the new side
-  side.value = newSide
-  saveSide(newSide)
-}
-
-/** Spring-physics animation to snap the control point back to default */
-function animateSnapBack() {
-  const stiffness = 0.12
-  const damping = 0.72
-  let vx = 0
-  let vy = 0
-
-  function step() {
-    vx = (vx - stiffness * stretchX.value) * damping
-    vy = (vy - stiffness * stretchY.value) * damping
-    stretchX.value += vx
-    stretchY.value += vy
-
-    if (
-      Math.abs(stretchX.value) < 0.3 &&
-      Math.abs(stretchY.value) < 0.3 &&
-      Math.abs(vx) < 0.3 &&
-      Math.abs(vy) < 0.3
-    ) {
-      stretchX.value = 0
-      stretchY.value = 0
-      springRaf = 0
-      return
-    }
-
-    springRaf = requestAnimationFrame(step)
-  }
-
-  springRaf = requestAnimationFrame(step)
-}
-
-/* ------------------------------------------------------------------ */
-/*  Cleanup                                                            */
-/* ------------------------------------------------------------------ */
-onBeforeUnmount(() => {
-  if (springRaf) cancelAnimationFrame(springRaf)
-  removeListeners()
-})
-</script>
-
-<style scoped>
-/* ------------------------------------------------------------------ */
-/*  Container — fixed in corner, non-blocking                          */
-/* ------------------------------------------------------------------ */
-.dcs-ribbon-container {
-  position: fixed;
-  top: 0;
-  z-index: 2147483647;
-  pointer-events: none;
-  user-select: none;
-  -webkit-user-select: none;
-}
-
-.dcs-ribbon-container--left {
-  left: 0;
-  right: auto;
-}
-
-.dcs-ribbon-container--right {
-  right: 0;
-  left: auto;
-}
-
-/* ------------------------------------------------------------------ */
-/*  SVG canvas                                                         */
-/* ------------------------------------------------------------------ */
-.dcs-ribbon-svg {
-  display: block;
-  width: 260px;
-  height: 260px;
-  overflow: visible;
-  pointer-events: none;
-}
-
-/* ------------------------------------------------------------------ */
-/*  Band (visual only — touch handled by overlay div)                  */
-/* ------------------------------------------------------------------ */
-.dcs-ribbon-band {
-  pointer-events: none;
-}
-
-/* ------------------------------------------------------------------ */
-/*  Stitched borders                                                   */
-/* ------------------------------------------------------------------ */
-.dcs-ribbon-stitch {
-  fill: none;
-  stroke: rgba(255, 255, 255, 0.15);
-  stroke-width: 1;
-  stroke-dasharray: 4 3;
-  pointer-events: none;
-}
-
-/* ------------------------------------------------------------------ */
-/*  Text                                                               */
-/* ------------------------------------------------------------------ */
-.dcs-ribbon-text {
-  fill: #e0e7ff;
-  font-family: 'Inter', 'Segoe UI', system-ui, -apple-system, sans-serif;
-  font-weight: 600;
-  font-size: 12px;
-  letter-spacing: 0.06em;
-  text-transform: uppercase;
-  pointer-events: none;
-}
-
-/* Full label for wide screens */
-.dcs-ribbon-text--full {
-  display: block;
-}
-.dcs-ribbon-text--compact {
-  display: none;
-}
-
-/* ------------------------------------------------------------------ */
-/*  Touch overlay — transparent HTML div for reliable mobile touch     */
-/*                                                                     */
-/*  Android Chrome ignores touch-action on SVG <path> elements because */
-/*  the compositor only walks HTML elements. This HTML <div> with      */
-/*  clip-path creates a shaped, invisible hit area where touch-action  */
-/*  is guaranteed to work.                                             */
-/* ------------------------------------------------------------------ */
-.dcs-ribbon-touch {
-  position: absolute;
-  top: 0;
-  left: 0;
-  width: 260px;
-  height: 260px;
-  touch-action: none;
-  pointer-events: auto;
-  cursor: grab;
-  -webkit-tap-highlight-color: transparent;
-  /* clip-path set via :style binding for left/right side */
-}
-
-.dcs-ribbon-touch--dragging {
-  cursor: grabbing;
-}
-
-/* Compact label for narrow screens */
-@media (max-width: 640px) {
-  .dcs-ribbon-svg {
-    width: 200px;
-    height: 200px;
-  }
-  .dcs-ribbon-touch {
-    width: 200px;
-    height: 200px;
-  }
-  .dcs-ribbon-text--full {
-    display: none;
-  }
-  .dcs-ribbon-text--compact {
-    display: block;
-    font-size: 11px;
-  }
-}
+<template>
+  <Teleport to="body">
+    <div v-if="isVisible" :class="['dcs-ribbon-container', `dcs-ribbon-container--${side}`]">
+      <svg
+        :viewBox="`0 0 ${SVG_SIZE} ${SVG_SIZE}`"
+        class="dcs-ribbon-svg"
+      >
+        <defs>
+          <path id="dcs-ribbon-text-path" :d="textPath" />
+          <linearGradient
+            id="dcs-ribbon-grad"
+            :x1="side === 'left' ? '0%' : '100%'"
+            y1="100%"
+            :x2="side === 'left' ? '100%' : '0%'"
+            y2="0%"
+          >
+            <stop offset="0%" stop-color="#1a1a2e" />
+            <stop offset="40%" stop-color="#16213e" />
+            <stop offset="100%" stop-color="#0f3460" />
+          </linearGradient>
+          <filter id="dcs-ribbon-ts">
+            <feDropShadow dx="0" dy="1" stdDeviation="0.8" flood-color="rgba(0,0,0,0.5)" />
+          </filter>
+        </defs>
+
+        <!-- Drop shadow (offset copy of band) -->
+        <path
+          :d="bandPath"
+          fill="rgba(0,0,0,0.2)"
+          :transform="side === 'left' ? 'translate(2,3)' : 'translate(-2,3)'"
+        />
+
+        <!-- Main ribbon band -->
+        <path
+          :d="bandPath"
+          fill="url(#dcs-ribbon-grad)"
+          stroke="rgba(255,255,255,0.08)"
+          stroke-width="1"
+          class="dcs-ribbon-band"
+        />
+
+        <!-- Decorative stitched borders -->
+        <path :d="outerStitchPath" class="dcs-ribbon-stitch" />
+        <path :d="innerStitchPath" class="dcs-ribbon-stitch" />
+
+        <!-- Text: full (wide screens) -->
+        <text
+          class="dcs-ribbon-text dcs-ribbon-text--full"
+          dominant-baseline="central"
+          filter="url(#dcs-ribbon-ts)"
+        >
+          <textPath href="#dcs-ribbon-text-path" startOffset="50%" text-anchor="middle">
+            Duff Cloud Services Preview Site{{ displayVersion }}
+          </textPath>
+        </text>
+
+        <!-- Text: compact (narrow screens) -->
+        <text
+          class="dcs-ribbon-text dcs-ribbon-text--compact"
+          dominant-baseline="central"
+          filter="url(#dcs-ribbon-ts)"
+        >
+          <textPath href="#dcs-ribbon-text-path" startOffset="50%" text-anchor="middle">
+            DCS Preview{{ displayVersion }}
+          </textPath>
+        </text>
+      </svg>
+
+      <!--
+        Touch overlay: transparent HTML <div> sitting on top of the SVG.
+        Android Chrome ignores touch-action: none on SVG <path> elements
+        because the compositor only checks HTML elements in the hit chain.
+        This HTML div with clip-path creates a reliable touch-action: none
+        hit area over the ribbon band that works on all mobile browsers.
+      -->
+      <div
+        ref="touchOverlayRef"
+        :class="['dcs-ribbon-touch', { 'dcs-ribbon-touch--dragging': isDragging }]"
+        :style="touchClipStyle"
+        @pointerdown.stop.prevent="onPointerDown"
+      />
+    </div>
+  </Teleport>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, onMounted, onBeforeUnmount, watch } from 'vue'
+
+/* ------------------------------------------------------------------ */
+/*  Props                                                              */
+/* ------------------------------------------------------------------ */
+const props = withDefaults(
+  defineProps<{
+    /** Override the auto-detected version string (e.g. "1.2.3"). */
+    version?: string | null
+  }>(),
+  {
+    version: null,
+  },
+)
+
+/* ------------------------------------------------------------------ */
+/*  Geometry constants                                                 */
+/* ------------------------------------------------------------------ */
+
+/** SVG viewBox size (square, covers the ribbon corner area) */
+const SVG_SIZE = 260
+
+/** Where the ribbon center-line meets each viewport edge */
+const EP = 220
+
+/** Half the ribbon band width (perpendicular to curve) */
+const HW = 20
+
+/** Default bezier control-point position (x = y → symmetric 45° curve) */
+const CP0 = 90
+
+/**
+ * Perpendicular offset for band edges relative to center control point.
+ * HW / √2 because the perpendicular to a 45° diagonal has (1/√2, 1/√2)
+ * components.
+ */
+const CPO = Math.round(HW / Math.SQRT2) // ≈ 14
+
+/** Stitch-line inset from band edges (px in SVG space) */
+const STI = 4
+
+/* ------------------------------------------------------------------ */
+/*  Constants                                                          */
+/* ------------------------------------------------------------------ */
+
+/** The preview domain where the ribbon should be displayed */
+const PREVIEW_DOMAIN = 'preview.duffcloudservices.com'
+
+/**
+ * Query string parameter that suppresses the preview ribbon.
+ * Used by GitHub Actions snapshot capture so screenshots don't include the ribbon overlay.
+ * Example: https://preview.duffcloudservices.com/kept/?dcs-hide-ribbon
+ */
+const HIDE_RIBBON_PARAM = 'dcs-hide-ribbon'
+
+/** localStorage key for persisting which corner the ribbon is docked to */
+const STORAGE_KEY = 'dcs-preview-ribbon-side'
+
+/* ------------------------------------------------------------------ */
+/*  Visibility gate                                                    */
+/* ------------------------------------------------------------------ */
+const isVisible = ref(false)
+
+function shouldShow(): boolean {
+  if (globalThis.window === undefined) return false
+
+  const host = globalThis.location.hostname
+
+  // Only show on the preview domain
+  if (host !== PREVIEW_DOMAIN) return false
+
+  // Never show in the visual page editor (iframe inside portal)
+  try {
+    if (globalThis.self !== globalThis.top) return false
+  } catch {
+    // cross-origin – inside an iframe → editor context
+    return false
+  }
+
+  // Allow suppression via query parameter (for automated screenshot capture)
+  const params = new URLSearchParams(globalThis.location.search)
+  if (params.has(HIDE_RIBBON_PARAM)) return false
+
+  return true
+}
+
+/* ------------------------------------------------------------------ */
+/*  Side state (which corner the ribbon is docked to, persisted)       */
+/* ------------------------------------------------------------------ */
+const side = ref<'left' | 'right'>('left')
+
+function loadSide(): 'left' | 'right' {
+  try {
+    const s = localStorage.getItem(STORAGE_KEY)
+    if (s === 'left' || s === 'right') return s
+  } catch { /* noop */ }
+  return 'left'
+}
+
+function saveSide(s: 'left' | 'right') {
+  try { localStorage.setItem(STORAGE_KEY, s) } catch { /* noop */ }
+}
+
+/* ------------------------------------------------------------------ */
+/*  Version display                                                    */
+/* ------------------------------------------------------------------ */
+const resolvedVersion = ref<string | null>(props.version ?? null)
+
+const displayVersion = computed(() =>
+  resolvedVersion.value ? ` v${resolvedVersion.value}` : '',
+)
+
+// Sync prop changes
+watch(
+  () => props.version,
+  (v) => {
+    if (v !== null && v !== undefined) resolvedVersion.value = v
+  },
+)
+
+/* ------------------------------------------------------------------ */
+/*  Lifecycle                                                          */
+/* ------------------------------------------------------------------ */
+onMounted(async () => {
+  isVisible.value = shouldShow()
+  if (!isVisible.value) return
+
+  side.value = loadSide()
+
+  // Resolve version
+  if (resolvedVersion.value) return
+
+  try {
+    const envVersion = (import.meta.env as Record<string, string | undefined>)
+      .VITE_SITE_VERSION
+    if (envVersion) {
+      resolvedVersion.value = envVersion
+      return
+    }
+  } catch {
+    /* noop */
+  }
+
+  try {
+    const slug =
+      (import.meta.env as Record<string, string | undefined>).VITE_SITE_SLUG ??
+      ''
+    if (!slug) return
+    const base =
+      (import.meta.env as Record<string, string | undefined>)
+        .VITE_API_BASE_URL ?? 'https://portal.duffcloudservices.com'
+    const res = await fetch(
+      `${base}/api/v1/sites/${slug}/release-notes/latest`,
+      { headers: { Accept: 'application/json' } },
+    )
+    if (res.ok) {
+      const data = await res.json()
+      if (data.version) resolvedVersion.value = data.version
+    }
+  } catch {
+    /* non-critical */
+  }
+})
+
+/* ------------------------------------------------------------------ */
+/*  Elastic stretch state (control-point displacement)                 */
+/* ------------------------------------------------------------------ */
+const stretchX = ref(0)
+const stretchY = ref(0)
+const isDragging = ref(false)
+
+/**
+ * Absolute SVG-space control point for the band center-line.
+ * Left side default: (CP0, CP0) = (90, 90)
+ * Right side default: (SVG_SIZE - CP0, CP0) = (170, 90)
+ * stretchX/Y displace the control point in screen-mapped SVG units.
+ */
+const cx = computed(() =>
+  side.value === 'left'
+    ? CP0 + stretchX.value
+    : SVG_SIZE - CP0 + stretchX.value,
+)
+const cy = computed(() => CP0 + stretchY.value)
+
+/**
+ * Perpendicular sign: for left-side ribbon the outward perpendicular
+ * direction is (+1, +1); for right-side it is (-1, +1).
+ * This determines how CPO is applied to get outer/inner band edges.
+ */
+const ps = computed(() => (side.value === 'left' ? 1 : -1))
+
+/* ------------------------------------------------------------------ */
+/*  SVG path computation (side-aware, with elastic control-point)      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Text center-line. On the right side the path direction is reversed
+ * so that textPath renders left-to-right (readable).
+ */
+const textPath = computed(() => {
+  if (side.value === 'left') {
+    return `M 0,${EP} Q ${cx.value},${cy.value} ${EP},0`
+  }
+  return `M ${SVG_SIZE - EP},0 Q ${cx.value},${cy.value} ${SVG_SIZE},${EP}`
+})
+
+const bandPath = computed(() => {
+  const p = ps.value
+  // Outer edge control point (further from corner)
+  const ocx = cx.value + p * CPO
+  const ocy = cy.value + CPO
+  // Inner edge control point (closer to corner)
+  const icx = cx.value - p * CPO
+  const icy = cy.value - CPO
+
+  if (side.value === 'left') {
+    return [
+      `M 0,${EP + HW} Q ${ocx},${ocy} ${EP + HW},0`,
+      `L ${EP - HW},0`,
+      `Q ${icx},${icy} 0,${EP - HW}`,
+      `Z`,
+    ].join(' ')
+  }
+
+  return [
+    `M ${SVG_SIZE},${EP + HW} Q ${ocx},${ocy} ${SVG_SIZE - EP - HW},0`,
+    `L ${SVG_SIZE - EP + HW},0`,
+    `Q ${icx},${icy} ${SVG_SIZE},${EP - HW}`,
+    `Z`,
+  ].join(' ')
+})
+
+const outerStitchPath = computed(() => {
+  const p = ps.value
+  const scx = cx.value + p * (CPO - 3)
+  const scy = cy.value + (CPO - 3)
+  const d = EP + HW - STI
+
+  if (side.value === 'left') {
+    return `M 0,${d} Q ${scx},${scy} ${d},0`
+  }
+  return `M ${SVG_SIZE},${d} Q ${scx},${scy} ${SVG_SIZE - d},0`
+})
+
+const innerStitchPath = computed(() => {
+  const p = ps.value
+  const scx = cx.value - p * (CPO - 3)
+  const scy = cy.value - (CPO - 3)
+  const d = EP - HW + STI
+
+  if (side.value === 'left') {
+    return `M 0,${d} Q ${scx},${scy} ${d},0`
+  }
+  return `M ${SVG_SIZE},${d} Q ${scx},${scy} ${SVG_SIZE - d},0`
+})
+
+/* ------------------------------------------------------------------ */
+/*  Touch overlay clip-path                                            */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Clip-path polygon that creates an invisible hit area over the ribbon
+ * band, wider than the visible band for comfortable touch targeting.
+ * This is on an HTML <div>, so touch-action: none is guaranteed to work
+ * on Android Chrome (unlike SVG <path> elements).
+ */
+const touchClipStyle = computed(() => {
+  if (side.value === 'left') {
+    // Quadrilateral covering the band diagonal: bottom-left → top-right
+    return { clipPath: 'polygon(0% 100%, 100% 0%, 65% 0%, 0% 65%)' }
+  }
+  // Right side: mirrored
+  return { clipPath: 'polygon(100% 100%, 0% 0%, 35% 0%, 100% 65%)' }
+})
+
+/* ------------------------------------------------------------------ */
+/*  Drag: elastic control-point stretch + flip on midpoint crossing    */
+/* ------------------------------------------------------------------ */
+const touchOverlayRef = ref<HTMLDivElement | null>(null)
+let dragStart: { x: number; y: number } | null = null
+let springRaf = 0
+
+/**
+ * Get the rendered pixel size of the SVG element.
+ * Used to convert screen-space drag deltas to SVG-space units.
+ */
+function getSvgPixelSize(): number {
+  return window.innerWidth <= 640 ? 200 : 260
+}
+
+function onPointerDown(e: PointerEvent) {
+  // Cancel any in-progress spring animation
+  if (springRaf) {
+    cancelAnimationFrame(springRaf)
+    springRaf = 0
+  }
+
+  // Capture the pointer on the HTML overlay div.
+  // Unlike SVG <path> elements, HTML elements reliably support
+  // setPointerCapture on Android Chrome, ensuring all subsequent
+  // pointer events are delivered even when the finger moves outside.
+  const target = e.currentTarget as HTMLElement
+  target.setPointerCapture(e.pointerId)
+
+  isDragging.value = true
+  dragStart = { x: e.clientX, y: e.clientY }
+
+  globalThis.addEventListener('pointermove', onPointerMove)
+  globalThis.addEventListener('pointerup', onPointerUp)
+  globalThis.addEventListener('pointercancel', onPointerUp)
+}
+
+function onPointerMove(e: PointerEvent) {
+  if (!dragStart) return
+
+  // Convert screen-space drag delta to SVG-space units
+  const scale = SVG_SIZE / getSvgPixelSize()
+  stretchX.value = (e.clientX - dragStart.x) * scale
+  stretchY.value = (e.clientY - dragStart.y) * scale
+
+  // Flip when the pointer crosses the viewport midpoint
+  const mid = window.innerWidth / 2
+  if (side.value === 'left' && e.clientX > mid) {
+    triggerFlip('right', e)
+  } else if (side.value === 'right' && e.clientX < mid) {
+    triggerFlip('left', e)
+  }
+}
+
+function onPointerUp(e: PointerEvent) {
+  if (touchOverlayRef.value) {
+    try { touchOverlayRef.value.releasePointerCapture(e.pointerId) } catch { /* already released */ }
+  }
+  isDragging.value = false
+  dragStart = null
+  removeListeners()
+  animateSnapBack()
+}
+
+function removeListeners() {
+  globalThis.removeEventListener('pointermove', onPointerMove)
+  globalThis.removeEventListener('pointerup', onPointerUp)
+  globalThis.removeEventListener('pointercancel', onPointerUp)
+}
+
+/**
+ * Snap the ribbon to the opposite corner when the pointer crosses
+ * the viewport midpoint. Resets the elastic stretch, switches side,
+ * and persists the user's preference.
+ */
+function triggerFlip(newSide: 'left' | 'right', e: PointerEvent) {
+  // Reset stretch to default shape
+  stretchX.value = 0
+  stretchY.value = 0
+
+  // End drag
+  isDragging.value = false
+  dragStart = null
+  removeListeners()
+
+  // Release pointer capture
+  if (touchOverlayRef.value) {
+    try { touchOverlayRef.value.releasePointerCapture(e.pointerId) } catch { /* noop */ }
+  }
+
+  // Switch to the new side
+  side.value = newSide
+  saveSide(newSide)
+}
+
+/** Spring-physics animation to snap the control point back to default */
+function animateSnapBack() {
+  const stiffness = 0.12
+  const damping = 0.72
+  let vx = 0
+  let vy = 0
+
+  function step() {
+    vx = (vx - stiffness * stretchX.value) * damping
+    vy = (vy - stiffness * stretchY.value) * damping
+    stretchX.value += vx
+    stretchY.value += vy
+
+    if (
+      Math.abs(stretchX.value) < 0.3 &&
+      Math.abs(stretchY.value) < 0.3 &&
+      Math.abs(vx) < 0.3 &&
+      Math.abs(vy) < 0.3
+    ) {
+      stretchX.value = 0
+      stretchY.value = 0
+      springRaf = 0
+      return
+    }
+
+    springRaf = requestAnimationFrame(step)
+  }
+
+  springRaf = requestAnimationFrame(step)
+}
+
+/* ------------------------------------------------------------------ */
+/*  Cleanup                                                            */
+/* ------------------------------------------------------------------ */
+onBeforeUnmount(() => {
+  if (springRaf) cancelAnimationFrame(springRaf)
+  removeListeners()
+})
+</script>
+
+<style scoped>
+/* ------------------------------------------------------------------ */
+/*  Container — fixed in corner, non-blocking                          */
+/* ------------------------------------------------------------------ */
+.dcs-ribbon-container {
+  position: fixed;
+  top: 0;
+  z-index: 2147483647;
+  pointer-events: none;
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+.dcs-ribbon-container--left {
+  left: 0;
+  right: auto;
+}
+
+.dcs-ribbon-container--right {
+  right: 0;
+  left: auto;
+}
+
+/* ------------------------------------------------------------------ */
+/*  SVG canvas                                                         */
+/* ------------------------------------------------------------------ */
+.dcs-ribbon-svg {
+  display: block;
+  width: 260px;
+  height: 260px;
+  overflow: visible;
+  pointer-events: none;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Band (visual only — touch handled by overlay div)                  */
+/* ------------------------------------------------------------------ */
+.dcs-ribbon-band {
+  pointer-events: none;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Stitched borders                                                   */
+/* ------------------------------------------------------------------ */
+.dcs-ribbon-stitch {
+  fill: none;
+  stroke: rgba(255, 255, 255, 0.15);
+  stroke-width: 1;
+  stroke-dasharray: 4 3;
+  pointer-events: none;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Text                                                               */
+/* ------------------------------------------------------------------ */
+.dcs-ribbon-text {
+  fill: #e0e7ff;
+  font-family: 'Inter', 'Segoe UI', system-ui, -apple-system, sans-serif;
+  font-weight: 600;
+  font-size: 12px;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  pointer-events: none;
+}
+
+/* Full label for wide screens */
+.dcs-ribbon-text--full {
+  display: block;
+}
+.dcs-ribbon-text--compact {
+  display: none;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Touch overlay — transparent HTML div for reliable mobile touch     */
+/*                                                                     */
+/*  Android Chrome ignores touch-action on SVG <path> elements because */
+/*  the compositor only walks HTML elements. This HTML <div> with      */
+/*  clip-path creates a shaped, invisible hit area where touch-action  */
+/*  is guaranteed to work.                                             */
+/* ------------------------------------------------------------------ */
+.dcs-ribbon-touch {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 260px;
+  height: 260px;
+  touch-action: none;
+  pointer-events: auto;
+  cursor: grab;
+  -webkit-tap-highlight-color: transparent;
+  /* clip-path set via :style binding for left/right side */
+}
+
+.dcs-ribbon-touch--dragging {
+  cursor: grabbing;
+}
+
+/* Compact label for narrow screens */
+@media (max-width: 640px) {
+  .dcs-ribbon-svg {
+    width: 200px;
+    height: 200px;
+  }
+  .dcs-ribbon-touch {
+    width: 200px;
+    height: 200px;
+  }
+  .dcs-ribbon-text--full {
+    display: none;
+  }
+  .dcs-ribbon-text--compact {
+    display: block;
+    font-size: 11px;
+  }
+}
 </style>