From 8f80cbd39b69645fe9c173d9d14472ddf3322e58 Mon Sep 17 00:00:00 2001
From: Towsty <ianjmcarr@gmail.com>
Date: Thu, 3 Sep 2026 20:11:28 -0500
Subject: [PATCH] Show family branches in plain English with Start as the card
 head.

Collapsed cards use parts/forks/longest instead of pN codes; expanded Studio and Library trees get fork headers and from/branch labels.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 pages/index.vue        |  67 +++++++++++++-------------
 pages/library.vue      |  46 ++++++++++++++++--
 utils/libraryBrowse.ts | 104 +++++++++++++++++++++++++++++++++--------
 3 files changed, 158 insertions(+), 59 deletions(-)

diff --git a/pages/index.vue b/pages/index.vue
index 1f97ad6..2f754c7 100644
--- a/pages/index.vue
+++ b/pages/index.vue
@@ -1725,7 +1725,7 @@
                       />
                     </div>
                     <p class="truncate text-xs text-zinc-500">{{ clipMetaLine(entry.group.head) }}</p>
-                    <p v-if="familyBranchHint(entry.group.parts)" class="mt-1 truncate text-[11px] text-amber-200/80">{{ familyBranchHint(entry.group.parts) }}</p>
+                    <p v-if="familyBranchSummary(entry.group.parts)" class="mt-1 truncate text-[11px] text-amber-200/80">{{ familyBranchSummary(entry.group.parts) }}</p>
                     <p v-if="entry.group.head.globalLocks" class="mt-1 text-[11px] text-zinc-600">Global locks saved with this collection.</p>
                     <PermanenceRefStrip
                       v-if="entry.group.parts.length === 1 && !entry.group.head.hideThumbnail"
@@ -1782,19 +1782,26 @@
                   </div>
                 </div>
                 <ul v-if="expandedFamilies[entry.group.key] && entry.group.parts.length > 1" class="mt-3 space-y-2 border-t border-white/5 pt-3">
-                  <li
-                    v-for="node in treeOrderedParts(entry.group.parts)"
-                    :key="node.clip.id"
-                    class="flex cursor-pointer flex-wrap items-start gap-3 rounded-xl border p-2"
-                    :class="node.clip.id === reviewingClipId
-                      ? 'border-amber-300/80 bg-amber-400/15 ring-1 ring-amber-300/60'
-                      : extendOpen && node.clip.id === extendClipId
-                        ? 'border-amber-300/40 bg-amber-400/5'
-                        : 'border-white/5 bg-black/20'"
-                    :style="node.depth ? { marginLeft: `${Math.min(node.depth, 6) * 0.85}rem` } : undefined"
-                    :aria-current="node.clip.id === reviewingClipId ? 'true' : undefined"
-                    @click="onLibraryClipPartClick(node.clip, $event)"
-                  >
+                  <template v-for="node in familyDisplayNodes(entry.group.parts)" :key="node.key">
+                    <li
+                      v-if="node.type === 'fork'"
+                      class="rounded-lg px-2 py-1 text-[11px] font-medium uppercase tracking-wide text-amber-200/70"
+                      :style="node.depth ? { marginLeft: `${Math.min(node.depth, 6) * 0.85}rem` } : undefined"
+                    >
+                      {{ node.label }}
+                    </li>
+                    <li
+                      v-else
+                      class="flex cursor-pointer flex-wrap items-start gap-3 rounded-xl border p-2"
+                      :class="node.clip.id === reviewingClipId
+                        ? 'border-amber-300/80 bg-amber-400/15 ring-1 ring-amber-300/60'
+                        : extendOpen && node.clip.id === extendClipId
+                          ? 'border-amber-300/40 bg-amber-400/5'
+                          : 'border-white/5 bg-black/20'"
+                      :style="node.depth ? { marginLeft: `${Math.min(node.depth, 6) * 0.85}rem` } : undefined"
+                      :aria-current="node.clip.id === reviewingClipId ? 'true' : undefined"
+                      @click="onLibraryClipPartClick(node.clip, $event)"
+                    >
                     <ClipFrameThumbs
                       :hidden="node.clip.hideThumbnail"
                       :revealed="!!stitchReveal[node.clip.id]"
