@proulr/sdui-components 0.1.87 → 0.1.90

package/src/renderer/lib/sdui-media-block-props.ts

@@ -0,0 +1,282 @@
+import type { SduiMediaAspectToken, SduiAvatarSizeToken, SduiMediaFitToken, ShapeToken } from '@proulr/sdui-contract';
+import { isSduiSelectedTrue } from '@proulr/sdui-contract';
+import { isAppIconName, type AppIconName } from '../../catalog/app-icon-names';
+
+/**
+ * Parsing puro (node-testável) das props de blocos de mídia/estado
+ * (`content_image`, `avatar`, `icon_button`). Os componentes do renderer
+ * (`blocks/SduiMediaBlocks.tsx`) delegam aqui — nenhum import de
+ * react-native neste módulo.
+ *
+ * Wire é snake_case; acceptamos também a forma camelCase (wires antigos /
+ * props promocionais do BDC) lendo ambos os chaves por prop.
+ */
+
+/** Razões por token de aspecto (BFF escolhe token; px fica no app/lib). */
+export const SDUI_MEDIA_ASPECT_RATIOS: Record<SduiMediaAspectToken, number> = {
+  square: 1,
+  portrait: 4 / 5,
+  story: 9 / 16,
+  video: 16 / 9,
+  wide: 1.91,
+};
+
+/** Px por token de avatar. */
+export const SDUI_AVATAR_SIZES: Record<SduiAvatarSizeToken, number> = {
+  xs: 24,
+  sm: 32,
+  md: 40,
+  lg: 56,
+  xl: 88,
+};
+
+const AVATAR_SIZE_TOKENS = Object.keys(SDUI_AVATAR_SIZES) as SduiAvatarSizeToken[];
+const ASPECT_TOKENS = Object.keys(SDUI_MEDIA_ASPECT_RATIOS) as SduiMediaAspectToken[];
+const FIT_TOKENS: SduiMediaFitToken[] = ['cover', 'contain'];
+const SHAPE_TOKENS: ShapeToken[] = [
+  'cornerExtraSmall',
+  'cornerSmall',
+  'cornerMedium',
+  'cornerLarge',
+  'cornerExtraLarge',
+  'cornerFull',
+];
+
+function readString(props: Record<string, unknown>, ...keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = props[key];
+    if (typeof value === 'string') return value;
+  }
+  return undefined;
+}
+
+function readNumber(props: Record<string, unknown>, key: string): number | undefined {
+  const value = props[key];
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+function readBoolean(props: Record<string, unknown>, key: string): boolean | undefined {
+  const value = props[key];
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function pickToken<T extends string>(value: string | undefined, tokens: T[]): T | undefined {
+  return value && (tokens as string[]).includes(value) ? (value as T) : undefined;
+}
+
+export type SduiContentImageParsed = {
+  /** Path cru (pode ser binding já resolvido pelo materialize); `''` quando ausente. */
+  path: string;
+  width?: number;
+  height?: number;
+  aspectRatio?: number;
+  corner?: ShapeToken;
+  fit: SduiMediaFitToken;
+  blurFill: boolean;
+  testId?: string;
+};
+
+/**
+ * Frame estável para `content_image` (anti-flicker: dimensões vindas do wire,
+ * nunca do carregamento da imagem). Regras:
+ * - width+height → explícitos;
+ * - width-only / height-only → outro lado derivado do aspect (default square);
+ * - aspect-only → `aspectRatio` + `stretch` (ocupa a largura do pai);
+ * - nada → square + `stretch`.
+ */
+export type SduiMediaFrame = {
+  width?: number;
+  height?: number;
+  aspectRatio?: number;
+  stretch: boolean;
+};
+
+export function computeSduiMediaFrame(
+  width: number | undefined,
+  height: number | undefined,
+  aspectRatio: number | undefined,
+): SduiMediaFrame {
+  const ratio = aspectRatio ?? SDUI_MEDIA_ASPECT_RATIOS.square;
+  if (width && height) return { width, height, stretch: false };
+  if (width) return { width, height: width / ratio, stretch: false };
+  if (height) return { width: height * ratio, height, stretch: false };
+  return { aspectRatio: aspectRatio ?? 1, stretch: true };
+}
+
+export function parseSduiContentImageProps(
+  props: Record<string, unknown> | undefined,
+): SduiContentImageParsed {
+  const raw = props ?? {};
+  const fit = pickToken(readString(raw, 'fit'), FIT_TOKENS);
+  return {
+    path: (readString(raw, 'path', 'pathRef', 'path_ref') ?? '').trim(),
+    width: readNumber(raw, 'width'),
+    height: readNumber(raw, 'height'),
+    aspectRatio: (() => {
+      const token = pickToken(readString(raw, 'aspect'), ASPECT_TOKENS);
+      return token ? SDUI_MEDIA_ASPECT_RATIOS[token] : undefined;
+    })(),
+    corner: pickToken(readString(raw, 'corner'), SHAPE_TOKENS),
+    fit: fit ?? 'cover',
+    blurFill: readBoolean(raw, 'blur_fill') === true || readBoolean(raw, 'blurFill') === true,
+    testId: readString(raw, 'test_id', 'testId'),
+  };
+}
+
+/**
+ * Parsing puro das props do bloco `video` (frame genérico; playback é slot do
+ * app). Mesmas regras de frame de `content_image` (anti-flicker: dimensões
+ * vindas do wire). `poster_path` é opcional e binding-capable (já resolvido em
+ * materialize time).
+ */
+export type SduiVideoParsed = {
+  path: string;
+  posterPath?: string;
+  width?: number;
+  height?: number;
+  aspectRatio?: number;
+  corner?: ShapeToken;
+  fit: SduiMediaFitToken;
+  testId?: string;
+};
+
+export function parseSduiVideoProps(props: Record<string, unknown> | undefined): SduiVideoParsed {
+  const raw = props ?? {};
+  const fit = pickToken(readString(raw, 'fit'), FIT_TOKENS);
+  return {
+    path: (readString(raw, 'path', 'pathRef', 'path_ref') ?? '').trim(),
+    posterPath: readString(raw, 'poster_path', 'posterPath')?.trim(),
+    width: readNumber(raw, 'width'),
+    height: readNumber(raw, 'height'),
+    aspectRatio: (() => {
+      const token = pickToken(readString(raw, 'aspect'), ASPECT_TOKENS);
+      return token ? SDUI_MEDIA_ASPECT_RATIOS[token] : undefined;
+    })(),
+    corner: pickToken(readString(raw, 'corner'), SHAPE_TOKENS),
+    fit: fit ?? 'cover',
+    testId: readString(raw, 'test_id', 'testId'),
+  };
+}
+
+/**
+ * Parsing puro do `row_overflow_menu`: normaliza as entradas aninhadas
+ * (`action_id`/`actionId` ambos aceitos), valida ícones contra o catalog
+ * (`isAppIconName`) e aplica o trigger default `overflow`. Toda copy vem do
+ * wire — a lib não inventa strings.
+ */
+export type SduiRowOverflowMenuActionParsed = {
+  actionId: string;
+  label: string;
+  icon: AppIconName | null;
+  destructive: boolean;
+};
+
+export type SduiRowOverflowMenuParsed = {
+  triggerIcon: AppIconName;
+  actions: SduiRowOverflowMenuActionParsed[];
+  testId?: string;
+};
+
+/** Trigger default do overflow (token kebab já existente no catalog). */
+export const SDUI_ROW_OVERFLOW_DEFAULT_ICON: AppIconName = 'overflow';
+
+export function parseSduiRowOverflowMenuProps(
+  props: Record<string, unknown> | undefined,
+): SduiRowOverflowMenuParsed {
+  const raw = props ?? {};
+  const icon = readString(raw, 'icon');
+  const rawActions = Array.isArray(raw.actions) ? (raw.actions as unknown[]) : [];
+  const actions: SduiRowOverflowMenuActionParsed[] = [];
+  for (const value of rawActions) {
+    if (!value || typeof value !== 'object') continue;
+    const entry = value as Record<string, unknown>;
+    const actionId = readString(entry, 'action_id', 'actionId');
+    const label = readString(entry, 'label');
+    if (!actionId || !label) continue;
+    const entryIcon = readString(entry, 'icon');
+    actions.push({
+      actionId,
+      label,
+      icon: entryIcon && isAppIconName(entryIcon) ? entryIcon : null,
+      destructive: entry.destructive === true,
+    });
+  }
+  return {
+    triggerIcon: icon && isAppIconName(icon) ? icon : SDUI_ROW_OVERFLOW_DEFAULT_ICON,
+    actions,
+    testId: readString(raw, 'test_id', 'testId'),
+  };
+}
+
+export type SduiAvatarParsed = {
+  path: string;
+  name?: string;
+  initials?: string;
+  sizePx: number;
+  corner: ShapeToken;
+  testId?: string;
+};
+
+export function parseSduiAvatarProps(props: Record<string, unknown> | undefined): SduiAvatarParsed {
+  const raw = props ?? {};
+  const size = pickToken(readString(raw, 'size'), AVATAR_SIZE_TOKENS);
+  const corner = pickToken(readString(raw, 'corner'), SHAPE_TOKENS);
+  return {
+    path: (readString(raw, 'path', 'pathRef', 'path_ref') ?? '').trim(),
+    name: readString(raw, 'name'),
+    initials: readString(raw, 'initials'),
+    sizePx: size ? SDUI_AVATAR_SIZES[size] : SDUI_AVATAR_SIZES.md,
+    corner: corner ?? 'cornerFull',
+    testId: readString(raw, 'test_id', 'testId'),
+  };
+}
+
+export type SduiIconButtonParsed = {
+  icon: AppIconName | null;
+  selectedIcon: AppIconName | null;
+  actionId?: string;
+  /** Coerção única `selected`: `'true'`/`true` → selecionado (ver `isSduiSelectedTrue`). */
+  selected: boolean;
+  size?: number;
+  color?: string;
+  selectedColor?: string;
+  label?: string;
+  disabled: boolean;
+  testId?: string;
+};
+
+export function parseSduiIconButtonProps(
+  props: Record<string, unknown> | undefined,
+): SduiIconButtonParsed {
+  const raw = props ?? {};
+  const icon = readString(raw, 'icon');
+  const selectedIcon = readString(raw, 'selected_icon', 'selectedIcon');
+  return {
+    icon: icon && isAppIconName(icon) ? icon : null,
+    selectedIcon: selectedIcon && isAppIconName(selectedIcon) ? selectedIcon : null,
+    actionId: readString(raw, 'action_id', 'actionId'),
+    selected: isSduiSelectedTrue(raw.selected),
+    size: readNumber(raw, 'size'),
+    color: readString(raw, 'color'),
+    selectedColor: readString(raw, 'selected_color', 'selectedColor'),
+    label: readString(raw, 'label'),
+    disabled: readBoolean(raw, 'disabled') === true,
+    testId: readString(raw, 'test_id', 'testId'),
+  };
+}
+
+/**
+ * Iniciais a partir do nome de exibição: múltiplas palavras → primeira +
+ * última (estilo WhatsApp/Telegram); palavra única → até 2 letras. Sempre
+ * maiúsculas, máx. 2 caracteres.
+ */
+export function deriveSduiInitials(name: string | undefined): string {
+  if (!name) return '';
+  const words = name
+    .trim()
+    .split(/\s+/)
+    .filter((word) => /[\p{L}\p{N}]/u.test(word));
+  if (words.length === 0) return '';
+  if (words.length === 1) return [...(words[0] as string)].slice(0, 2).join('').toLocaleUpperCase();
+  return ((words[0] as string)[0] + (words[words.length - 1] as string)[0]).toLocaleUpperCase();
+}

package/src/renderer/lib/sdui-media-blocks.test.ts

@@ -0,0 +1,279 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import {
+  SDUI_AVATAR_SIZES,
+  SDUI_MEDIA_ASPECT_RATIOS,
+  SDUI_ROW_OVERFLOW_DEFAULT_ICON,
+  computeSduiMediaFrame,
+  deriveSduiInitials,
+  parseSduiAvatarProps,
+  parseSduiContentImageProps,
+  parseSduiIconButtonProps,
+  parseSduiRowOverflowMenuProps,
+  parseSduiVideoProps,
+} from './sdui-media-block-props';
+import { invokeSduiMediaResolver } from './sdui-media-uri';
+import { SDUI_BLOCK_TYPES } from '../../catalog/block-types';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+
+describe('invokeSduiMediaResolver (generic media capability contract)', () => {
+  it('renders nothing without a resolver or with an empty path', () => {
+    expect(invokeSduiMediaResolver(null, 'feeds/a.jpg')).toBeNull();
+    expect(invokeSduiMediaResolver((p) => `url:${p}`, '')).toBeNull();
+    expect(invokeSduiMediaResolver((p) => `url:${p}`, '   ')).toBeNull();
+  });
+
+  it('passes sync resolver results through; empty/non-string becomes null', () => {
+    expect(invokeSduiMediaResolver((p) => `url:${p}`, 'a/b.jpg')).toBe('url:a/b.jpg');
+    expect(invokeSduiMediaResolver(() => '', 'a')).toBeNull();
+    expect(invokeSduiMediaResolver(() => undefined as unknown as string, 'a')).toBeNull();
+  });
+
+  it('normalizes async resolver results (empty or rejection → null)', async () => {
+    const ok = invokeSduiMediaResolver(async (p) => `dl:${p}`, 'a.jpg');
+    expect(ok).toBeInstanceOf(Promise);
+    await expect(ok as Promise<string | null>).resolves.toBe('dl:a.jpg');
+    await expect(invokeSduiMediaResolver(async () => '', 'a') as Promise<string | null>).resolves.toBeNull();
+    await expect(
+      invokeSduiMediaResolver(async () => {
+        throw new Error('403');
+      }, 'a') as Promise<string | null>,
+    ).resolves.toBeNull();
+  });
+
+  it('swallows sync resolver exceptions (never a product fallback URL)', () => {
+    expect(
+      invokeSduiMediaResolver(() => {
+        throw new Error('boom');
+      }, 'a'),
+    ).toBeNull();
+  });
+
+  it('receives the trimmed path (binding already materialized by the app)', () => {
+    let received = '';
+    invokeSduiMediaResolver((p) => {
+      received = p;
+      return 'x';
+    }, '  posts/{{item.missing}}  '.replace('{{item.missing}}', ''));
+    expect(received).toBe('posts/');
+  });
+});
+
+describe('parseSduiContentImageProps', () => {
+  it('keeps binding-resolved path, computes ratio from aspect token, defaults fit', () => {
+    const parsed = parseSduiContentImageProps({
+      path: 'feeds/2026/a.jpg',
+      width: 100,
+      aspect: 'square',
+      corner: 'cornerMedium',
+      blur_fill: true,
+      test_id: 'img',
+    });
+    expect(parsed.path).toBe('feeds/2026/a.jpg');
+    expect(parsed.aspectRatio).toBe(SDUI_MEDIA_ASPECT_RATIOS.square);
+    expect(parsed.corner).toBe('cornerMedium');
+    expect(parsed.fit).toBe('cover');
+    expect(parsed.blurFill).toBe(true);
+    expect(parsed.testId).toBe('img');
+  });
+
+  it('accepts camel aliases and rejects unknown tokens (fail-soft, never throw)', () => {
+    const parsed = parseSduiContentImageProps({
+      pathRef: '{{item.media_path}}',
+      blurFill: true,
+      aspect: 'nope',
+      fit: 'stretch',
+      corner: 12,
+    });
+    expect(parsed.path).toBe('{{item.media_path}}');
+    expect(parsed.blurFill).toBe(true);
+    expect(parsed.aspectRatio).toBeUndefined();
+    expect(parsed.fit).toBe('cover');
+    expect(parsed.corner).toBeUndefined();
+  });
+
+  it('empty/missing path parses to empty string (block renders null without resolver)', () => {
+    expect(parseSduiContentImageProps({}).path).toBe('');
+    expect(parseSduiContentImageProps({ path: '  ' }).path).toBe('');
+    expect(parseSduiContentImageProps(undefined).path).toBe('');
+  });
+});
+
+describe('computeSduiMediaFrame (stable wire-driven frame)', () => {
+  it('keeps explicit width+height; derives the missing side from aspect (square default)', () => {
+    expect(computeSduiMediaFrame(100, 80, undefined)).toEqual({ width: 100, height: 80, stretch: false });
+    expect(computeSduiMediaFrame(100, undefined, SDUI_MEDIA_ASPECT_RATIOS.video)).toEqual({
+      width: 100,
+      height: 100 / SDUI_MEDIA_ASPECT_RATIOS.video,
+      stretch: false,
+    });
+    expect(computeSduiMediaFrame(undefined, 90, undefined)).toEqual({
+      width: 90,
+      height: 90,
+      stretch: false,
+    });
+  });
+
+  it('falls back to aspectRatio + stretch when no explicit dimension', () => {
+    expect(computeSduiMediaFrame(undefined, undefined, SDUI_MEDIA_ASPECT_RATIOS.portrait)).toEqual({
+      aspectRatio: 4 / 5,
+      stretch: true,
+    });
+    expect(computeSduiMediaFrame(undefined, undefined, undefined)).toEqual({
+      aspectRatio: 1,
+      stretch: true,
+    });
+  });
+});
+
+describe('parseSduiAvatarProps', () => {
+  it('maps size tokens to px and defaults circle + md', () => {
+    expect(parseSduiAvatarProps({ size: 'sm' }).sizePx).toBe(SDUI_AVATAR_SIZES.sm);
+    const defaulted = parseSduiAvatarProps({ name: 'Ana' });
+    expect(defaulted.sizePx).toBe(SDUI_AVATAR_SIZES.md);
+    expect(defaulted.corner).toBe('cornerFull');
+    expect(defaulted.path).toBe('');
+  });
+});
+
+describe('parseSduiIconButtonProps (selected-binding coercion)', () => {
+  it("treats 'true'/true as selected and 'false'/false/garbage as default", () => {
+    expect(parseSduiIconButtonProps({ icon: 'heart', selected: 'true' }).selected).toBe(true);
+    expect(parseSduiIconButtonProps({ icon: 'heart', selected: ' True ' }).selected).toBe(true);
+    expect(parseSduiIconButtonProps({ icon: 'heart', selected: true }).selected).toBe(true);
+    expect(parseSduiIconButtonProps({ icon: 'heart', selected: 'false' }).selected).toBe(false);
+    expect(parseSduiIconButtonProps({ icon: 'heart', selected: false }).selected).toBe(false);
+    expect(parseSduiIconButtonProps({ icon: 'heart' }).selected).toBe(false);
+    expect(parseSduiIconButtonProps({ icon: 'heart', selected: '1' }).selected).toBe(false);
+  });
+
+  it('validates icon tokens against AppIconName (unknown → null icon)', () => {
+    expect(parseSduiIconButtonProps({ icon: 'heart' }).icon).toBe('heart');
+    expect(parseSduiIconButtonProps({ icon: '💜' }).icon).toBeNull();
+    expect(parseSduiIconButtonProps({ icon: 'heart', selected_icon: 'heart-filled' }).selectedIcon).toBe(
+      'heart-filled',
+    );
+    expect(parseSduiIconButtonProps({ icon: 'heart', selected_icon: 'nada' }).selectedIcon).toBeNull();
+  });
+
+  it('reads snake and camel action ids', () => {
+    expect(parseSduiIconButtonProps({ icon: 'heart', action_id: 'like_1' }).actionId).toBe('like_1');
+    expect(parseSduiIconButtonProps({ icon: 'heart', actionId: 'like_2' }).actionId).toBe('like_2');
+  });
+});
+
+describe('deriveSduiInitials', () => {
+  it('derives first+last initials (up to two letters)', () => {
+    expect(deriveSduiInitials('Ana Beatriz')).toBe('AB');
+    expect(deriveSduiInitials('ana carla souza')).toBe('AS');
+    expect(deriveSduiInitials('xavier')).toBe('XA');
+    expect(deriveSduiInitials('   ')).toBe('');
+    expect(deriveSduiInitials(undefined)).toBe('');
+    expect(deriveSduiInitials('1234')).toBe('12');
+  });
+});
+
+describe('parseSduiVideoProps', () => {
+  it('parses path + poster bindings already resolved, aspect token and fit default', () => {
+    const parsed = parseSduiVideoProps({
+      path: 'clips/2026/a.mp4',
+      poster_path: 'clips/2026/a.jpg',
+      aspect: 'video',
+      test_id: 'clip-video',
+    });
+    expect(parsed).toEqual({
+      path: 'clips/2026/a.mp4',
+      posterPath: 'clips/2026/a.jpg',
+      aspectRatio: SDUI_MEDIA_ASPECT_RATIOS.video,
+      fit: 'cover',
+      testId: 'clip-video',
+    });
+  });
+
+  it('accepts camel aliases; empty poster becomes undefined-safe trim', () => {
+    const parsed = parseSduiVideoProps({ pathRef: 'v.mp4', posterPath: ' p.jpg ', width: 320 });
+    expect(parsed.path).toBe('v.mp4');
+    expect(parsed.posterPath).toBe('p.jpg');
+    expect(parsed.width).toBe(320);
+  });
+
+  it('empty/missing path parses to empty string (block renders null without resolver)', () => {
+    expect(parseSduiVideoProps({}).path).toBe('');
+    expect(parseSduiVideoProps(undefined).posterPath).toBeUndefined();
+    expect(parseSduiVideoProps({ path: '', poster_path: '' }).posterPath).toBe('');
+  });
+});
+
+describe('parseSduiRowOverflowMenuProps', () => {
+  it('normalizes nested actions (snake + camel action ids) and keeps caller copy verbatim', () => {
+    const parsed = parseSduiRowOverflowMenuProps({
+      icon: 'overflow',
+      actions: [
+        { action_id: 'delete_post_{{item.id}}', label: 'Excluir', icon: 'trash', destructive: true },
+        { actionId: 'bookmark_{{item.id}}', label: 'Salvar' },
+      ],
+      test_id: 'row-menu',
+    });
+    expect(parsed.triggerIcon).toBe('overflow');
+    expect(parsed.testId).toBe('row-menu');
+    expect(parsed.actions).toEqual([
+      {
+        actionId: 'delete_post_{{item.id}}',
+        label: 'Excluir',
+        icon: 'trash',
+        destructive: true,
+      },
+      { actionId: 'bookmark_{{item.id}}', label: 'Salvar', icon: null, destructive: false },
+    ]);
+  });
+
+  it('defaults trigger to `overflow` and drops malformed entries (no invented copy)', () => {
+    const parsed = parseSduiRowOverflowMenuProps({
+      icon: 'not-an-icon',
+      actions: [
+        { action_id: 'ok', label: 'OK' },
+        { action_id: '', label: 'Sem id' },
+        { label: 'Sem action' },
+        'noise',
+        null,
+      ],
+    });
+    expect(parsed.triggerIcon).toBe(SDUI_ROW_OVERFLOW_DEFAULT_ICON);
+    expect(parsed.actions).toHaveLength(1);
+    expect(parsed.actions[0]?.actionId).toBe('ok');
+  });
+
+  it('tolerates missing/non-array actions', () => {
+    expect(parseSduiRowOverflowMenuProps({}).actions).toEqual([]);
+    expect(parseSduiRowOverflowMenuProps({ actions: 'nope' }).actions).toEqual([]);
+    expect(parseSduiRowOverflowMenuProps(undefined).triggerIcon).toBe(SDUI_ROW_OVERFLOW_DEFAULT_ICON);
+  });
+});
+
+describe('registry + catalog wiring (static, node-safe)', () => {
+  it('catalog lists the three new block types', () => {
+    expect(SDUI_BLOCK_TYPES).toContain('content_image');
+    expect(SDUI_BLOCK_TYPES).toContain('avatar');
+    expect(SDUI_BLOCK_TYPES).toContain('icon_button');
+  });
+
+  it('catalog lists video and row_overflow_menu block types', () => {
+    expect(SDUI_BLOCK_TYPES).toContain('video');
+    expect(SDUI_BLOCK_TYPES).toContain('row_overflow_menu');
+  });
+
+  it('sdui-component-registry maps each block type to its media block component', () => {
+    const source = fs.readFileSync(
+      path.join(ROOT, 'src', 'renderer', 'sdui-component-registry.tsx'),
+      'utf8',
+    );
+    expect(source).toContain('content_image: SduiContentImageBlock');
+    expect(source).toContain('avatar: SduiAvatarBlock');
+    expect(source).toContain('icon_button: SduiIconButtonBlock');
+    expect(source).toContain('video: SduiVideoBlock');
+    expect(source).toContain('row_overflow_menu: SduiRowOverflowMenuBlock');
+  });
+});

package/src/renderer/lib/sdui-media-uri.ts

@@ -0,0 +1,39 @@
+/**
+ * Capability genérica de mídia do renderer: o BFF manda **path** (storage
+ * path, possivelmente vindo de binding `{{item.media_path}}`); o app fornece a
+ * resolução path → URL (download autenticado) via `SduiMediaResolver`.
+ * A lib permanece agnóstica de produto: sem resolver, path vazio, resolver
+ * assíncrono pendente, retorno `''` ou exceção → nada de mídia (nunca um
+ * path/URL de produto hardcoded).
+ */
+
+/** Contrato do resolver supplied pelo app (sync ou async). */
+export type SduiMediaResolver = (path: string) => Promise<string> | string;
+
+/**
+ * Invoca o resolver de forma segura, normalizando o resultado:
+ * - sem resolver ou path vazio → `null` (renderizar nada);
+ * - resolver síncrono → `string` (URL) ou `null` quando retornar `''`/não-string;
+ * - resolver assíncrono → `Promise<string | null>` (rejeição/`''` → `null`).
+ * Exceções do resolver são engolidas → `null` (a tela continua sem o media).
+ */
+export function invokeSduiMediaResolver(
+  resolver: SduiMediaResolver | null | undefined,
+  path: string,
+): string | null | Promise<string | null> {
+  const trimmed = typeof path === 'string' ? path.trim() : '';
+  if (!resolver || !trimmed) return null;
+  try {
+    const result = resolver(trimmed);
+    if (typeof result === 'string') return result.trim() ? result : null;
+    if (result && typeof (result as Promise<string>).then === 'function') {
+      return (result as Promise<string>).then(
+        (uri) => (typeof uri === 'string' && uri.trim() ? uri : null),
+        () => null,
+      );
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}