@proulr/sdui-contract 0.1.20 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proulr/sdui-contract",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/sdui-contract-types.ts

@@ -387,6 +387,18 @@ export type SduiScreenChromeMetaWire = {
   self_managed?: boolean;
   hub_kind?: 'inbox' | null;
   wide_layout?: 'chat_master_detail' | 'vibes_rail' | null;
+  /**
+   * Screen id da listagem que ocupa o painel mestre no wide. Obrigatório quando a
+   * rota é a própria tela de detalhe (`/s/chat.thread?conversation_id=…`): sem ele
+   * o shell renderizaria o wire do detalhe também na master — thread duplicada.
+   */
+  wide_master_screen_id?: string;
+  /**
+   * Destino fixo do botão voltar, ignorando o histórico. Usado quando a tela que
+   * antecedeu esta deixou de fazer sentido (ex.: conversa do Randoms que virou DM —
+   * voltar cai na lista de mensagens, não na fila).
+   */
+  back_screen_id?: string;
   surface?: 'discover' | 'vibes' | null;
   header_slot?: boolean;
   pull_refresh?: boolean;
@@ -396,6 +408,18 @@ export type SduiScreenChromeMetaWire = {
 
 export type SduiScreenMetaWire = {
   cache_ttl_ms?: number;
+  /**
+   * Intervalo mínimo (ms) entre fetches desta tela — throttle do prefetch forçado
+   * (resume/focus), onde o `cache_ttl_ms` não chega porque o app revalida por
+   * evento, não por expiração.
+   */
+  min_fetch_interval_ms?: number;
+  /**
+   * Revisão do wire, calculada pelo bff-core a partir do mesmo digest que gera o
+   * ETag. Serve para o app comparar conteúdo entre fetches guardados no disco
+   * (onde o header HTTP não sobrevive) sem manter o ETag como estado de produto.
+   */
+  rev?: string;
   offline_policy?: SduiOfflinePolicy;
   bff?: string;
   chrome?: SduiScreenChromeMetaWire;
@@ -453,6 +477,10 @@ export type SduiScreenChromeMeta = {
   selfManaged?: boolean;
   hubKind?: 'inbox' | null;
   wideLayout?: 'chat_master_detail' | 'vibes_rail' | null;
+  /** Listing screen rendered in the wide master pane when this screen is the detail. */
+  wideMasterScreenId?: string;
+  /** Screen the back button goes to, bypassing history (the previous screen no longer makes sense). */
+  backScreenId?: string;
   surface?: 'discover' | 'vibes' | null;
   headerSlot?: boolean;
   pullRefresh?: boolean;
@@ -462,6 +490,9 @@ export type SduiScreenChromeMeta = {
 
 export type SduiScreenMeta = {
   cacheTtlMs: number;
+  minFetchIntervalMs?: number;
+  /** Revisão do wire (digest do bff-core) — mesma origem do ETag da resposta. */
+  rev?: string;
   offlinePolicy: SduiOfflinePolicy;
   bff?: string;
   chrome?: SduiScreenChromeMeta;

package/src/sdui-screen-codec.test.ts

@@ -42,6 +42,25 @@ describe('decodeSduiScreenWire', () => {
     });
   });
 
+  it('maps meta.rev and throttles min_fetch_interval_ms to positive numbers', () => {
+    const screen = decodeSduiScreenWire({
+      schema_version: 1,
+      screen_id: 'chat.inbox',
+      blocks: [],
+      meta: { rev: 'abc123', min_fetch_interval_ms: 30_000 },
+    });
+    expect(screen.meta).toMatchObject({ rev: 'abc123', minFetchIntervalMs: 30_000 });
+
+    const junk = decodeSduiScreenWire({
+      schema_version: 1,
+      screen_id: 'chat.inbox',
+      blocks: [],
+      meta: { rev: '', min_fetch_interval_ms: 0 },
+    });
+    expect(junk.meta).not.toHaveProperty('rev');
+    expect(junk.meta).not.toHaveProperty('minFetchIntervalMs');
+  });
+
   it('decodes native_capability actions with capability_id', () => {
     const screen = decodeSduiScreenWire({
       schema_version: 1,
@@ -73,6 +92,8 @@ describe('decodeSduiScreenWire', () => {
           surface: 'discover',
           hub_kind: 'inbox',
           wide_layout: 'chat_master_detail',
+          wide_master_screen_id: 'chat.inbox',
+          back_screen_id: 'chat.inbox',
           owns_header: false,
           self_managed: false,
           auto_action_id: 'open_random_thread',
@@ -86,6 +107,8 @@ describe('decodeSduiScreenWire', () => {
       selfManaged: false,
       hubKind: 'inbox',
       wideLayout: 'chat_master_detail',
+      wideMasterScreenId: 'chat.inbox',
+      backScreenId: 'chat.inbox',
       surface: 'discover',
       headerSlot: true,
       pullRefresh: true,

package/src/sdui-screen-codec.ts

@@ -76,6 +76,8 @@ function mapChromeMetaWire(
     selfManaged: wire.self_managed,
     hubKind: wire.hub_kind,
     wideLayout: wire.wide_layout,
+    wideMasterScreenId: wire.wide_master_screen_id,
+    backScreenId: wire.back_screen_id,
     surface: wire.surface,
     headerSlot: wire.header_slot,
     pullRefresh: wire.pull_refresh,
@@ -84,8 +86,14 @@ function mapChromeMetaWire(
 }
 
 function mapMetaWire(wire: SduiScreenMetaWire | undefined): SduiScreenMeta {
+  const minFetchIntervalMs =
+    typeof wire?.min_fetch_interval_ms === 'number' && wire.min_fetch_interval_ms > 0
+      ? wire.min_fetch_interval_ms
+      : undefined;
   return {
     cacheTtlMs: wire?.cache_ttl_ms ?? DEFAULT_CACHE_TTL_MS,
+    ...(minFetchIntervalMs === undefined ? {} : { minFetchIntervalMs }),
+    ...(typeof wire?.rev === 'string' && wire.rev ? { rev: wire.rev } : {}),
     offlinePolicy: wire?.offline_policy ?? DEFAULT_OFFLINE_POLICY,
     bff: wire?.bff,
     chrome: mapChromeMetaWire(wire?.chrome),