docs(assets): unify display_name helper docstrings + fixture tests (FE-747)

src/platform/assets/utils/assetMetadataUtils.test.ts

@@ -420,6 +420,46 @@ describe('assetMetadataUtils', () => {
     })
   })
 
+  describe('unified asset response shape (BE-808 RFC)', () => {
+    // Cloud asset: `asset.name` is a content hash; `display_name` carries
+    // the user-facing label.
+    const cloudShape: AssetItem = {
+      ...mockAsset,
+      id: 'cloud-asset-id',
+      name: 'blake3:abc1234567890def.png',
+      hash: 'blake3:abc1234567890def.png',
+      display_name: 'sunset.png'
+    }
+
+    // OSS asset: `asset.name` is already the filename; `display_name` is
+    // nullable per BE-1045 spec — clients fall back to `asset.name`.
+    const ossShape: AssetItem = {
+      ...mockAsset,
+      id: 'oss-asset-id',
+      name: 'sunset.png',
+      hash: null,
+      display_name: undefined
+    }
+
+    it('renders the same label for the Cloud and OSS shapes via getAssetDisplayFilename', () => {
+      expect(getAssetDisplayFilename(cloudShape)).toBe('sunset.png')
+      expect(getAssetDisplayFilename(ossShape)).toBe('sunset.png')
+    })
+
+    it('renders the same label via getAssetCardTitle', () => {
+      expect(getAssetCardTitle(cloudShape)).toBe('sunset.png')
+      expect(getAssetCardTitle(ossShape)).toBe('sunset.png')
+    })
+
+    it('honours OSS-emitted display_name when present', () => {
+      const ossWithDisplayName: AssetItem = {
+        ...ossShape,
+        display_name: 'Curated Sunset'
+      }
+      expect(getAssetDisplayFilename(ossWithDisplayName)).toBe('Curated Sunset')
+    })
+  })
+
   describe('getAssetMetadataDimensions', () => {
     it('returns dimensions when width/height are positive integers', () => {
       const asset = { ...mockAsset, metadata: { width: 1024, height: 768 } }

src/platform/assets/utils/assetMetadataUtils.ts

@@ -189,13 +189,9 @@ export function getAssetStoredFilename(asset: AssetItem): string {
 }
 
 /**
- * Gets the human-readable filename to render in UI surfaces.
- * Fallback chain: user_metadata.filename → metadata.filename →
- * asset.display_name → asset.name.
- *
- * `display_name` is populated by queue output mappers in Cloud where
- * `asset.name` is a content hash. Use this helper for labels/titles only;
- * for serialized identifiers use {@link getAssetFilename}.
+ * Human-readable filename for UI labels.
+ * Fallback: user_metadata.filename → metadata.filename → display_name → asset.name.
+ * For serialized identifiers use {@link getAssetFilename}.
  */
 export function getAssetDisplayFilename(asset: AssetItem): string {
   return (
@@ -208,7 +204,7 @@ export function getAssetDisplayFilename(asset: AssetItem): string {
  * Prefers a user-curated name (user_metadata.name / metadata.name) when it
  * actually differs from asset.name, so a user-renamed model keeps its
  * display name. Falls through to {@link getAssetDisplayFilename} when the
- * curated name is absent or equal to asset.name (Cloud hash case).
+ * curated name is absent or equal to asset.name (hash-keyed asset case).
  */
 export function getAssetCardTitle(asset: AssetItem): string {
   const curatedName = getStringProperty(asset, 'name')