@@ -1817,7 +1824,8 @@
                         >
                         <p v-else class="min-w-0 flex-1 truncate text-sm font-medium">
                           {{ node.clip.name || node.clip.prompt }}
-                          <span v-if="clipBranchFromLabel(node.clip, entry.group.parts)" class="ml-1.5 text-[11px] font-normal text-amber-200/80">{{ clipBranchFromLabel(node.clip, entry.group.parts) }}</span>
+                          <span v-if="node.fromLabel" class="ml-1.5 text-[11px] font-normal text-amber-200/80">{{ node.fromLabel }}</span>
+                          <span v-if="node.branchLabel" class="ml-1.5 text-[11px] font-normal text-zinc-400">{{ node.branchLabel }}</span>
                           <span v-if="extendOpen && node.clip.id === extendClipId" class="ml-1.5 text-[10px] font-semibold uppercase tracking-wide text-amber-200">extending</span>
                         </p>
                         <PromptPreviewTip
@@ -1878,7 +1886,8 @@
                         empty="No generator settings were saved with this clip."
                       />
                     </div>
-                  </li>
+                    </li>
+                  </template>
                 </ul>
                 </template>
                 <template v-else-if="entry.kind === 'still' && entry.stillGroup">
@@ -2249,13 +2258,12 @@ import { parseImageAspect, generateSizeForAspect } from '~/utils/imageAspect'
 import { buildOutputBaseName, nextUniqueName } from '~/utils/outputNames'
 import { emptyKeepPrompts, insertKeepSnippet, normalizeKeepPrompts, type KeepPrompt, type KeepPromptLists } from '~/utils/keepPrompts'
 import {
-  clipBranchFromLabel,
   clipPartLabel,
   familyBaseName,
-  familyBranchCount,
-  familyBranchHint,
-  nextClipPartName,
-  treeOrderedParts
+  familyBranchSummary,
+  familyDisplayNodes,
+  familyRootClip,
+  nextClipPartName
 } from '~/utils/libraryBrowse'
 import {
   IMAGE_V2_CFG_DEFAULT,
@@ -3355,8 +3363,8 @@ const libraryGroups = computed(() => {
   }
   return [...groups.entries()]
     .map(([key, parts]) => {
-      const sorted = [...parts].sort(sortClipParts)
-      return { key, head: sorted[0], parts: sorted }
+      const head = familyRootClip(parts)
+      return { key, head, parts: [...parts] }
     })
     .sort((a, b) => b.head.createdAt - a.head.createdAt)
 })
@@ -3501,14 +3509,6 @@ function chronologicalStills(parts: LibraryStill[]) {
   })
 }
 
