From 55586cf01d7fb414940b38368c04c487a61e3301 Mon Sep 17 00:00:00 2001
From: JayceeB1 <45721154+JayceeB1@users.noreply.github.com>
Date: Fri, 9 Oct 2026 23:26:53 +0200
Subject: [PATCH 01/11] integrate(#242): play GLB animation clips in viewer

Adapted from OmarB97/modly (upstream PR #242).
---
 src/areas/generate/components/Viewer3D.tsx | 46 ++++++++++++++++++++--
 1 file changed, 43 insertions(+), 3 deletions(-)

diff --git a/src/areas/generate/components/Viewer3D.tsx b/src/areas/generate/components/Viewer3D.tsx
index a1edc2d4..0d43d5c2 100644
--- a/src/areas/generate/components/Viewer3D.tsx
+++ b/src/areas/generate/components/Viewer3D.tsx
@@ -2,7 +2,7 @@ import { Component, Suspense, useCallback, useEffect, useMemo, useRef, useState
 import type { ReactNode, ErrorInfo, MutableRefObject } from 'react'
 import { Canvas, useFrame, useLoader, useThree } from '@react-three/fiber'
 import type { ThreeEvent } from '@react-three/fiber'
-import { Environment, GizmoHelper, Lightformer, OrbitControls, useGizmoContext, useGLTF } from '@react-three/drei'
+import { Environment, GizmoHelper, Html, Lightformer, OrbitControls, useGizmoContext, useGLTF } from '@react-three/drei'
 import { EffectComposer, Outline, Select, Selection } from '@react-three/postprocessing'
 import * as THREE from 'three'
 import { OBJLoader } from 'three/examples/jsm/loaders/OBJLoader.js'
@@ -281,8 +281,48 @@ function MeshModel({ url, jobId, viewMode, selected, onStats, onSelect, onObject
 }
 
 function GltfMeshModel(props: MeshModelProps): JSX.Element {
-  const { scene } = useGLTF(props.url)
-  return <SceneMeshModel {...props} scene={scene} loaderType="gltf" />
+  const gltf = useGLTF(props.url)
+  const { scene, animations } = gltf
+  const mixerRef = useRef<THREE.AnimationMixer | null>(null)
+  const [clipIndex, setClipIndex] = useState(0)
+
+  // Rigged models arrive with one or more clips; without a mixer they render
+  // frozen in bind pose, which reads as "the rig failed".
+  useEffect(() => {
+    if (!animations?.length) {
+      mixerRef.current = null
+      return
+    }
+    const mixer = new THREE.AnimationMixer(scene)
+    mixer.clipAction(animations[Math.min(clipIndex, animations.length - 1)]).play()
+    mixerRef.current = mixer
+    return () => {
+      mixer.stopAllAction()
+      mixer.uncacheRoot(scene)
+      mixerRef.current = null
+    }
+  }, [scene, animations, clipIndex])
+
+  useFrame((_state, delta) => mixerRef.current?.update(delta))
+
+  return (
+    <>
+      <SceneMeshModel {...props} scene={scene} loaderType="gltf" />
+      {animations && animations.length > 1 && (
+        <Html position={[0, 0, 0]} wrapperClass="clip-picker">
+          <select
+            value={clipIndex}
+            onChange={(e) => setClipIndex(Number(e.target.value))}
+            className="bg-zinc-800 text-zinc-200 border border-zinc-700 rounded px-2 py-1 text-xs"
+          >
+            {animations.map((clip, i) => (
+              <option key={clip.name || i} value={i}>{clip.name || }</option>
+            ))}
+          </select>
+        </Html>
+      )}
+    </>
+  )
 }
 
 function ObjMeshModel(props: MeshModelProps): JSX.Element {

From dcfaec81df2b9e4b8577905afe2923100193a2b5 Mon Sep 17 00:00:00 2001
From: JayceeB1 <45721154+JayceeB1@users.noreply.github.com>
Date: Fri, 9 Oct 2026 23:27:22 +0200
Subject: [PATCH 02/11] integrate(#244): normalize manifest input slots before
 preflight

Adapted from OmarB97/modly PR #244 with tests merged into the current test file.
---
 src/areas/workflows/mockExtensions.test.mjs | 31 +++++++++++++++++++++
 src/areas/workflows/mockExtensions.ts       | 12 ++++++--
 src/areas/workflows/preflight.ts            |  3 +-
 3 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/src/areas/workflows/mockExtensions.test.mjs b/src/areas/workflows/mockExtensions.test.mjs
index a3edbe84..0230418f 100644
--- a/src/areas/workflows/mockExtensions.test.mjs
+++ b/src/areas/workflows/mockExtensions.test.mjs
@@ -60,3 +60,34 @@ test('workflow discovery excludes corrupted extensions with preserved nodes', ()
 
   assert.deepEqual(result.map((entry) => entry.id), ['healthy-model/generate'])
 })
+
+test('object-shaped manifest inputs are normalized to plain type strings', () => {
+  const { buildAllWorkflowExtensions } = loadModule()
+  const ext = extension('process', {
+    nodes: [{
+      id: 'image-to-image', name: 'Image to Image', input: 'image',
+      inputs: [
+        { name: 'front', label: 'Front', type: 'image', required: true },
+        { name: 'back', label: 'Back', type: 'image', required: false },
+      ],
+      output: 'image', paramsSchema: [],
+    }],
+  })
+  assert.deepEqual(buildAllWorkflowExtensions([], [ext])[0].inputs, ['image', 'image'])
+})
+
+test('plain-string multi-input manifest values are preserved', () => {
+  const { buildAllWorkflowExtensions } = loadModule()
+  const ext = extension('process', {
+    nodes: [{ id: 'p', name: 'Process', input: 'image', inputs: ['image', 'text'],
+      inputLabels: ['Source', 'Prompt'], output: 'mesh', paramsSchema: [] }],
+  })
+  const [node] = buildAllWorkflowExtensions([], [ext])
+  assert.deepEqual(node.inputs, ['image', 'text'])
+  assert.deepEqual(node.inputLabels, ['Source', 'Prompt'])
+})
+
+test('manifest without multi-input keeps inputs undefined', () => {
+  const { buildAllWorkflowExtensions } = loadModule()
+  assert.equal(buildAllWorkflowExtensions([], [extension('process')])[0].inputs, undefined)
+})
diff --git a/src/areas/workflows/mockExtensions.ts b/src/areas/workflows/mockExtensions.ts
index 9bdb9a0a..0adc3433 100644
--- a/src/areas/workflows/mockExtensions.ts
+++ b/src/areas/workflows/mockExtensions.ts
@@ -32,6 +32,14 @@ function applyParamDefaults(
   )
 }
 
+// Normalize untyped third-party extension manifests at their IPC boundary.
+function normalizeInputs(raw: WorkflowExtension['inputs']): WorkflowExtension['inputs'] {
+  if (!raw) return raw
+  return raw.map((entry) => typeof entry === 'string'
+    ? entry
+    : (entry as unknown as { type: WorkflowExtension['input'] }).type)
+}
+
 export function buildAllWorkflowExtensions(
   modelExtensions:   ModelExtension[],
   processExtensions: ProcessExtension[],
@@ -50,7 +58,7 @@ export function buildAllWorkflowExtensions(
         name:            node.name,
         description:     ext.description ?? '',
         input:           node.input,
-        inputs:          node.inputs,
+        inputs:          normalizeInputs(node.inputs),
         inputLabels:     node.inputLabels,
         output:          node.output,
         params:          applyParamDefaults(node.paramsSchema as ParamSchema[], node.paramDefaults),
@@ -72,7 +80,7 @@ export function buildAllWorkflowExtensions(
         name:            node.name,
         description:     ext.description ?? '',
         input:           node.input,
-        inputs:          node.inputs,
+        inputs:          normalizeInputs(node.inputs),
         inputLabels:     node.inputLabels,
         output:          node.output,
         params:          applyParamDefaults(node.paramsSchema as ParamSchema[], node.paramDefaults),
diff --git a/src/areas/workflows/preflight.ts b/src/areas/workflows/preflight.ts
index 068a9277..677ae78c 100644
--- a/src/areas/workflows/preflight.ts
+++ b/src/areas/workflows/preflight.ts
@@ -34,7 +34,8 @@ function formatType(type: DataType): string {
   if (type === 'mesh') return 'mesh'
   if (type === 'image') return 'image'
   if (type === 'audio') return 'audio'
-  return 'text'
+  if (type === 'text') return 'text'
+  return String(type)
 }
 
 function formatRequiredTypes(types: DataType[]): string {

From c0beb4bb4504fe3c27abf8ce90cf0aed715367ed Mon Sep 17 00:00:00 2001
From: JayceeB1 <45721154+JayceeB1@users.noreply.github.com>
Date: Fri, 9 Oct 2026 23:28:18 +0200
Subject: [PATCH 03/11] integrate(#243): resizable asset library with
 thumbnails

Adapted onto current Modly Next viewer/exporter; UI state conflict resolved explicitly.
---
 .../main/artifact-registry-service.test.ts    | 27 ++++++
 electron/main/artifact-registry-service.ts    | 25 ++++++
 .../preload/artifact-registry-preload.test.ts |  2 +
 electron/preload/electron-api.ts              |  3 +
 src/areas/generate/GeneratePage.tsx           | 82 +++++++++++++++++--
 .../generate/assetLibraryService.test.ts      | 19 +++++
 src/areas/generate/assetLibraryService.ts     |  9 ++
 src/areas/generate/assetLibraryUi.test.ts     | 12 +++
 src/areas/generate/assetLibraryUi.ts          | 29 +++++++
 src/shared/types/assetLibrary.ts              | 10 +++
 src/shared/types/electron.d.ts                |  3 +
 11 files changed, 215 insertions(+), 6 deletions(-)

diff --git a/electron/main/artifact-registry-service.test.ts b/electron/main/artifact-registry-service.test.ts
index 276e90a1..3283a813 100644
--- a/electron/main/artifact-registry-service.test.ts
+++ b/electron/main/artifact-registry-service.test.ts
@@ -10,6 +10,7 @@ import {
   normalizeWorkspaceAssetPath,
   openWorkspaceAssetLibraryEntry,
   readWorkspaceAssetLibraryEntry,
+  readWorkspaceAssetLibraryThumbnail,
   registerWorkspaceAssetLibraryIpcHandlers,
 } from './artifact-registry-service.ts'
 
@@ -210,6 +211,27 @@ test('fails closed for unsafe, self, missing, and mismatched sourceWorkspacePath
   assert.equal(!mismatched.success && mismatched.error.code, 'not-openable')
 }))
 
+test('reads a sibling .thumb.png for GLB assets and stays silent when one is missing', () => withWorkspace(async (workspaceDir) => {
+  await mkdir(path.join(workspaceDir, 'Exports/props'), { recursive: true })
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.glb'), 'glb')
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.thumb.png'), 'fake-png-bytes')
+  await writeFile(path.join(workspaceDir, 'Exports/props/no-thumb.glb'), 'glb')
+  await writeFile(path.join(workspaceDir, 'Exports/static.ply'), 'ply')
+
+  const withThumb = await readWorkspaceAssetLibraryThumbnail({ workspaceDir, workspacePath: 'Exports/props/hero.glb' })
+  assert.equal(withThumb.success, true)
+  assert.equal(withThumb.success && withThumb.dataUrl, `data:image/png;base64,${Buffer.from('fake-png-bytes').toString('base64')}`)
+
+  const withoutThumb = await readWorkspaceAssetLibraryThumbnail({ workspaceDir, workspacePath: 'Exports/props/no-thumb.glb' })
+  assert.equal(withoutThumb.success, false)
+
+  const nonMesh = await readWorkspaceAssetLibraryThumbnail({ workspaceDir, workspacePath: 'Exports/static.ply' })
+  assert.equal(nonMesh.success, false)
+
+  const unsafe = await readWorkspaceAssetLibraryThumbnail({ workspaceDir, workspacePath: '../secret.glb' })
+  assert.equal(unsafe.success, false)
+}))
+
 test('IPC read and open handlers forward sourceWorkspacePath without trusting malformed payloads', async () => {
   const handlers = new Map<string, (event: unknown, payload: unknown) => Promise<unknown>>()
   registerWorkspaceAssetLibraryIpcHandlers({
@@ -236,7 +258,12 @@ test('registers workspace library IPC handlers with structured results', async (
   assert.equal(typeof handlers.get('workspace:library:list'), 'function')
   assert.equal(typeof handlers.get('workspace:library:read'), 'function')
   assert.equal(typeof handlers.get('workspace:library:open'), 'function')
+  assert.equal(typeof handlers.get('workspace:library:thumbnail'), 'function')
   const result = await handlers.get('workspace:library:read')?.({}, { workspacePath: '../escape.glb' })
   assert.equal(typeof (result as { success?: unknown }).success, 'boolean')
   assert.equal((result as { success: boolean, error?: { code: string } }).error?.code, 'unsafe-path')
+  const thumbnail = await handlers.get('workspace:library:thumbnail')?.({}, { workspacePath: '../escape.glb' })
+  assert.equal((thumbnail as { success: boolean }).success, false)
+  const missingPayload = await handlers.get('workspace:library:thumbnail')?.({}, {})
+  assert.equal((missingPayload as { success: boolean }).success, false)
 })
diff --git a/electron/main/artifact-registry-service.ts b/electron/main/artifact-registry-service.ts
index 2acb657f..c6d3232f 100644
--- a/electron/main/artifact-registry-service.ts
+++ b/electron/main/artifact-registry-service.ts
@@ -12,6 +12,7 @@ import type {
   AssetLibraryPreviewPayload,
   AssetLibraryReadResult,
   AssetLibrarySourceScope,
+  AssetLibraryThumbnailResult,
 } from '../../src/shared/types/assetLibrary'
 import type { ArtifactProvenance } from '../../src/shared/types/artifacts'
 
@@ -51,6 +52,10 @@ export interface WorkspaceAssetLibraryReadRequest extends WorkspaceAssetLibraryR
   sourceWorkspacePath?: string
 }
 
+export interface WorkspaceAssetLibraryThumbnailRequest extends WorkspaceAssetLibraryRequest {
+  workspacePath: string
+}
+
 interface AssetLibraryMetadata {
   sourceWorkspacePath?: string
   manifestWorkspacePath?: string
@@ -343,6 +348,21 @@ export async function openWorkspaceAssetLibraryEntry(request: WorkspaceAssetLibr
   return { success: true, entry: read.entry }
 }
 
+// Thumbnails are pre-rendered beside their source mesh (see thumbs.py): a
+// `<name>.glb` asset may have a sibling `<name>.thumb.png`. Missing files are
+// a normal, silent condition, never surfaced as an AssetLibraryError.
+export async function readWorkspaceAssetLibraryThumbnail(request: WorkspaceAssetLibraryThumbnailRequest): Promise<AssetLibraryThumbnailResult> {
+  try {
+    const normalized = normalizeWorkspaceAssetPath(request.workspaceDir, request.workspacePath)
+    if (!isGlbOrGltf(normalized.workspacePath)) return { success: false }
+    const thumbnailAbsolutePath = normalized.absolutePath.replace(/\.(glb|gltf)$/i, '.thumb.png')
+    const buffer = await readFile(thumbnailAbsolutePath)
+    return { success: true, dataUrl: `data:image/png;base64,${buffer.toString('base64')}` }
+  } catch {
+    return { success: false }
+  }
+}
+
 function readPayloadRequest(payload: unknown): { workspacePath?: string, sourceWorkspacePath?: string } {
   if (typeof payload !== 'object' || payload === null) return {}
   const values = payload as { workspacePath?: unknown, sourceWorkspacePath?: unknown }
@@ -364,4 +384,9 @@ export function registerWorkspaceAssetLibraryIpcHandlers(deps: WorkspaceAssetLib
     if (!workspacePath) return { success: false, error: libraryError('invalid-request', 'workspacePath is required.') }
     return openWorkspaceAssetLibraryEntry({ workspaceDir: deps.getWorkspaceDir(), workspacePath, sourceWorkspacePath })
   })
+  deps.ipcMain.handle('workspace:library:thumbnail', async (_event, payload) => {
+    const { workspacePath } = readPayloadRequest(payload)
+    if (!workspacePath) return { success: false }
+    return readWorkspaceAssetLibraryThumbnail({ workspaceDir: deps.getWorkspaceDir(), workspacePath })
+  })
 }
diff --git a/electron/preload/artifact-registry-preload.test.ts b/electron/preload/artifact-registry-preload.test.ts
index 9dec46fd..e4a9fc76 100644
--- a/electron/preload/artifact-registry-preload.test.ts
+++ b/electron/preload/artifact-registry-preload.test.ts
@@ -24,6 +24,7 @@ test('preload exposes scoped workspace library list/read/open methods', async ()
     workspacePath: 'Workflows/checkpoints/hero.landmarks.v1.json',
     sourceWorkspacePath: 'Workflows/checkpoints/hero.glb',
   })
+  await api.workspace.library.thumbnail({ workspacePath: 'Exports/hero.glb' })
 
   assert.deepEqual(calls, [
     { channel: 'workspace:library:list', payload: undefined },
@@ -41,6 +42,7 @@ test('preload exposes scoped workspace library list/read/open methods', async ()
         sourceWorkspacePath: 'Workflows/checkpoints/hero.glb',
       },
     },
+    { channel: 'workspace:library:thumbnail', payload: { workspacePath: 'Exports/hero.glb' } },
   ])
 })
 
diff --git a/electron/preload/electron-api.ts b/electron/preload/electron-api.ts
index f119582e..b6629e36 100644
--- a/electron/preload/electron-api.ts
+++ b/electron/preload/electron-api.ts
@@ -4,6 +4,8 @@ import type {
   AssetLibraryOpenResult,
   AssetLibraryReadRequest,
   AssetLibraryReadResult,
+  AssetLibraryThumbnailRequest,
+  AssetLibraryThumbnailResult,
 } from '../../src/shared/types/assetLibrary'
 
 export interface IpcRendererLike {
@@ -231,6 +233,7 @@ export function createElectronApi(ipcRenderer: IpcRendererLike, webFrame: WebFra
         list: (): Promise<AssetLibraryListResult> => ipcRenderer.invoke('workspace:library:list') as Promise<AssetLibraryListResult>,
         read: (request: AssetLibraryReadRequest): Promise<AssetLibraryReadResult> => ipcRenderer.invoke('workspace:library:read', request) as Promise<AssetLibraryReadResult>,
         open: (request: AssetLibraryOpenRequest): Promise<AssetLibraryOpenResult> => ipcRenderer.invoke('workspace:library:open', request) as Promise<AssetLibraryOpenResult>,
+        thumbnail: (request: AssetLibraryThumbnailRequest): Promise<AssetLibraryThumbnailResult> => ipcRenderer.invoke('workspace:library:thumbnail', request) as Promise<AssetLibraryThumbnailResult>,
       },
     },
 
diff --git a/src/areas/generate/GeneratePage.tsx b/src/areas/generate/GeneratePage.tsx
index 073ea487..98684fdd 100644
--- a/src/areas/generate/GeneratePage.tsx
+++ b/src/areas/generate/GeneratePage.tsx
@@ -13,12 +13,15 @@ import { resolveAssetLibraryOpenTarget, type ProjectedAssetLibraryEntry } from '
 import {
   ASSET_LIBRARY_SORT_OPTIONS,
   buildAssetLibraryOpenRequest,
+  clampAssetLibraryPanelWidth,
   createAssetLibraryOpenJob,
   describeAssetLibraryOpenability,
   filterAssetLibraryScopeGroups,
   getDefaultAssetLibraryCollapsedSectionKeys,
+  getStoredAssetLibraryPanelWidth,
   isAssetLibraryEntryOpenable,
   resolveOpenPanelAfterLibrarySelection,
+  storeAssetLibraryPanelWidth,
   toggleAssetLibrarySectionKey,
   type AssetLibrarySortMode,
   type GenerateOpenPanel,
@@ -468,6 +471,8 @@ function AssetLibraryPopover({
   searchQuery,
   sortMode,
   collapsedSectionKeys,
+  thumbnails,
+  panelWidth,
   onSelectEntry,
   onSearchQueryChange,
   onSortModeChange,
@@ -475,6 +480,7 @@ function AssetLibraryPopover({
   onOpenSelected,
   onRefresh,
   onClose,
+  onResizeMouseDown,
 }: {
   entries: ProjectedAssetLibraryEntry[]
   selectedEntryId: string | null
@@ -484,6 +490,9 @@ function AssetLibraryPopover({
   searchQuery: string
   sortMode: AssetLibrarySortMode
   collapsedSectionKeys: string[]
+  /** Data URLs keyed by workspacePath, populated lazily as thumbnails load. */
+  thumbnails: Record<string, string>
+  panelWidth: number
   onSelectEntry: (entryId: string) => void
   onSearchQueryChange: (value: string) => void
   onSortModeChange: (value: AssetLibrarySortMode) => void
@@ -491,6 +500,7 @@ function AssetLibraryPopover({
   onOpenSelected: () => void
   onRefresh: () => void
   onClose: () => void
+  onResizeMouseDown: (event: React.MouseEvent) => void
 }) {
   const scopeGroups = filterAssetLibraryScopeGroups(entries, searchQuery, sortMode)
   const visibleEntryIds = new Set(scopeGroups.flatMap((scopeGroup) => scopeGroup.entryGroups.flatMap((group) => group.entries.map((entry) => entry.id))))
@@ -509,7 +519,8 @@ function AssetLibraryPopover({
     <div
       role="dialog"
       aria-label="Workspace library"
-      className="absolute top-full left-0 mt-1 z-50 w-[320px] max-w-[calc(100vw-2rem)] bg-zinc-900 border border-zinc-700/60 rounded-xl p-3 flex flex-col gap-3 shadow-xl"
+      style={{ width: panelWidth }}
+      className="absolute top-full left-0 mt-1 z-50 max-w-[calc(100vw-2rem)] bg-zinc-900 border border-zinc-700/60 rounded-xl p-3 flex flex-col gap-3 shadow-xl"
     >
       <div className="flex items-center justify-between gap-2">
         <div>
@@ -525,6 +536,15 @@ function AssetLibraryPopover({
         </button>
       </div>
 
+      {/* Resize handle — drag to widen/narrow the library panel; size is persisted. */}
+      <div
+        onMouseDown={onResizeMouseDown}
+        role="separator"
+        aria-orientation="vertical"
+        aria-label="Resize workspace library panel"
+        className="absolute top-0 right-0 bottom-0 w-1.5 cursor-col-resize hover:bg-violet-400/40 active:bg-violet-400/60 transition-colors rounded-r-xl"
+      />
+
       <button
         type="button"
         onClick={onRefresh}
@@ -605,6 +625,7 @@ function AssetLibraryPopover({
                             <div id={capabilityRegionId}>
                               {group.entries.map((entry) => {
                                 const selected = entry.id === selectedEntryId
+                                const thumbnailDataUrl = thumbnails[entry.workspacePath]
                                 return (
                                   <button
                                     key={entry.id}
@@ -613,14 +634,23 @@ function AssetLibraryPopover({
                                     aria-pressed={selected}
                                     aria-label={`Select library asset ${entry.displayName}`}
                                     onClick={() => onSelectEntry(entry.id)}
-                                    className={`w-full text-left px-4 py-2 border-t border-zinc-800 first:border-t-0 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400
+                                    className={`flex w-full items-center gap-3 text-left px-4 py-2 border-t border-zinc-800 first:border-t-0 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400
                                       ${selected ? 'bg-violet-500/10 text-zinc-100' : 'text-zinc-300 hover:bg-zinc-800/80'}`}
                                   >
-                                    <div className="flex items-center justify-between gap-2">
-                                      <span className="text-xs font-medium">{entry.displayName}</span>
-                                      <span className="text-[10px] uppercase tracking-wider text-zinc-500">{entry.capability ?? entry.state.replace(/-/g, ' ')}</span>
+                                    {thumbnailDataUrl && (
+                                      <img
+                                        src={thumbnailDataUrl}
+                                        alt=""
+                                        className="h-20 w-20 shrink-0 rounded-lg border border-zinc-800 bg-zinc-950 object-contain"
+                                      />
+                                    )}
+                                    <div className="min-w-0 flex-1">
+                                      <div className="flex items-center justify-between gap-2">
+                                        <span className="text-xs font-medium">{entry.displayName}</span>
+                                        <span className="text-[10px] uppercase tracking-wider text-zinc-500">{entry.capability ?? entry.state.replace(/-/g, ' ')}</span>
+                                      </div>
+                                      <p className="mt-1 truncate text-[10px] text-zinc-500">{entry.workspacePath}</p>
                                     </div>
-                                    <p className="mt-1 truncate text-[10px] text-zinc-500">{entry.workspacePath}</p>
                                   </button>
                                 )
                               })}
@@ -675,8 +705,11 @@ export default function GeneratePage(): JSX.Element {
   const [librarySearchQuery, setLibrarySearchQuery] = useState('')
   const [librarySortMode, setLibrarySortMode] = useState<AssetLibrarySortMode>('type')
   const [libraryCollapsedSectionKeys, setLibraryCollapsedSectionKeys] = useState<string[]>(() => getDefaultAssetLibraryCollapsedSectionKeys())
+  const [libraryThumbnails, setLibraryThumbnails] = useState<Record<string, string>>({})
+  const [libraryPanelWidth, setLibraryPanelWidth] = useState<number>(() => getStoredAssetLibraryPanelWidth())
   const [gizmoMode, setGizmoMode] = useState<'translate' | 'rotate' | 'scale' | null>(null)
   const dragging = useRef(false)
+  const libraryPanelDragging = useRef(false)
   const [selectedPointLightId, setSelectedPointLightId] = useState<string | null>(null)
   // Populated by Viewer3D — undoes the latest live gizmo transform, if any.
   const gizmoUndoRef = useRef<(() => boolean) | null>(null)
@@ -758,6 +791,11 @@ export default function GeneratePage(): JSX.Element {
     // eslint-disable-next-line react-hooks/exhaustive-deps -- lazy-load guarded by loaded/loading flags
   }, [openPanel, libraryLoaded, libraryLoading])
 
+  // Persist the library panel's width so a manual resize survives app restarts.
+  useEffect(() => {
+    storeAssetLibraryPanelWidth(libraryPanelWidth)
+  }, [libraryPanelWidth])
+
   async function handleUnloadAll() {
     await window.electron.model.unloadAll()
     setUnloadStatus('done')
@@ -863,6 +901,7 @@ export default function GeneratePage(): JSX.Element {
         ? current
         : result.entries.find(isAssetLibraryEntryOpenable)?.id ?? result.entries[0]?.id ?? null)
       setLibraryLoaded(true)
+      void loadLibraryThumbnails(result.entries)
     } catch (err) {
       setLibraryLoaded(false)
       setLibraryEntries([])
@@ -873,6 +912,17 @@ export default function GeneratePage(): JSX.Element {
     }
   }
 
+  // Thumbnails are best-effort: only .glb/.gltf entries can have a rendered
+  // .thumb.png, and a missing one is silently skipped rather than surfaced.
+  async function loadLibraryThumbnails(entries: ProjectedAssetLibraryEntry[]) {
+    const candidates = entries.filter((entry) => entry.previewKind === '3d-model')
+    const results = await Promise.all(candidates.map(async (entry) => {
+      const result = await assetLibraryService.thumbnail({ workspacePath: entry.workspacePath })
+      return [entry.workspacePath, result.success ? result.dataUrl : null] as const
+    }))
+    setLibraryThumbnails(Object.fromEntries(results.filter((pair): pair is [string, string] => pair[1] !== null)))
+  }
+
   async function handleOpenSelectedLibraryEntry() {
     const selectedEntry = libraryEntries.find((entry) => entry.id === librarySelectedEntryId) ?? null
     if (!selectedEntry) {
@@ -959,6 +1009,23 @@ export default function GeneratePage(): JSX.Element {
     window.addEventListener('mouseup', onMouseUp)
   }, [])
 
+  const onLibraryPanelResizeMouseDown = useCallback((e: React.MouseEvent) => {
+    e.preventDefault()
+    libraryPanelDragging.current = true
+
+    const onMouseMove = (ev: MouseEvent) => {
+      if (!libraryPanelDragging.current) return
+      setLibraryPanelWidth((w) => clampAssetLibraryPanelWidth(w + ev.movementX))
+    }
+    const onMouseUp = () => {
+      libraryPanelDragging.current = false
+      window.removeEventListener('mousemove', onMouseMove)
+      window.removeEventListener('mouseup', onMouseUp)
+    }
+    window.addEventListener('mousemove', onMouseMove)
+    window.addEventListener('mouseup', onMouseUp)
+  }, [])
+
   return (
     <>
       <div className="flex flex-col border-r border-zinc-800 bg-surface-400 overflow-hidden shrink-0" style={{ width: panelWidth }}>
@@ -1082,6 +1149,8 @@ export default function GeneratePage(): JSX.Element {
                 searchQuery={librarySearchQuery}
                 sortMode={librarySortMode}
                 collapsedSectionKeys={libraryCollapsedSectionKeys}
+                thumbnails={libraryThumbnails}
+                panelWidth={libraryPanelWidth}
                 onSelectEntry={(entryId) => {
                   setLibraryError(null)
                   setLibrarySelectedEntryId(entryId)
@@ -1092,6 +1161,7 @@ export default function GeneratePage(): JSX.Element {
                 onOpenSelected={() => { void handleOpenSelectedLibraryEntry() }}
                 onRefresh={() => { void loadLibraryEntries() }}
                 onClose={() => setOpenPanel(null)}
+                onResizeMouseDown={onLibraryPanelResizeMouseDown}
               />
             )}
           </div>
diff --git a/src/areas/generate/assetLibraryService.test.ts b/src/areas/generate/assetLibraryService.test.ts
index 9e7938c4..0ac08bce 100644
--- a/src/areas/generate/assetLibraryService.test.ts
+++ b/src/areas/generate/assetLibraryService.test.ts
@@ -50,6 +50,7 @@ test('renderer service delegates safe IPC calls and normalizes returned entries'
     }),
     read: async () => ({ success: false, error: { code: 'missing', message: 'Missing' } }),
     open: async (request) => { openRequest = request; return { success: false, error: { code: 'missing', message: 'Missing' } } },
+    thumbnail: async () => ({ success: false }),
   })
 
   const result = await service.list()
@@ -58,3 +59,21 @@ test('renderer service delegates safe IPC calls and normalizes returned entries'
   await service.open({ workspacePath: 'Workflows/hero.landmarks.v1.json', sourceWorkspacePath: 'Workflows/hero.glb' })
   assert.deepEqual(openRequest, { workspacePath: 'Workflows/hero.landmarks.v1.json', sourceWorkspacePath: 'Workflows/hero.glb' })
 })
+
+test('renderer service validates thumbnail requests before IPC and never surfaces an error', async () => {
+  let invoked = false
+  const service = createAssetLibraryService({
+    list: async () => ({ success: true, entries: [] }),
+    read: async () => ({ success: false, error: { code: 'unexpected', message: 'should not run' } }),
+    open: async () => ({ success: false, error: { code: 'unexpected', message: 'should not run' } }),
+    thumbnail: async () => { invoked = true; return { success: true, dataUrl: 'data:image/png;base64,ok' } },
+  })
+
+  const unsafe = await service.thumbnail({ workspacePath: '../escape.glb' })
+  assert.deepEqual(unsafe, { success: false })
+  assert.equal(invoked, false)
+
+  const safe = await service.thumbnail({ workspacePath: 'Exports/hero.glb' })
+  assert.deepEqual(safe, { success: true, dataUrl: 'data:image/png;base64,ok' })
+  assert.equal(invoked, true)
+})
diff --git a/src/areas/generate/assetLibraryService.ts b/src/areas/generate/assetLibraryService.ts
index 38738579..5c18d49d 100644
--- a/src/areas/generate/assetLibraryService.ts
+++ b/src/areas/generate/assetLibraryService.ts
@@ -5,6 +5,8 @@ import type {
   AssetLibraryOpenResult,
   AssetLibraryReadRequest,
   AssetLibraryReadResult,
+  AssetLibraryThumbnailRequest,
+  AssetLibraryThumbnailResult,
 } from '../../shared/types/assetLibrary'
 import { projectAssetLibraryEntry, type ProjectedAssetLibraryEntry } from './assetLibraryProjection'
 
@@ -12,6 +14,7 @@ export interface AssetLibraryPreloadApi {
   list: () => Promise<AssetLibraryListResult>
   read: (request: AssetLibraryReadRequest) => Promise<AssetLibraryReadResult>
   open: (request: AssetLibraryOpenRequest) => Promise<AssetLibraryOpenResult>
+  thumbnail: (request: AssetLibraryThumbnailRequest) => Promise<AssetLibraryThumbnailResult>
 }
 
 export type ProjectedAssetLibraryListResult =
@@ -60,6 +63,12 @@ export function createAssetLibraryService(api: AssetLibraryPreloadApi) {
       if (!result.success) return result
       return { success: true, entry: projectAssetLibraryEntry(result.entry) }
     },
+    // A missing/invalid thumbnail is never an error the UI needs to show — the
+    // Library list just falls back to its text-only row.
+    async thumbnail(request: AssetLibraryThumbnailRequest): Promise<AssetLibraryThumbnailResult> {
+      if (validateWorkspacePath(request.workspacePath)) return { success: false }
+      return api.thumbnail(request)
+    },
   }
 }
 
diff --git a/src/areas/generate/assetLibraryUi.test.ts b/src/areas/generate/assetLibraryUi.test.ts
index e6b9fbca..681c292e 100644
--- a/src/areas/generate/assetLibraryUi.test.ts
+++ b/src/areas/generate/assetLibraryUi.test.ts
@@ -3,12 +3,15 @@ import test from 'node:test'
 
 import {
   buildAssetLibraryOpenRequest,
+  clampAssetLibraryPanelWidth,
   createAssetLibraryOpenJob,
   describeAssetLibraryOpenability,
   filterAssetLibraryScopeGroups,
   getDefaultAssetLibraryCollapsedSectionKeys,
+  getStoredAssetLibraryPanelWidth,
   isAssetLibraryEntryOpenable,
   resolveOpenPanelAfterLibrarySelection,
+  storeAssetLibraryPanelWidth,
   toggleAssetLibrarySectionKey,
   type AssetLibrarySortMode,
   type GenerateOpenPanel,
@@ -123,3 +126,12 @@ test('builds linked-source open requests and import jobs for safe sidecars', ()
   assert.equal(selection?.historyUrl, '/workspace/Workflows/run/hero.glb')
   assert.equal(selection?.job.outputUrl, '/workspace/Workflows/run/hero.glb')
 })
+
+test('Library panel width clamps to sane bounds and degrades silently without a localStorage', () => {
+  assert.equal(clampAssetLibraryPanelWidth(0), 260)
+  assert.equal(clampAssetLibraryPanelWidth(999), 560)
+  assert.equal(clampAssetLibraryPanelWidth(400), 400)
+  // node --test has no `localStorage` global — both helpers must fall back rather than throw.
+  assert.equal(getStoredAssetLibraryPanelWidth(), 320)
+  assert.doesNotThrow(() => storeAssetLibraryPanelWidth(400))
+})
diff --git a/src/areas/generate/assetLibraryUi.ts b/src/areas/generate/assetLibraryUi.ts
index 5e83e65a..295dd185 100644
--- a/src/areas/generate/assetLibraryUi.ts
+++ b/src/areas/generate/assetLibraryUi.ts
@@ -168,6 +168,35 @@ export function resolveOpenPanelAfterLibrarySelection(currentPanel: GenerateOpen
   return currentPanel === 'library' ? 'library' : currentPanel
 }
 
+export const ASSET_LIBRARY_PANEL_MIN_WIDTH = 260
+export const ASSET_LIBRARY_PANEL_MAX_WIDTH = 560
+export const ASSET_LIBRARY_PANEL_DEFAULT_WIDTH = 320
+
+const ASSET_LIBRARY_PANEL_WIDTH_STORAGE_KEY = 'modly-library-panel-width'
+
+export function clampAssetLibraryPanelWidth(width: number): number {
+  return Math.min(ASSET_LIBRARY_PANEL_MAX_WIDTH, Math.max(ASSET_LIBRARY_PANEL_MIN_WIDTH, width))
+}
+
+/** Reads the user's saved Library panel width, falling back to the default when unset, invalid, or unreadable. */
+export function getStoredAssetLibraryPanelWidth(): number {
+  try {
+    const raw = Number(localStorage.getItem(ASSET_LIBRARY_PANEL_WIDTH_STORAGE_KEY))
+    return Number.isFinite(raw) && raw > 0 ? clampAssetLibraryPanelWidth(raw) : ASSET_LIBRARY_PANEL_DEFAULT_WIDTH
+  } catch {
+    return ASSET_LIBRARY_PANEL_DEFAULT_WIDTH
+  }
+}
+
+/** Persists the Library panel width so it survives app restarts. */
+export function storeAssetLibraryPanelWidth(width: number): void {
+  try {
+    localStorage.setItem(ASSET_LIBRARY_PANEL_WIDTH_STORAGE_KEY, String(width))
+  } catch {
+    // Ignore quota/private-mode failures — the panel just won't remember its size.
+  }
+}
+
 function sortAssetLibraryEntries(
   entries: ProjectedAssetLibraryEntry[],
   sortMode: AssetLibrarySortMode,
diff --git a/src/shared/types/assetLibrary.ts b/src/shared/types/assetLibrary.ts
index fb5a602d..87c48785 100644
--- a/src/shared/types/assetLibrary.ts
+++ b/src/shared/types/assetLibrary.ts
@@ -81,3 +81,13 @@ export type AssetLibraryReadResult =
 export type AssetLibraryOpenResult =
   | { success: true, entry: AssetLibraryEntry }
   | { success: false, error: AssetLibraryError }
+
+export interface AssetLibraryThumbnailRequest {
+  workspacePath: string
+}
+
+// Missing thumbnails are an expected, silent condition (not every asset has
+// a rendered preview), so failure carries no error payload for the UI to show.
+export type AssetLibraryThumbnailResult =
+  | { success: true, dataUrl: string }
+  | { success: false }
diff --git a/src/shared/types/electron.d.ts b/src/shared/types/electron.d.ts
index c171b664..ab907c17 100644
--- a/src/shared/types/electron.d.ts
+++ b/src/shared/types/electron.d.ts
@@ -7,6 +7,8 @@ import type {
   AssetLibraryOpenResult,
   AssetLibraryReadRequest,
   AssetLibraryReadResult,
+  AssetLibraryThumbnailRequest,
+  AssetLibraryThumbnailResult,
 } from './assetLibrary'
 
 // ─── Extension types ──────────────────────────────────────────────────────────
@@ -297,6 +299,7 @@ declare global {
           list: () => Promise<AssetLibraryListResult>
           read: (request: AssetLibraryReadRequest) => Promise<AssetLibraryReadResult>
           open: (request: AssetLibraryOpenRequest) => Promise<AssetLibraryOpenResult>
+          thumbnail: (request: AssetLibraryThumbnailRequest) => Promise<AssetLibraryThumbnailResult>
         }
       }
       setup: {

From 7264ac59d632b0af2ab49977b04840b6a10614f1 Mon Sep 17 00:00:00 2001
From: JayceeB1 <45721154+JayceeB1@users.noreply.github.com>
Date: Fri, 9 Oct 2026 23:30:50 +0200
Subject: [PATCH 04/11] fix(viewer): repair malformed animation clip fallback
 from #242

---
 src/areas/generate/components/Viewer3D.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/areas/generate/components/Viewer3D.tsx b/src/areas/generate/components/Viewer3D.tsx
index 0d43d5c2..e3de5d6b 100644
--- a/src/areas/generate/components/Viewer3D.tsx
+++ b/src/areas/generate/components/Viewer3D.tsx
@@ -316,7 +316,7 @@ function GltfMeshModel(props: MeshModelProps): JSX.Element {
             className="bg-zinc-800 text-zinc-200 border border-zinc-700 rounded px-2 py-1 text-xs"
           >
             {animations.map((clip, i) => (
-              <option key={clip.name || i} value={i}>{clip.name || }</option>
+              <option key={clip.name || i} value={i}>{clip.name || ('Clip ' + (i + 1))}</option>
             ))}
           </select>
         </Html>

From ac6ac8a9de7bbe3b5c776d5695b3c3432f6df205 Mon Sep 17 00:00:00 2001
From: JayceeB1 <45721154+JayceeB1@users.noreply.github.com>
Date: Fri, 9 Oct 2026 23:33:14 +0200
Subject: [PATCH 05/11] integrate(#245): desktop UI, animation motion bar and
 exporter metadata

Manually reconcile viewer/param panel with 0.4.3 APIs; omit obsolete package-lock refresh.
---
 electron/main/index.ts                        |  59 +++++++++
 src/areas/generate/GeneratePage.tsx           |  42 +++++-
 src/areas/generate/components/MotionBar.tsx   |  48 +++++++
 src/areas/generate/components/Viewer3D.tsx    |  85 +++++++-----
 .../generate/components/WorkflowPanel.tsx     | 124 +++++++++++++++---
 .../nodes/mesh-exporter/manifest.json         |  21 +++
 .../nodes/mesh-exporter/processor.ts          |  74 +++++++++--
 src/shared/types/electron.d.ts                |   2 +-
 8 files changed, 391 insertions(+), 64 deletions(-)
 create mode 100644 src/areas/generate/components/MotionBar.tsx

diff --git a/electron/main/index.ts b/electron/main/index.ts
index 2f3f5b83..5b28bcb3 100644
--- a/electron/main/index.ts
+++ b/electron/main/index.ts
@@ -1,5 +1,6 @@
 import { app, BrowserWindow, shell, session } from 'electron'
 import { join } from 'path'
+import { readFileSync, writeFileSync } from 'fs'
 import { electronApp, optimizer, is } from '@electron-toolkit/utils'
 import { setupIpcHandlers } from './ipc-handlers'
 import { PythonBridge } from './python-bridge'
@@ -18,6 +19,37 @@ let pythonBridge: PythonBridge | null = null
 process.stdout?.on('error', () => {})
 process.stderr?.on('error', () => {})
 
+// UI zoom: Ctrl/Cmd with + / - / 0 scales the whole window like a browser,
+// clamped to a sane range and persisted across restarts. This is done at the
+// Chromium level (not CSS) so pointer math in the 3D viewport stays correct.
+const ZOOM_MIN = -2
+const ZOOM_MAX = 4
+
+function zoomFilePath(): string {
+  return join(app.getPath('userData'), 'ui-zoom.json')
+}
+
+function loadZoomLevel(): number {
+  try {
+    const saved = JSON.parse(readFileSync(zoomFilePath(), 'utf-8')) as { level?: number }
+    return typeof saved.level === 'number' ? saved.level : 0
+  } catch {
+    return 0
+  }
+}
+
+function saveZoomLevel(level: number): void {
+  try {
+    writeFileSync(zoomFilePath(), JSON.stringify({ level }), 'utf-8')
+  } catch (err) {
+    logger.error(`Failed to persist UI zoom level: ${err}`)
+  }
+}
+
+function clampZoomLevel(level: number): number {
+  return Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, level))
+}
+
 function createWindow(): void {
   mainWindow = new BrowserWindow({
     width: 1280,
@@ -60,6 +92,33 @@ function createWindow(): void {
       event.preventDefault()
       app.quit()
     }
+
+    const isZoomChord = input.type === 'keyDown' && (input.control || input.meta) && !input.alt
+    if (!isZoomChord) return
+
+    const wc = mainWindow?.webContents
+    if (!wc) return
+
+    if (input.key === '+' || input.key === '=') {
+      event.preventDefault()
+      const level = clampZoomLevel(wc.getZoomLevel() + 0.5)
+      wc.setZoomLevel(level)
+      saveZoomLevel(level)
+    } else if (input.key === '-' || input.key === '_') {
+      event.preventDefault()
+      const level = clampZoomLevel(wc.getZoomLevel() - 0.5)
+      wc.setZoomLevel(level)
+      saveZoomLevel(level)
+    } else if (input.key === '0') {
+      event.preventDefault()
+      wc.setZoomLevel(0)
+      saveZoomLevel(0)
+    }
+  })
+
+  mainWindow.webContents.on('did-finish-load', () => {
+    const level = loadZoomLevel()
+    if (level) mainWindow?.webContents.setZoomLevel(level)
   })
 
   mainWindow.webContents.setWindowOpenHandler((details) => {
diff --git a/src/areas/generate/GeneratePage.tsx b/src/areas/generate/GeneratePage.tsx
index 98684fdd..45d75907 100644
--- a/src/areas/generate/GeneratePage.tsx
+++ b/src/areas/generate/GeneratePage.tsx
@@ -28,9 +28,32 @@ import {
 } from './assetLibraryUi'
 
 const MIN_WIDTH = 220
-const MAX_WIDTH = 520
+const MAX_WIDTH = 900
 const DEFAULT_WIDTH = 320
 
+const PANEL_WIDTH_STORAGE_KEY = 'modly-panel-width'
+
+function clampPanelWidth(width: number): number {
+  return Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, width))
+}
+
+function getStoredPanelWidth(): number {
+  try {
+    const raw = Number(localStorage.getItem(PANEL_WIDTH_STORAGE_KEY))
+    return Number.isFinite(raw) && raw > 0 ? clampPanelWidth(raw) : DEFAULT_WIDTH
+  } catch {
+    return DEFAULT_WIDTH
+  }
+}
+
+function storePanelWidth(width: number): void {
+  try {
+    localStorage.setItem(PANEL_WIDTH_STORAGE_KEY, String(width))
+  } catch {
+    // Resizing still works if persisted settings are unavailable.
+  }
+}
+
 const MAX_POINT_LIGHTS = 6
 
 function createPointLight(): PointLight {
@@ -691,7 +714,7 @@ function AssetLibraryPopover({
 
 export default function GeneratePage(): JSX.Element {
   const [unloadStatus, setUnloadStatus] = useState<'idle' | 'done'>('idle')
-  const [panelWidth, setPanelWidth] = useState(DEFAULT_WIDTH)
+  const [panelWidth, setPanelWidth] = useState<number>(() => getStoredPanelWidth())
   const [openPanel, setOpenPanel] = useState<GenerateOpenPanel>(null)
   const [decimating, setDecimating] = useState(false)
   const [smoothing, setSmoothing] = useState(false)
@@ -796,6 +819,11 @@ export default function GeneratePage(): JSX.Element {
     storeAssetLibraryPanelWidth(libraryPanelWidth)
   }, [libraryPanelWidth])
 
+  // Persist the generate options panel's width so a manual resize survives app restarts.
+  useEffect(() => {
+    storePanelWidth(panelWidth)
+  }, [panelWidth])
+
   async function handleUnloadAll() {
     await window.electron.model.unloadAll()
     setUnloadStatus('done')
@@ -998,7 +1026,7 @@ export default function GeneratePage(): JSX.Element {
 
     const onMouseMove = (ev: MouseEvent) => {
       if (!dragging.current) return
-      setPanelWidth((w) => Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, w + ev.movementX)))
+      setPanelWidth((w) => clampPanelWidth(w + ev.movementX))
     }
     const onMouseUp = () => {
       dragging.current = false
@@ -1032,10 +1060,14 @@ export default function GeneratePage(): JSX.Element {
         <WorkflowPanel />
       </div>
 
-      {/* Resize handle */}
+      {/* Resize handle — drag to widen/narrow the generate options panel; size is persisted. */}
       <div
         onMouseDown={onMouseDown}
-        className="w-1 shrink-0 cursor-col-resize hover:bg-accent/40 active:bg-accent/60 transition-colors"
+        role="separator"
+        aria-orientation="vertical"
+        aria-label="Resize the generate options panel"
+        title="Drag to make this panel wider or narrower"
+        className="w-2 shrink-0 cursor-col-resize bg-zinc-600/40 hover:bg-accent/60 active:bg-accent/70 transition-colors"
       />
 
       <div className="flex-1 flex flex-col overflow-hidden">
diff --git a/src/areas/generate/components/MotionBar.tsx b/src/areas/generate/components/MotionBar.tsx
new file mode 100644
index 00000000..293f2435
--- /dev/null
+++ b/src/areas/generate/components/MotionBar.tsx
@@ -0,0 +1,48 @@
+export interface MotionClip {
+  name: string
+}
+
+interface MotionBarProps {
+  clips:       MotionClip[]
+  activeIndex: number
+  onChange:    (index: number) => void
+}
+
+function clipLabel(clip: MotionClip, index: number): string {
+  return clip.name || `Motion ${index + 1}`
+}
+
+/** Bottom-left overlay for scrubbing a rigged model's animation clips. */
+export function MotionBar({ clips, activeIndex, onChange }: MotionBarProps): JSX.Element | null {
+  if (clips.length === 0) return null
+
+  if (clips.length === 1) {
+    return (
+      <div className="flex items-center gap-2 bg-zinc-900/70 border border-zinc-700/50 backdrop-blur-sm rounded-xl px-3 py-1.5 pointer-events-none">
+        <span className="text-[10px] text-zinc-500">Playing</span>
+        <span className="text-xs text-zinc-300">{clipLabel(clips[0], 0)}</span>
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex items-center gap-2 bg-zinc-900/70 border border-zinc-700/50 backdrop-blur-sm rounded-xl px-2 py-1.5">
+      <span className="text-[10px] text-zinc-500 pl-1">Motion</span>
+      <select
+        value={activeIndex}
+        onChange={(e) => onChange(Number(e.target.value))}
+        className="bg-zinc-800 text-zinc-200 border border-zinc-700 rounded-md px-2 py-1 text-xs focus:outline-none focus:border-accent/60"
+      >
+        {clips.map((clip, i) => (
+          <option key={i} value={i}>{clipLabel(clip, i)}</option>
+        ))}
+      </select>
+      <button
+        onClick={() => onChange((activeIndex + 1) % clips.length)}
+        className="px-2 py-1 rounded-md text-[11px] font-medium bg-zinc-700 hover:bg-zinc-600 text-zinc-200 transition-colors"
+      >
+        Next
+      </button>
+    </div>
+  )
+}
diff --git a/src/areas/generate/components/Viewer3D.tsx b/src/areas/generate/components/Viewer3D.tsx
index e3de5d6b..0624b939 100644
--- a/src/areas/generate/components/Viewer3D.tsx
+++ b/src/areas/generate/components/Viewer3D.tsx
@@ -2,7 +2,7 @@ import { Component, Suspense, useCallback, useEffect, useMemo, useRef, useState
 import type { ReactNode, ErrorInfo, MutableRefObject } from 'react'
 import { Canvas, useFrame, useLoader, useThree } from '@react-three/fiber'
 import type { ThreeEvent } from '@react-three/fiber'
-import { Environment, GizmoHelper, Html, Lightformer, OrbitControls, useGizmoContext, useGLTF } from '@react-three/drei'
+import { Environment, GizmoHelper, Lightformer, OrbitControls, useGizmoContext, useGLTF } from '@react-three/drei'
 import { EffectComposer, Outline, Select, Selection } from '@react-three/postprocessing'
 import * as THREE from 'three'
 import { OBJLoader } from 'three/examples/jsm/loaders/OBJLoader.js'
@@ -20,6 +20,7 @@ import SplatViewer, { type SplatViewerHandle } from './SplatViewer'
 import { useGeneration } from '@shared/hooks/useGeneration'
 import { useAppStore } from '@shared/stores/appStore'
 import { ViewerToolbar, type ViewMode } from './ViewerToolbar'
+import { MotionBar, type MotionClip } from './MotionBar'
 import type { LightSettings, PointLight } from '@shared/stores/appStore'
 import { DEFAULT_LIGHT_SETTINGS } from '@shared/stores/appStore'
 
@@ -259,6 +260,8 @@ interface MeshModelProps {
   onStats: (stats: { vertices: number; triangles: number }) => void
   onSelect: () => void
   onObject: (obj: THREE.Object3D | null) => void
+  onClips: (clips: MotionClip[]) => void
+  clipIndex: number
 }
 
 function centerSceneOnGrid(scene: THREE.Object3D): void {
@@ -274,55 +277,64 @@ function centerSceneOnGrid(scene: THREE.Object3D): void {
   scene.updateMatrixWorld(true)
 }
 
-function MeshModel({ url, jobId, viewMode, selected, onStats, onSelect, onObject }: MeshModelProps): JSX.Element {
+function MeshModel({ url, jobId, viewMode, selected, onStats, onSelect, onObject, onClips, clipIndex }: MeshModelProps): JSX.Element {
   const extension = url.split('?')[0]?.split('.').pop()?.toLowerCase()
-  const common = { url, jobId, viewMode, selected, onStats, onSelect, onObject }
+  const common = { url, jobId, viewMode, selected, onStats, onSelect, onObject, onClips, clipIndex }
   return extension === 'obj' ? <ObjMeshModel {...common} /> : <GltfMeshModel {...common} />
 }
 
 function GltfMeshModel(props: MeshModelProps): JSX.Element {
   const gltf = useGLTF(props.url)
   const { scene, animations } = gltf
-  const mixerRef = useRef<THREE.AnimationMixer | null>(null)
-  const [clipIndex, setClipIndex] = useState(0)
+  const mixerRef  = useRef<THREE.AnimationMixer | null>(null)
+  const actionRef = useRef<THREE.AnimationAction | null>(null)
+  const { onClips, clipIndex } = props
 
   // Rigged models arrive with one or more clips; without a mixer they render
-  // frozen in bind pose, which reads as "the rig failed".
+  // frozen in bind pose, which reads as "the rig failed". The mixer lives for
+  // as long as this model does — clip switches below reuse it.
   useEffect(() => {
     if (!animations?.length) {
       mixerRef.current = null
+      actionRef.current = null
       return
     }
     const mixer = new THREE.AnimationMixer(scene)
-    mixer.clipAction(animations[Math.min(clipIndex, animations.length - 1)]).play()
     mixerRef.current = mixer
     return () => {
       mixer.stopAllAction()
       mixer.uncacheRoot(scene)
       mixerRef.current = null
+      actionRef.current = null
     }
-  }, [scene, animations, clipIndex])
+  }, [scene, animations])
+
+  // Tell the viewer which clips are available so it can render the motion bar.
+  useEffect(() => {
+    onClips(animations?.map((clip) => ({ name: clip.name })) ?? [])
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- onClips is a stable callback
+  }, [animations])
+
+  // Switch to the selected clip, cross-fading so playback never hard-cuts.
+  useEffect(() => {
+    const mixer = mixerRef.current
+    if (!mixer || !animations?.length) return
+    const clip = animations[Math.min(clipIndex, animations.length - 1)]
+    const next = mixer.clipAction(clip)
+    next.reset().setLoop(THREE.LoopRepeat, Infinity)
+    const prev = actionRef.current
+    if (prev && prev !== next) {
+      prev.fadeOut(0.25)
+      next.fadeIn(0.25).play()
+    } else {
+      next.play()
+    }
+    actionRef.current = next
+  }, [animations, clipIndex])
 
   useFrame((_state, delta) => mixerRef.current?.update(delta))
 
-  return (
-    <>
-      <SceneMeshModel {...props} scene={scene} loaderType="gltf" />
-      {animations && animations.length > 1 && (
-        <Html position={[0, 0, 0]} wrapperClass="clip-picker">
-          <select
-            value={clipIndex}
-            onChange={(e) => setClipIndex(Number(e.target.value))}
-            className="bg-zinc-800 text-zinc-200 border border-zinc-700 rounded px-2 py-1 text-xs"
-          >
-            {animations.map((clip, i) => (
-              <option key={clip.name || i} value={i}>{clip.name || ('Clip ' + (i + 1))}</option>
-            ))}
-          </select>
-        </Html>
-      )}
-    </>
-  )
+  return <SceneMeshModel {...props} scene={scene} loaderType="gltf" />
 }
 
 function ObjMeshModel(props: MeshModelProps): JSX.Element {
@@ -1052,6 +1064,8 @@ export default function Viewer3D({
 
   const [viewMode, setViewMode] = useState<ViewMode>('solid')
   const [autoRotate, setAutoRotate] = useState(false)
+  const [clips, setClips] = useState<MotionClip[]>([])
+  const [activeClipIndex, setActiveClipIndex] = useState(0)
   const selected = useAppStore((s) => s.meshSelected)
   const setSelected = useAppStore((s) => s.setMeshSelected)
   const canvasRef = useRef<HTMLCanvasElement | null>(null)
@@ -1095,6 +1109,8 @@ export default function Viewer3D({
     setSelected(false)
     setViewMode('solid')
     setStoreMeshStats(null)
+    setClips([])
+    setActiveClipIndex(0)
     // eslint-disable-next-line react-hooks/exhaustive-deps -- reset only when the model changes; setters are stable
   }, [modelUrl])
 
@@ -1303,6 +1319,8 @@ export default function Viewer3D({
                   onStats={setStoreMeshStats}
                   onSelect={handleMeshSelect}
                   onObject={setMeshObject}
+                  onClips={setClips}
+                  clipIndex={activeClipIndex}
                 />
               </Suspense>
             </Selection>
@@ -1366,12 +1384,15 @@ export default function Viewer3D({
           />
         )}
 
-        {/* Bottom-left stats overlay */}
-        {meshStats && (
-          <div className="absolute bottom-4 left-4 pointer-events-none">
-            <p className="text-xs text-zinc-500">
-              {meshStats.triangles.toLocaleString()} tri &bull; {meshStats.vertices.toLocaleString()} verts
-            </p>
+        {/* Bottom-left overlays — mesh stats and the motion bar */}
+        {(meshStats || clips.length > 0) && (
+          <div className="absolute bottom-4 left-4 flex flex-col items-start gap-2">
+            {meshStats && (
+              <p className="text-xs text-zinc-500 pointer-events-none">
+                {meshStats.triangles.toLocaleString()} tri &bull; {meshStats.vertices.toLocaleString()} verts
+              </p>
+            )}
+            <MotionBar clips={clips} activeIndex={activeClipIndex} onChange={setActiveClipIndex} />
           </div>
         )}
 
diff --git a/src/areas/generate/components/WorkflowPanel.tsx b/src/areas/generate/components/WorkflowPanel.tsx
index 14b25781..472ef125 100644
--- a/src/areas/generate/components/WorkflowPanel.tsx
+++ b/src/areas/generate/components/WorkflowPanel.tsx
@@ -58,6 +58,83 @@ function topoSortNodes(nodes: Workflow['nodes'], edges: Workflow['edges']): WFNo
   return result
 }
 
+// ─── Tag suggestions ──────────────────────────────────────────────────────────
+
+const TAG_STOPWORDS = new Set([
+  'a', 'an', 'the', 'of', 'for', 'and', 'or', 'to', 'in', 'on', 'my', 'this', 'is', 'with',
+])
+
+const FIXED_TAG_VOCAB = [
+  'prop', 'character', 'creature', 'environment', 'weapon',
+  'furniture', 'hero-asset', 'background', 'low-poly', 'stylized', 'realistic',
+]
+
+const MAX_TAG_SUGGESTIONS = 10
+
+/** Slugified words pulled from the typed name/project, plus a small fixed vocabulary — capped and deduped. */
+function suggestedTags(modelName: string, project: string): string[] {
+  const fromFields = `${modelName} ${project}`
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((word) => word.length > 1 && !TAG_STOPWORDS.has(word))
+
+  const seen = new Set<string>()
+  const suggestions: string[] = []
+  for (const tag of [...fromFields, ...FIXED_TAG_VOCAB]) {
+    if (!tag || seen.has(tag)) continue
+    seen.add(tag)
+    suggestions.push(tag)
+    if (suggestions.length >= MAX_TAG_SUGGESTIONS) break
+  }
+  return suggestions
+}
+
+function parseTags(value: string): string[] {
+  return value.split(',').map((s) => s.trim()).filter(Boolean)
+}
+
+/** Appends a tag to the comma-separated value, or removes it if already present. */
+function toggleTag(value: string, tag: string): string {
+  const tags = parseTags(value)
+  const i = tags.indexOf(tag)
+  if (i >= 0) tags.splice(i, 1)
+  else tags.push(tag)
+  return tags.join(', ')
+}
+
+
+function TagSuggestionPills({ value, onChange, modelName, project }: {
+  value:     string
+  onChange:  (v: string) => void
+  modelName: string
+  project:   string
+}) {
+  const suggestions = useMemo(() => suggestedTags(modelName, project), [modelName, project])
+  if (suggestions.length === 0) return null
+
+  const active = new Set(parseTags(value))
+
+  return (
+    <div className="flex flex-wrap gap-1.5">
+      {suggestions.map((tag) => (
+        <button
+          key={tag}
+          type="button"
+          onClick={() => onChange(toggleTag(value, tag))}
+          className={`px-2 py-0.5 rounded-full text-[10px] border transition-colors ${
+            active.has(tag)
+              ? 'bg-accent/20 border-accent/60 text-accent-light'
+              : 'bg-zinc-800 border-zinc-700 text-zinc-400 hover:border-zinc-600 hover:text-zinc-200'
+          }`}
+        >
+          {tag}
+        </button>
+      ))}
+    </div>
+  )
+}
+
+
 // ─── Param field ──────────────────────────────────────────────────────────────
 
 const inputCls = 'w-full bg-zinc-800 border border-zinc-700/80 rounded-md px-2 py-1 text-[11px] text-zinc-200 focus:outline-none focus:border-accent/60'
@@ -201,7 +278,7 @@ function ImageParamRow({ nodeId, nodes, onPatch }: { nodeId: string; nodes: Flow
           <rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="8.5" cy="8.5" r="1.5"/>
           <polyline points="21 15 16 10 5 21"/>
         </svg>
-        <span className="text-[11px] font-medium text-zinc-300">Image</span>
+        <span className="text-[11px] font-medium text-zinc-300">Your sketch or photo — required</span>
       </div>
       {preview ? (
         <button onClick={browse} className="relative w-full aspect-square rounded-lg overflow-hidden border border-zinc-700 group">
@@ -298,13 +375,13 @@ function TextParamRow({ nodeId, nodes, onPatch }: { nodeId: string; nodes: FlowN
         <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="#fbbf24" strokeWidth="2">
           <path d="M17 6.1H3M21 12.1H3M15.1 18H3"/>
         </svg>
-        <span className="text-[11px] font-medium text-zinc-300">Text</span>
+        <span className="text-[11px] font-medium text-zinc-300">Extra details — optional</span>
       </div>
       <textarea
         value={text}
         onChange={(e) => onPatch(nodeId, { params: { ...(data?.params ?? {}), text: e.target.value } })}
-        placeholder="Enter text…" rows={3}
-        className="w-full bg-zinc-800 border border-zinc-700/80 rounded-md px-2.5 py-2 text-[11px] text-zinc-200 placeholder-zinc-600 focus:outline-none focus:border-amber-500/40 resize-none leading-relaxed"
+        placeholder="Enter text…" rows={14}
+        className="w-full bg-zinc-800 border border-zinc-700/80 rounded-md px-2.5 py-2 text-[11px] text-zinc-200 placeholder-zinc-600 focus:outline-none focus:border-amber-500/40 resize-y min-h-[14rem] leading-relaxed"
       />
     </div>
   )
@@ -401,22 +478,33 @@ function ExtensionParamRow({ nodeId, ext, nodes, onPatch }: { nodeId: string; ex
         <div className="mt-2 flex flex-col gap-2">
           {ext.params.map((param) => {
             const val = ((data?.params[param.id] ?? param.default) as number | string)
+            const setValue = (v: number | string) =>
+              onPatch(nodeId, { params: { ...(data?.params ?? {}), [param.id]: v } })
             return (
-              <div key={param.id} className="flex items-center gap-2">
-                <label className="text-[10px] text-zinc-500 w-20 shrink-0 truncate">{param.label}</label>
-                <div className="flex-1">
-                  <ParamField param={withWeightVariantAvailability(param, ext.weightVariants, installedVariants)} value={val}
-                    onChange={(v) => onPatch(nodeId, { params: { ...(data?.params ?? {}), [param.id]: v } })} />
-                  {/* Offer the install instead of leaving the panel on selection. */}
-                  {isMissingWeightVariant(param.id, val, ext.weightVariants, installedVariants) && (
-                    <button
-                      onClick={() => openExtension(ext.extensionId)}
-                      className="mt-1 text-[10px] text-amber-400 hover:text-amber-300 hover:underline"
-                    >
-                      Not installed — install it
-                    </button>
-                  )}
+              <div key={param.id} className="flex flex-col gap-1.5">
+                <div className="flex items-center gap-2">
+                  <label className="text-[10px] text-zinc-500 w-32 shrink-0 leading-tight">{param.label}</label>
+                  <div className="flex-1">
+                    <ParamField param={withWeightVariantAvailability(param, ext.weightVariants, installedVariants)} value={val}
+                      onChange={setValue} />
+                    {isMissingWeightVariant(param.id, val, ext.weightVariants, installedVariants) && (
+                      <button
+                        onClick={() => openExtension(ext.extensionId)}
+                        className="mt-1 text-[10px] text-amber-400 hover:text-amber-300 hover:underline"
+                      >
+                        Not installed — install it
+                      </button>
+                    )}
+                  </div>
                 </div>
+                {param.id === 'tags' && (
+                  <TagSuggestionPills
+                    value={String(val)}
+                    onChange={setValue}
+                    modelName={String(data?.params['model_name'] ?? '')}
+                    project={String(data?.params['project'] ?? '')}
+                  />
+                )}
               </div>
             )
           })}
diff --git a/src/areas/workflows/nodes/mesh-exporter/manifest.json b/src/areas/workflows/nodes/mesh-exporter/manifest.json
index 20eb7a86..82b0e645 100644
--- a/src/areas/workflows/nodes/mesh-exporter/manifest.json
+++ b/src/areas/workflows/nodes/mesh-exporter/manifest.json
@@ -13,6 +13,27 @@
       "input": "mesh",
       "output": "mesh",
       "params_schema": [
+        {
+          "id": "model_name",
+          "label": "Name this model (optional)",
+          "type": "text",
+          "default": "",
+          "description": "Used for the file name, e.g. 'brass floor lamp' becomes brass-floor-lamp-4f2a.glb. Leave it blank for a dated name."
+        },
+        {
+          "id": "project",
+          "label": "Which game or project is this for? (optional)",
+          "type": "text",
+          "default": "",
+          "description": "Files are filed under a folder of this name, so the Library groups a game's models together instead of one long list."
+        },
+        {
+          "id": "tags",
+          "label": "Tags (optional, comma separated)",
+          "type": "text",
+          "default": "",
+          "description": "Saved with the model. The exporter adds what it can tell on its own — rigged, animated, textured, how heavy it is."
+        },
         {
           "id": "export_format",
           "label": "Export Format",
diff --git a/src/areas/workflows/nodes/mesh-exporter/processor.ts b/src/areas/workflows/nodes/mesh-exporter/processor.ts
index 4c188561..256c2c0b 100644
--- a/src/areas/workflows/nodes/mesh-exporter/processor.ts
+++ b/src/areas/workflows/nodes/mesh-exporter/processor.ts
@@ -200,16 +200,74 @@ const processor = async (
   context.progress(20, 'Loading mesh…')
   const doc = await io.read(input.filePath)
 
-  let outPath: string
-  if (outputPath) {
-    fs.mkdirSync(outputPath, { recursive: true })
-    outPath = path.join(outputPath, `export-${Date.now()}${ext}`)
-  } else {
-    const exportsDir = path.join(context.workspaceDir, 'Exports')
-    fs.mkdirSync(exportsDir, { recursive: true })
-    outPath = path.join(exportsDir, `export-${Date.now()}${ext}`)
+  // modly-friendly-names: a folder of export-1785194887022.glb tells you nothing.
+  const stamp  = new Date()
+  const pad    = (n: number): string => String(n).padStart(2, '0')
+  const unique = Date.now().toString(36).slice(-4)
+  const typed  = String(params['model_name'] ?? '').trim()
+  const slug   = typed
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48)
+  const dated = `model-${stamp.getFullYear()}-${pad(stamp.getMonth() + 1)}-${pad(stamp.getDate())}`
+    + `-${pad(stamp.getHours())}${pad(stamp.getMinutes())}`
+  const baseName = `${slug || dated}-${unique}${ext}`
+
+  const slugify = (s: unknown): string => String(s ?? '').toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40)
+  const project = slugify(params['project'])
+
+  const root = outputPath || path.join(context.workspaceDir, 'Exports')
+  const dir  = project ? path.join(root, project) : root
+  fs.mkdirSync(dir, { recursive: true })
+  const outPath = path.join(dir, baseName)
+
+  // Tags: what the operator typed, plus what the file itself can tell us.
+  const typedTags = String(params['tags'] ?? '').split(',').map(slugify).filter(Boolean)
+  const suggested: string[] = []
+  try {
+    const r = doc.getRoot()
+    if (r.listSkins().length) suggested.push('rigged')
+    if (r.listAnimations().length) {
+      suggested.push('animated')
+      for (const a of r.listAnimations()) {
+        const n = slugify(a.getName())
+        if (n) suggested.push(`clip-${n}`)
+      }
+    }
+    if (r.listTextures().length) suggested.push('textured')
+    let tris = 0
+    for (const m of r.listMeshes())
+      for (const prim of m.listPrimitives()) {
+        const idx = prim.getIndices()
+        tris += idx ? idx.getCount() / 3
+                    : (prim.getAttribute('POSITION')?.getCount() ?? 0) / 3
+      }
+    tris = Math.round(tris)
+    suggested.push(tris < 5000 ? 'low-poly' : tris > 100000 ? 'high-poly' : 'mid-poly')
+    if (project) suggested.push(project)
+  } catch (e) {
+    context.log(`tagging skipped: ${e}`)
   }
+  const tags = Array.from(new Set([...typedTags, ...suggested]))
+
   fs.mkdirSync(path.dirname(outPath), { recursive: true })
+  fs.writeFileSync(outPath.replace(/\.[^.]+$/, '') + '.tags.json', JSON.stringify({
+    name:    typed || null,
+    project: params['project'] || null,
+    tags,
+    created: new Date().toISOString(),
+  }, null, 2))
+
+  try {
+    const asset = doc.getRoot().getAsset()
+    asset.extras = Object.assign({}, asset.extras, {
+      modly: { name: typed || null, project: params['project'] || null, tags },
+    })
+  } catch (e) {
+    context.log(`could not embed tags: ${e}`)
+  }
 
   context.progress(50, `Exporting as ${format.toUpperCase()}…`)
 
diff --git a/src/shared/types/electron.d.ts b/src/shared/types/electron.d.ts
index ab907c17..caa0bf33 100644
--- a/src/shared/types/electron.d.ts
+++ b/src/shared/types/electron.d.ts
@@ -66,7 +66,7 @@ export type PickerIntent = 'folder' | 'image' | 'mesh' | 'text'
 export interface ParamSchema {
   id:       string
   label:    string
-  type:     'select' | 'int' | 'float' | 'string' | 'file-select'
+  type:     'select' | 'int' | 'float' | 'string' | 'text' | 'file-select'
   default:  number | string
   options?: { value: number | string; label: string }[]
   min?:     number

From 2f9d05d64bce826c3661a2eb614deae65ebbb3ea Mon Sep 17 00:00:00 2001
From: JayceeB1 <45721154+JayceeB1@users.noreply.github.com>
Date: Fri, 9 Oct 2026 23:34:29 +0200
Subject: [PATCH 06/11] integrate(#247): searchable and vertically resizable
 library panel

Reconciled state additions with the current 0.4.3 Generate page.
---
 src/areas/generate/GeneratePage.tsx       | 88 +++++++++++++++++------
 src/areas/generate/assetLibraryUi.test.ts | 30 ++++++++
 src/areas/generate/assetLibraryUi.ts      | 44 ++++++++++++
 3 files changed, 141 insertions(+), 21 deletions(-)

diff --git a/src/areas/generate/GeneratePage.tsx b/src/areas/generate/GeneratePage.tsx
index 45d75907..cd46aa46 100644
--- a/src/areas/generate/GeneratePage.tsx
+++ b/src/areas/generate/GeneratePage.tsx
@@ -13,14 +13,18 @@ import { resolveAssetLibraryOpenTarget, type ProjectedAssetLibraryEntry } from '
 import {
   ASSET_LIBRARY_SORT_OPTIONS,
   buildAssetLibraryOpenRequest,
+  clampAssetLibraryPanelHeight,
   clampAssetLibraryPanelWidth,
   createAssetLibraryOpenJob,
   describeAssetLibraryOpenability,
   filterAssetLibraryScopeGroups,
   getDefaultAssetLibraryCollapsedSectionKeys,
+  getStoredAssetLibraryPanelHeight,
   getStoredAssetLibraryPanelWidth,
   isAssetLibraryEntryOpenable,
+  isAssetLibrarySectionExpanded,
   resolveOpenPanelAfterLibrarySelection,
+  storeAssetLibraryPanelHeight,
   storeAssetLibraryPanelWidth,
   toggleAssetLibrarySectionKey,
   type AssetLibrarySortMode,
@@ -496,6 +500,7 @@ function AssetLibraryPopover({
   collapsedSectionKeys,
   thumbnails,
   panelWidth,
+  panelHeight,
   onSelectEntry,
   onSearchQueryChange,
   onSortModeChange,
@@ -504,6 +509,7 @@ function AssetLibraryPopover({
   onRefresh,
   onClose,
   onResizeMouseDown,
+  onResizeHeightMouseDown,
 }: {
   entries: ProjectedAssetLibraryEntry[]
   selectedEntryId: string | null
@@ -516,6 +522,7 @@ function AssetLibraryPopover({
   /** Data URLs keyed by workspacePath, populated lazily as thumbnails load. */
   thumbnails: Record<string, string>
   panelWidth: number
+  panelHeight: number
   onSelectEntry: (entryId: string) => void
   onSearchQueryChange: (value: string) => void
   onSortModeChange: (value: AssetLibrarySortMode) => void
@@ -524,6 +531,7 @@ function AssetLibraryPopover({
   onRefresh: () => void
   onClose: () => void
   onResizeMouseDown: (event: React.MouseEvent) => void
+  onResizeHeightMouseDown: (event: React.MouseEvent) => void
 }) {
   const scopeGroups = filterAssetLibraryScopeGroups(entries, searchQuery, sortMode)
   const visibleEntryIds = new Set(scopeGroups.flatMap((scopeGroup) => scopeGroup.entryGroups.flatMap((group) => group.entries.map((entry) => entry.id))))
@@ -531,6 +539,7 @@ function AssetLibraryPopover({
     ? entries.find((entry) => entry.id === selectedEntryId) ?? null
     : null
   const normalizedSearchQuery = searchQuery.trim()
+  const hasActiveSearch = normalizedSearchQuery.length > 0
   const openDisabled = !selectedEntry || !isAssetLibraryEntryOpenable(selectedEntry) || loading || opening
   const selectedMessage = selectedEntry
     ? describeAssetLibraryOpenability(selectedEntry)
@@ -542,10 +551,10 @@ function AssetLibraryPopover({
     <div
       role="dialog"
       aria-label="Workspace library"
-      style={{ width: panelWidth }}
-      className="absolute top-full left-0 mt-1 z-50 max-w-[calc(100vw-2rem)] bg-zinc-900 border border-zinc-700/60 rounded-xl p-3 flex flex-col gap-3 shadow-xl"
+      style={{ width: panelWidth, height: panelHeight }}
+      className="absolute top-full left-0 mt-1 z-50 max-w-[calc(100vw-2rem)] max-h-[calc(100vh-4rem)] bg-zinc-900 border border-zinc-700/60 rounded-xl p-3 flex flex-col gap-3 shadow-xl overflow-hidden"
     >
-      <div className="flex items-center justify-between gap-2">
+      <div className="flex items-center justify-between gap-2 shrink-0">
         <div>
           <p className="text-[10px] text-zinc-500 uppercase tracking-wider">Workspace library</p>
           <p className="text-xs text-zinc-300">Select a workspace asset and open the supported source in Generate.</p>
@@ -564,20 +573,29 @@ function AssetLibraryPopover({
         onMouseDown={onResizeMouseDown}
         role="separator"
         aria-orientation="vertical"
-        aria-label="Resize workspace library panel"
+        aria-label="Resize workspace library panel width"
         className="absolute top-0 right-0 bottom-0 w-1.5 cursor-col-resize hover:bg-violet-400/40 active:bg-violet-400/60 transition-colors rounded-r-xl"
       />
 
+      {/* Resize handle — drag to grow/shrink the library panel; size is persisted. */}
+      <div
+        onMouseDown={onResizeHeightMouseDown}
+        role="separator"
+        aria-orientation="horizontal"
+        aria-label="Resize workspace library panel height"
+        className="absolute bottom-0 left-0 right-0 h-1.5 cursor-row-resize hover:bg-violet-400/40 active:bg-violet-400/60 transition-colors rounded-b-xl"
+      />
+
       <button
         type="button"
         onClick={onRefresh}
         disabled={loading || opening}
-        className="self-start px-2.5 py-1.5 text-[11px] text-zinc-300 bg-zinc-800 hover:bg-zinc-700 disabled:opacity-50 disabled:pointer-events-none rounded-lg transition-colors"
+        className="self-start shrink-0 px-2.5 py-1.5 text-[11px] text-zinc-300 bg-zinc-800 hover:bg-zinc-700 disabled:opacity-50 disabled:pointer-events-none rounded-lg transition-colors"
       >
         Refresh assets
       </button>
 
-      <div className="flex items-end gap-2">
+      <div className="flex items-end gap-2 shrink-0">
         <div className="flex min-w-0 flex-1 flex-col gap-1.5">
           <label htmlFor="asset-library-search" className="text-[11px] text-zinc-300">Search workspace assets</label>
           <input
@@ -586,7 +604,7 @@ function AssetLibraryPopover({
             value={searchQuery}
             onChange={(event) => onSearchQueryChange(event.target.value)}
             placeholder="Search by name, path, scope, or capability"
-            className="bg-zinc-800 border border-zinc-700 rounded-lg px-2.5 py-1.5 text-xs text-zinc-200 w-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400"
+            className="appearance-none bg-zinc-800 border border-zinc-700 rounded-lg px-2.5 py-1.5 text-xs text-zinc-200 w-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400"
           />
         </div>
         <div className="flex w-24 shrink-0 flex-col gap-1.5">
@@ -605,15 +623,15 @@ function AssetLibraryPopover({
       </div>
 
       {loading ? (
-        <p role="status" className="text-xs text-zinc-400">Loading workspace assets…</p>
+        <p role="status" className="flex-1 min-h-0 flex items-center justify-center text-xs text-zinc-400">Loading workspace assets…</p>
       ) : scopeGroups.length === 0 && !normalizedSearchQuery ? (
-        <p role="status" className="text-xs text-zinc-500">No workspace assets are indexed yet.</p>
+        <p role="status" className="flex-1 min-h-0 flex items-center justify-center text-xs text-zinc-500">No workspace assets are indexed yet.</p>
       ) : scopeGroups.length === 0 ? (
-        <p role="status" className="text-xs text-zinc-500">{`No workspace assets match “${normalizedSearchQuery}”.`}</p>
+        <p role="status" className="flex-1 min-h-0 flex items-center justify-center text-center text-xs text-zinc-500">{`No workspace assets match “${normalizedSearchQuery}”.`}</p>
       ) : (
-        <div role="list" aria-label="Workspace library assets" className="max-h-64 overflow-y-auto rounded-lg border border-zinc-800 bg-zinc-950/40">
+        <div role="list" aria-label="Workspace library assets" className="flex-1 min-h-0 overflow-y-auto overflow-x-hidden rounded-lg border border-zinc-800 bg-zinc-950/40">
           {scopeGroups.map((scopeGroup) => {
-            const scopeExpanded = !collapsedSectionKeys.includes(scopeGroup.sectionKey)
+            const scopeExpanded = isAssetLibrarySectionExpanded(collapsedSectionKeys, scopeGroup.sectionKey, hasActiveSearch)
             const scopeRegionId = `asset-library-${scopeGroup.sectionKey.replace(/[^a-z0-9-]+/gi, '-')}`
             return (
               <section key={scopeGroup.sectionKey} role="group" aria-label={`Source scope ${scopeGroup.sourceScopeLabel}`} className="border-b border-zinc-800 last:border-b-0">
@@ -622,7 +640,8 @@ function AssetLibraryPopover({
                   aria-expanded={scopeExpanded}
                   aria-controls={scopeRegionId}
                   onClick={() => onToggleSection(scopeGroup.sectionKey)}
-                  className="flex w-full items-center justify-between gap-2 px-3 py-2 text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400"
+                  disabled={hasActiveSearch}
+                  className="flex w-full items-center justify-between gap-2 px-3 py-2 text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400 disabled:opacity-50 disabled:pointer-events-none"
                 >
                   <span className="text-[10px] font-semibold uppercase tracking-[0.18em] text-zinc-300">{scopeGroup.sourceScopeLabel}</span>
                   <span className="text-[10px] text-zinc-500">{scopeExpanded ? 'Hide' : 'Show'}</span>
@@ -630,7 +649,7 @@ function AssetLibraryPopover({
                 {scopeExpanded && (
                   <div id={scopeRegionId}>
                     {scopeGroup.entryGroups.map((group) => {
-                      const capabilityExpanded = !collapsedSectionKeys.includes(group.sectionKey)
+                      const capabilityExpanded = isAssetLibrarySectionExpanded(collapsedSectionKeys, group.sectionKey, hasActiveSearch)
                       const capabilityRegionId = `asset-library-${group.sectionKey.replace(/[^a-z0-9-]+/gi, '-')}`
                       return (
                         <section key={group.sectionKey} role="group" aria-label={`Capability category ${group.capabilityLabel}`} className="border-t border-zinc-800 first:border-t-0">
@@ -639,7 +658,8 @@ function AssetLibraryPopover({
                             aria-expanded={capabilityExpanded}
                             aria-controls={capabilityRegionId}
                             onClick={() => onToggleSection(group.sectionKey)}
-                            className="flex w-full items-center justify-between gap-2 px-4 py-2 text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400"
+                            disabled={hasActiveSearch}
+                            className="flex w-full items-center justify-between gap-2 px-4 py-2 text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400 disabled:opacity-50 disabled:pointer-events-none"
                           >
                             <span className="text-[10px] font-semibold uppercase tracking-[0.18em] text-zinc-400">{group.capabilityLabel}</span>
                             <span className="text-[10px] text-zinc-500">{capabilityExpanded ? 'Hide' : 'Show'}</span>
@@ -657,20 +677,20 @@ function AssetLibraryPopover({
                                     aria-pressed={selected}
                                     aria-label={`Select library asset ${entry.displayName}`}
                                     onClick={() => onSelectEntry(entry.id)}
-                                    className={`flex w-full items-center gap-3 text-left px-4 py-2 border-t border-zinc-800 first:border-t-0 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400
+                                    className={`flex w-full items-center gap-3 text-left px-4 py-1.5 border-t border-zinc-800 first:border-t-0 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400
                                       ${selected ? 'bg-violet-500/10 text-zinc-100' : 'text-zinc-300 hover:bg-zinc-800/80'}`}
                                   >
                                     {thumbnailDataUrl && (
                                       <img
                                         src={thumbnailDataUrl}
                                         alt=""
-                                        className="h-20 w-20 shrink-0 rounded-lg border border-zinc-800 bg-zinc-950 object-contain"
+                                        className="h-10 w-10 shrink-0 rounded-lg border border-zinc-800 bg-zinc-950 object-contain"
                                       />
                                     )}
                                     <div className="min-w-0 flex-1">
                                       <div className="flex items-center justify-between gap-2">
-                                        <span className="text-xs font-medium">{entry.displayName}</span>
-                                        <span className="text-[10px] uppercase tracking-wider text-zinc-500">{entry.capability ?? entry.state.replace(/-/g, ' ')}</span>
+                                        <span className="truncate text-xs font-medium">{entry.displayName}</span>
+                                        <span className="shrink-0 text-[10px] uppercase tracking-wider text-zinc-500">{entry.capability ?? entry.state.replace(/-/g, ' ')}</span>
                                       </div>
                                       <p className="mt-1 truncate text-[10px] text-zinc-500">{entry.workspacePath}</p>
                                     </div>
@@ -690,7 +710,7 @@ function AssetLibraryPopover({
         </div>
       )}
 
-      <div className="rounded-lg border border-zinc-800 bg-zinc-950/40 px-3 py-2">
+      <div className="shrink-0 rounded-lg border border-zinc-800 bg-zinc-950/40 px-3 py-2">
         <p className="text-[11px] text-zinc-400">{selectedMessage}</p>
         {error && <p role="alert" className="mt-2 text-[11px] text-amber-300">{error}</p>}
       </div>
@@ -700,7 +720,7 @@ function AssetLibraryPopover({
         onClick={onOpenSelected}
         disabled={openDisabled}
         aria-label="Open selected asset"
-        className="px-3 py-2 bg-violet-600 hover:bg-violet-500 disabled:bg-zinc-700 disabled:text-zinc-500 text-white text-xs rounded-lg transition-colors font-medium"
+        className="shrink-0 px-3 py-2 bg-violet-600 hover:bg-violet-500 disabled:bg-zinc-700 disabled:text-zinc-500 text-white text-xs rounded-lg transition-colors font-medium"
       >
         {opening ? 'Opening…' : 'Open selected asset'}
       </button>
@@ -730,9 +750,11 @@ export default function GeneratePage(): JSX.Element {
   const [libraryCollapsedSectionKeys, setLibraryCollapsedSectionKeys] = useState<string[]>(() => getDefaultAssetLibraryCollapsedSectionKeys())
   const [libraryThumbnails, setLibraryThumbnails] = useState<Record<string, string>>({})
   const [libraryPanelWidth, setLibraryPanelWidth] = useState<number>(() => getStoredAssetLibraryPanelWidth())
+  const [libraryPanelHeight, setLibraryPanelHeight] = useState<number>(() => getStoredAssetLibraryPanelHeight())
   const [gizmoMode, setGizmoMode] = useState<'translate' | 'rotate' | 'scale' | null>(null)
   const dragging = useRef(false)
   const libraryPanelDragging = useRef(false)
+  const libraryPanelHeightDragging = useRef(false)
   const [selectedPointLightId, setSelectedPointLightId] = useState<string | null>(null)
   // Populated by Viewer3D — undoes the latest live gizmo transform, if any.
   const gizmoUndoRef = useRef<(() => boolean) | null>(null)
@@ -819,6 +841,11 @@ export default function GeneratePage(): JSX.Element {
     storeAssetLibraryPanelWidth(libraryPanelWidth)
   }, [libraryPanelWidth])
 
+  // Persist the library panel's height so a manual resize survives app restarts.
+  useEffect(() => {
+    storeAssetLibraryPanelHeight(libraryPanelHeight)
+  }, [libraryPanelHeight])
+
   // Persist the generate options panel's width so a manual resize survives app restarts.
   useEffect(() => {
     storePanelWidth(panelWidth)
@@ -1054,6 +1081,23 @@ export default function GeneratePage(): JSX.Element {
     window.addEventListener('mouseup', onMouseUp)
   }, [])
 
+  const onLibraryPanelResizeHeightMouseDown = useCallback((e: React.MouseEvent) => {
+    e.preventDefault()
+    libraryPanelHeightDragging.current = true
+
+    const onMouseMove = (ev: MouseEvent) => {
+      if (!libraryPanelHeightDragging.current) return
+      setLibraryPanelHeight((h) => clampAssetLibraryPanelHeight(h + ev.movementY))
+    }
+    const onMouseUp = () => {
+      libraryPanelHeightDragging.current = false
+      window.removeEventListener('mousemove', onMouseMove)
+      window.removeEventListener('mouseup', onMouseUp)
+    }
+    window.addEventListener('mousemove', onMouseMove)
+    window.addEventListener('mouseup', onMouseUp)
+  }, [])
+
   return (
     <>
       <div className="flex flex-col border-r border-zinc-800 bg-surface-400 overflow-hidden shrink-0" style={{ width: panelWidth }}>
@@ -1183,6 +1227,7 @@ export default function GeneratePage(): JSX.Element {
                 collapsedSectionKeys={libraryCollapsedSectionKeys}
                 thumbnails={libraryThumbnails}
                 panelWidth={libraryPanelWidth}
+                panelHeight={libraryPanelHeight}
                 onSelectEntry={(entryId) => {
                   setLibraryError(null)
                   setLibrarySelectedEntryId(entryId)
@@ -1194,6 +1239,7 @@ export default function GeneratePage(): JSX.Element {
                 onRefresh={() => { void loadLibraryEntries() }}
                 onClose={() => setOpenPanel(null)}
                 onResizeMouseDown={onLibraryPanelResizeMouseDown}
+                onResizeHeightMouseDown={onLibraryPanelResizeHeightMouseDown}
               />
             )}
           </div>
diff --git a/src/areas/generate/assetLibraryUi.test.ts b/src/areas/generate/assetLibraryUi.test.ts
index 681c292e..e53d9821 100644
--- a/src/areas/generate/assetLibraryUi.test.ts
+++ b/src/areas/generate/assetLibraryUi.test.ts
@@ -3,14 +3,18 @@ import test from 'node:test'
 
 import {
   buildAssetLibraryOpenRequest,
+  clampAssetLibraryPanelHeight,
   clampAssetLibraryPanelWidth,
   createAssetLibraryOpenJob,
   describeAssetLibraryOpenability,
   filterAssetLibraryScopeGroups,
   getDefaultAssetLibraryCollapsedSectionKeys,
+  getStoredAssetLibraryPanelHeight,
   getStoredAssetLibraryPanelWidth,
   isAssetLibraryEntryOpenable,
+  isAssetLibrarySectionExpanded,
   resolveOpenPanelAfterLibrarySelection,
+  storeAssetLibraryPanelHeight,
   storeAssetLibraryPanelWidth,
   toggleAssetLibrarySectionKey,
   type AssetLibrarySortMode,
@@ -135,3 +139,29 @@ test('Library panel width clamps to sane bounds and degrades silently without a
   assert.equal(getStoredAssetLibraryPanelWidth(), 320)
   assert.doesNotThrow(() => storeAssetLibraryPanelWidth(400))
 })
+
+test('Library panel height clamps to sane bounds and degrades silently without a localStorage', () => {
+  assert.equal(clampAssetLibraryPanelHeight(0), 280)
+  assert.equal(clampAssetLibraryPanelHeight(9999), 1000)
+  assert.equal(clampAssetLibraryPanelHeight(500), 500)
+  // node --test has no `localStorage` global — both helpers must fall back rather than throw.
+  assert.equal(getStoredAssetLibraryPanelHeight(), 860)
+  assert.doesNotThrow(() => storeAssetLibraryPanelHeight(500))
+})
+
+test('a live search always shows matched sections, and clearing it falls back to the untouched collapsed-key state', () => {
+  const collapsed = ['scope:workflows', 'capability:workflows:mesh']
+
+  // Nothing typed yet: rendering follows the real collapsed-key list.
+  assert.equal(isAssetLibrarySectionExpanded(collapsed, 'scope:workflows', false), false)
+  assert.equal(isAssetLibrarySectionExpanded(collapsed, 'scope:exports', false), true)
+
+  // A live search forces every visible (already-filtered-to-matches) section open,
+  // regardless of what's actually in collapsedSectionKeys.
+  assert.equal(isAssetLibrarySectionExpanded(collapsed, 'scope:workflows', true), true)
+  assert.equal(isAssetLibrarySectionExpanded(collapsed, 'capability:workflows:mesh', true), true)
+
+  // Clearing the query (hasActiveSearch: false) restores exactly the prior state —
+  // collapsedSectionKeys was never mutated by the search itself.
+  assert.equal(isAssetLibrarySectionExpanded(collapsed, 'scope:workflows', false), false)
+})
diff --git a/src/areas/generate/assetLibraryUi.ts b/src/areas/generate/assetLibraryUi.ts
index 295dd185..47416c4a 100644
--- a/src/areas/generate/assetLibraryUi.ts
+++ b/src/areas/generate/assetLibraryUi.ts
@@ -68,6 +68,21 @@ export function toggleAssetLibrarySectionKey(currentKeys: string[], sectionKey:
     : [...currentKeys, sectionKey]
 }
 
+/**
+ * A section renders expanded either because the user left it expanded, or
+ * because a live search matched into it — search always wins so results are
+ * visible without clicking through "Show" first. Clearing the query falls
+ * straight back through to the untouched `collapsedSectionKeys`, so whatever
+ * was collapsed before searching stays collapsed after.
+ */
+export function isAssetLibrarySectionExpanded(
+  collapsedSectionKeys: string[],
+  sectionKey: string,
+  hasActiveSearch: boolean,
+): boolean {
+  return hasActiveSearch || !collapsedSectionKeys.includes(sectionKey)
+}
+
 export function buildAssetLibraryOpenRequest(entry: ProjectedAssetLibraryEntry): AssetLibraryOpenRequest {
   const target = resolveAssetLibraryOpenTarget(entry)
   return target.kind === 'linked-source'
@@ -197,6 +212,35 @@ export function storeAssetLibraryPanelWidth(width: number): void {
   }
 }
 
+export const ASSET_LIBRARY_PANEL_MIN_HEIGHT = 280
+export const ASSET_LIBRARY_PANEL_MAX_HEIGHT = 1000
+export const ASSET_LIBRARY_PANEL_DEFAULT_HEIGHT = 860
+
+const ASSET_LIBRARY_PANEL_HEIGHT_STORAGE_KEY = 'modly-library-panel-height'
+
+export function clampAssetLibraryPanelHeight(height: number): number {
+  return Math.min(ASSET_LIBRARY_PANEL_MAX_HEIGHT, Math.max(ASSET_LIBRARY_PANEL_MIN_HEIGHT, height))
+}
+
+/** Reads the user's saved Library panel height, falling back to the default when unset, invalid, or unreadable. */
+export function getStoredAssetLibraryPanelHeight(): number {
+  try {
+    const raw = Number(localStorage.getItem(ASSET_LIBRARY_PANEL_HEIGHT_STORAGE_KEY))
+    return Number.isFinite(raw) && raw > 0 ? clampAssetLibraryPanelHeight(raw) : ASSET_LIBRARY_PANEL_DEFAULT_HEIGHT
+  } catch {
+    return ASSET_LIBRARY_PANEL_DEFAULT_HEIGHT
+  }
+}
+
+/** Persists the Library panel height so it survives app restarts. */
+export function storeAssetLibraryPanelHeight(height: number): void {
+  try {
+    localStorage.setItem(ASSET_LIBRARY_PANEL_HEIGHT_STORAGE_KEY, String(height))
+  } catch {
+    // Ignore quota/private-mode failures — the panel just won't remember its size.
+  }
+}
+
 function sortAssetLibraryEntries(
   entries: ProjectedAssetLibraryEntry[],
   sortMode: AssetLibrarySortMode,

From 6972a21b430db2e81f601b4bdbb3a2aa1a50a7dd Mon Sep 17 00:00:00 2001
From: JayceeB1 <45721154+JayceeB1@users.noreply.github.com>
Date: Fri, 9 Oct 2026 23:35:06 +0200
Subject: [PATCH 07/11] integrate(#248): widen library and add hover motion
 previews

Reconciled preview-type import with current Modly Generate imports.
---
 .../main/artifact-registry-service.test.ts    |  89 +++++++
 electron/main/artifact-registry-service.ts    | 116 ++++++++-
 .../preload/artifact-registry-preload.test.ts |   2 +
 src/areas/generate/GeneratePage.tsx           | 246 ++++++++++++++----
 .../generate/assetLibraryService.test.ts      |  17 ++
 src/areas/generate/assetLibraryUi.test.ts     |  12 +-
 src/areas/generate/assetLibraryUi.ts          |  11 +-
 src/shared/types/assetLibrary.test.ts         |  22 ++
 src/shared/types/assetLibrary.ts              |  16 +-
 9 files changed, 470 insertions(+), 61 deletions(-)

diff --git a/electron/main/artifact-registry-service.test.ts b/electron/main/artifact-registry-service.test.ts
index 3283a813..98078384 100644
--- a/electron/main/artifact-registry-service.test.ts
+++ b/electron/main/artifact-registry-service.test.ts
@@ -232,6 +232,95 @@ test('reads a sibling .thumb.png for GLB assets and stays silent when one is mis
   assert.equal(unsafe.success, false)
 }))
 
+test('attaches preview clip metadata to the thumbnail response when a manifest exists', () => withWorkspace(async (workspaceDir) => {
+  await mkdir(path.join(workspaceDir, 'Exports/props'), { recursive: true })
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.glb'), 'glb')
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.thumb.png'), 'fake-png-bytes')
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.preview-idle.webp'), 'fake-idle-webp')
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.preview-walk.webp'), 'fake-walk-webp')
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.previews.json'), JSON.stringify([
+    { clip: 'idle', file: 'hero.preview-idle.webp', duration: 1.5 },
+    { clip: 'walk', file: 'hero.preview-walk.webp', duration: 0.8 },
+  ]))
+
+  const withThumb = await readWorkspaceAssetLibraryThumbnail({ workspaceDir, workspacePath: 'Exports/props/hero.glb' })
+  assert.equal(withThumb.success, true)
+  assert.deepEqual(withThumb.success && withThumb.previews, [
+    { clip: 'idle', duration: 1.5 },
+    { clip: 'walk', duration: 0.8 },
+  ])
+}))
+
+test('fetches a specific preview clip WebP by name over the same thumbnail request', () => withWorkspace(async (workspaceDir) => {
+  await mkdir(path.join(workspaceDir, 'Exports/props'), { recursive: true })
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.glb'), 'glb')
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.preview-walk.webp'), 'fake-walk-webp')
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.previews.json'), JSON.stringify([
+    { clip: 'walk', file: 'hero.preview-walk.webp', duration: 0.8 },
+  ]))
+
+  const clip = await readWorkspaceAssetLibraryThumbnail({ workspaceDir, workspacePath: 'Exports/props/hero.glb', previewClip: 'walk' })
+  assert.equal(clip.success, true)
+  assert.equal(clip.success && clip.dataUrl, `data:image/webp;base64,${Buffer.from('fake-walk-webp').toString('base64')}`)
+
+  const unknownClip = await readWorkspaceAssetLibraryThumbnail({ workspaceDir, workspacePath: 'Exports/props/hero.glb', previewClip: 'sprint' })
+  assert.equal(unknownClip.success, false)
+}))
+
+test('thumbnail response carries no previews field when no manifest exists, and stays silent on a malformed one', () => withWorkspace(async (workspaceDir) => {
+  await mkdir(path.join(workspaceDir, 'Exports/props'), { recursive: true })
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.glb'), 'glb')
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.thumb.png'), 'fake-png-bytes')
+  await writeFile(path.join(workspaceDir, 'Exports/props/broken.glb'), 'glb')
+  await writeFile(path.join(workspaceDir, 'Exports/props/broken.thumb.png'), 'fake-png-bytes')
+  await writeFile(path.join(workspaceDir, 'Exports/props/broken.previews.json'), 'not valid json{')
+
+  const noManifest = await readWorkspaceAssetLibraryThumbnail({ workspaceDir, workspacePath: 'Exports/props/hero.glb' })
+  assert.equal(noManifest.success, true)
+  assert.equal(noManifest.success && noManifest.previews, undefined)
+
+  const malformedManifest = await readWorkspaceAssetLibraryThumbnail({ workspaceDir, workspacePath: 'Exports/props/broken.glb' })
+  assert.equal(malformedManifest.success, true)
+  assert.equal(malformedManifest.success && malformedManifest.previews, undefined)
+}))
+
+test('rejects a preview manifest entry that tries to escape the asset directory via its file field', () => withWorkspace(async (workspaceDir) => {
+  await mkdir(path.join(workspaceDir, 'Exports/props'), { recursive: true })
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.glb'), 'glb')
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.thumb.png'), 'fake-png-bytes')
+  await writeFile(path.join(workspaceDir, 'secret.webp'), 'top-secret-bytes')
+  await writeFile(path.join(workspaceDir, 'Exports/props/hero.previews.json'), JSON.stringify([
+    { clip: 'escape-relative', file: '../../secret.webp', duration: 1 },
+    { clip: 'escape-absolute', file: '/etc/passwd', duration: 1 },
+    { clip: 'wrong-extension', file: 'hero.glb', duration: 1 },
+  ]))
+
+  // The manifest lists the clip in its metadata (harmless — it's just a name),
+  // but every attempt to actually fetch the referenced file must fail closed.
+  const listed = await readWorkspaceAssetLibraryThumbnail({ workspaceDir, workspacePath: 'Exports/props/hero.glb' })
+  assert.equal(listed.success, true)
+  assert.equal(listed.success && listed.previews?.length, 3)
+
+  const relative = await readWorkspaceAssetLibraryThumbnail({ workspaceDir, workspacePath: 'Exports/props/hero.glb', previewClip: 'escape-relative' })
+  assert.equal(relative.success, false)
+  const absolute = await readWorkspaceAssetLibraryThumbnail({ workspaceDir, workspacePath: 'Exports/props/hero.glb', previewClip: 'escape-absolute' })
+  assert.equal(absolute.success, false)
+  const wrongExtension = await readWorkspaceAssetLibraryThumbnail({ workspaceDir, workspacePath: 'Exports/props/hero.glb', previewClip: 'wrong-extension' })
+  assert.equal(wrongExtension.success, false)
+}))
+
+test('IPC thumbnail handler forwards previewClip from payload', async () => {
+  const handlers = new Map<string, (event: unknown, payload: unknown) => Promise<unknown>>()
+  registerWorkspaceAssetLibraryIpcHandlers({
+    ipcMain: { handle: (channel, handler) => handlers.set(channel, handler) },
+    getWorkspaceDir: () => '/tmp/modly-workspace',
+  })
+
+  const result = await handlers.get('workspace:library:thumbnail')?.({}, { workspacePath: 'Exports/hero.glb', previewClip: 'walk' })
+  // No such workspace/file in this test, so it must fail closed rather than throw.
+  assert.equal((result as { success: boolean }).success, false)
+})
+
 test('IPC read and open handlers forward sourceWorkspacePath without trusting malformed payloads', async () => {
   const handlers = new Map<string, (event: unknown, payload: unknown) => Promise<unknown>>()
   registerWorkspaceAssetLibraryIpcHandlers({
diff --git a/electron/main/artifact-registry-service.ts b/electron/main/artifact-registry-service.ts
index c6d3232f..d5b3b7e2 100644
--- a/electron/main/artifact-registry-service.ts
+++ b/electron/main/artifact-registry-service.ts
@@ -8,6 +8,7 @@ import type {
   AssetLibraryError,
   AssetLibraryListResult,
   AssetLibraryOpenResult,
+  AssetLibraryPreviewClip,
   AssetLibraryPreviewKind,
   AssetLibraryPreviewPayload,
   AssetLibraryReadResult,
@@ -54,6 +55,7 @@ export interface WorkspaceAssetLibraryReadRequest extends WorkspaceAssetLibraryR
 
 export interface WorkspaceAssetLibraryThumbnailRequest extends WorkspaceAssetLibraryRequest {
   workspacePath: string
+  previewClip?: string
 }
 
 interface AssetLibraryMetadata {
@@ -348,27 +350,131 @@ export async function openWorkspaceAssetLibraryEntry(request: WorkspaceAssetLibr
   return { success: true, entry: read.entry }
 }
 
+function previewManifestAbsolutePathFor(absolutePath: string): string {
+  return absolutePath.replace(/\.(glb|gltf)$/i, '.previews.json')
+}
+
+interface AssetLibraryPreviewManifestEntry {
+  clip: string
+  file: string
+  duration: number
+}
+
+function parsePreviewManifestList(raw: unknown): unknown[] {
+  if (Array.isArray(raw)) return raw
+  if (typeof raw === 'object' && raw !== null) {
+    const container = raw as Record<string, unknown>
+    if (Array.isArray(container.previews)) return container.previews
+    if (Array.isArray(container.clips)) return container.clips
+  }
+  return []
+}
+
+function parsePreviewManifestEntry(raw: unknown): AssetLibraryPreviewManifestEntry | null {
+  if (typeof raw !== 'object' || raw === null) return null
+  const candidate = raw as Record<string, unknown>
+  const clip = stringField(candidate.clip)
+  const file = stringField(candidate.file)
+  const duration = typeof candidate.duration === 'number' && Number.isFinite(candidate.duration) ? candidate.duration : undefined
+  if (!clip || !file || duration === undefined) return null
+  return { clip, file, duration }
+}
+
+// The preview manifest and its clips are generated by a separate pipeline (not
+// thumbs.py) and may not exist yet, or may be malformed mid-write — both are
+// normal, silent conditions handled the same way a missing thumbnail is.
+async function readPreviewManifestEntries(absolutePath: string): Promise<AssetLibraryPreviewManifestEntry[]> {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(await readFile(previewManifestAbsolutePathFor(absolutePath), 'utf8'))
+  } catch {
+    return []
+  }
+  return parsePreviewManifestList(parsed)
+    .map(parsePreviewManifestEntry)
+    .filter((entry): entry is AssetLibraryPreviewManifestEntry => entry !== null)
+}
+
+async function readAssetLibraryPreviewClips(absolutePath: string): Promise<AssetLibraryPreviewClip[]> {
+  const entries = await readPreviewManifestEntries(absolutePath)
+  return entries.map(({ clip, duration }) => ({ clip, duration }))
+}
+
+/**
+ * Resolves a manifest-listed clip name to a safe absolute WebP path. The
+ * manifest's `file` is trusted only as a filename — any directory component is
+ * discarded via `basename` — and the reconstructed sibling workspace path is
+ * re-validated through the same `normalizeWorkspaceAssetPath` guard every
+ * other workspace library read uses, so a stale or malformed manifest can
+ * never point outside the asset's own directory.
+ */
+async function resolvePreviewClipAbsolutePath(
+  workspaceDir: string,
+  workspacePath: string,
+  absolutePath: string,
+  previewClip: string,
+): Promise<string | null> {
+  const entries = await readPreviewManifestEntries(absolutePath)
+  const match = entries.find((entry) => entry.clip === previewClip)
+  if (!match) return null
+  const fileName = basename(match.file)
+  if (extensionOf(fileName) !== 'webp') return null
+  const siblingWorkspacePath = [...workspacePath.split('/').slice(0, -1), fileName].join('/')
+  let normalized: NormalizedWorkspaceAssetPath
+  try {
+    normalized = normalizeWorkspaceAssetPath(workspaceDir, siblingWorkspacePath)
+  } catch {
+    return null
+  }
+  try {
+    await stat(normalized.absolutePath)
+  } catch {
+    return null
+  }
+  return normalized.absolutePath
+}
+
 // Thumbnails are pre-rendered beside their source mesh (see thumbs.py): a
 // `<name>.glb` asset may have a sibling `<name>.thumb.png`. Missing files are
 // a normal, silent condition, never surfaced as an AssetLibraryError.
+//
+// The same request also serves looping preview clips generated by a separate
+// pipeline as `<name>.preview-<clip>.webp`, listed in a sibling
+// `<name>.previews.json` manifest. Passing `previewClip` fetches that clip's
+// WebP instead of the static thumbnail; omitting it fetches the static
+// thumbnail as before and, when a manifest exists, attaches the clip list so
+// the UI can offer hover-to-animate without a second round trip to discover
+// it. No manifest yet (the common case until the preview pipeline lands) is
+// indistinguishable from today's behavior.
 export async function readWorkspaceAssetLibraryThumbnail(request: WorkspaceAssetLibraryThumbnailRequest): Promise<AssetLibraryThumbnailResult> {
   try {
     const normalized = normalizeWorkspaceAssetPath(request.workspaceDir, request.workspacePath)
     if (!isGlbOrGltf(normalized.workspacePath)) return { success: false }
+
+    if (request.previewClip) {
+      const clipAbsolutePath = await resolvePreviewClipAbsolutePath(request.workspaceDir, normalized.workspacePath, normalized.absolutePath, request.previewClip)
+      if (!clipAbsolutePath) return { success: false }
+      const buffer = await readFile(clipAbsolutePath)
+      return { success: true, dataUrl: `data:image/webp;base64,${buffer.toString('base64')}` }
+    }
+
     const thumbnailAbsolutePath = normalized.absolutePath.replace(/\.(glb|gltf)$/i, '.thumb.png')
     const buffer = await readFile(thumbnailAbsolutePath)
-    return { success: true, dataUrl: `data:image/png;base64,${buffer.toString('base64')}` }
+    const dataUrl = `data:image/png;base64,${buffer.toString('base64')}`
+    const previews = await readAssetLibraryPreviewClips(normalized.absolutePath)
+    return previews.length > 0 ? { success: true, dataUrl, previews } : { success: true, dataUrl }
   } catch {
     return { success: false }
   }
 }
 
-function readPayloadRequest(payload: unknown): { workspacePath?: string, sourceWorkspacePath?: string } {
+function readPayloadRequest(payload: unknown): { workspacePath?: string, sourceWorkspacePath?: string, previewClip?: string } {
   if (typeof payload !== 'object' || payload === null) return {}
-  const values = payload as { workspacePath?: unknown, sourceWorkspacePath?: unknown }
+  const values = payload as { workspacePath?: unknown, sourceWorkspacePath?: unknown, previewClip?: unknown }
   return {
     workspacePath: typeof values.workspacePath === 'string' ? values.workspacePath : undefined,
     sourceWorkspacePath: typeof values.sourceWorkspacePath === 'string' ? values.sourceWorkspacePath : undefined,
+    previewClip: typeof values.previewClip === 'string' ? values.previewClip : undefined,
   }
 }
 
@@ -385,8 +491,8 @@ export function registerWorkspaceAssetLibraryIpcHandlers(deps: WorkspaceAssetLib
     return openWorkspaceAssetLibraryEntry({ workspaceDir: deps.getWorkspaceDir(), workspacePath, sourceWorkspacePath })
   })
   deps.ipcMain.handle('workspace:library:thumbnail', async (_event, payload) => {
-    const { workspacePath } = readPayloadRequest(payload)
+    const { workspacePath, previewClip } = readPayloadRequest(payload)
     if (!workspacePath) return { success: false }
-    return readWorkspaceAssetLibraryThumbnail({ workspaceDir: deps.getWorkspaceDir(), workspacePath })
+    return readWorkspaceAssetLibraryThumbnail({ workspaceDir: deps.getWorkspaceDir(), workspacePath, previewClip })
   })
 }
diff --git a/electron/preload/artifact-registry-preload.test.ts b/electron/preload/artifact-registry-preload.test.ts
index e4a9fc76..85661914 100644
--- a/electron/preload/artifact-registry-preload.test.ts
+++ b/electron/preload/artifact-registry-preload.test.ts
@@ -25,6 +25,7 @@ test('preload exposes scoped workspace library list/read/open methods', async ()
     sourceWorkspacePath: 'Workflows/checkpoints/hero.glb',
   })
   await api.workspace.library.thumbnail({ workspacePath: 'Exports/hero.glb' })
+  await api.workspace.library.thumbnail({ workspacePath: 'Exports/hero.glb', previewClip: 'walk' })
 
   assert.deepEqual(calls, [
     { channel: 'workspace:library:list', payload: undefined },
@@ -43,6 +44,7 @@ test('preload exposes scoped workspace library list/read/open methods', async ()
       },
     },
     { channel: 'workspace:library:thumbnail', payload: { workspacePath: 'Exports/hero.glb' } },
+    { channel: 'workspace:library:thumbnail', payload: { workspacePath: 'Exports/hero.glb', previewClip: 'walk' } },
   ])
 })
 
diff --git a/src/areas/generate/GeneratePage.tsx b/src/areas/generate/GeneratePage.tsx
index cd46aa46..447a5a08 100644
--- a/src/areas/generate/GeneratePage.tsx
+++ b/src/areas/generate/GeneratePage.tsx
@@ -10,6 +10,7 @@ import WorkflowPanel from './components/WorkflowPanel'
 import { getDefaultAssetLibraryService } from './assetLibraryService'
 import { buildOrcaSlicerDeepLink, canOpenInOrcaSlicer } from './orcaSlicerLink'
 import { resolveAssetLibraryOpenTarget, type ProjectedAssetLibraryEntry } from './assetLibraryProjection'
+import type { AssetLibraryPreviewClip } from '../../shared/types/assetLibrary'
 import {
   ASSET_LIBRARY_SORT_OPTIONS,
   buildAssetLibraryOpenRequest,
@@ -489,6 +490,10 @@ function AssetLibraryToggleButton({
   )
 }
 
+// A stable empty-array reference for entries with no preview manifest yet, so
+// rows don't see a fresh `[]` identity on every parent re-render.
+const EMPTY_PREVIEW_CLIPS: AssetLibraryPreviewClip[] = []
+
 function AssetLibraryPopover({
   entries,
   selectedEntryId,
@@ -499,13 +504,15 @@ function AssetLibraryPopover({
   sortMode,
   collapsedSectionKeys,
   thumbnails,
+  previews,
   panelWidth,
   panelHeight,
-  onSelectEntry,
+  onActivateEntry,
   onSearchQueryChange,
   onSortModeChange,
   onToggleSection,
   onOpenSelected,
+  onFetchPreviewFrame,
   onRefresh,
   onClose,
   onResizeMouseDown,
@@ -521,13 +528,17 @@ function AssetLibraryPopover({
   collapsedSectionKeys: string[]
   /** Data URLs keyed by workspacePath, populated lazily as thumbnails load. */
   thumbnails: Record<string, string>
+  /** Preview clip metadata keyed by workspacePath; empty until a preview manifest exists for that asset. */
+  previews: Record<string, AssetLibraryPreviewClip[]>
   panelWidth: number
   panelHeight: number
-  onSelectEntry: (entryId: string) => void
+  /** A row click both selects and, when the entry is openable, opens it immediately — no second confirming click. */
+  onActivateEntry: (entryId: string) => void
   onSearchQueryChange: (value: string) => void
   onSortModeChange: (value: AssetLibrarySortMode) => void
   onToggleSection: (sectionKey: string) => void
   onOpenSelected: () => void
+  onFetchPreviewFrame: (workspacePath: string, clip: string) => Promise<string | null>
   onRefresh: () => void
   onClose: () => void
   onResizeMouseDown: (event: React.MouseEvent) => void
@@ -666,37 +677,18 @@ function AssetLibraryPopover({
                           </button>
                           {capabilityExpanded && (
                             <div id={capabilityRegionId}>
-                              {group.entries.map((entry) => {
-                                const selected = entry.id === selectedEntryId
-                                const thumbnailDataUrl = thumbnails[entry.workspacePath]
-                                return (
-                                  <button
-                                    key={entry.id}
-                                    type="button"
-                                    role="listitem"
-                                    aria-pressed={selected}
-                                    aria-label={`Select library asset ${entry.displayName}`}
-                                    onClick={() => onSelectEntry(entry.id)}
-                                    className={`flex w-full items-center gap-3 text-left px-4 py-1.5 border-t border-zinc-800 first:border-t-0 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400
-                                      ${selected ? 'bg-violet-500/10 text-zinc-100' : 'text-zinc-300 hover:bg-zinc-800/80'}`}
-                                  >
-                                    {thumbnailDataUrl && (
-                                      <img
-                                        src={thumbnailDataUrl}
-                                        alt=""
-                                        className="h-10 w-10 shrink-0 rounded-lg border border-zinc-800 bg-zinc-950 object-contain"
-                                      />
-                                    )}
-                                    <div className="min-w-0 flex-1">
-                                      <div className="flex items-center justify-between gap-2">
-                                        <span className="truncate text-xs font-medium">{entry.displayName}</span>
-                                        <span className="shrink-0 text-[10px] uppercase tracking-wider text-zinc-500">{entry.capability ?? entry.state.replace(/-/g, ' ')}</span>
-                                      </div>
-                                      <p className="mt-1 truncate text-[10px] text-zinc-500">{entry.workspacePath}</p>
-                                    </div>
-                                  </button>
-                                )
-                              })}
+                              {group.entries.map((entry) => (
+                                <AssetLibraryEntryRow
+                                  key={entry.id}
+                                  entry={entry}
+                                  selected={entry.id === selectedEntryId}
+                                  disabled={opening}
+                                  thumbnailDataUrl={thumbnails[entry.workspacePath]}
+                                  previewClips={previews[entry.workspacePath] ?? EMPTY_PREVIEW_CLIPS}
+                                  onActivate={() => onActivateEntry(entry.id)}
+                                  onFetchPreviewFrame={onFetchPreviewFrame}
+                                />
+                              ))}
                             </div>
                           )}
                         </section>
@@ -728,6 +720,122 @@ function AssetLibraryPopover({
   )
 }
 
+/**
+ * One Library row. A click both selects and (when openable) opens the asset —
+ * the "Open selected asset" button stays as a secondary affordance, not the
+ * only path. Hovering swaps the static thumbnail for a looping preview clip,
+ * lazily fetched over the same thumbnail IPC call, when one exists; with no
+ * preview manifest yet, `previewClips` is empty and the row behaves exactly
+ * as it did before — no extra fetches, no hover swap, no cycle control.
+ */
+function AssetLibraryEntryRow({
+  entry,
+  selected,
+  disabled,
+  thumbnailDataUrl,
+  previewClips,
+  onActivate,
+  onFetchPreviewFrame,
+}: {
+  entry: ProjectedAssetLibraryEntry
+  selected: boolean
+  disabled: boolean
+  thumbnailDataUrl: string | undefined
+  previewClips: AssetLibraryPreviewClip[]
+  onActivate: () => void
+  onFetchPreviewFrame: (workspacePath: string, clip: string) => Promise<string | null>
+}) {
+  const [hovered, setHovered] = useState(false)
+  const [clipIndex, setClipIndex] = useState(0)
+  const [previewFrames, setPreviewFrames] = useState<Record<string, string>>({})
+  const mountedRef = useRef(true)
+  useEffect(() => () => { mountedRef.current = false }, [])
+
+  const activeClip = previewClips.length > 0 ? previewClips[clipIndex % previewClips.length] : undefined
+  const activeFrameUrl = activeClip ? previewFrames[activeClip.clip] : undefined
+
+  // Lazy, hover-triggered, and cached per clip for this row's lifetime — a
+  // second hover (or cycling back to a clip already seen) never re-fetches.
+  useEffect(() => {
+    if (!hovered || !activeClip || previewFrames[activeClip.clip]) return
+    void onFetchPreviewFrame(entry.workspacePath, activeClip.clip).then((dataUrl) => {
+      if (mountedRef.current && dataUrl) {
+        setPreviewFrames((current) => ({ ...current, [activeClip.clip]: dataUrl }))
+      }
+    })
+  }, [hovered, activeClip, entry.workspacePath, previewFrames, onFetchPreviewFrame])
+
+  function cycleClip(step: 1 | -1, event: React.MouseEvent | React.KeyboardEvent) {
+    event.preventDefault()
+    event.stopPropagation()
+    setClipIndex((current) => (current + step + previewClips.length) % previewClips.length)
+  }
+
+  function handleCycleKeyDown(step: 1 | -1, event: React.KeyboardEvent) {
+    if (event.key !== 'Enter' && event.key !== ' ') return
+    cycleClip(step, event)
+  }
+
+  const displayedThumbnailUrl = hovered && activeFrameUrl ? activeFrameUrl : thumbnailDataUrl
+
+  return (
+    <button
+      type="button"
+      role="listitem"
+      aria-pressed={selected}
+      aria-label={`Open library asset ${entry.displayName}`}
+      onClick={onActivate}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+      disabled={disabled}
+      className={`flex w-full items-center gap-3 text-left px-4 py-1.5 border-t border-zinc-800 first:border-t-0 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400 disabled:opacity-50 disabled:pointer-events-none
+        ${selected ? 'bg-violet-500/10 text-zinc-100' : 'text-zinc-300 hover:bg-zinc-800/80'}`}
+    >
+      {thumbnailDataUrl && (
+        <div className="relative h-10 w-10 shrink-0">
+          <img
+            src={displayedThumbnailUrl}
+            alt=""
+            className="h-10 w-10 rounded-lg border border-zinc-800 bg-zinc-950 object-contain"
+          />
+          {/* Mini clip selector — only once a hover has fetched more than one clip; never rendered otherwise. */}
+          {hovered && previewClips.length > 1 && (
+            <>
+              <span
+                role="button"
+                tabIndex={0}
+                aria-label={`Show previous preview clip for ${entry.displayName}`}
+                onClick={(event) => cycleClip(-1, event)}
+                onKeyDown={(event) => handleCycleKeyDown(-1, event)}
+                className="absolute inset-y-0 left-0 flex w-3.5 cursor-pointer items-center justify-center rounded-l-lg bg-black/60 text-[10px] leading-none text-zinc-100 hover:bg-black/80 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-violet-400"
+              >
+                ‹
+              </span>
+              <span
+                role="button"
+                tabIndex={0}
+                aria-label={`Show next preview clip for ${entry.displayName}`}
+                onClick={(event) => cycleClip(1, event)}
+                onKeyDown={(event) => handleCycleKeyDown(1, event)}
+                className="absolute inset-y-0 right-0 flex w-3.5 cursor-pointer items-center justify-center rounded-r-lg bg-black/60 text-[10px] leading-none text-zinc-100 hover:bg-black/80 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-violet-400"
+              >
+                ›
+              </span>
+            </>
+          )}
+        </div>
+      )}
+      <div className="min-w-0 flex-1">
+        <div className="flex items-center justify-between gap-2">
+          <span className="truncate text-xs font-medium">{entry.displayName}</span>
+          <span className="shrink-0 text-[10px] uppercase tracking-wider text-zinc-500">{entry.capability ?? entry.state.replace(/-/g, ' ')}</span>
+        </div>
+        <p className="mt-1 truncate text-[10px] text-zinc-500">{entry.workspacePath}</p>
+      </div>
+    </button>
+  )
+}
+
 // ---------------------------------------------------------------------------
 // GeneratePage
 // ---------------------------------------------------------------------------
@@ -749,6 +857,7 @@ export default function GeneratePage(): JSX.Element {
   const [librarySortMode, setLibrarySortMode] = useState<AssetLibrarySortMode>('type')
   const [libraryCollapsedSectionKeys, setLibraryCollapsedSectionKeys] = useState<string[]>(() => getDefaultAssetLibraryCollapsedSectionKeys())
   const [libraryThumbnails, setLibraryThumbnails] = useState<Record<string, string>>({})
+  const [libraryPreviews, setLibraryPreviews] = useState<Record<string, AssetLibraryPreviewClip[]>>({})
   const [libraryPanelWidth, setLibraryPanelWidth] = useState<number>(() => getStoredAssetLibraryPanelWidth())
   const [libraryPanelHeight, setLibraryPanelHeight] = useState<number>(() => getStoredAssetLibraryPanelHeight())
   const [gizmoMode, setGizmoMode] = useState<'translate' | 'rotate' | 'scale' | null>(null)
@@ -969,30 +1078,59 @@ export default function GeneratePage(): JSX.Element {
 
   // Thumbnails are best-effort: only .glb/.gltf entries can have a rendered
   // .thumb.png, and a missing one is silently skipped rather than surfaced.
+  // The same request also carries preview clip metadata when a preview
+  // manifest exists for that asset — most entries won't have one yet, and
+  // those are simply absent from libraryPreviews.
   async function loadLibraryThumbnails(entries: ProjectedAssetLibraryEntry[]) {
+    type ThumbnailFetchResult = { workspacePath: string, dataUrl: string | null, previews: AssetLibraryPreviewClip[] }
     const candidates = entries.filter((entry) => entry.previewKind === '3d-model')
-    const results = await Promise.all(candidates.map(async (entry) => {
+    const results: ThumbnailFetchResult[] = await Promise.all(candidates.map(async (entry) => {
       const result = await assetLibraryService.thumbnail({ workspacePath: entry.workspacePath })
-      return [entry.workspacePath, result.success ? result.dataUrl : null] as const
+      return {
+        workspacePath: entry.workspacePath,
+        dataUrl: result.success ? result.dataUrl : null,
+        previews: result.success ? result.previews ?? [] : [],
+      }
     }))
-    setLibraryThumbnails(Object.fromEntries(results.filter((pair): pair is [string, string] => pair[1] !== null)))
+    setLibraryThumbnails(Object.fromEntries(
+      results
+        .filter((result): result is ThumbnailFetchResult & { dataUrl: string } => result.dataUrl !== null)
+        .map((result) => [result.workspacePath, result.dataUrl]),
+    ))
+    setLibraryPreviews(Object.fromEntries(
+      results.filter((result) => result.previews.length > 0).map((result) => [result.workspacePath, result.previews]),
+    ))
   }
 
-  async function handleOpenSelectedLibraryEntry() {
-    const selectedEntry = libraryEntries.find((entry) => entry.id === librarySelectedEntryId) ?? null
-    if (!selectedEntry) {
+  // Fetches one looping preview clip's WebP, lazily, over the same thumbnail
+  // IPC call the static thumbnails use. A miss (clip removed, file unreadable)
+  // resolves to null rather than throwing, so a row can just keep its static
+  // thumbnail.
+  const fetchLibraryPreviewFrame = useCallback(async (workspacePath: string, clip: string): Promise<string | null> => {
+    try {
+      const result = await assetLibraryService.thumbnail({ workspacePath, previewClip: clip })
+      return result.success ? result.dataUrl : null
+    } catch {
+      return null
+    }
+  }, [assetLibraryService])
+
+  // Shared by both the "Open selected asset" button and a direct row click —
+  // a row activation selects first, then opens through this same path.
+  async function openLibraryEntry(entry: ProjectedAssetLibraryEntry | null) {
+    if (!entry) {
       setLibraryError('Select an asset before opening it in Generate.')
       return
     }
-    if (!isAssetLibraryEntryOpenable(selectedEntry)) {
-      setLibraryError(describeAssetLibraryOpenability(selectedEntry))
+    if (!isAssetLibraryEntryOpenable(entry)) {
+      setLibraryError(describeAssetLibraryOpenability(entry))
       return
     }
 
     setLibraryOpening(true)
     setLibraryError(null)
     try {
-      const result = await assetLibraryService.open(buildAssetLibraryOpenRequest(selectedEntry))
+      const result = await assetLibraryService.open(buildAssetLibraryOpenRequest(entry))
       if (!result.success) {
         setLibraryError(result.error.message)
         return
@@ -1003,7 +1141,7 @@ export default function GeneratePage(): JSX.Element {
         setLibraryError(describeAssetLibraryOpenability(result.entry))
         return
       }
-      setLibraryEntries((currentEntries) => currentEntries.map((entry) => entry.id === result.entry.id ? result.entry : entry))
+      setLibraryEntries((currentEntries) => currentEntries.map((candidate) => candidate.id === result.entry.id ? result.entry : candidate))
       setLibrarySelectedEntryId(result.entry.id)
       setCurrentJob(selection.job)
       pushMeshUrl(selection.historyUrl)
@@ -1015,6 +1153,21 @@ export default function GeneratePage(): JSX.Element {
     }
   }
 
+  async function handleOpenSelectedLibraryEntry() {
+    const selectedEntry = libraryEntries.find((entry) => entry.id === librarySelectedEntryId) ?? null
+    await openLibraryEntry(selectedEntry)
+  }
+
+  // A single click on a row both selects and opens it — no second click on
+  // "Open selected asset" required. Non-openable entries still get selected,
+  // surfacing the same "why not" message they always have.
+  async function handleActivateLibraryEntry(entryId: string) {
+    setLibraryError(null)
+    setLibrarySelectedEntryId(entryId)
+    const entry = libraryEntries.find((candidate) => candidate.id === entryId) ?? null
+    await openLibraryEntry(entry)
+  }
+
   async function handleSmooth(iterations: number) {
     if (!currentJob?.outputUrl) return
     setSmoothing(true)
@@ -1226,16 +1379,15 @@ export default function GeneratePage(): JSX.Element {
                 sortMode={librarySortMode}
                 collapsedSectionKeys={libraryCollapsedSectionKeys}
                 thumbnails={libraryThumbnails}
+                previews={libraryPreviews}
                 panelWidth={libraryPanelWidth}
                 panelHeight={libraryPanelHeight}
-                onSelectEntry={(entryId) => {
-                  setLibraryError(null)
-                  setLibrarySelectedEntryId(entryId)
-                }}
+                onActivateEntry={(entryId) => { void handleActivateLibraryEntry(entryId) }}
                 onSearchQueryChange={setLibrarySearchQuery}
                 onSortModeChange={setLibrarySortMode}
                 onToggleSection={(sectionKey) => setLibraryCollapsedSectionKeys((current) => toggleAssetLibrarySectionKey(current, sectionKey))}
                 onOpenSelected={() => { void handleOpenSelectedLibraryEntry() }}
+                onFetchPreviewFrame={fetchLibraryPreviewFrame}
                 onRefresh={() => { void loadLibraryEntries() }}
                 onClose={() => setOpenPanel(null)}
                 onResizeMouseDown={onLibraryPanelResizeMouseDown}
diff --git a/src/areas/generate/assetLibraryService.test.ts b/src/areas/generate/assetLibraryService.test.ts
index 0ac08bce..6a2bda1c 100644
--- a/src/areas/generate/assetLibraryService.test.ts
+++ b/src/areas/generate/assetLibraryService.test.ts
@@ -77,3 +77,20 @@ test('renderer service validates thumbnail requests before IPC and never surface
   assert.deepEqual(safe, { success: true, dataUrl: 'data:image/png;base64,ok' })
   assert.equal(invoked, true)
 })
+
+test('renderer service forwards previewClip through to the thumbnail IPC call unchanged', async () => {
+  let receivedRequest: unknown = null
+  const service = createAssetLibraryService({
+    list: async () => ({ success: true, entries: [] }),
+    read: async () => ({ success: false, error: { code: 'read-failed', message: 'should not run' } }),
+    open: async () => ({ success: false, error: { code: 'read-failed', message: 'should not run' } }),
+    thumbnail: async (request) => {
+      receivedRequest = request
+      return { success: true, dataUrl: 'data:image/webp;base64,ok', previews: [{ clip: 'walk', duration: 0.8 }] }
+    },
+  })
+
+  const result = await service.thumbnail({ workspacePath: 'Exports/hero.glb', previewClip: 'walk' })
+  assert.deepEqual(receivedRequest, { workspacePath: 'Exports/hero.glb', previewClip: 'walk' })
+  assert.deepEqual(result, { success: true, dataUrl: 'data:image/webp;base64,ok', previews: [{ clip: 'walk', duration: 0.8 }] })
+})
diff --git a/src/areas/generate/assetLibraryUi.test.ts b/src/areas/generate/assetLibraryUi.test.ts
index e53d9821..70013acc 100644
--- a/src/areas/generate/assetLibraryUi.test.ts
+++ b/src/areas/generate/assetLibraryUi.test.ts
@@ -132,12 +132,14 @@ test('builds linked-source open requests and import jobs for safe sidecars', ()
 })
 
 test('Library panel width clamps to sane bounds and degrades silently without a localStorage', () => {
-  assert.equal(clampAssetLibraryPanelWidth(0), 260)
-  assert.equal(clampAssetLibraryPanelWidth(999), 560)
-  assert.equal(clampAssetLibraryPanelWidth(400), 400)
+  assert.equal(clampAssetLibraryPanelWidth(0), 380)
+  assert.equal(clampAssetLibraryPanelWidth(9999), 960)
+  assert.equal(clampAssetLibraryPanelWidth(700), 700)
+  // A prior session's narrow, dragged-down width must clamp back up to the new floor.
+  assert.equal(clampAssetLibraryPanelWidth(280), 380)
   // node --test has no `localStorage` global — both helpers must fall back rather than throw.
-  assert.equal(getStoredAssetLibraryPanelWidth(), 320)
-  assert.doesNotThrow(() => storeAssetLibraryPanelWidth(400))
+  assert.equal(getStoredAssetLibraryPanelWidth(), 640)
+  assert.doesNotThrow(() => storeAssetLibraryPanelWidth(700))
 })
 
 test('Library panel height clamps to sane bounds and degrades silently without a localStorage', () => {
diff --git a/src/areas/generate/assetLibraryUi.ts b/src/areas/generate/assetLibraryUi.ts
index 47416c4a..03355e78 100644
--- a/src/areas/generate/assetLibraryUi.ts
+++ b/src/areas/generate/assetLibraryUi.ts
@@ -183,9 +183,14 @@ export function resolveOpenPanelAfterLibrarySelection(currentPanel: GenerateOpen
   return currentPanel === 'library' ? 'library' : currentPanel
 }
 
-export const ASSET_LIBRARY_PANEL_MIN_WIDTH = 260
-export const ASSET_LIBRARY_PANEL_MAX_WIDTH = 560
-export const ASSET_LIBRARY_PANEL_DEFAULT_WIDTH = 320
+// Wide enough that a 40px thumbnail, a readable name, its full workspace path,
+// and its type badge all sit on one row without truncating for typical asset
+// names — narrow (~280px) made the panel unusable even at full height. Raising
+// the minimum (not just the default) also repairs the shape for anyone who
+// already dragged a prior session's panel down toward the old, cramped floor.
+export const ASSET_LIBRARY_PANEL_MIN_WIDTH = 380
+export const ASSET_LIBRARY_PANEL_MAX_WIDTH = 960
+export const ASSET_LIBRARY_PANEL_DEFAULT_WIDTH = 640
 
 const ASSET_LIBRARY_PANEL_WIDTH_STORAGE_KEY = 'modly-library-panel-width'
 
diff --git a/src/shared/types/assetLibrary.test.ts b/src/shared/types/assetLibrary.test.ts
index 8a6e7494..d9d836f8 100644
--- a/src/shared/types/assetLibrary.test.ts
+++ b/src/shared/types/assetLibrary.test.ts
@@ -14,6 +14,8 @@ import type {
   AssetLibraryOpenRequest,
   AssetLibraryReadResult,
   AssetLibrarySourceLink,
+  AssetLibraryThumbnailRequest,
+  AssetLibraryThumbnailResult,
 } from './assetLibrary.ts'
 
 test('declares capability-first asset taxonomy without extension categories', () => {
@@ -115,6 +117,26 @@ test('AssetLibraryEntry carries library-owned source, manifest, artifact, versio
   assert.equal(entry.provenance?.source, 'library-sidecar')
 })
 
+test('thumbnail requests and results can carry a previewClip name and its clip list', () => {
+  // Typed (not `satisfies`) so the omitted optional `previewClip` is still
+  // part of `staticRequest`'s type instead of narrowing it away entirely.
+  const staticRequest: AssetLibraryThumbnailRequest = { workspacePath: 'Exports/hero.glb' }
+  const clipRequest: AssetLibraryThumbnailRequest = { workspacePath: 'Exports/hero.glb', previewClip: 'walk' }
+  const staticResult = {
+    success: true,
+    dataUrl: 'data:image/png;base64,aa',
+    previews: [{ clip: 'idle', duration: 1.5 }, { clip: 'walk', duration: 0.8 }],
+  } satisfies AssetLibraryThumbnailResult
+  const clipResult = { success: true, dataUrl: 'data:image/webp;base64,bb' } satisfies AssetLibraryThumbnailResult
+  const miss = { success: false } satisfies AssetLibraryThumbnailResult
+
+  assert.equal(staticRequest.previewClip, undefined)
+  assert.equal(clipRequest.previewClip, 'walk')
+  assert.equal(staticResult.previews?.[1]?.clip, 'walk')
+  assert.equal(clipResult.success && clipResult.dataUrl, 'data:image/webp;base64,bb')
+  assert.equal(miss.success, false)
+})
+
 test('read and open requests can carry a sourceWorkspacePath for linked-source opens', () => {
   const request = {
     workspacePath: 'Workflows/checkpoints/hero.landmarks.v1.json',
diff --git a/src/shared/types/assetLibrary.ts b/src/shared/types/assetLibrary.ts
index 87c48785..662bc9eb 100644
--- a/src/shared/types/assetLibrary.ts
+++ b/src/shared/types/assetLibrary.ts
@@ -82,12 +82,26 @@ export type AssetLibraryOpenResult =
   | { success: true, entry: AssetLibraryEntry }
   | { success: false, error: AssetLibraryError }
 
+export interface AssetLibraryPreviewClip {
+  /** Animation clip name, matched against the manifest and echoed back on request. */
+  clip: string
+  /** Loop duration in seconds, as reported by the manifest. */
+  duration: number
+}
+
 export interface AssetLibraryThumbnailRequest {
   workspacePath: string
+  /**
+   * When set, request the looping preview WebP for this clip instead of the
+   * static thumbnail. Omit to fetch the static thumbnail (default), which also
+   * carries the `previews` clip list when one exists so the UI can decide
+   * whether hover-to-animate is available at all.
+   */
+  previewClip?: string
 }
 
 // Missing thumbnails are an expected, silent condition (not every asset has
 // a rendered preview), so failure carries no error payload for the UI to show.
 export type AssetLibraryThumbnailResult =
-  | { success: true, dataUrl: string }
+  | { success: true, dataUrl: string, previews?: AssetLibraryPreviewClip[] }
   | { success: false }

From 124f389ea65c5c7287c71375a650c02c09596927 Mon Sep 17 00:00:00 2001
From: JayceeB1 <45721154+JayceeB1@users.noreply.github.com>
Date: Fri, 9 Oct 2026 23:35:48 +0200
Subject: [PATCH 08/11] integrate(#249): group library assets by project and
 lineage

Ported onto current 0.4.3 asset registry; adapted test insertion to current suite.
---
 .../main/artifact-registry-service.test.ts    |  47 +-
 electron/main/artifact-registry-service.ts    | 111 +++-
 src/areas/generate/GeneratePage.tsx           | 573 +++++++++++++-----
 src/areas/generate/assetLibraryProjection.ts  |  22 +-
 src/areas/generate/assetLibraryUi.test.ts     | 208 ++++---
 src/areas/generate/assetLibraryUi.ts          | 311 ++++++----
 src/shared/types/assetLibrary.test.ts         |  14 +-
 src/shared/types/assetLibrary.ts              |  28 +-
 8 files changed, 946 insertions(+), 368 deletions(-)

diff --git a/electron/main/artifact-registry-service.test.ts b/electron/main/artifact-registry-service.test.ts
index 98078384..9f4a6ec6 100644
--- a/electron/main/artifact-registry-service.test.ts
+++ b/electron/main/artifact-registry-service.test.ts
@@ -23,7 +23,8 @@ async function withWorkspace(run: (workspaceDir: string) => Promise<void>) {
   }
 }
 
-test('normalizes only workspace-relative paths under allowed Workflows and Exports roots', () => withWorkspace(async (workspaceDir) => {
+test('normalizes only workspace-relative paths under allowed model roots', () => withWorkspace(async (workspaceDir) => {
+  assert.equal(normalizeWorkspaceAssetPath(workspaceDir, 'Default/hero.glb').workspacePath, 'Default/hero.glb')
   assert.equal(normalizeWorkspaceAssetPath(workspaceDir, 'Workflows/checkpoints/hero.glb').workspacePath, 'Workflows/checkpoints/hero.glb')
   assert.equal(normalizeWorkspaceAssetPath(workspaceDir, 'Exports/hero.glb').workspacePath, 'Exports/hero.glb')
   assert.throws(() => normalizeWorkspaceAssetPath(workspaceDir, '../secret.glb'), /traversal|escape|relative/i)
@@ -77,6 +78,50 @@ test('registers a generated scene directory through its canonical manifest artif
   assert.equal(scene && scene.state, 'ready')
 }))
 
+test('indexes generated models and reads project, structural tags, creation time, and lineage from model sidecars', () => withWorkspace(async (workspaceDir) => {
+  await mkdir(path.join(workspaceDir, 'Default'), { recursive: true })
+  await mkdir(path.join(workspaceDir, 'Exports/adventure'), { recursive: true })
+  await writeFile(path.join(workspaceDir, 'Default/hero.glb'), 'glb')
+  await writeFile(path.join(workspaceDir, 'Default/hero.tags.json'), JSON.stringify({
+    name: 'Hero',
+    project: null,
+    tags: ['mid-poly'],
+    created: '2026-06-15T10:00:00.000Z',
+  }))
+  await writeFile(path.join(workspaceDir, 'Exports/adventure/hero-rigged.glb'), 'glb')
+  await writeFile(path.join(workspaceDir, 'Exports/adventure/hero-rigged.tags.json'), JSON.stringify({
+    name: 'Hero Rigged',
+    project: 'Adventure',
+    tags: ['rigged', 'animated', 'clip-hero-walk', 'mid-poly'],
+    created: '2026-06-16T10:00:00.000Z',
+    derived_from: {
+      parent: { path: 'Default/hero.glb', name: 'Hero' },
+      root: { path: 'Default/hero.glb', name: 'Hero' },
+    },
+  }))
+
+  const result = await listWorkspaceAssetLibrary({ workspaceDir })
+  assert.equal(result.success, true)
+  if (!result.success) return
+  assert.deepEqual(result.entries.map((entry) => entry.workspacePath), [
+    'Default/hero.glb',
+    'Exports/adventure/hero-rigged.glb',
+  ])
+
+  const root = result.entries[0]
+  const derived = result.entries[1]
+  assert.equal(root.sourceScope, 'generated')
+  assert.equal(root.displayName, 'Hero')
+  assert.equal(derived.displayName, 'Hero Rigged')
+  assert.equal(derived.capability, 'rigged-mesh')
+  assert.equal(derived.createdAt, '2026-06-16T10:00:00.000Z')
+  assert.equal(derived.semantic?.project, 'Adventure')
+  assert.deepEqual(derived.semantic?.tags, ['rigged', 'animated', 'clip-hero-walk', 'mid-poly'])
+  assert.equal(derived.semantic?.derivedFrom?.parent.workspacePath, 'Default/hero.glb')
+  assert.equal(derived.semantic?.derivedFrom?.root.workspacePath, 'Default/hero.glb')
+}))
+
+
 test('reads and opens only safe GLB/GLTF workspace assets', () => withWorkspace(async (workspaceDir) => {
   await mkdir(path.join(workspaceDir, 'Workflows/checkpoints'), { recursive: true })
   await mkdir(path.join(workspaceDir, 'Exports'), { recursive: true })
diff --git a/electron/main/artifact-registry-service.ts b/electron/main/artifact-registry-service.ts
index d5b3b7e2..1e03bc0c 100644
--- a/electron/main/artifact-registry-service.ts
+++ b/electron/main/artifact-registry-service.ts
@@ -12,6 +12,8 @@ import type {
   AssetLibraryPreviewKind,
   AssetLibraryPreviewPayload,
   AssetLibraryReadResult,
+  AssetLibraryLineageLink,
+  AssetLibrarySemanticMetadata,
   AssetLibrarySourceScope,
   AssetLibraryThumbnailResult,
 } from '../../src/shared/types/assetLibrary'
@@ -19,9 +21,9 @@ import type { ArtifactProvenance } from '../../src/shared/types/artifacts'
 
 const WINDOWS_ABSOLUTE_PATH = /^[a-zA-Z]:[\\/]/
 const ENCODED_ESCAPE_PATTERN = /%2e|%2f|%5c/i
-const ALLOWED_ROOTS = ['Workflows', 'Exports'] as const
+const ALLOWED_ROOTS = ['Default', 'Workflows', 'Exports'] as const
 const SKIPPED_DIRS = new Set(['tmp', 'temp', 'cache'])
-const INTERNAL_SUFFIXES = ['.artifact.json', '.rigmeta.json'] as const
+const INTERNAL_SUFFIXES = ['.artifact.json', '.rigmeta.json', '.tags.json', '.previews.json', '.thumb.png'] as const
 const TEXT_EXTENSIONS = new Set(['json', 'txt', 'md'])
 const INTRINSIC_MOTION_EXTENSIONS = new Set(['bvh', 'npz'])
 const MESH_EXTENSIONS = new Set(['glb', 'gltf', 'obj', 'stl', 'ply', 'splat'])
@@ -67,6 +69,11 @@ interface AssetLibraryMetadata {
   warnings: string[]
 }
 
+interface AssetLibrarySemanticRead {
+  semantic?: AssetLibrarySemanticMetadata
+  warnings: string[]
+}
+
 export interface IpcMainLike {
   handle(channel: string, handler: (event: unknown, payload?: unknown) => Promise<unknown>): void
 }
@@ -119,7 +126,9 @@ function isGlbOrGltf(workspacePath: string): boolean {
 }
 
 function sourceScopeFor(workspacePath: string): AssetLibrarySourceScope {
-  return workspacePath.startsWith('Exports/') ? 'exports' : 'workflows'
+  if (workspacePath.startsWith('Exports/')) return 'exports'
+  if (workspacePath.startsWith('Workflows/')) return 'workflows'
+  return 'generated'
 }
 
 export function classifyAssetLibraryCandidate(candidate: AssetLibraryClassificationCandidate): AssetLibraryClassification {
@@ -157,6 +166,11 @@ function objectField(value: unknown): Record<string, unknown> | undefined {
   return typeof value === 'object' && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : undefined
 }
 
+function stringListField(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return [...new Set(value.map(stringField).filter((item): item is string => item !== undefined))]
+}
+
 function manifestCapabilityFor(workspacePath: string): 'generated-world' | 'scene-manifest' | undefined {
   if (workspacePath.endsWith('.world.json')) return 'generated-world'
   if (workspacePath.endsWith('.scene.json')) return 'scene-manifest'
@@ -211,12 +225,87 @@ async function readMetadata(workspaceDir: string, workspacePath: string, absolut
   return metadata
 }
 
+function semanticSidecarPathFor(absolutePath: string): string {
+  return absolutePath.replace(/\.[^./\\]+$/, '') + '.tags.json'
+}
+
+function safeSemanticLineageLink(
+  workspaceDir: string,
+  value: unknown,
+): AssetLibraryLineageLink | undefined {
+  const candidate = objectField(value)
+  const rawPath = stringField(candidate?.path ?? candidate?.workspacePath)
+  if (!rawPath) return undefined
+  try {
+    const { workspacePath } = normalizeWorkspaceAssetPath(workspaceDir, rawPath)
+    return {
+      workspacePath,
+      displayName: stringField(candidate?.name ?? candidate?.displayName),
+    }
+  } catch {
+    return undefined
+  }
+}
+
+async function readSemanticMetadata(
+  workspaceDir: string,
+  absolutePath: string,
+): Promise<AssetLibrarySemanticRead> {
+  let parsed: Record<string, unknown>
+  try {
+    const raw = JSON.parse(await readFile(semanticSidecarPathFor(absolutePath), 'utf8')) as unknown
+    const object = objectField(raw)
+    if (!object) return { warnings: ['Asset metadata sidecar is not a JSON object.'] }
+    parsed = object
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { warnings: [] }
+    return { warnings: ['Asset metadata sidecar could not be read.'] }
+  }
+
+  const warnings: string[] = []
+  const name = stringField(parsed.name)
+  const project = stringField(parsed.project)
+  const tags = stringListField(parsed.tags)
+  if (parsed.tags !== undefined && !Array.isArray(parsed.tags)) {
+    warnings.push('Ignored invalid asset tags.')
+  }
+
+  const createdRaw = stringField(parsed.created)
+  const created = createdRaw && Number.isFinite(Date.parse(createdRaw)) ? createdRaw : undefined
+  if (createdRaw && !created) warnings.push('Ignored invalid asset creation date.')
+
+  let derivedFrom: AssetLibrarySemanticMetadata['derivedFrom']
+  if (parsed.derived_from !== undefined) {
+    const rawDerivedFrom = objectField(parsed.derived_from)
+    const parent = safeSemanticLineageLink(workspaceDir, rawDerivedFrom?.parent)
+    const root = safeSemanticLineageLink(workspaceDir, rawDerivedFrom?.root)
+    if (parent && root) {
+      derivedFrom = { parent, root }
+    } else {
+      warnings.push('Ignored unsafe or invalid asset lineage.')
+    }
+  }
+
+  return {
+    semantic: {
+      ...(name ? { name } : {}),
+      ...(project ? { project } : {}),
+      tags,
+      ...(created ? { created } : {}),
+      ...(derivedFrom ? { derivedFrom } : {}),
+    },
+    warnings,
+  }
+}
+
 function shouldSkipDirectory(name: string): boolean {
   return name.startsWith('.') || SKIPPED_DIRS.has(name.toLowerCase())
 }
 
 function shouldSkipFile(name: string): boolean {
-  return name.startsWith('.') || INTERNAL_SUFFIXES.some((suffix) => name.endsWith(suffix))
+  return name.startsWith('.')
+    || INTERNAL_SUFFIXES.some((suffix) => name.endsWith(suffix))
+    || /\.preview-[^/\\]+\.webp$/i.test(name)
 }
 
 async function hasRigMetadata(absolutePath: string): Promise<boolean> {
@@ -233,13 +322,18 @@ async function hasRigMetadata(absolutePath: string): Promise<boolean> {
 async function buildEntry(workspaceDir: string, workspacePath: string): Promise<AssetLibraryEntry> {
   const { absolutePath } = normalizeWorkspaceAssetPath(workspaceDir, workspacePath)
   const stats = await stat(absolutePath)
-  const classification = classifyAssetLibraryCandidate({ workspacePath, hasRigMetadata: await hasRigMetadata(absolutePath) })
+  const semanticRead = await readSemanticMetadata(workspaceDir, absolutePath)
+  const semanticTags = semanticRead.semantic?.tags ?? []
+  const classification = classifyAssetLibraryCandidate({
+    workspacePath,
+    hasRigMetadata: semanticTags.includes('rigged') || await hasRigMetadata(absolutePath),
+  })
   const metadata = await readMetadata(workspaceDir, workspacePath, absolutePath)
   const manifestCapability = metadata.manifestWorkspacePath ? manifestCapabilityFor(metadata.manifestWorkspacePath) : undefined
   return {
     id: `library:${workspacePath}`,
     workspacePath,
-    displayName: basename(workspacePath),
+    displayName: semanticRead.semantic?.name ?? basename(workspacePath),
     sourceScope: sourceScopeFor(workspacePath),
     capability: classification.capability,
     state: classification.state,
@@ -249,11 +343,12 @@ async function buildEntry(workspaceDir: string, workspacePath: string): Promise<
     artifactId: metadata.artifactId,
     versionId: metadata.versionId,
     provenance: metadata.provenance,
-    warnings: metadata.warnings,
+    warnings: [...metadata.warnings, ...semanticRead.warnings],
     openable: classification.openable,
     nonOpenableReason: classification.nonOpenableReason,
-    createdAt: (stats.birthtime.getTime() > 0 ? stats.birthtime : stats.mtime).toISOString(),
+    createdAt: semanticRead.semantic?.created ?? (stats.birthtime.getTime() > 0 ? stats.birthtime : stats.mtime).toISOString(),
     updatedAt: stats.mtime.toISOString(),
+    semantic: semanticRead.semantic,
   }
 }
 
diff --git a/src/areas/generate/GeneratePage.tsx b/src/areas/generate/GeneratePage.tsx
index 447a5a08..86636dab 100644
--- a/src/areas/generate/GeneratePage.tsx
+++ b/src/areas/generate/GeneratePage.tsx
@@ -12,13 +12,17 @@ import { buildOrcaSlicerDeepLink, canOpenInOrcaSlicer } from './orcaSlicerLink'
 import { resolveAssetLibraryOpenTarget, type ProjectedAssetLibraryEntry } from './assetLibraryProjection'
 import type { AssetLibraryPreviewClip } from '../../shared/types/assetLibrary'
 import {
+  ASSET_LIBRARY_KIND_FILTERS,
+  ASSET_LIBRARY_POLY_FILTERS,
   ASSET_LIBRARY_SORT_OPTIONS,
+  buildAssetLibraryProjectGroups,
   buildAssetLibraryOpenRequest,
   clampAssetLibraryPanelHeight,
   clampAssetLibraryPanelWidth,
+  createDefaultAssetLibraryFilters,
   createAssetLibraryOpenJob,
   describeAssetLibraryOpenability,
-  filterAssetLibraryScopeGroups,
+  formatAssetLibraryClipName,
   getDefaultAssetLibraryCollapsedSectionKeys,
   getStoredAssetLibraryPanelHeight,
   getStoredAssetLibraryPanelWidth,
@@ -28,7 +32,10 @@ import {
   storeAssetLibraryPanelHeight,
   storeAssetLibraryPanelWidth,
   toggleAssetLibrarySectionKey,
+  type AssetLibraryFilters,
+  type AssetLibraryLineageFamily,
   type AssetLibrarySortMode,
+  type AssetLibraryViewMode,
   type GenerateOpenPanel,
 } from './assetLibraryUi'
 
@@ -502,6 +509,8 @@ function AssetLibraryPopover({
   error,
   searchQuery,
   sortMode,
+  viewMode,
+  filters,
   collapsedSectionKeys,
   thumbnails,
   previews,
@@ -510,6 +519,8 @@ function AssetLibraryPopover({
   onActivateEntry,
   onSearchQueryChange,
   onSortModeChange,
+  onViewModeChange,
+  onFiltersChange,
   onToggleSection,
   onOpenSelected,
   onFetchPreviewFrame,
@@ -525,6 +536,8 @@ function AssetLibraryPopover({
   error: string | null
   searchQuery: string
   sortMode: AssetLibrarySortMode
+  viewMode: AssetLibraryViewMode
+  filters: AssetLibraryFilters
   collapsedSectionKeys: string[]
   /** Data URLs keyed by workspacePath, populated lazily as thumbnails load. */
   thumbnails: Record<string, string>
@@ -536,6 +549,8 @@ function AssetLibraryPopover({
   onActivateEntry: (entryId: string) => void
   onSearchQueryChange: (value: string) => void
   onSortModeChange: (value: AssetLibrarySortMode) => void
+  onViewModeChange: (value: AssetLibraryViewMode) => void
+  onFiltersChange: (value: AssetLibraryFilters) => void
   onToggleSection: (sectionKey: string) => void
   onOpenSelected: () => void
   onFetchPreviewFrame: (workspacePath: string, clip: string) => Promise<string | null>
@@ -544,17 +559,20 @@ function AssetLibraryPopover({
   onResizeMouseDown: (event: React.MouseEvent) => void
   onResizeHeightMouseDown: (event: React.MouseEvent) => void
 }) {
-  const scopeGroups = filterAssetLibraryScopeGroups(entries, searchQuery, sortMode)
-  const visibleEntryIds = new Set(scopeGroups.flatMap((scopeGroup) => scopeGroup.entryGroups.flatMap((group) => group.entries.map((entry) => entry.id))))
+  const projectGroups = buildAssetLibraryProjectGroups(entries, searchQuery, sortMode, filters)
+  const visibleEntryIds = new Set(projectGroups.flatMap((group) => group.families.flatMap((family) => family.entries.map((entry) => entry.id))))
   const selectedEntry = selectedEntryId && visibleEntryIds.has(selectedEntryId)
     ? entries.find((entry) => entry.id === selectedEntryId) ?? null
     : null
   const normalizedSearchQuery = searchQuery.trim()
-  const hasActiveSearch = normalizedSearchQuery.length > 0
+  const hasActiveFilters = filters.kind !== 'all' || filters.poly !== 'all' || filters.needsAttention
+  const hasActiveDiscovery = normalizedSearchQuery.length > 0 || hasActiveFilters
+  const familyCount = projectGroups.reduce((count, group) => count + group.families.length, 0)
+  const versionCount = projectGroups.reduce((count, group) => count + group.entryCount, 0)
   const openDisabled = !selectedEntry || !isAssetLibraryEntryOpenable(selectedEntry) || loading || opening
   const selectedMessage = selectedEntry
     ? describeAssetLibraryOpenability(selectedEntry)
-    : scopeGroups.length === 0 && normalizedSearchQuery
+    : projectGroups.length === 0 && normalizedSearchQuery
       ? `No workspace assets match “${normalizedSearchQuery}”.`
       : 'Select an asset to open it in Generate.'
 
@@ -567,16 +585,26 @@ function AssetLibraryPopover({
     >
       <div className="flex items-center justify-between gap-2 shrink-0">
         <div>
-          <p className="text-[10px] text-zinc-500 uppercase tracking-wider">Workspace library</p>
-          <p className="text-xs text-zinc-300">Select a workspace asset and open the supported source in Generate.</p>
+          <p className="text-[10px] text-zinc-500 uppercase tracking-wider">Asset Library</p>
+          <p className="text-xs text-zinc-300">Browse models by project, traits, and version family.</p>
+        </div>
+        <div className="flex items-center gap-2">
+          <button
+            type="button"
+            onClick={onRefresh}
+            disabled={loading || opening}
+            className="px-2 py-1 text-[11px] text-zinc-400 hover:text-zinc-200 bg-zinc-800 hover:bg-zinc-700 disabled:opacity-50 rounded-lg transition-colors"
+          >
+            Refresh
+          </button>
+          <button
+            type="button"
+            onClick={onClose}
+            className="px-2 py-1 text-[11px] text-zinc-400 hover:text-zinc-200 bg-zinc-800 hover:bg-zinc-700 rounded-lg transition-colors"
+          >
+            Close
+          </button>
         </div>
-        <button
-          type="button"
-          onClick={onClose}
-          className="px-2 py-1 text-[11px] text-zinc-400 hover:text-zinc-200 bg-zinc-800 hover:bg-zinc-700 rounded-lg transition-colors"
-        >
-          Close library
-        </button>
       </div>
 
       {/* Resize handle — drag to widen/narrow the library panel; size is persisted. */}
@@ -597,28 +625,19 @@ function AssetLibraryPopover({
         className="absolute bottom-0 left-0 right-0 h-1.5 cursor-row-resize hover:bg-violet-400/40 active:bg-violet-400/60 transition-colors rounded-b-xl"
       />
 
-      <button
-        type="button"
-        onClick={onRefresh}
-        disabled={loading || opening}
-        className="self-start shrink-0 px-2.5 py-1.5 text-[11px] text-zinc-300 bg-zinc-800 hover:bg-zinc-700 disabled:opacity-50 disabled:pointer-events-none rounded-lg transition-colors"
-      >
-        Refresh assets
-      </button>
-
       <div className="flex items-end gap-2 shrink-0">
         <div className="flex min-w-0 flex-1 flex-col gap-1.5">
-          <label htmlFor="asset-library-search" className="text-[11px] text-zinc-300">Search workspace assets</label>
+          <label htmlFor="asset-library-search" className="text-[11px] text-zinc-300">Search assets</label>
           <input
             id="asset-library-search"
             type="search"
             value={searchQuery}
             onChange={(event) => onSearchQueryChange(event.target.value)}
-            placeholder="Search by name, path, scope, or capability"
+            placeholder="Search names, projects, tags, clips, or locations"
             className="appearance-none bg-zinc-800 border border-zinc-700 rounded-lg px-2.5 py-1.5 text-xs text-zinc-200 w-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400"
           />
         </div>
-        <div className="flex w-24 shrink-0 flex-col gap-1.5">
+        <div className="flex w-36 shrink-0 flex-col gap-1.5">
           <label htmlFor="asset-library-sort" className="text-[11px] text-zinc-300">Sort</label>
           <select
             id="asset-library-sort"
@@ -631,69 +650,136 @@ function AssetLibraryPopover({
             ))}
           </select>
         </div>
+        <div className="flex shrink-0 rounded-lg border border-zinc-700 bg-zinc-800 p-0.5" aria-label="Library view">
+          {(['gallery', 'list'] as const).map((mode) => (
+            <button
+              key={mode}
+              type="button"
+              aria-pressed={viewMode === mode}
+              onClick={() => onViewModeChange(mode)}
+              className={`rounded-md px-2.5 py-1.5 text-[11px] capitalize transition-colors ${
+                viewMode === mode ? 'bg-violet-600 text-white' : 'text-zinc-400 hover:text-zinc-200'
+              }`}
+            >
+              {mode}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      <div className="shrink-0 space-y-2 rounded-lg border border-zinc-800 bg-zinc-950/40 p-2.5">
+        <div className="flex flex-wrap items-center gap-1.5">
+          <span className="mr-1 text-[10px] font-medium uppercase tracking-wider text-zinc-500">What it is</span>
+          {ASSET_LIBRARY_KIND_FILTERS.map((option) => (
+            <button
+              key={option.value}
+              type="button"
+              aria-pressed={filters.kind === option.value}
+              onClick={() => onFiltersChange({ ...filters, kind: option.value })}
+              className={`rounded-full border px-2.5 py-1 text-[10px] transition-colors ${
+                filters.kind === option.value
+                  ? 'border-violet-400/70 bg-violet-500/20 text-violet-100'
+                  : 'border-zinc-700 bg-zinc-800 text-zinc-400 hover:text-zinc-200'
+              }`}
+            >
+              {option.label}
+            </button>
+          ))}
+        </div>
+        <div className="flex flex-wrap items-center gap-1.5">
+          <span className="mr-1 text-[10px] font-medium uppercase tracking-wider text-zinc-500">File weight</span>
+          {ASSET_LIBRARY_POLY_FILTERS.map((option) => (
+            <button
+              key={option.value}
+              type="button"
+              aria-pressed={filters.poly === option.value}
+              onClick={() => onFiltersChange({ ...filters, poly: option.value })}
+              className={`rounded-full border px-2.5 py-1 text-[10px] transition-colors ${
+                filters.poly === option.value
+                  ? 'border-sky-400/70 bg-sky-500/15 text-sky-100'
+                  : 'border-zinc-700 bg-zinc-800 text-zinc-400 hover:text-zinc-200'
+              }`}
+            >
+              {option.label}
+            </button>
+          ))}
+          <button
+            type="button"
+            aria-pressed={filters.needsAttention}
+            onClick={() => onFiltersChange({ ...filters, needsAttention: !filters.needsAttention })}
+            className={`ml-auto rounded-full border px-2.5 py-1 text-[10px] transition-colors ${
+              filters.needsAttention
+                ? 'border-amber-400/70 bg-amber-500/15 text-amber-100'
+                : 'border-zinc-700 bg-zinc-800 text-zinc-400 hover:text-zinc-200'
+            }`}
+          >
+            Needs a name
+          </button>
+        </div>
       </div>
 
       {loading ? (
         <p role="status" className="flex-1 min-h-0 flex items-center justify-center text-xs text-zinc-400">Loading workspace assets…</p>
-      ) : scopeGroups.length === 0 && !normalizedSearchQuery ? (
+      ) : projectGroups.length === 0 && !hasActiveDiscovery ? (
         <p role="status" className="flex-1 min-h-0 flex items-center justify-center text-xs text-zinc-500">No workspace assets are indexed yet.</p>
-      ) : scopeGroups.length === 0 ? (
-        <p role="status" className="flex-1 min-h-0 flex items-center justify-center text-center text-xs text-zinc-500">{`No workspace assets match “${normalizedSearchQuery}”.`}</p>
+      ) : projectGroups.length === 0 ? (
+        <p role="status" className="flex-1 min-h-0 flex items-center justify-center text-center text-xs text-zinc-500">
+          No assets match these search and filter choices.
+        </p>
       ) : (
-        <div role="list" aria-label="Workspace library assets" className="flex-1 min-h-0 overflow-y-auto overflow-x-hidden rounded-lg border border-zinc-800 bg-zinc-950/40">
-          {scopeGroups.map((scopeGroup) => {
-            const scopeExpanded = isAssetLibrarySectionExpanded(collapsedSectionKeys, scopeGroup.sectionKey, hasActiveSearch)
-            const scopeRegionId = `asset-library-${scopeGroup.sectionKey.replace(/[^a-z0-9-]+/gi, '-')}`
+        <div className="flex-1 min-h-0 overflow-y-auto overflow-x-hidden rounded-lg border border-zinc-800 bg-zinc-950/40">
+          <div className="sticky top-0 z-10 flex items-center justify-between border-b border-zinc-800 bg-zinc-950/95 px-3 py-2 backdrop-blur">
+            <span className="text-[10px] uppercase tracking-wider text-zinc-500">Grouped by project</span>
+            <span className="text-[10px] text-zinc-500">{familyCount} families · {versionCount} versions</span>
+          </div>
+          {projectGroups.map((projectGroup) => {
+            const projectExpanded = isAssetLibrarySectionExpanded(collapsedSectionKeys, projectGroup.sectionKey, hasActiveDiscovery)
+            const projectRegionId = `asset-library-${projectGroup.sectionKey.replace(/[^a-z0-9-]+/gi, '-')}`
             return (
-              <section key={scopeGroup.sectionKey} role="group" aria-label={`Source scope ${scopeGroup.sourceScopeLabel}`} className="border-b border-zinc-800 last:border-b-0">
+              <section key={projectGroup.sectionKey} role="group" aria-label={`Project ${projectGroup.projectLabel}`} className="border-b border-zinc-800 last:border-b-0">
                 <button
                   type="button"
-                  aria-expanded={scopeExpanded}
-                  aria-controls={scopeRegionId}
-                  onClick={() => onToggleSection(scopeGroup.sectionKey)}
-                  disabled={hasActiveSearch}
-                  className="flex w-full items-center justify-between gap-2 px-3 py-2 text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400 disabled:opacity-50 disabled:pointer-events-none"
+                  aria-expanded={projectExpanded}
+                  aria-controls={projectRegionId}
+                  onClick={() => onToggleSection(projectGroup.sectionKey)}
+                  disabled={hasActiveDiscovery}
+                  className="flex w-full items-center justify-between gap-3 bg-zinc-900/80 px-3 py-2.5 text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400 disabled:pointer-events-none"
                 >
-                  <span className="text-[10px] font-semibold uppercase tracking-[0.18em] text-zinc-300">{scopeGroup.sourceScopeLabel}</span>
-                  <span className="text-[10px] text-zinc-500">{scopeExpanded ? 'Hide' : 'Show'}</span>
+                  <span className="flex items-center gap-2">
+                    <span className={`text-xs font-semibold ${projectGroup.projectKey === 'needs-project' ? 'text-amber-200' : 'text-zinc-200'}`}>
+                      {projectGroup.projectLabel}
+                    </span>
+                    {projectGroup.projectKey === 'needs-project' && (
+                      <span className="rounded-full bg-amber-500/15 px-2 py-0.5 text-[9px] text-amber-200">Add project metadata</span>
+                    )}
+                  </span>
+                  <span className="text-[10px] text-zinc-500">
+                    {projectGroup.families.length} {projectGroup.families.length === 1 ? 'family' : 'families'} · {projectGroup.entryCount} versions · {projectExpanded ? 'Hide' : 'Show'}
+                  </span>
                 </button>
-                {scopeExpanded && (
-                  <div id={scopeRegionId}>
-                    {scopeGroup.entryGroups.map((group) => {
-                      const capabilityExpanded = isAssetLibrarySectionExpanded(collapsedSectionKeys, group.sectionKey, hasActiveSearch)
-                      const capabilityRegionId = `asset-library-${group.sectionKey.replace(/[^a-z0-9-]+/gi, '-')}`
-                      return (
-                        <section key={group.sectionKey} role="group" aria-label={`Capability category ${group.capabilityLabel}`} className="border-t border-zinc-800 first:border-t-0">
-                          <button
-                            type="button"
-                            aria-expanded={capabilityExpanded}
-                            aria-controls={capabilityRegionId}
-                            onClick={() => onToggleSection(group.sectionKey)}
-                            disabled={hasActiveSearch}
-                            className="flex w-full items-center justify-between gap-2 px-4 py-2 text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400 disabled:opacity-50 disabled:pointer-events-none"
-                          >
-                            <span className="text-[10px] font-semibold uppercase tracking-[0.18em] text-zinc-400">{group.capabilityLabel}</span>
-                            <span className="text-[10px] text-zinc-500">{capabilityExpanded ? 'Hide' : 'Show'}</span>
-                          </button>
-                          {capabilityExpanded && (
-                            <div id={capabilityRegionId}>
-                              {group.entries.map((entry) => (
-                                <AssetLibraryEntryRow
-                                  key={entry.id}
-                                  entry={entry}
-                                  selected={entry.id === selectedEntryId}
-                                  disabled={opening}
-                                  thumbnailDataUrl={thumbnails[entry.workspacePath]}
-                                  previewClips={previews[entry.workspacePath] ?? EMPTY_PREVIEW_CLIPS}
-                                  onActivate={() => onActivateEntry(entry.id)}
-                                  onFetchPreviewFrame={onFetchPreviewFrame}
-                                />
-                              ))}
-                            </div>
-                          )}
-                        </section>
-                      )
-                    })}
+                {projectExpanded && (
+                  <div
+                    id={projectRegionId}
+                    role="list"
+                    aria-label={`${projectGroup.projectLabel} asset families`}
+                    className={viewMode === 'gallery'
+                      ? 'grid grid-cols-[repeat(auto-fill,minmax(210px,1fr))] gap-3 p-3'
+                      : 'divide-y divide-zinc-800'
+                    }
+                  >
+                    {projectGroup.families.map((family) => (
+                      <AssetLibraryFamilyCard
+                        key={family.key}
+                        family={family}
+                        viewMode={viewMode}
+                        selectedEntryId={selectedEntryId}
+                        disabled={opening}
+                        thumbnails={thumbnails}
+                        previews={previews}
+                        onActivateEntry={onActivateEntry}
+                        onFetchPreviewFrame={onFetchPreviewFrame}
+                      />
+                    ))}
                   </div>
                 )}
               </section>
@@ -721,49 +807,53 @@ function AssetLibraryPopover({
 }
 
 /**
- * One Library row. A click both selects and (when openable) opens the asset —
- * the "Open selected asset" button stays as a secondary affordance, not the
- * only path. Hovering swaps the static thumbnail for a looping preview clip,
- * lazily fetched over the same thumbnail IPC call, when one exists; with no
- * preview manifest yet, `previewClips` is empty and the row behaves exactly
- * as it did before — no extra fetches, no hover swap, no cycle control.
+ * One semantic asset family. Gallery cards load their active motion clip
+ * immediately so animation is visible without a precision hover. List rows
+ * retain the compact scanner from v2 and lazy-load animation on hover.
  */
-function AssetLibraryEntryRow({
-  entry,
-  selected,
+function AssetLibraryFamilyCard({
+  family,
+  viewMode,
+  selectedEntryId,
   disabled,
-  thumbnailDataUrl,
-  previewClips,
-  onActivate,
+  thumbnails,
+  previews,
+  onActivateEntry,
   onFetchPreviewFrame,
 }: {
-  entry: ProjectedAssetLibraryEntry
-  selected: boolean
+  family: AssetLibraryLineageFamily
+  viewMode: AssetLibraryViewMode
+  selectedEntryId: string | null
   disabled: boolean
-  thumbnailDataUrl: string | undefined
-  previewClips: AssetLibraryPreviewClip[]
-  onActivate: () => void
+  thumbnails: Record<string, string>
+  previews: Record<string, AssetLibraryPreviewClip[]>
+  onActivateEntry: (entryId: string) => void
   onFetchPreviewFrame: (workspacePath: string, clip: string) => Promise<string | null>
 }) {
+  const entry = family.primaryEntry
+  const thumbnailDataUrl = thumbnails[entry.workspacePath]
+  const previewClips = previews[entry.workspacePath] ?? EMPTY_PREVIEW_CLIPS
+  const selected = family.entries.some((candidate) => candidate.id === selectedEntryId)
   const [hovered, setHovered] = useState(false)
   const [clipIndex, setClipIndex] = useState(0)
   const [previewFrames, setPreviewFrames] = useState<Record<string, string>>({})
+  const [versionsExpanded, setVersionsExpanded] = useState(false)
   const mountedRef = useRef(true)
   useEffect(() => () => { mountedRef.current = false }, [])
 
   const activeClip = previewClips.length > 0 ? previewClips[clipIndex % previewClips.length] : undefined
   const activeFrameUrl = activeClip ? previewFrames[activeClip.clip] : undefined
 
-  // Lazy, hover-triggered, and cached per clip for this row's lifetime — a
-  // second hover (or cycling back to a clip already seen) never re-fetches.
+  // Gallery motion is the feature, so it begins without requiring a hover.
+  // Compact list rows stay lazy. Every fetched clip is cached per family.
   useEffect(() => {
-    if (!hovered || !activeClip || previewFrames[activeClip.clip]) return
+    if ((viewMode !== 'gallery' && !hovered) || !activeClip || previewFrames[activeClip.clip]) return
     void onFetchPreviewFrame(entry.workspacePath, activeClip.clip).then((dataUrl) => {
       if (mountedRef.current && dataUrl) {
         setPreviewFrames((current) => ({ ...current, [activeClip.clip]: dataUrl }))
       }
     })
-  }, [hovered, activeClip, entry.workspacePath, previewFrames, onFetchPreviewFrame])
+  }, [viewMode, hovered, activeClip, entry.workspacePath, previewFrames, onFetchPreviewFrame])
 
   function cycleClip(step: 1 | -1, event: React.MouseEvent | React.KeyboardEvent) {
     event.preventDefault()
@@ -776,66 +866,245 @@ function AssetLibraryEntryRow({
     cycleClip(step, event)
   }
 
-  const displayedThumbnailUrl = hovered && activeFrameUrl ? activeFrameUrl : thumbnailDataUrl
+  function activateEntry(entryId: string, event?: React.SyntheticEvent) {
+    event?.preventDefault()
+    event?.stopPropagation()
+    if (!disabled) onActivateEntry(entryId)
+  }
+
+  function handleCardKeyDown(event: React.KeyboardEvent<HTMLElement>) {
+    if (event.target !== event.currentTarget || (event.key !== 'Enter' && event.key !== ' ')) return
+    activateEntry(entry.id, event)
+  }
+
+  const displayedThumbnailUrl = activeFrameUrl ?? thumbnailDataUrl
+  const tags = new Set(entry.semantic?.tags ?? [])
+  const badges = [
+    tags.has('animated') ? 'Animated' : null,
+    tags.has('rigged') || entry.capability === 'rigged-mesh' ? 'Rigged' : null,
+    tags.has('character') || tags.has('creature') ? 'Character' : null,
+    tags.has('prop') ? 'Prop' : null,
+    tags.has('low-poly') ? 'Light' : tags.has('mid-poly') ? 'Medium' : tags.has('high-poly') ? 'Heavy' : null,
+    tags.has('unnamed') || !entry.semantic?.name ? 'Needs name' : null,
+  ].filter((badge): badge is string => Boolean(badge))
+  const dateLabel = formatAssetLibraryDate(entry.createdAt)
+
+  const clipControls = activeClip && (
+    <div className={`flex items-center gap-2 ${viewMode === 'gallery'
+      ? 'border-t border-zinc-700/70 bg-zinc-950 px-2 py-2'
+      : 'mt-1'
+    }`}>
+      {previewClips.length > 1 && (
+        <button
+          type="button"
+          aria-label={`Show previous animation for ${family.name}`}
+          onClick={(event) => cycleClip(-1, event)}
+          onKeyDown={(event) => handleCycleKeyDown(-1, event)}
+          className="flex h-6 w-6 shrink-0 items-center justify-center rounded-md bg-zinc-800 text-sm text-zinc-200 hover:bg-zinc-700 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-violet-400"
+        >
+          ‹
+        </button>
+      )}
+      <span className="min-w-0 flex-1 truncate text-center text-[10px] font-medium text-violet-200">
+        {viewMode === 'gallery' ? 'Animation: ' : ''}{formatAssetLibraryClipName(activeClip.clip)}
+      </span>
+      <span className="shrink-0 text-[9px] text-zinc-500">{clipIndex + 1}/{previewClips.length}</span>
+      {previewClips.length > 1 && (
+        <button
+          type="button"
+          aria-label={`Show next animation for ${family.name}`}
+          onClick={(event) => cycleClip(1, event)}
+          onKeyDown={(event) => handleCycleKeyDown(1, event)}
+          className="flex h-6 w-6 shrink-0 items-center justify-center rounded-md bg-zinc-800 text-sm text-zinc-200 hover:bg-zinc-700 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-violet-400"
+        >
+          ›
+        </button>
+      )}
+    </div>
+  )
+
+  if (viewMode === 'list') {
+    return (
+      <article
+        role="listitem"
+        tabIndex={disabled ? -1 : 0}
+        aria-disabled={disabled}
+        aria-label={`Open asset family ${family.name}`}
+        onClick={() => activateEntry(entry.id)}
+        onKeyDown={handleCardKeyDown}
+        onMouseEnter={() => setHovered(true)}
+        onMouseLeave={() => setHovered(false)}
+        className={`cursor-pointer px-3 py-2 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-violet-400 ${
+          selected ? 'bg-violet-500/10' : 'hover:bg-zinc-800/70'
+        } ${disabled ? 'pointer-events-none opacity-50' : ''}`}
+      >
+        <div className="flex items-center gap-3">
+          <div className="relative h-14 w-14 shrink-0 overflow-hidden rounded-lg border border-zinc-700 bg-zinc-950">
+            {displayedThumbnailUrl ? (
+              <img src={displayedThumbnailUrl} alt="" className="h-full w-full object-contain" />
+            ) : (
+              <AssetLibraryPreviewPlaceholder />
+            )}
+          </div>
+          <div className="min-w-0 flex-1">
+            <div className="flex items-center gap-2">
+              <span className="truncate text-xs font-medium text-zinc-200">{family.name}</span>
+              {family.entries.length > 1 && (
+                <span className="shrink-0 rounded-full bg-violet-500/15 px-2 py-0.5 text-[9px] text-violet-200">{family.entries.length} versions</span>
+              )}
+            </div>
+            <div className="mt-1 flex flex-wrap gap-1">
+              {badges.slice(0, 4).map((badge) => (
+                <span key={badge} className={`rounded-full px-1.5 py-0.5 text-[8px] ${
+                  badge === 'Needs name' ? 'bg-amber-500/15 text-amber-200' : 'bg-zinc-800 text-zinc-400'
+                }`}>{badge}</span>
+              ))}
+            </div>
+            <p className="mt-1 truncate text-[9px] text-zinc-500" title={entry.workspacePath}>{entry.workspacePath}</p>
+          </div>
+          <div className="w-40 shrink-0">{clipControls}</div>
+          <span className="w-16 shrink-0 text-right text-[9px] text-zinc-500">{dateLabel}</span>
+          {family.entries.length > 1 && (
+            <button
+              type="button"
+              aria-expanded={versionsExpanded}
+              onClick={(event) => {
+                event.preventDefault()
+                event.stopPropagation()
+                setVersionsExpanded((current) => !current)
+              }}
+              className="shrink-0 rounded-md bg-zinc-800 px-2 py-1 text-[9px] text-zinc-300 hover:bg-zinc-700"
+            >
+              {versionsExpanded ? 'Hide versions' : 'Show versions'}
+            </button>
+          )}
+        </div>
+        {versionsExpanded && <AssetLibraryVersionRows family={family} selectedEntryId={selectedEntryId} onActivateEntry={activateEntry} />}
+      </article>
+    )
+  }
 
   return (
-    <button
-      type="button"
+    <article
       role="listitem"
-      aria-pressed={selected}
-      aria-label={`Open library asset ${entry.displayName}`}
-      onClick={onActivate}
+      tabIndex={disabled ? -1 : 0}
+      aria-disabled={disabled}
+      aria-label={`Open asset family ${family.name}`}
+      onClick={() => activateEntry(entry.id)}
+      onKeyDown={handleCardKeyDown}
       onMouseEnter={() => setHovered(true)}
       onMouseLeave={() => setHovered(false)}
-      disabled={disabled}
-      className={`flex w-full items-center gap-3 text-left px-4 py-1.5 border-t border-zinc-800 first:border-t-0 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400 disabled:opacity-50 disabled:pointer-events-none
-        ${selected ? 'bg-violet-500/10 text-zinc-100' : 'text-zinc-300 hover:bg-zinc-800/80'}`}
+      className={`min-w-0 cursor-pointer overflow-hidden rounded-xl border bg-zinc-900 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-400 ${
+        selected ? 'border-violet-400/70 bg-violet-500/10' : 'border-zinc-700/80 hover:border-zinc-600'
+      } ${disabled ? 'pointer-events-none opacity-50' : ''}`}
     >
-      {thumbnailDataUrl && (
-        <div className="relative h-10 w-10 shrink-0">
+      <div className="relative h-40 w-full overflow-hidden bg-zinc-950">
+        {displayedThumbnailUrl ? (
           <img
             src={displayedThumbnailUrl}
             alt=""
-            className="h-10 w-10 rounded-lg border border-zinc-800 bg-zinc-950 object-contain"
+            className="h-full w-full object-contain"
           />
-          {/* Mini clip selector — only once a hover has fetched more than one clip; never rendered otherwise. */}
-          {hovered && previewClips.length > 1 && (
-            <>
-              <span
-                role="button"
-                tabIndex={0}
-                aria-label={`Show previous preview clip for ${entry.displayName}`}
-                onClick={(event) => cycleClip(-1, event)}
-                onKeyDown={(event) => handleCycleKeyDown(-1, event)}
-                className="absolute inset-y-0 left-0 flex w-3.5 cursor-pointer items-center justify-center rounded-l-lg bg-black/60 text-[10px] leading-none text-zinc-100 hover:bg-black/80 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-violet-400"
-              >
-                ‹
-              </span>
-              <span
-                role="button"
-                tabIndex={0}
-                aria-label={`Show next preview clip for ${entry.displayName}`}
-                onClick={(event) => cycleClip(1, event)}
-                onKeyDown={(event) => handleCycleKeyDown(1, event)}
-                className="absolute inset-y-0 right-0 flex w-3.5 cursor-pointer items-center justify-center rounded-r-lg bg-black/60 text-[10px] leading-none text-zinc-100 hover:bg-black/80 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-violet-400"
-              >
-                ›
-              </span>
-            </>
-          )}
+        ) : (
+          <AssetLibraryPreviewPlaceholder />
+        )}
+        {activeFrameUrl && (
+          <span className="absolute left-2 top-2 rounded-full border border-violet-300/30 bg-violet-950/80 px-2 py-1 text-[9px] font-medium text-violet-100">
+            Playing
+          </span>
+        )}
+        {family.entries.length > 1 && (
+          <span className="absolute right-2 top-2 rounded-full border border-zinc-600 bg-black/75 px-2 py-1 text-[9px] font-medium text-zinc-100">
+            {family.entries.length} versions
+          </span>
+        )}
+      </div>
+      {clipControls}
+      <div className="p-3">
+        <div className="flex items-start justify-between gap-2">
+          <h3 className="min-w-0 truncate text-xs font-semibold text-zinc-100">{family.name}</h3>
+          <span className="shrink-0 text-[9px] text-zinc-500">{dateLabel}</span>
         </div>
-      )}
-      <div className="min-w-0 flex-1">
-        <div className="flex items-center justify-between gap-2">
-          <span className="truncate text-xs font-medium">{entry.displayName}</span>
-          <span className="shrink-0 text-[10px] uppercase tracking-wider text-zinc-500">{entry.capability ?? entry.state.replace(/-/g, ' ')}</span>
+        <div className="mt-2 flex min-h-5 flex-wrap gap-1">
+          {badges.slice(0, 4).map((badge) => (
+            <span key={badge} className={`rounded-full px-2 py-0.5 text-[9px] ${
+              badge === 'Needs name' ? 'bg-amber-500/15 text-amber-200' : 'bg-zinc-800 text-zinc-300'
+            }`}>{badge}</span>
+          ))}
         </div>
-        <p className="mt-1 truncate text-[10px] text-zinc-500">{entry.workspacePath}</p>
+        <p className="mt-2 truncate border-t border-zinc-800 pt-2 text-[9px] text-zinc-500" title={entry.workspacePath}>
+          Stored at {entry.workspacePath}
+        </p>
+        {family.entries.length > 1 && (
+          <button
+            type="button"
+            aria-expanded={versionsExpanded}
+            onClick={(event) => {
+              event.preventDefault()
+              event.stopPropagation()
+              setVersionsExpanded((current) => !current)
+            }}
+            className="mt-2 w-full rounded-lg border border-violet-400/20 bg-violet-500/10 px-2 py-1.5 text-[10px] font-medium text-violet-200 hover:bg-violet-500/20"
+          >
+            {versionsExpanded ? 'Hide version family' : `Show all ${family.entries.length} versions`}
+          </button>
+        )}
       </div>
-    </button>
+      {versionsExpanded && <AssetLibraryVersionRows family={family} selectedEntryId={selectedEntryId} onActivateEntry={activateEntry} />}
+    </article>
   )
 }
 
+function AssetLibraryVersionRows({
+  family,
+  selectedEntryId,
+  onActivateEntry,
+}: {
+  family: AssetLibraryLineageFamily
+  selectedEntryId: string | null
+  onActivateEntry: (entryId: string, event?: React.SyntheticEvent) => void
+}) {
+  return (
+    <div className="border-t border-zinc-700 bg-zinc-950/70 p-2">
+      <p className="px-1 pb-1.5 text-[9px] font-medium uppercase tracking-wider text-zinc-500">Version family</p>
+      <div className="space-y-1">
+        {family.entries.map((entry, index) => (
+          <button
+            key={entry.id}
+            type="button"
+            onClick={(event) => onActivateEntry(entry.id, event)}
+            className={`flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-left hover:bg-zinc-800 ${
+              entry.id === selectedEntryId ? 'bg-violet-500/15' : ''
+            }`}
+          >
+            <span className="w-11 shrink-0 text-[9px] font-medium text-zinc-300">{index === 0 ? 'Latest' : `Older ${index}`}</span>
+            <span className="min-w-0 flex-1 truncate text-[9px] text-zinc-400" title={entry.workspacePath}>{entry.workspacePath}</span>
+            <span className="shrink-0 text-[8px] text-zinc-600">{formatAssetLibraryDate(entry.createdAt)}</span>
+          </button>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+function AssetLibraryPreviewPlaceholder() {
+  return (
+    <div className="flex h-full w-full items-center justify-center text-zinc-700" aria-hidden="true">
+      <svg width="36" height="36" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.2">
+        <path d="m12 2 8 4.5v9L12 20l-8-4.5v-9L12 2Z" />
+        <path d="m4 6.5 8 4.5 8-4.5M12 11v9" />
+      </svg>
+    </div>
+  )
+}
+
+function formatAssetLibraryDate(value: string | undefined): string {
+  if (!value) return 'Unknown date'
+  const date = new Date(value)
+  if (!Number.isFinite(date.getTime())) return 'Unknown date'
+  return date.toLocaleDateString(undefined, { month: 'short', day: 'numeric' })
+}
+
 // ---------------------------------------------------------------------------
 // GeneratePage
 // ---------------------------------------------------------------------------
@@ -854,7 +1123,9 @@ export default function GeneratePage(): JSX.Element {
   const [libraryOpening, setLibraryOpening] = useState(false)
   const [libraryError, setLibraryError] = useState<string | null>(null)
   const [librarySearchQuery, setLibrarySearchQuery] = useState('')
-  const [librarySortMode, setLibrarySortMode] = useState<AssetLibrarySortMode>('type')
+  const [librarySortMode, setLibrarySortMode] = useState<AssetLibrarySortMode>('date')
+  const [libraryViewMode, setLibraryViewMode] = useState<AssetLibraryViewMode>('gallery')
+  const [libraryFilters, setLibraryFilters] = useState<AssetLibraryFilters>(() => createDefaultAssetLibraryFilters())
   const [libraryCollapsedSectionKeys, setLibraryCollapsedSectionKeys] = useState<string[]>(() => getDefaultAssetLibraryCollapsedSectionKeys())
   const [libraryThumbnails, setLibraryThumbnails] = useState<Record<string, string>>({})
   const [libraryPreviews, setLibraryPreviews] = useState<Record<string, AssetLibraryPreviewClip[]>>({})
@@ -1060,10 +1331,18 @@ export default function GeneratePage(): JSX.Element {
         setLibraryError(result.error.message)
         return
       }
+      const defaultPrimaryEntry = buildAssetLibraryProjectGroups(
+        result.entries,
+        '',
+        'date',
+        createDefaultAssetLibraryFilters(),
+      )
+        .flatMap((group) => group.families.map((family) => family.primaryEntry))
+        .find(isAssetLibraryEntryOpenable)
       setLibraryEntries(result.entries)
       setLibrarySelectedEntryId((current) => current && result.entries.some((entry) => entry.id === current)
         ? current
-        : result.entries.find(isAssetLibraryEntryOpenable)?.id ?? result.entries[0]?.id ?? null)
+        : defaultPrimaryEntry?.id ?? result.entries.find(isAssetLibraryEntryOpenable)?.id ?? result.entries[0]?.id ?? null)
       setLibraryLoaded(true)
       void loadLibraryThumbnails(result.entries)
     } catch (err) {
@@ -1377,6 +1656,8 @@ export default function GeneratePage(): JSX.Element {
                 error={libraryError}
                 searchQuery={librarySearchQuery}
                 sortMode={librarySortMode}
+                viewMode={libraryViewMode}
+                filters={libraryFilters}
                 collapsedSectionKeys={libraryCollapsedSectionKeys}
                 thumbnails={libraryThumbnails}
                 previews={libraryPreviews}
@@ -1385,6 +1666,8 @@ export default function GeneratePage(): JSX.Element {
                 onActivateEntry={(entryId) => { void handleActivateLibraryEntry(entryId) }}
                 onSearchQueryChange={setLibrarySearchQuery}
                 onSortModeChange={setLibrarySortMode}
+                onViewModeChange={setLibraryViewMode}
+                onFiltersChange={setLibraryFilters}
                 onToggleSection={(sectionKey) => setLibraryCollapsedSectionKeys((current) => toggleAssetLibrarySectionKey(current, sectionKey))}
                 onOpenSelected={() => { void handleOpenSelectedLibraryEntry() }}
                 onFetchPreviewFrame={fetchLibraryPreviewFrame}
diff --git a/src/areas/generate/assetLibraryProjection.ts b/src/areas/generate/assetLibraryProjection.ts
index b65f5b50..1a6369d3 100644
--- a/src/areas/generate/assetLibraryProjection.ts
+++ b/src/areas/generate/assetLibraryProjection.ts
@@ -21,7 +21,7 @@ export interface AssetLibraryScopeGroup {
 
 function isSafeWorkspacePath(workspacePath: string): boolean {
   const normalized = workspacePath.replace(/\\/g, '/').trim()
-  return /^(Workflows|Exports)\//.test(normalized)
+  return /^(Default|Workflows|Exports)\//.test(normalized)
     && !normalized.split('/').includes('..')
     && !/%2e|%2f|%5c/i.test(normalized)
     && !normalized.startsWith('/')
@@ -40,9 +40,22 @@ export function projectAssetLibraryEntry(entry: AssetLibraryEntry): ProjectedAss
   }
   const safeSource = entry.source && isSafeWorkspacePath(entry.source.workspacePath) ? entry.source : undefined
   const safeManifest = entry.manifest && isSafeWorkspacePath(entry.manifest.workspacePath) ? entry.manifest : undefined
+  const safeParent = entry.semantic?.derivedFrom?.parent && isSafeWorkspacePath(entry.semantic.derivedFrom.parent.workspacePath)
+    ? entry.semantic.derivedFrom.parent
+    : undefined
+  const safeRoot = entry.semantic?.derivedFrom?.root && isSafeWorkspacePath(entry.semantic.derivedFrom.root.workspacePath)
+    ? entry.semantic.derivedFrom.root
+    : undefined
   if (entry.source && !safeSource) warnings.push('Ignored unsafe source workspace path.')
   if (entry.manifest && !safeManifest) warnings.push('Ignored unsafe manifest workspace path.')
-  return { ...entry, source: safeSource, manifest: safeManifest, warnings: [...new Set(warnings)] }
+  if (entry.semantic?.derivedFrom && (!safeParent || !safeRoot)) warnings.push('Ignored unsafe asset lineage.')
+  const semantic = entry.semantic
+    ? {
+        ...entry.semantic,
+        derivedFrom: safeParent && safeRoot ? { parent: safeParent, root: safeRoot } : undefined,
+      }
+    : undefined
+  return { ...entry, source: safeSource, manifest: safeManifest, semantic, warnings: [...new Set(warnings)] }
 }
 
 export function resolveAssetLibraryOpenTarget(entry: ProjectedAssetLibraryEntry): AssetLibraryOpenTarget {
@@ -80,6 +93,11 @@ export function filterAssetLibraryEntries(entries: ProjectedAssetLibraryEntry[],
     entry.state,
     entry.source?.workspacePath ?? '',
     entry.manifest?.workspacePath ?? '',
+    entry.semantic?.name ?? '',
+    entry.semantic?.project ?? '',
+    ...(entry.semantic?.tags ?? []),
+    entry.semantic?.derivedFrom?.parent.workspacePath ?? '',
+    entry.semantic?.derivedFrom?.root.workspacePath ?? '',
   ].some((value) => value.toLowerCase().includes(needle)))
 }
 
diff --git a/src/areas/generate/assetLibraryUi.test.ts b/src/areas/generate/assetLibraryUi.test.ts
index 70013acc..145ab6be 100644
--- a/src/areas/generate/assetLibraryUi.test.ts
+++ b/src/areas/generate/assetLibraryUi.test.ts
@@ -3,11 +3,13 @@ import test from 'node:test'
 
 import {
   buildAssetLibraryOpenRequest,
+  buildAssetLibraryProjectGroups,
   clampAssetLibraryPanelHeight,
   clampAssetLibraryPanelWidth,
   createAssetLibraryOpenJob,
+  createDefaultAssetLibraryFilters,
   describeAssetLibraryOpenability,
-  filterAssetLibraryScopeGroups,
+  formatAssetLibraryClipName,
   getDefaultAssetLibraryCollapsedSectionKeys,
   getStoredAssetLibraryPanelHeight,
   getStoredAssetLibraryPanelWidth,
@@ -17,6 +19,7 @@ import {
   storeAssetLibraryPanelHeight,
   storeAssetLibraryPanelWidth,
   toggleAssetLibrarySectionKey,
+  type AssetLibraryFilters,
   type AssetLibrarySortMode,
   type GenerateOpenPanel,
 } from './assetLibraryUi.ts'
@@ -25,83 +28,136 @@ import type { AssetLibraryEntry } from '../../shared/types/assetLibrary.ts'
 
 function entry(overrides: Partial<AssetLibraryEntry> = {}): ProjectedAssetLibraryEntry {
   const base: AssetLibraryEntry = {
-    id: 'library:Workflows/hero.glb',
-    workspacePath: 'Workflows/hero.glb',
+    id: 'library:Default/hero.glb',
+    workspacePath: 'Default/hero.glb',
     displayName: 'hero.glb',
-    sourceScope: 'workflows',
+    sourceScope: 'generated',
     capability: 'mesh',
     state: 'ready',
     previewKind: '3d-model',
     warnings: [],
     openable: true,
     createdAt: '2026-06-16T10:00:00.000Z',
+    semantic: { name: 'Hero', tags: ['mid-poly'] },
     ...overrides,
   }
   return projectAssetLibraryEntry(base)
 }
 
-function groupPaths(entries: ProjectedAssetLibraryEntry[], search = '', sortMode: AssetLibrarySortMode = 'type'): string[] {
-  return filterAssetLibraryScopeGroups(entries, search, sortMode).flatMap((scopeGroup) => (
-    scopeGroup.entryGroups.flatMap((group) => group.entries.map((item) => item.workspacePath))
-  ))
+const root = entry({
+  id: 'root',
+  workspacePath: 'Default/hero.glb',
+  displayName: 'Hero',
+  createdAt: '2026-06-15T10:00:00.000Z',
+  semantic: { name: 'Hero', tags: ['mid-poly'] },
+})
+
+const derived = entry({
+  id: 'derived',
+  workspacePath: 'Exports/adventure/hero-rigged.glb',
+  displayName: 'Hero Rigged',
+  sourceScope: 'exports',
+  capability: 'rigged-mesh',
+  createdAt: '2026-06-18T10:00:00.000Z',
+  semantic: {
+    name: 'Hero Rigged',
+    project: 'Adventure',
+    tags: ['rigged', 'animated', 'character', 'mid-poly', 'clip-hero-walk'],
+    derivedFrom: {
+      parent: { workspacePath: 'Default/hero.glb', displayName: 'Hero' },
+      root: { workspacePath: 'Default/hero.glb', displayName: 'Hero' },
+    },
+  },
+})
+
+const prop = entry({
+  id: 'prop',
+  workspacePath: 'Exports/props/chair.glb',
+  displayName: 'Chair',
+  sourceScope: 'exports',
+  createdAt: '2026-06-17T10:00:00.000Z',
+  semantic: { name: 'Chair', project: 'Props', tags: ['prop', 'low-poly', 'textured'] },
+})
+
+const unnamed = entry({
+  id: 'unnamed',
+  workspacePath: 'Workflows/run/1785_abcd.glb',
+  displayName: '1785_abcd.glb',
+  sourceScope: 'workflows',
+  createdAt: '2026-06-19T10:00:00.000Z',
+  semantic: { tags: ['unnamed', 'high-poly'] },
+})
+
+function groups(
+  entries: ProjectedAssetLibraryEntry[],
+  search = '',
+  sortMode: AssetLibrarySortMode = 'date',
+  filters: AssetLibraryFilters = createDefaultAssetLibraryFilters(),
+) {
+  return buildAssetLibraryProjectGroups(entries, search, sortMode, filters)
 }
 
-test('organizes visible library assets by scope and capability with collapsible section keys', () => {
-  const entries = [
-    entry({ id: 'workflow-mesh', workspacePath: 'Workflows/run/hero.glb', displayName: 'hero.glb', sourceScope: 'workflows', capability: 'mesh' }),
-    entry({ id: 'export-rig', workspacePath: 'Exports/rig/hero-rig.gltf', displayName: 'hero-rig.gltf', sourceScope: 'exports', capability: 'rigged-mesh' }),
-    entry({ id: 'hidden-cache', workspacePath: 'Workflows/run/cache/internal.glb', displayName: 'internal.glb', sourceScope: 'workflows' }),
-    entry({ id: 'unsupported', workspacePath: 'Exports/readme.txt', displayName: 'readme.txt', sourceScope: 'exports', state: 'unsupported', openable: false }),
-  ]
-
-  const groups = filterAssetLibraryScopeGroups(entries, '', 'type')
-  assert.deepEqual(groups.map((group) => [group.sourceScope, group.entryGroups.map((entryGroup) => entryGroup.capability)]), [
-    ['workflows', ['mesh']],
-    ['exports', ['rigged-mesh']],
-  ])
-  assert.deepEqual(groupPaths(entries), ['Workflows/run/hero.glb', 'Exports/rig/hero-rig.gltf'])
-  assert.equal(getDefaultAssetLibraryCollapsedSectionKeys().includes('scope:workflows'), true)
-  assert.deepEqual(toggleAssetLibrarySectionKey(['scope:workflows'], 'scope:workflows'), [])
-  assert.deepEqual(toggleAssetLibrarySectionKey([], 'scope:exports'), ['scope:exports'])
+test('groups by project and collapses every version that shares a lineage root', () => {
+  const result = groups([root, derived, prop, unnamed])
+
+  assert.deepEqual(result.map((group) => group.projectLabel), ['Adventure', 'Props', 'Needs project'])
+  const heroFamily = result[0].families[0]
+  assert.equal(heroFamily.rootWorkspacePath, 'Default/hero.glb')
+  assert.equal(heroFamily.primaryEntry.id, 'derived')
+  assert.deepEqual(heroFamily.entries.map((item) => item.id), ['derived', 'root'])
+  assert.equal(result.reduce((count, group) => count + group.families.length, 0), 3)
+  assert.equal(result.reduce((count, group) => count + group.entryCount, 0), 4)
+  assert.deepEqual(getDefaultAssetLibraryCollapsedSectionKeys(), [])
+  assert.deepEqual(toggleAssetLibrarySectionKey([], 'project:adventure'), ['project:adventure'])
 })
 
-test('searches workspace assets by name path capability scope source and manifest while supporting name/date sorting', () => {
-  const entries = [
-    entry({ id: 'b', workspacePath: 'Workflows/run/zebra.glb', displayName: 'zebra.glb', sourceScope: 'workflows', capability: 'mesh', createdAt: '2026-06-15T10:00:00.000Z' }),
-    entry({ id: 'a', workspacePath: 'Exports/rig/alpha.gltf', displayName: 'alpha.gltf', sourceScope: 'exports', capability: 'rigged-mesh', createdAt: '2026-06-16T10:00:00.000Z' }),
-    entry({
-      id: 'c', workspacePath: 'Exports/motion/walk.json', displayName: 'walk.json', sourceScope: 'exports', capability: 'animation-motion', openable: false, previewKind: 'text',
-      source: { workspacePath: 'Workflows/run/zebra.glb', displayName: 'zebra.glb' },
-      manifest: { workspacePath: 'Exports/motion/walk.scene.json', capability: 'scene-manifest' },
-    }),
-  ]
-
-  assert.deepEqual(groupPaths(entries, 'rigged'), ['Exports/rig/alpha.gltf'])
-  assert.deepEqual(groupPaths(entries, 'walk.scene'), ['Exports/motion/walk.json'])
-  assert.deepEqual(groupPaths(entries, 'zebra.glb'), ['Workflows/run/zebra.glb', 'Exports/motion/walk.json'])
-  assert.deepEqual(groupPaths(entries, 'exports', 'name'), ['Exports/rig/alpha.gltf', 'Exports/motion/walk.json'])
-  assert.deepEqual(groupPaths(entries, '', 'date'), ['Workflows/run/zebra.glb', 'Exports/rig/alpha.gltf', 'Exports/motion/walk.json'])
+test('searches semantic metadata and lineage while filters answer real asset questions', () => {
+  const entries = [root, derived, prop, unnamed]
+
+  assert.deepEqual(groups(entries, 'clip-hero-walk').map((group) => group.projectLabel), ['Adventure'])
+  assert.deepEqual(groups(entries, 'Default/hero.glb')[0].families[0].entries.map((item) => item.id), ['derived', 'root'])
+  assert.deepEqual(groups(entries, 'props').map((group) => group.projectLabel), ['Props'])
+
+  assert.deepEqual(groups(entries, '', 'date', { kind: 'rigged', poly: 'all', needsAttention: false }).map((group) => group.projectLabel), ['Adventure'])
+  assert.deepEqual(groups(entries, '', 'date', { kind: 'animated', poly: 'all', needsAttention: false }).map((group) => group.projectLabel), ['Adventure'])
+  assert.deepEqual(groups(entries, '', 'date', { kind: 'character', poly: 'all', needsAttention: false }).map((group) => group.projectLabel), ['Adventure'])
+  assert.deepEqual(groups(entries, '', 'date', { kind: 'prop', poly: 'all', needsAttention: false }).map((group) => group.projectLabel), ['Props'])
+  assert.deepEqual(groups(entries, '', 'date', { kind: 'all', poly: 'high-poly', needsAttention: false }).map((group) => group.projectLabel), ['Needs project'])
+  assert.deepEqual(groups(entries, '', 'date', { kind: 'all', poly: 'all', needsAttention: true }).map((group) => group.projectLabel), ['Needs project'])
 })
 
-test('opens only safe glb and gltf entries through existing Generate job and history state', () => {
-  const glb = entry({ workspacePath: 'Workflows/run/hero.glb', displayName: 'hero.glb' })
-  const ply = entry({ workspacePath: 'Exports/scan.ply', displayName: 'scan.ply', openable: false, nonOpenableReason: 'Only .glb/.gltf workspace assets are openable in this release.' })
+test('defaults to newest-first families and retains name and type sorting', () => {
+  const olderProp = entry({
+    id: 'older-prop',
+    workspacePath: 'Exports/props/table.glb',
+    displayName: 'Table',
+    sourceScope: 'exports',
+    createdAt: '2026-06-14T10:00:00.000Z',
+    semantic: { name: 'Table', project: 'Props', tags: ['prop', 'high-poly'] },
+  })
+
+  assert.deepEqual(groups([olderProp, prop])[0].families.map((family) => family.name), ['Chair', 'Table'])
+  assert.deepEqual(groups([olderProp, prop], '', 'name')[0].families.map((family) => family.name), ['Chair', 'Table'])
+  assert.deepEqual(groups([root, derived, prop], '', 'type').flatMap((group) => group.families.map((family) => family.name)), ['Hero Rigged', 'Chair'])
+})
+
+test('opens safe Default, Workflows, and Exports models through existing Generate job state', () => {
+  const glb = entry({ workspacePath: 'Default/hero.glb', displayName: 'Hero' })
+  const ply = entry({ workspacePath: 'Exports/scan.ply', displayName: 'scan.ply', sourceScope: 'exports', openable: false, nonOpenableReason: 'Only .glb/.gltf workspace assets are openable in this release.' })
 
   assert.equal(isAssetLibraryEntryOpenable(glb), true)
   assert.equal(isAssetLibraryEntryOpenable(ply), false)
   assert.equal(describeAssetLibraryOpenability(glb), 'Ready to open this asset directly in Generate.')
   assert.equal(describeAssetLibraryOpenability(ply), 'Only .glb/.gltf workspace assets are openable in this release.')
-  assert.deepEqual(buildAssetLibraryOpenRequest(glb), { workspacePath: 'Workflows/run/hero.glb' })
+  assert.deepEqual(buildAssetLibraryOpenRequest(glb), { workspacePath: 'Default/hero.glb' })
 
   const target = resolveAssetLibraryOpenTarget(glb)
   assert.equal(target.kind, 'self')
   if (target.kind !== 'self') throw new Error('expected self target')
 
   const selection = createAssetLibraryOpenJob(glb, target, 1718546400000)
-  assert.equal(selection.historyUrl, '/workspace/Workflows/run/hero.glb')
+  assert.equal(selection.historyUrl, '/workspace/Default/hero.glb')
   assert.equal(selection.job.status, 'done')
-  assert.equal(selection.job.outputUrl, '/workspace/Workflows/run/hero.glb')
-  assert.equal(selection.job.originalOutputUrl, '/workspace/Workflows/run/hero.glb')
   assert.equal(resolveOpenPanelAfterLibrarySelection('library' satisfies GenerateOpenPanel), 'library')
 })
 
@@ -110,60 +166,42 @@ test('builds linked-source open requests and import jobs for safe sidecars', ()
     id: 'sidecar',
     workspacePath: 'Workflows/run/hero.landmarks.v1.json',
     displayName: 'hero.landmarks.v1.json',
+    sourceScope: 'workflows',
     capability: 'landmarks-sidecar',
     previewKind: 'text',
     openable: false,
-    source: { workspacePath: 'Workflows/run/hero.glb', displayName: 'hero.glb' },
+    source: { workspacePath: 'Default/hero.glb', displayName: 'hero.glb' },
   })
 
   assert.equal(isAssetLibraryEntryOpenable(sidecar), true)
-  assert.equal(describeAssetLibraryOpenability(sidecar), 'Ready to open linked source hero.glb in Generate.')
   assert.deepEqual(buildAssetLibraryOpenRequest(sidecar), {
     workspacePath: 'Workflows/run/hero.landmarks.v1.json',
-    sourceWorkspacePath: 'Workflows/run/hero.glb',
+    sourceWorkspacePath: 'Default/hero.glb',
   })
-
-  const target = resolveAssetLibraryOpenTarget(sidecar)
-  assert.equal(target.kind, 'linked-source')
-  if (target.kind !== 'linked-source') throw new Error('expected linked source target')
-  const selection = createAssetLibraryOpenJob(sidecar, target, 1718546400001)
-  assert.equal(selection?.historyUrl, '/workspace/Workflows/run/hero.glb')
-  assert.equal(selection?.job.outputUrl, '/workspace/Workflows/run/hero.glb')
 })
 
-test('Library panel width clamps to sane bounds and degrades silently without a localStorage', () => {
-  assert.equal(clampAssetLibraryPanelWidth(0), 380)
-  assert.equal(clampAssetLibraryPanelWidth(9999), 960)
+test('Library panel clamps to gallery-safe bounds and degrades silently without localStorage', () => {
+  assert.equal(clampAssetLibraryPanelWidth(0), 560)
+  assert.equal(clampAssetLibraryPanelWidth(9999), 1200)
   assert.equal(clampAssetLibraryPanelWidth(700), 700)
-  // A prior session's narrow, dragged-down width must clamp back up to the new floor.
-  assert.equal(clampAssetLibraryPanelWidth(280), 380)
-  // node --test has no `localStorage` global — both helpers must fall back rather than throw.
-  assert.equal(getStoredAssetLibraryPanelWidth(), 640)
+  assert.equal(getStoredAssetLibraryPanelWidth(), 880)
   assert.doesNotThrow(() => storeAssetLibraryPanelWidth(700))
-})
 
-test('Library panel height clamps to sane bounds and degrades silently without a localStorage', () => {
-  assert.equal(clampAssetLibraryPanelHeight(0), 280)
-  assert.equal(clampAssetLibraryPanelHeight(9999), 1000)
+  assert.equal(clampAssetLibraryPanelHeight(0), 420)
+  assert.equal(clampAssetLibraryPanelHeight(9999), 1200)
   assert.equal(clampAssetLibraryPanelHeight(500), 500)
-  // node --test has no `localStorage` global — both helpers must fall back rather than throw.
-  assert.equal(getStoredAssetLibraryPanelHeight(), 860)
+  assert.equal(getStoredAssetLibraryPanelHeight(), 900)
   assert.doesNotThrow(() => storeAssetLibraryPanelHeight(500))
 })
 
-test('a live search always shows matched sections, and clearing it falls back to the untouched collapsed-key state', () => {
-  const collapsed = ['scope:workflows', 'capability:workflows:mesh']
-
-  // Nothing typed yet: rendering follows the real collapsed-key list.
-  assert.equal(isAssetLibrarySectionExpanded(collapsed, 'scope:workflows', false), false)
-  assert.equal(isAssetLibrarySectionExpanded(collapsed, 'scope:exports', false), true)
-
-  // A live search forces every visible (already-filtered-to-matches) section open,
-  // regardless of what's actually in collapsedSectionKeys.
-  assert.equal(isAssetLibrarySectionExpanded(collapsed, 'scope:workflows', true), true)
-  assert.equal(isAssetLibrarySectionExpanded(collapsed, 'capability:workflows:mesh', true), true)
+test('live discovery expands matching projects without overwriting collapse state', () => {
+  const collapsed = ['project:adventure']
+  assert.equal(isAssetLibrarySectionExpanded(collapsed, 'project:adventure', false), false)
+  assert.equal(isAssetLibrarySectionExpanded(collapsed, 'project:props', false), true)
+  assert.equal(isAssetLibrarySectionExpanded(collapsed, 'project:adventure', true), true)
+})
 
-  // Clearing the query (hasActiveSearch: false) restores exactly the prior state —
-  // collapsedSectionKeys was never mutated by the search itself.
-  assert.equal(isAssetLibrarySectionExpanded(collapsed, 'scope:workflows', false), false)
+test('formats machine clip names as legible animation names', () => {
+  assert.equal(formatAssetLibraryClipName('slow_turn_glance'), 'Slow Turn Glance')
+  assert.equal(formatAssetLibraryClipName('RigAction'), 'Rig Action')
 })
diff --git a/src/areas/generate/assetLibraryUi.ts b/src/areas/generate/assetLibraryUi.ts
index 03355e78..bd07fc35 100644
--- a/src/areas/generate/assetLibraryUi.ts
+++ b/src/areas/generate/assetLibraryUi.ts
@@ -3,20 +3,33 @@ import type { AssetLibraryOpenRequest } from '../../shared/types/assetLibrary'
 import { resolveAssetLibraryOpenTarget, type AssetLibraryOpenTarget, type ProjectedAssetLibraryEntry } from './assetLibraryProjection'
 
 export type GenerateOpenPanel = 'export' | 'decimate' | 'smooth' | 'import' | 'library' | 'light' | null
-export type AssetLibrarySortMode = 'type' | 'name' | 'date'
+export type AssetLibrarySortMode = 'date' | 'name' | 'type'
+export type AssetLibraryViewMode = 'gallery' | 'list'
+export type AssetLibraryKindFilter = 'all' | 'rigged' | 'animated' | 'character' | 'prop'
+export type AssetLibraryPolyFilter = 'all' | 'low-poly' | 'mid-poly' | 'high-poly'
+
+export interface AssetLibraryFilters {
+  kind: AssetLibraryKindFilter
+  poly: AssetLibraryPolyFilter
+  needsAttention: boolean
+}
 
-export interface AssetLibraryEntryGroup {
-  capability: NonNullable<ProjectedAssetLibraryEntry['capability']>
-  capabilityLabel: string
-  sectionKey: string
+export interface AssetLibraryLineageFamily {
+  key: string
+  rootWorkspacePath: string
+  name: string
+  project?: string
   entries: ProjectedAssetLibraryEntry[]
+  primaryEntry: ProjectedAssetLibraryEntry
+  tags: string[]
 }
 
-export interface AssetLibrarySourceScopeGroup {
-  sourceScope: ProjectedAssetLibraryEntry['sourceScope']
-  sourceScopeLabel: string
+export interface AssetLibraryProjectGroup {
+  projectKey: string
+  projectLabel: string
   sectionKey: string
-  entryGroups: AssetLibraryEntryGroup[]
+  families: AssetLibraryLineageFamily[]
+  entryCount: number
 }
 
 export interface AssetLibraryOpenSelection {
@@ -24,42 +37,36 @@ export interface AssetLibraryOpenSelection {
   job: GenerationJob
 }
 
-const ASSET_LIBRARY_CAPABILITY_SECTIONS = [
-  { capability: 'mesh', label: 'Mesh' },
-  { capability: 'rigged-mesh', label: 'Rigged mesh' },
-  { capability: 'animation-motion', label: 'Animations/motions' },
-  { capability: 'landmarks-sidecar', label: 'Landmarks sidecars' },
-  { capability: 'generated-world', label: 'Generated worlds' },
-  { capability: 'scene-manifest', label: 'Scene manifests' },
-] as const satisfies ReadonlyArray<{ capability: NonNullable<ProjectedAssetLibraryEntry['capability']>, label: string }>
-
-const ASSET_LIBRARY_SOURCE_SCOPE_SECTIONS = [
-  { sourceScope: 'workflows', label: 'Workflows' },
-  { sourceScope: 'exports', label: 'Exports' },
-] as const satisfies ReadonlyArray<{ sourceScope: ProjectedAssetLibraryEntry['sourceScope'], label: string }>
+export const ASSET_LIBRARY_SORT_OPTIONS = [
+  { value: 'date', label: 'Recently added' },
+  { value: 'name', label: 'Name A–Z' },
+  { value: 'type', label: 'Asset type' },
+] as const satisfies ReadonlyArray<{ value: AssetLibrarySortMode, label: string }>
 
-const ASSET_LIBRARY_CAPABILITY_ORDER = new Map(
-  ASSET_LIBRARY_CAPABILITY_SECTIONS.map((section, index) => [section.capability, index]),
-)
+export const ASSET_LIBRARY_KIND_FILTERS = [
+  { value: 'all', label: 'All assets' },
+  { value: 'rigged', label: 'Rigged' },
+  { value: 'animated', label: 'Animated' },
+  { value: 'character', label: 'Characters' },
+  { value: 'prop', label: 'Props' },
+] as const satisfies ReadonlyArray<{ value: AssetLibraryKindFilter, label: string }>
+
+export const ASSET_LIBRARY_POLY_FILTERS = [
+  { value: 'all', label: 'Any weight' },
+  { value: 'low-poly', label: 'Light' },
+  { value: 'mid-poly', label: 'Medium' },
+  { value: 'high-poly', label: 'Heavy' },
+] as const satisfies ReadonlyArray<{ value: AssetLibraryPolyFilter, label: string }>
 
 const ASSET_LIBRARY_INTERNAL_DIRECTORY_NAMES = new Set(['tmp', 'temp', 'cache'])
+const NEEDS_PROJECT_KEY = 'needs-project'
 
-export const ASSET_LIBRARY_SORT_OPTIONS = [
-  { value: 'type', label: 'Type' },
-  { value: 'name', label: 'Name' },
-  { value: 'date', label: 'Date' },
-] as const satisfies ReadonlyArray<{ value: AssetLibrarySortMode, label: string }>
+export function createDefaultAssetLibraryFilters(): AssetLibraryFilters {
+  return { kind: 'all', poly: 'all', needsAttention: false }
+}
 
 export function getDefaultAssetLibraryCollapsedSectionKeys(): string[] {
-  const sectionKeys = ASSET_LIBRARY_SOURCE_SCOPE_SECTIONS.flatMap((scopeSection) => {
-    const capabilityKeys = ASSET_LIBRARY_CAPABILITY_SECTIONS.map(
-      (capabilitySection) => `capability:${scopeSection.sourceScope}:${capabilitySection.capability}`,
-    )
-
-    return [`scope:${scopeSection.sourceScope}`, ...capabilityKeys]
-  })
-
-  return [...sectionKeys]
+  return []
 }
 
 export function toggleAssetLibrarySectionKey(currentKeys: string[], sectionKey: string): string[] {
@@ -69,18 +76,15 @@ export function toggleAssetLibrarySectionKey(currentKeys: string[], sectionKey:
 }
 
 /**
- * A section renders expanded either because the user left it expanded, or
- * because a live search matched into it — search always wins so results are
- * visible without clicking through "Show" first. Clearing the query falls
- * straight back through to the untouched `collapsedSectionKeys`, so whatever
- * was collapsed before searching stays collapsed after.
+ * Search and semantic filters always expose their matching projects. Clearing
+ * them restores the operator's untouched collapse choices.
  */
 export function isAssetLibrarySectionExpanded(
   collapsedSectionKeys: string[],
   sectionKey: string,
-  hasActiveSearch: boolean,
+  hasActiveDiscovery: boolean,
 ): boolean {
-  return hasActiveSearch || !collapsedSectionKeys.includes(sectionKey)
+  return hasActiveDiscovery || !collapsedSectionKeys.includes(sectionKey)
 }
 
 export function buildAssetLibraryOpenRequest(entry: ProjectedAssetLibraryEntry): AssetLibraryOpenRequest {
@@ -110,53 +114,83 @@ export function filterVisibleAssetLibraryEntries(entries: ProjectedAssetLibraryE
   return entries.filter((entry) => entry.state !== 'unsupported' && !hasInternalAssetLibraryDirectory(entry.workspacePath))
 }
 
-export function filterAssetLibraryScopeGroups(
+export function buildAssetLibraryProjectGroups(
   entries: ProjectedAssetLibraryEntry[],
   searchQuery: string,
   sortMode: AssetLibrarySortMode,
-): AssetLibrarySourceScopeGroup[] {
+  filters: AssetLibraryFilters,
+): AssetLibraryProjectGroup[] {
   const normalizedSearchQuery = normalizeAssetLibrarySearchQuery(searchQuery)
-  const visibleEntries = filterVisibleAssetLibraryEntries(entries)
-
-  return ASSET_LIBRARY_SOURCE_SCOPE_SECTIONS
-    .map((scopeSection) => {
-      const scopeEntries = visibleEntries.filter((entry) => entry.sourceScope === scopeSection.sourceScope)
-      const scopeMatches = normalizedSearchQuery.length > 0 && matchesAssetLibrarySearch(scopeSection.label, normalizedSearchQuery)
-
-      const entryGroups = ASSET_LIBRARY_CAPABILITY_SECTIONS
-        .map((capabilitySection) => {
-          const capabilityEntries = scopeEntries.filter((entry) => entry.capability === capabilitySection.capability)
-          if (capabilityEntries.length === 0) return null
-
-          const capabilityMatches = scopeMatches || (normalizedSearchQuery.length > 0 && matchesAssetLibrarySearch(capabilitySection.label, normalizedSearchQuery))
-          const visibleCapabilityEntries = !normalizedSearchQuery || capabilityMatches
-            ? capabilityEntries
-            : capabilityEntries.filter((entry) => matchesAssetLibraryEntrySearch(entry, normalizedSearchQuery))
-
-          if (visibleCapabilityEntries.length === 0) return null
-
-          return {
-            capability: capabilitySection.capability,
-            capabilityLabel: capabilitySection.label,
-            sectionKey: `capability:${scopeSection.sourceScope}:${capabilitySection.capability}`,
-            entries: sortAssetLibraryEntries(visibleCapabilityEntries, sortMode),
-          }
-        })
-        .filter((group): group is AssetLibraryEntryGroup => group !== null)
-
-      const sortedEntryGroups = sortMode === 'type'
-        ? entryGroups
-        : [...entryGroups].sort((left, right) => compareAssetLibraryEntryGroups(left, right, sortMode))
-
-      if (sortedEntryGroups.length === 0) return null
-      return {
-        sourceScope: scopeSection.sourceScope,
-        sourceScopeLabel: scopeSection.label,
-        sectionKey: `scope:${scopeSection.sourceScope}`,
-        entryGroups: sortedEntryGroups,
-      }
-    })
-    .filter((group): group is AssetLibrarySourceScopeGroup => group !== null)
+  const families = buildAssetLibraryLineageFamilies(filterVisibleAssetLibraryEntries(entries))
+    .filter((family) => (
+      (!normalizedSearchQuery || matchesAssetLibraryFamilySearch(family, normalizedSearchQuery))
+      && family.entries.some((entry) => matchesAssetLibraryFilters(entry, filters))
+    ))
+
+  const groups = new Map<string, AssetLibraryProjectGroup>()
+  for (const family of families) {
+    const projectLabel = family.project ?? 'Needs project'
+    const projectKey = family.project
+      ? normalizeProjectKey(family.project)
+      : NEEDS_PROJECT_KEY
+    const current = groups.get(projectKey) ?? {
+      projectKey,
+      projectLabel,
+      sectionKey: `project:${projectKey}`,
+      families: [],
+      entryCount: 0,
+    }
+    current.families.push(family)
+    current.entryCount += family.entries.length
+    groups.set(projectKey, current)
+  }
+
+  return [...groups.values()]
+    .map((group) => ({
+      ...group,
+      families: [...group.families].sort((left, right) => compareAssetLibraryFamilies(left, right, sortMode)),
+    }))
+    .sort(compareAssetLibraryProjectGroups)
+}
+
+export function buildAssetLibraryLineageFamilies(
+  entries: ProjectedAssetLibraryEntry[],
+): AssetLibraryLineageFamily[] {
+  const grouped = new Map<string, ProjectedAssetLibraryEntry[]>()
+  for (const entry of entries) {
+    const rootWorkspacePath = entry.semantic?.derivedFrom?.root.workspacePath ?? entry.workspacePath
+    grouped.set(rootWorkspacePath, [...(grouped.get(rootWorkspacePath) ?? []), entry])
+  }
+
+  return [...grouped.entries()].map(([rootWorkspacePath, familyEntries]) => {
+    const sortedEntries = [...familyEntries].sort((left, right) => compareAssetLibraryEntries(left, right, 'date'))
+    const primaryEntry = sortedEntries[0]
+    const namedEntry = sortedEntries.find((entry) => entry.semantic?.name)
+    const rootName = sortedEntries
+      .map((entry) => entry.semantic?.derivedFrom?.root.displayName)
+      .find((name): name is string => Boolean(name))
+    const project = primaryEntry.semantic?.project
+      ?? sortedEntries.map((entry) => entry.semantic?.project).find((value): value is string => Boolean(value))
+
+    return {
+      key: rootWorkspacePath,
+      rootWorkspacePath,
+      name: primaryEntry.semantic?.name ?? namedEntry?.semantic?.name ?? rootName ?? primaryEntry.displayName,
+      project,
+      entries: sortedEntries,
+      primaryEntry,
+      tags: [...new Set(sortedEntries.flatMap((entry) => entry.semantic?.tags ?? []))],
+    }
+  })
+}
+
+export function formatAssetLibraryClipName(clip: string): string {
+  const words = clip
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .trim()
+  if (!words) return 'Animation'
+  return words.replace(/\b\w/g, (letter) => letter.toUpperCase())
 }
 
 export function createAssetLibraryOpenJob(
@@ -183,14 +217,11 @@ export function resolveOpenPanelAfterLibrarySelection(currentPanel: GenerateOpen
   return currentPanel === 'library' ? 'library' : currentPanel
 }
 
-// Wide enough that a 40px thumbnail, a readable name, its full workspace path,
-// and its type badge all sit on one row without truncating for typical asset
-// names — narrow (~280px) made the panel unusable even at full height. Raising
-// the minimum (not just the default) also repairs the shape for anyone who
-// already dragged a prior session's panel down toward the old, cramped floor.
-export const ASSET_LIBRARY_PANEL_MIN_WIDTH = 380
-export const ASSET_LIBRARY_PANEL_MAX_WIDTH = 960
-export const ASSET_LIBRARY_PANEL_DEFAULT_WIDTH = 640
+// Gallery-first dimensions: even the narrowest supported panel keeps a
+// motion preview well above the old 40px row thumbnail.
+export const ASSET_LIBRARY_PANEL_MIN_WIDTH = 560
+export const ASSET_LIBRARY_PANEL_MAX_WIDTH = 1200
+export const ASSET_LIBRARY_PANEL_DEFAULT_WIDTH = 880
 
 const ASSET_LIBRARY_PANEL_WIDTH_STORAGE_KEY = 'modly-library-panel-width'
 
@@ -198,7 +229,6 @@ export function clampAssetLibraryPanelWidth(width: number): number {
   return Math.min(ASSET_LIBRARY_PANEL_MAX_WIDTH, Math.max(ASSET_LIBRARY_PANEL_MIN_WIDTH, width))
 }
 
-/** Reads the user's saved Library panel width, falling back to the default when unset, invalid, or unreadable. */
 export function getStoredAssetLibraryPanelWidth(): number {
   try {
     const raw = Number(localStorage.getItem(ASSET_LIBRARY_PANEL_WIDTH_STORAGE_KEY))
@@ -208,18 +238,17 @@ export function getStoredAssetLibraryPanelWidth(): number {
   }
 }
 
-/** Persists the Library panel width so it survives app restarts. */
 export function storeAssetLibraryPanelWidth(width: number): void {
   try {
     localStorage.setItem(ASSET_LIBRARY_PANEL_WIDTH_STORAGE_KEY, String(width))
   } catch {
-    // Ignore quota/private-mode failures — the panel just won't remember its size.
+    // The panel still works when storage is unavailable.
   }
 }
 
-export const ASSET_LIBRARY_PANEL_MIN_HEIGHT = 280
-export const ASSET_LIBRARY_PANEL_MAX_HEIGHT = 1000
-export const ASSET_LIBRARY_PANEL_DEFAULT_HEIGHT = 860
+export const ASSET_LIBRARY_PANEL_MIN_HEIGHT = 420
+export const ASSET_LIBRARY_PANEL_MAX_HEIGHT = 1200
+export const ASSET_LIBRARY_PANEL_DEFAULT_HEIGHT = 900
 
 const ASSET_LIBRARY_PANEL_HEIGHT_STORAGE_KEY = 'modly-library-panel-height'
 
@@ -227,7 +256,6 @@ export function clampAssetLibraryPanelHeight(height: number): number {
   return Math.min(ASSET_LIBRARY_PANEL_MAX_HEIGHT, Math.max(ASSET_LIBRARY_PANEL_MIN_HEIGHT, height))
 }
 
-/** Reads the user's saved Library panel height, falling back to the default when unset, invalid, or unreadable. */
 export function getStoredAssetLibraryPanelHeight(): number {
   try {
     const raw = Number(localStorage.getItem(ASSET_LIBRARY_PANEL_HEIGHT_STORAGE_KEY))
@@ -237,32 +265,42 @@ export function getStoredAssetLibraryPanelHeight(): number {
   }
 }
 
-/** Persists the Library panel height so it survives app restarts. */
 export function storeAssetLibraryPanelHeight(height: number): void {
   try {
     localStorage.setItem(ASSET_LIBRARY_PANEL_HEIGHT_STORAGE_KEY, String(height))
   } catch {
-    // Ignore quota/private-mode failures — the panel just won't remember its size.
+    // The panel still works when storage is unavailable.
   }
 }
 
-function sortAssetLibraryEntries(
-  entries: ProjectedAssetLibraryEntry[],
-  sortMode: AssetLibrarySortMode,
-): ProjectedAssetLibraryEntry[] {
-  return [...entries].sort((left, right) => compareAssetLibraryEntries(left, right, sortMode))
+function compareAssetLibraryProjectGroups(left: AssetLibraryProjectGroup, right: AssetLibraryProjectGroup): number {
+  if (left.projectKey === NEEDS_PROJECT_KEY && right.projectKey !== NEEDS_PROJECT_KEY) return 1
+  if (right.projectKey === NEEDS_PROJECT_KEY && left.projectKey !== NEEDS_PROJECT_KEY) return -1
+  return left.projectLabel.localeCompare(right.projectLabel, undefined, { sensitivity: 'base' })
 }
 
-function compareAssetLibraryEntryGroups(
-  left: AssetLibraryEntryGroup,
-  right: AssetLibraryEntryGroup,
-  sortMode: Exclude<AssetLibrarySortMode, 'type'>,
+function compareAssetLibraryFamilies(
+  left: AssetLibraryLineageFamily,
+  right: AssetLibraryLineageFamily,
+  sortMode: AssetLibrarySortMode,
 ): number {
-  const entryComparison = compareAssetLibraryEntries(left.entries[0], right.entries[0], sortMode)
-  if (entryComparison !== 0) return entryComparison
+  if (sortMode === 'name') {
+    return left.name.localeCompare(right.name, undefined, { sensitivity: 'base' })
+  }
+  if (sortMode === 'type') {
+    const rankDifference = assetLibraryFamilyTypeRank(left) - assetLibraryFamilyTypeRank(right)
+    if (rankDifference !== 0) return rankDifference
+    return left.name.localeCompare(right.name, undefined, { sensitivity: 'base' })
+  }
+  return compareAssetLibraryEntries(left.primaryEntry, right.primaryEntry, 'date')
+}
 
-  return (ASSET_LIBRARY_CAPABILITY_ORDER.get(left.capability) ?? Number.MAX_SAFE_INTEGER)
-    - (ASSET_LIBRARY_CAPABILITY_ORDER.get(right.capability) ?? Number.MAX_SAFE_INTEGER)
+function assetLibraryFamilyTypeRank(family: AssetLibraryLineageFamily): number {
+  if (family.tags.includes('animated')) return 0
+  if (family.tags.includes('rigged')) return 1
+  if (family.tags.includes('character') || family.tags.includes('creature')) return 2
+  if (family.tags.includes('prop')) return 3
+  return 4
 }
 
 function compareAssetLibraryEntries(
@@ -278,10 +316,6 @@ function compareAssetLibraryEntries(
     if (leftTime === null && rightTime !== null) return 1
   }
 
-  return compareAssetLibraryEntryNames(left, right)
-}
-
-function compareAssetLibraryEntryNames(left: ProjectedAssetLibraryEntry, right: ProjectedAssetLibraryEntry): number {
   const displayNameComparison = left.displayName.localeCompare(right.displayName, undefined, { sensitivity: 'base' })
   if (displayNameComparison !== 0) return displayNameComparison
   const workspacePathComparison = left.workspacePath.localeCompare(right.workspacePath, undefined, { sensitivity: 'base' })
@@ -299,8 +333,22 @@ function parseAssetLibrarySortTimestamp(value: string | undefined): number | nul
   return Number.isFinite(epochMs) ? epochMs : null
 }
 
-function normalizeAssetLibrarySearchQuery(searchQuery: string): string {
-  return searchQuery.trim().toLocaleLowerCase()
+function matchesAssetLibraryFilters(entry: ProjectedAssetLibraryEntry, filters: AssetLibraryFilters): boolean {
+  const tags = new Set(entry.semantic?.tags ?? [])
+  const kindMatches = filters.kind === 'all'
+    || (filters.kind === 'rigged' && (tags.has('rigged') || entry.capability === 'rigged-mesh'))
+    || (filters.kind === 'animated' && tags.has('animated'))
+    || (filters.kind === 'character' && ['character', 'characters', 'creature'].some((tag) => tags.has(tag)))
+    || (filters.kind === 'prop' && ['prop', 'props'].some((tag) => tags.has(tag)))
+  const polyMatches = filters.poly === 'all' || tags.has(filters.poly)
+  const attentionMatches = !filters.needsAttention || tags.has('unnamed') || !entry.semantic?.name
+  return kindMatches && polyMatches && attentionMatches
+}
+
+function matchesAssetLibraryFamilySearch(family: AssetLibraryLineageFamily, normalizedSearchQuery: string): boolean {
+  return matchesAssetLibrarySearch(family.name, normalizedSearchQuery)
+    || matchesAssetLibrarySearch(family.project ?? '', normalizedSearchQuery)
+    || family.entries.some((entry) => matchesAssetLibraryEntrySearch(entry, normalizedSearchQuery))
 }
 
 function matchesAssetLibraryEntrySearch(entry: ProjectedAssetLibraryEntry, normalizedSearchQuery: string): boolean {
@@ -312,16 +360,29 @@ function matchesAssetLibraryEntrySearch(entry: ProjectedAssetLibraryEntry, norma
     entry.manifest?.workspacePath,
     entry.capability,
     entry.sourceScope,
+    entry.semantic?.name,
+    entry.semantic?.project,
+    entry.semantic?.derivedFrom?.parent.workspacePath,
+    entry.semantic?.derivedFrom?.root.workspacePath,
     ...entry.warnings,
+    ...(entry.semantic?.tags ?? []),
   ]
     .filter((value): value is string => typeof value === 'string' && value.length > 0)
     .some((value) => matchesAssetLibrarySearch(value, normalizedSearchQuery))
 }
 
+function normalizeAssetLibrarySearchQuery(searchQuery: string): string {
+  return searchQuery.trim().toLocaleLowerCase()
+}
+
 function matchesAssetLibrarySearch(value: string, normalizedSearchQuery: string): boolean {
   return value.toLocaleLowerCase().includes(normalizedSearchQuery)
 }
 
+function normalizeProjectKey(project: string): string {
+  return project.toLocaleLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || NEEDS_PROJECT_KEY
+}
+
 function hasInternalAssetLibraryDirectory(workspacePath: string): boolean {
   const segments = workspacePath.replace(/\\/g, '/').trim().split('/').filter(Boolean)
   return segments.slice(1, -1).some((segment) => segment.startsWith('.') || ASSET_LIBRARY_INTERNAL_DIRECTORY_NAMES.has(segment.toLocaleLowerCase()))
diff --git a/src/shared/types/assetLibrary.test.ts b/src/shared/types/assetLibrary.test.ts
index d9d836f8..68753c1d 100644
--- a/src/shared/types/assetLibrary.test.ts
+++ b/src/shared/types/assetLibrary.test.ts
@@ -29,7 +29,7 @@ test('declares capability-first asset taxonomy without extension categories', ()
   ])
   assert.deepEqual(ASSET_ENTRY_STATES, ['ready', 'unknown-metadata', 'unsupported', 'unsafe'])
   assert.deepEqual(ASSET_LIBRARY_PREVIEW_KINDS, ['3d-model', 'text', 'binary', 'none'])
-  assert.deepEqual(ASSET_LIBRARY_SOURCE_SCOPES, ['workflows', 'exports'])
+  assert.deepEqual(ASSET_LIBRARY_SOURCE_SCOPES, ['generated', 'workflows', 'exports'])
   assert.deepEqual(ASSET_LIBRARY_MANIFEST_CAPABILITIES, ['generated-world', 'scene-manifest'])
   assert.equal((ASSET_CAPABILITIES as readonly string[]).includes('glb'), false)
   assert.equal((ASSET_CAPABILITIES as readonly string[]).includes('splat'), false)
@@ -47,6 +47,16 @@ test('AssetLibraryEntry keeps capability, source scope, provenance, warnings, an
     provenance: { workflowId: 'wf-1', workflowNodeId: 'node-1' },
     warnings: ['Rig metadata was inferred from a sidecar.'],
     openable: true,
+    semantic: {
+      name: 'Hero',
+      project: 'Adventure',
+      tags: ['rigged', 'animated', 'mid-poly'],
+      created: '2026-06-16T10:00:00.000Z',
+      derivedFrom: {
+        parent: { workspacePath: 'Default/hero.glb', displayName: 'Hero' },
+        root: { workspacePath: 'Default/hero.glb', displayName: 'Hero' },
+      },
+    },
   } satisfies AssetLibraryEntry
 
   const list = { success: true, entries: [entry] } satisfies AssetLibraryListResult
@@ -55,6 +65,8 @@ test('AssetLibraryEntry keeps capability, source scope, provenance, warnings, an
   assert.equal(list.entries[0]?.provenance?.workflowId, 'wf-1')
   assert.equal(list.entries[0]?.warnings[0], 'Rig metadata was inferred from a sidecar.')
   assert.equal(list.entries[0]?.openable, true)
+  assert.equal(list.entries[0]?.semantic?.project, 'Adventure')
+  assert.equal(list.entries[0]?.semantic?.derivedFrom?.root.workspacePath, 'Default/hero.glb')
 })
 
 test('structured results preserve renderer-visible error codes and read previews', () => {
diff --git a/src/shared/types/assetLibrary.ts b/src/shared/types/assetLibrary.ts
index 662bc9eb..5f886891 100644
--- a/src/shared/types/assetLibrary.ts
+++ b/src/shared/types/assetLibrary.ts
@@ -11,7 +11,7 @@ export const ASSET_CAPABILITIES = [
 
 export const ASSET_ENTRY_STATES = ['ready', 'unknown-metadata', 'unsupported', 'unsafe'] as const
 export const ASSET_LIBRARY_PREVIEW_KINDS = ['3d-model', 'text', 'binary', 'none'] as const
-export const ASSET_LIBRARY_SOURCE_SCOPES = ['workflows', 'exports'] as const
+export const ASSET_LIBRARY_SOURCE_SCOPES = ['generated', 'workflows', 'exports'] as const
 export const ASSET_LIBRARY_MANIFEST_CAPABILITIES = ['generated-world', 'scene-manifest'] as const
 
 export type AssetCapability = typeof ASSET_CAPABILITIES[number]
@@ -43,6 +43,32 @@ export interface AssetLibraryEntry {
   nonOpenableReason?: string
   createdAt?: string
   updatedAt?: string
+  semantic?: AssetLibrarySemanticMetadata
+}
+
+export interface AssetLibraryLineageLink {
+  workspacePath: string
+  displayName?: string
+}
+
+export interface AssetLibraryDerivedFrom {
+  /** The asset used directly to create this version. */
+  parent: AssetLibraryLineageLink
+  /** The first asset in the version family. */
+  root: AssetLibraryLineageLink
+}
+
+/**
+ * Human and structural metadata stored beside a model in `<model>.tags.json`.
+ * The embedded `asset.extras.modly` copy carries the same name/project/tags
+ * fields; the sidecar additionally owns creation time and lineage.
+ */
+export interface AssetLibrarySemanticMetadata {
+  name?: string
+  project?: string
+  tags: string[]
+  created?: string
+  derivedFrom?: AssetLibraryDerivedFrom
 }
 
 export interface AssetLibrarySourceLink {

From fe08e05fe01d946e1508bb9940e3f6bacab6254b Mon Sep 17 00:00:00 2001
From: JayceeB1 <45721154+JayceeB1@users.noreply.github.com>
Date: Fri, 9 Oct 2026 23:37:01 +0200
Subject: [PATCH 09/11] fix(integration): render free-text exporter parameters
 as text inputs

---
 src/areas/generate/components/WorkflowPanel.tsx | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/areas/generate/components/WorkflowPanel.tsx b/src/areas/generate/components/WorkflowPanel.tsx
index 472ef125..54e40bae 100644
--- a/src/areas/generate/components/WorkflowPanel.tsx
+++ b/src/areas/generate/components/WorkflowPanel.tsx
@@ -169,6 +169,10 @@ function ParamField({ param, value, onChange }: {
       </div>
     )
   }
+  if (param.type === 'text') {
+    return <input type="text" value={value as string} placeholder={param.tooltip ?? ''}
+      onChange={(event) => onChange(event.target.value)} className={inputCls} />
+  }
   if (param.type === 'float') {
     return <FloatInput value={value as number} onChange={(v) => onChange(v)} className={inputCls}
       min={param.min} max={param.max} step={param.step} label={param.label} />

From b9755b1d1d3b124b92a03306f3c311512a0b7b3c Mon Sep 17 00:00:00 2001
From: JayceeB1 <45721154+JayceeB1@users.noreply.github.com>
Date: Fri, 9 Oct 2026 23:38:02 +0200
Subject: [PATCH 10/11] docs(integration): record upstream PR coverage and
 validation blockers

---
 ...experimental-library-integration-ledger.md | 59 +++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 docs/experimental-library-integration-ledger.md

diff --git a/docs/experimental-library-integration-ledger.md b/docs/experimental-library-integration-ledger.md
new file mode 100644
index 00000000..21028973
--- /dev/null
+++ b/docs/experimental-library-integration-ledger.md
@@ -0,0 +1,59 @@
+# Experimental Library & Lineage Integration Ledger — 2026-10-09
+
+> **NOT A RELEASE.** Review branch only. Parent: \`integration/modly-next-2026-10-09\`
+> (upstream v0.4.3 + separate candidate fixes). This port has **not** passed
+> combined npm/TypeScript/Python tests or a Windows desktop smoke test.
+
+## Source PRs ported as separate commits
+
+| Upstream PR | Feature | Port note |
+| --- | --- | --- |
+| [#242](https://github.com/lightningpixel/modly/pull/242) | Animated GLB clips | Corrected malformed upstream JSX fallback \`{clip.name || }\` on our branch, then incorporated the MotionBar replacement from #245. |
+| [#243](https://github.com/lightningpixel/modly/pull/243) | Library thumbnails and width persistence | Reconciled GeneratePage state with current mesh-export UI. |
+| [#244](https://github.com/lightningpixel/modly/pull/244) | Normalize manifest object-shaped input slots | Merged 3 regression cases into the newer existing test file. |
+| [#245](https://github.com/lightningpixel/modly/pull/245) | Motion bar, tag UX, export metadata, panel zoom/resize | Reconciled viewer and parameter controls with 0.4.3; intentionally did not overwrite newer \`package-lock.json\`. Added required free-text param renderer. |
+| [#247](https://github.com/lightningpixel/modly/pull/247) | Taller resizable Library | Reconciled stored height and state refs with current viewer. |
+| [#248](https://github.com/lightningpixel/modly/pull/248) | Wider Library, direct open, hover-preview | Reconciled preview type imports. |
+| [#249](https://github.com/lightningpixel/modly/pull/249) | Gallery grouped by project and lineage | Integrated updated asset-index tests in current suite. |
+
+**Credits:** The work is based on PRs submitted by OmarB97 to Lightning Pixel's
+Modly repository. The adaptations in this fork do not supersede their source PRs.
+
+## Not ported: requires an independent functional adaptation
+
+- **#246 (Chat + asset context):** its old Ollama agent backend does not match
+  current 0.4.3 llama.cpp/chat architecture. The workflow runner input routing
+  also changed. Do not paste the old agent router or silently drop context.
+- **#250 (Optimizer preset semantics):** the source PR targets a legacy
+  \`processor.ts\`, whereas 0.4.3 uses a Python workflow adapter feeding a shared
+  mesh-op registry. A "full detail/no simplification" preset needs a reviewed
+  end-to-end contract that does not alter unrelated direct mesh API calls.
+- **#251 (Workflow parameter binding and library sync):** stack depends on the
+  #250 behavior. Port only after defining stable override precedence and tests.
+- **#252 (Artist intent record and texture hot reload):** much larger divergent
+  patch (workflow and API changes, new watcher services, extra proof assets).
+  Requires separate rebase and validation against 0.4.3 and #246/#251.
+
+## Validation checklist — currently not executed on the combined branch
+
+- [ ] Install dependencies reproducibly and run \`npm run lint\`.
+- [ ] \`npm run test:node\` and \`npm run test:py\`.
+- [ ] \`npx tsc --noEmit -p tsconfig.node.json\`.
+- [ ] \`npm run build\`.
+- [ ] Native Windows checks: launch Electron and load GLB with 1 and 3 clips,
+  switch motion bar clips, unload, and verify mixer teardown.
+- [ ] Check Library thumbnails, previews, project/lineage filters and persistent
+  panel size across restart, with missing/corrupt metadata.
+- [ ] Export rigged GLB/OBJ/STL/PLY, verify transforms/tags and project lineage.
+- [ ] Retry free-text params and object-shaped manifest inputs.
+- [ ] Verify source #370 destructive-storage safeguards and related tests in
+  the final combined branch.
+- [ ] Review source #266 local API security separately (not included).
+
+## Integration rules
+
+1. Keep the user's \`main\` and upstream untouched.
+2. Pin reviewed source PR/commit IDs; credit original contributors.
+3. A matching patch hunk is **not** a passing test.
+4. Do not merge this branch into Modly Next before validating the full
+   app and resolving the remaining integration ledger.

From f755bb252a1d79176ab2aef3481d1c3af4209027 Mon Sep 17 00:00:00 2001
From: JayceeB1 <45721154+JayceeB1@users.noreply.github.com>
Date: Fri, 9 Oct 2026 23:38:48 +0200
Subject: [PATCH 11/11] docs(integration): fix Markdown code-span formatting

---
 .../experimental-library-integration-ledger.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs/experimental-library-integration-ledger.md b/docs/experimental-library-integration-ledger.md
index 21028973..fd4fad9a 100644
--- a/docs/experimental-library-integration-ledger.md
+++ b/docs/experimental-library-integration-ledger.md
@@ -1,6 +1,6 @@
 # Experimental Library & Lineage Integration Ledger — 2026-10-09
 
-> **NOT A RELEASE.** Review branch only. Parent: \`integration/modly-next-2026-10-09\`
+> **NOT A RELEASE.** Review branch only. Parent: `integration/modly-next-2026-10-09`
 > (upstream v0.4.3 + separate candidate fixes). This port has **not** passed
 > combined npm/TypeScript/Python tests or a Windows desktop smoke test.
 
@@ -8,10 +8,10 @@
 
 | Upstream PR | Feature | Port note |
 | --- | --- | --- |
-| [#242](https://github.com/lightningpixel/modly/pull/242) | Animated GLB clips | Corrected malformed upstream JSX fallback \`{clip.name || }\` on our branch, then incorporated the MotionBar replacement from #245. |
+| [#242](https://github.com/lightningpixel/modly/pull/242) | Animated GLB clips | Corrected malformed upstream JSX fallback `{clip.name || }` on our branch, then incorporated the MotionBar replacement from #245. |
 | [#243](https://github.com/lightningpixel/modly/pull/243) | Library thumbnails and width persistence | Reconciled GeneratePage state with current mesh-export UI. |
 | [#244](https://github.com/lightningpixel/modly/pull/244) | Normalize manifest object-shaped input slots | Merged 3 regression cases into the newer existing test file. |
-| [#245](https://github.com/lightningpixel/modly/pull/245) | Motion bar, tag UX, export metadata, panel zoom/resize | Reconciled viewer and parameter controls with 0.4.3; intentionally did not overwrite newer \`package-lock.json\`. Added required free-text param renderer. |
+| [#245](https://github.com/lightningpixel/modly/pull/245) | Motion bar, tag UX, export metadata, panel zoom/resize | Reconciled viewer and parameter controls with 0.4.3; intentionally did not overwrite newer `package-lock.json`. Added required free-text param renderer. |
 | [#247](https://github.com/lightningpixel/modly/pull/247) | Taller resizable Library | Reconciled stored height and state refs with current viewer. |
 | [#248](https://github.com/lightningpixel/modly/pull/248) | Wider Library, direct open, hover-preview | Reconciled preview type imports. |
 | [#249](https://github.com/lightningpixel/modly/pull/249) | Gallery grouped by project and lineage | Integrated updated asset-index tests in current suite. |
@@ -25,7 +25,7 @@ Modly repository. The adaptations in this fork do not supersede their source PRs
   current 0.4.3 llama.cpp/chat architecture. The workflow runner input routing
   also changed. Do not paste the old agent router or silently drop context.
 - **#250 (Optimizer preset semantics):** the source PR targets a legacy
-  \`processor.ts\`, whereas 0.4.3 uses a Python workflow adapter feeding a shared
+  `processor.ts`, whereas 0.4.3 uses a Python workflow adapter feeding a shared
   mesh-op registry. A "full detail/no simplification" preset needs a reviewed
   end-to-end contract that does not alter unrelated direct mesh API calls.
 - **#251 (Workflow parameter binding and library sync):** stack depends on the
@@ -36,10 +36,10 @@ Modly repository. The adaptations in this fork do not supersede their source PRs
 
 ## Validation checklist — currently not executed on the combined branch
 
-- [ ] Install dependencies reproducibly and run \`npm run lint\`.
-- [ ] \`npm run test:node\` and \`npm run test:py\`.
-- [ ] \`npx tsc --noEmit -p tsconfig.node.json\`.
-- [ ] \`npm run build\`.
+- [ ] Install dependencies reproducibly and run `npm run lint`.
+- [ ] `npm run test:node` and `npm run test:py`.
+- [ ] `npx tsc --noEmit -p tsconfig.node.json`.
+- [ ] `npm run build`.
 - [ ] Native Windows checks: launch Electron and load GLB with 1 and 3 clips,
   switch motion bar clips, unload, and verify mixer teardown.
 - [ ] Check Library thumbnails, previews, project/lineage filters and persistent
@@ -52,7 +52,7 @@ Modly repository. The adaptations in this fork do not supersede their source PRs
 
 ## Integration rules
 
-1. Keep the user's \`main\` and upstream untouched.
+1. Keep the user's `main` and upstream untouched.
 2. Pin reviewed source PR/commit IDs; credit original contributors.
 3. A matching patch hunk is **not** a passing test.
 4. Do not merge this branch into Modly Next before validating the full