-function sortClipParts(a: LibraryClip, b: LibraryClip) {
-  const durationDelta = (Number(b.duration) || 0) - (Number(a.duration) || 0)
-  if (durationDelta) return durationDelta
-  const chainDelta = (b.chainIndex || 0) - (a.chainIndex || 0)
-  if (chainDelta) return chainDelta
-  return a.createdAt - b.createdAt
-}
-
 function chronologicalParts(parts: LibraryClip[]) {
   return [...parts].sort((a, b) => {
     const chain = (a.chainIndex || 0) - (b.chainIndex || 0)
@@ -3531,9 +3531,8 @@ function previousClipIdFor(item: LibraryClip, parts: LibraryClip[]) {
 
 function familyExpandLabel(parts: LibraryClip[], expanded?: boolean) {
   if (expanded) return 'Collapse'
-  const branches = familyBranchCount(parts)
-  if (branches) return `Expand ${parts.length} parts · ${branches} branch${branches === 1 ? '' : 'es'}`
-  return `Expand ${parts.length} parts`
+  const summary = familyBranchSummary(parts)
+  return summary ? `Expand · ${summary}` : `Expand ${parts.length} parts`
 }
 
 function ensureFamilyExpanded(item: LibraryClip) {
diff --git a/pages/library.vue b/pages/library.vue
index 8c8cc27..c86aa21 100644
--- a/pages/library.vue
+++ b/pages/library.vue
@@ -303,7 +303,34 @@
               </svg>
             </button>
           </div>
-          <div v-if="focusedParts.length > 1" class="mt-3 grid grid-cols-5 gap-1.5">
+          <div v-if="focused.kind === 'clip' && focusedDisplayNodes.length > 1" class="mt-3 space-y-1.5">
+            <template v-for="node in focusedDisplayNodes" :key="node.key">
+              <p
+                v-if="node.type === 'fork'"
+                class="px-1 text-[11px] font-medium uppercase tracking-wide text-amber-200/70"
+                :style="node.depth ? { marginLeft: `${Math.min(node.depth, 6) * 0.65}rem` } : undefined"
+              >
+                {{ node.label }}
+              </p>
+              <button
+                v-else
+                type="button"
+                class="flex w-full items-center gap-2 overflow-hidden rounded-lg border border-white/10 p-1 text-left"
+                :class="node.clip.id === focusedPartId ? 'ring-2 ring-amber-300' : ''"
+                :style="node.depth ? { marginLeft: `${Math.min(node.depth, 6) * 0.65}rem` } : undefined"
+                @click="focusPart(node.clip.id)"
+              >
+                <img :src="partThumb(node.clip)" alt="" class="h-12 w-12 shrink-0 rounded object-cover" loading="lazy">
+                <span class="min-w-0 flex-1">
+                  <span class="block truncate text-xs font-medium text-zinc-100">{{ node.clip.name }}</span>
+                  <span v-if="node.fromLabel || node.branchLabel" class="block truncate text-[11px] text-amber-200/80">
+                    {{ [node.fromLabel, node.branchLabel].filter(Boolean).join(' · ') }}
+                  </span>
+                </span>
+              </button>
+            </template>
+          </div>
+          <div v-else-if="focusedParts.length > 1" class="mt-3 grid grid-cols-5 gap-1.5">
             <button
               v-for="part in focusedParts"
               :key="part.id"
@@ -453,10 +480,13 @@ import {
   buildLibraryEntries,
   chronologicalStills,
   clipBranchFromLabel,
-  familyBranchHint,
+  clipBranchLetterLabel,
+  familyBranchSummary,
+  familyDisplayNodes,
   formatClipDuration,
   formatWhen,
   treeOrderedParts,
+  type FamilyDisplayNode,
   type LibraryClip,
   type LibraryEntry,
   type LibraryFilter,
@@ -614,6 +644,10 @@ const focusedParts = computed(() => {
   if (focused.value?.kind === 'clip') return focused.value.group?.parts || []
   return focused.value?.stillGroup?.parts || []
 })
+const focusedDisplayNodes = computed((): FamilyDisplayNode[] => {
+  if (focused.value?.kind !== 'clip' || !focused.value.group) return []
+  return familyDisplayNodes(focused.value.group.parts)
+})
 const focusedNavParts = computed(() => {
   const parts = focusedParts.value
   if (parts.length < 2) return []
@@ -624,7 +658,9 @@ const focusedBranchHint = computed(() => {
   if (focused.value?.kind !== 'clip' || !focused.value.group) return ''
   const parts = focused.value.group.parts
   const current = parts.find(part => part.id === focusedPartId.value)
-  return (current && clipBranchFromLabel(current, parts)) || familyBranchHint(parts)
+  if (!current) return familyBranchSummary(parts)
+  const bits = [clipBranchFromLabel(current, parts), clipBranchLetterLabel(current)].filter(Boolean)
+  return bits.join(' · ') || familyBranchSummary(parts)
 })
 const focusedNavIndex = computed(() => {
   const id = focusedPartId.value
@@ -806,8 +842,8 @@ function partCount(entry: LibraryEntry) {
 
 function cardMeta(entry: LibraryEntry) {
   if (entry.kind === 'clip' && entry.group) {
-    const branches = familyBranchHint(entry.group.parts)
-    return [formatClipDuration(entry.group.head.duration), formatWhen(entry.createdAt), branches].filter(Boolean).join(' · ')
+    const summary = familyBranchSummary(entry.group.parts)
+    return [formatClipDuration(entry.group.head.duration), formatWhen(entry.createdAt), summary].filter(Boolean).join(' · ')
   }
   if (entry.kind === 'track' && entry.track) {
     return [formatClipDuration(entry.track.duration), formatWhen(entry.createdAt)].filter(Boolean).join(' · ')
diff --git a/utils/libraryBrowse.ts b/utils/libraryBrowse.ts
index 515495f..c58c2e4 100644
--- a/utils/libraryBrowse.ts
+++ b/utils/libraryBrowse.ts
@@ -136,14 +136,17 @@ export function nextClipPartName(name: string, existingNames: string[] = []) {
 
 export type ClipTreeNode = { clip: LibraryClip; depth: number }
 
+export type FamilyDisplayNode =
+  | { type: 'fork'; key: string; depth: number; label: string; parentId: string }
+  | { type: 'clip'; key: string; depth: number; clip: LibraryClip; fromLabel: string; branchLabel: string }
+
 function sortTreeSiblings(a: LibraryClip, b: LibraryClip) {
   const chain = (a.chainIndex || 0) - (b.chainIndex || 0)
   if (chain) return chain
   return a.createdAt - b.createdAt
 }
 
-export function treeOrderedParts(parts: LibraryClip[]): ClipTreeNode[] {
-  if (!parts.length) return []
+function buildClipChildren(parts: LibraryClip[]) {
   const byId = new Map(parts.map(part => [part.id, part]))
   const children = new Map<string, LibraryClip[]>()
   const roots: LibraryClip[] = []
@@ -159,6 +162,12 @@ export function treeOrderedParts(parts: LibraryClip[]): ClipTreeNode[] {
   }
   roots.sort(sortTreeSiblings)
   for (const list of children.values()) list.sort(sortTreeSiblings)
+  return { byId, children, roots }
+}
+
+export function treeOrderedParts(parts: LibraryClip[]): ClipTreeNode[] {
+  if (!parts.length) return []
+  const { children, roots } = buildClipChildren(parts)
   const out: ClipTreeNode[] = []
   const walk = (clip: LibraryClip, depth: number) => {
     out.push({ clip, depth })
@@ -168,6 +177,17 @@ export function treeOrderedParts(parts: LibraryClip[]): ClipTreeNode[] {
   return out
 }
 
+export function familyRootClip(parts: LibraryClip[]): LibraryClip {
+  if (!parts.length) throw new Error('familyRootClip requires at least one clip')
+  const { roots } = buildClipChildren(parts)
+  if (roots.length) return roots[0]
+  return chronologicalParts(parts)[0] || parts[0]
+}
+
+export function familyLongestDuration(parts: LibraryClip[]) {
+  return parts.reduce((max, part) => Math.max(max, Number(part.duration) || 0), 0)
+}
+
 export function familyBranchCount(parts: LibraryClip[]) {
   const counts = new Map<string, number>()
   for (const part of parts) {
@@ -177,31 +197,75 @@ export function familyBranchCount(parts: LibraryClip[]) {
   return [...counts.values()].filter(count => count > 1).length
 }
 
+/** Plain English family line for collapsed cards. No p2→p3 codes. */
+export function familyBranchSummary(parts: LibraryClip[]) {
+  if (parts.length <= 1) return ''
+  const forks = familyBranchCount(parts)
+  const longest = familyLongestDuration(parts)
+  const bits = [`${parts.length} parts`]
+  if (forks) bits.push(`${forks} fork${forks === 1 ? '' : 's'}`)
+  if (longest > 0) bits.push(`longest ${formatClipDuration(longest)}`)
+  return bits.join(' · ')
+}
+
+/** @deprecated Use familyBranchSummary — kept so old imports do not break. */
 export function familyBranchHint(parts: LibraryClip[]) {
-  const groups = new Map<string, LibraryClip[]>()
-  for (const part of parts) {
-    if (!part.parentClipId) continue
-    const list = groups.get(part.parentClipId) || []
-    list.push(part)
-    groups.set(part.parentClipId, list)
-  }
-  const branched = [...groups.entries()].filter(([, kids]) => kids.length > 1)
-  if (!branched.length) return ''
-  return branched.map(([parentId, kids]) => {
-    const parent = parts.find(part => part.id === parentId)
-    const from = clipPartLabel(parent?.name) || 'a part'
-    const names = kids.map(kid => clipPartLabel(kid.name) || kid.name || 'part').join(', ')
-    return `${from} → ${names}`
-  }).join(' · ')
+  return familyBranchSummary(parts)
+}
+
+export function clipParentDisplayLabel(parent: LibraryClip | undefined, parts: LibraryClip[]) {
+  if (!parent) return ''
+  const byId = new Map(parts.map(part => [part.id, part]))
+  const isRoot = !parent.parentClipId || !byId.has(parent.parentClipId)
+  if (isRoot) return 'Start'
+  return clipPartLabel(parent.name) || parent.name || 'previous'
+}
+
+export function clipBranchLetterLabel(item: LibraryClip) {
+  const match = String(item.name || '').trim().match(/\s+p\d+([a-z])$/i)
+  if (!match?.[1]) return ''
+  return `branch ${match[1].toUpperCase()}`
 }
 
 export function clipBranchFromLabel(item: LibraryClip, parts: LibraryClip[]) {
   if (!item.parentClipId) return ''
   const parent = parts.find(part => part.id === item.parentClipId)
-  const from = clipPartLabel(parent?.name) || parent?.name
+  const from = clipParentDisplayLabel(parent, parts)
   return from ? `from ${from}` : ''
 }
 
+export function familyDisplayNodes(parts: LibraryClip[]): FamilyDisplayNode[] {
+  if (!parts.length) return []
+  const { byId, children, roots } = buildClipChildren(parts)
+  const out: FamilyDisplayNode[] = []
+  const walk = (clip: LibraryClip, depth: number) => {
+    const parent = clip.parentClipId ? byId.get(clip.parentClipId) : undefined
+    const from = clip.parentClipId ? clipParentDisplayLabel(parent, parts) : ''
+    out.push({
+      type: 'clip',
+      key: `clip:${clip.id}`,
+      depth,
+      clip,
+      fromLabel: from ? `from ${from}` : '',
+      branchLabel: clipBranchLetterLabel(clip)
+    })
+    const kids = children.get(clip.id) || []
+    if (kids.length > 1) {
+      const parentLabel = clipParentDisplayLabel(clip, parts) || clipPartLabel(clip.name) || 'Start'
+      out.push({
+        type: 'fork',
+        key: `fork:${clip.id}`,
+        depth: depth + 1,
+        label: `Forks from ${parentLabel} (${kids.length})`,
+        parentId: clip.id
+      })
+    }
+    for (const child of kids) walk(child, depth + 1)
+  }
+  for (const root of roots) walk(root, 0)
+  return out
+}
+
 export function clipFamilyKey(clip: LibraryClip) {
   if (clip.familyId) return `family:${clip.folderId}:${clip.familyId}`
   const base = familyBaseName(clip.name || '').toLowerCase()
@@ -298,8 +362,8 @@ function groupClips(clips: LibraryClip[]): ClipGroup[] {
     groups.set(key, list)
   }
   return [...groups.entries()].map(([key, parts]) => {
-    const sorted = [...parts].sort(sortClipParts)
-    return { key, head: sorted[0], parts: sorted }
+    const head = familyRootClip(parts)
+    return { key, head, parts: [...parts] }
   })
 }