@hed-hog/core 0.0.400 → 0.0.401

package/src/pdf/document/pdf-document.renderer.ts

@@ -0,0 +1,215 @@
+import { buildDocumentCss } from './pdf-document.css';
+import { PdfDocumentTheme } from './pdf-document.theme';
+import {
+  PdfDocumentBlock,
+  PdfDocumentCard,
+  PdfDocumentInput,
+  PdfDocumentRow,
+  PdfDocumentTableCell,
+  PdfDocumentTableColumn,
+} from './pdf-document.types';
+
+/**
+ * Único ponto por onde texto entra no HTML. Nome de aluno, título de curso e
+ * rótulo de tarefa são dados de usuário indo para um Chromium headless.
+ */
+export function escapeHtml(value: unknown): string {
+  if (value === null || value === undefined) return '';
+
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+const formatGeneratedAt = (date: Date, locale: string): string =>
+  new Intl.DateTimeFormat(locale, {
+    day: '2-digit',
+    month: 'long',
+    year: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  }).format(date);
+
+const toCell = (value: PdfDocumentRow[number]): PdfDocumentTableCell => {
+  if (value === null || value === undefined) return { text: '—', tone: 'muted' };
+  if (typeof value === 'object') return value;
+  return { text: String(value) };
+};
+
+const alignClass = (column: PdfDocumentTableColumn): string =>
+  column.align === 'right'
+    ? ' class="align-right"'
+    : column.align === 'center'
+      ? ' class="align-center"'
+      : '';
+
+function renderCards(items: PdfDocumentCard[], columns: number, variant: string): string {
+  const cards = items
+    .map(
+      (item) =>
+        `<div class="card"><div class="card-label">${escapeHtml(item.label)}</div>` +
+        `<div class="card-value">${escapeHtml(item.value)}</div>` +
+        (item.hint ? `<div class="card-hint">${escapeHtml(item.hint)}</div>` : '') +
+        '</div>',
+    )
+    .join('');
+
+  return `<div class="cards cards-${columns} cards-${variant}">${cards}</div>`;
+}
+
+function renderTable(block: Extract<PdfDocumentBlock, { kind: 'table' }>): string {
+  const {
+    columns,
+    rows,
+    numbered = false,
+    numberHeader = '#',
+    zebra = true,
+    compact = false,
+    emptyText = 'Nenhum registro no recorte selecionado.',
+    truncatedNote,
+  } = block;
+
+  if (rows.length === 0) {
+    return `<div class="table-empty">${escapeHtml(emptyText)}</div>`;
+  }
+
+  const head =
+    (numbered ? `<th class="idx">${escapeHtml(numberHeader)}</th>` : '') +
+    columns
+      .map(
+        (column) =>
+          `<th${alignClass(column)}${column.width ? ` style="width:${escapeHtml(column.width)}"` : ''}>` +
+          `${escapeHtml(column.header)}</th>`,
+      )
+      .join('');
+
+  // `push` + `join` em vez de concatenar em laço: uma conta grande gera milhares
+  // de linhas, e a string intermediária de cada passo é o que faz o render
+  // arrastar.
+  const body: string[] = [];
+
+  rows.forEach((row, index) => {
+    const cells: string[] = [];
+
+    if (numbered) cells.push(`<td class="idx">${index + 1}</td>`);
+
+    columns.forEach((column, columnIndex) => {
+      const cell = toCell(row[columnIndex]);
+      const tone = cell.tone && cell.tone !== 'default' ? ` tone-${cell.tone}` : '';
+      const align =
+        column.align === 'right' ? ' align-right' : column.align === 'center' ? ' align-center' : '';
+
+      cells.push(
+        `<td class="${(tone + align).trim()}">${escapeHtml(cell.text)}` +
+          (cell.sub ? `<div class="cell-sub">${escapeHtml(cell.sub)}</div>` : '') +
+          '</td>',
+      );
+    });
+
+    body.push(`<tr>${cells.join('')}</tr>`);
+  });
+
+  const table =
+    `<table class="doc-table${zebra ? ' zebra' : ''}${compact ? ' compact' : ''}">` +
+    `<thead><tr>${head}</tr></thead><tbody>${body.join('')}</tbody></table>`;
+
+  return truncatedNote ? `${table}<div class="note">${escapeHtml(truncatedNote)}</div>` : table;
+}
+
+export function renderBlock(block: PdfDocumentBlock): string {
+  switch (block.kind) {
+    case 'section':
+      return (
+        `<h2>${escapeHtml(block.title)}` +
+        (block.hint ? `<span class="section-hint">${escapeHtml(block.hint)}</span>` : '') +
+        '</h2>'
+      );
+
+    case 'cards':
+      return renderCards(block.items, block.columns ?? 4, block.variant ?? 'metric');
+
+    case 'table':
+      return renderTable(block);
+
+    case 'chart':
+      return (
+        '<div class="chart">' +
+        (block.title ? `<div class="chart-title">${escapeHtml(block.title)}</div>` : '') +
+        block.svg +
+        (block.caption ? `<div class="chart-caption">${escapeHtml(block.caption)}</div>` : '') +
+        '</div>'
+      );
+
+    case 'chartGrid':
+      return (
+        '<div class="chart-grid">' +
+        block.items
+          .map(
+            (item) =>
+              '<div class="chart">' +
+              (item.title ? `<div class="chart-title">${escapeHtml(item.title)}</div>` : '') +
+              item.svg +
+              (item.caption ? `<div class="chart-caption">${escapeHtml(item.caption)}</div>` : '') +
+              '</div>',
+          )
+          .join('') +
+        '</div>'
+      );
+
+    case 'note':
+      return `<div class="note${block.tone === 'accent' ? ' note-accent' : ''}">${escapeHtml(block.text)}</div>`;
+
+    case 'legend':
+      return `<div class="legend">${block.lines.map((l) => `<p>${escapeHtml(l)}</p>`).join('')}</div>`;
+
+    case 'pageBreak':
+      return '<div class="page-break"></div>';
+
+    default:
+      return '';
+  }
+}
+
+export function renderDocumentHtml(input: PdfDocumentInput, theme: PdfDocumentTheme): string {
+  const locale = input.locale ?? 'pt-BR';
+  const generatedAt = input.generatedAt ?? new Date();
+  const logo = input.logoDataUri || theme.logoUrl;
+
+  const meta = (input.meta ?? [])
+    .map(
+      (item) =>
+        `<div>${escapeHtml(item.label)}: <span class="meta-value">${escapeHtml(item.value)}</span></div>`,
+    )
+    .join('');
+
+  const body = input.blocks.map((block) => renderBlock(block)).join('\n');
+
+  return `<!DOCTYPE html>
+<html lang="${escapeHtml(locale)}">
+  <head>
+    <meta charset="utf-8" />
+    <title>${escapeHtml(input.title)}</title>
+    <style>${buildDocumentCss(theme, input.landscape ?? false)}</style>
+  </head>
+  <body>
+    <header>
+      <div class="brand">
+        <img src="${escapeHtml(logo)}" alt="${escapeHtml(theme.companyName)}" />
+        <div class="brand-text">
+          ${input.eyebrow ? `<div class="eyebrow">${escapeHtml(input.eyebrow)}</div>` : ''}
+          <h1>${escapeHtml(input.title)}</h1>
+          ${input.subtitle ? `<div class="company-name">${escapeHtml(input.subtitle)}</div>` : ''}
+        </div>
+      </div>
+      <div class="meta-block">
+        <div>Gerado em: <span class="meta-value">${escapeHtml(formatGeneratedAt(generatedAt, locale))}</span></div>
+        ${meta}
+      </div>
+    </header>
+    ${body}
+  </body>
+</html>`;
+}

package/src/pdf/document/pdf-document.service.ts

@@ -0,0 +1,77 @@
+import { Inject, Injectable, forwardRef } from '@nestjs/common';
+
+import { BrandAssetService } from '../../setting/brand-asset.service';
+import { SettingService } from '../../setting/setting.service';
+import { PdfService } from '../pdf.service';
+import {
+  PDF_DOCUMENT_MARGIN,
+  buildAccentHeaderTemplate,
+  buildFooterTemplate,
+} from './pdf-document.chrome';
+import { renderDocumentHtml } from './pdf-document.renderer';
+import {
+  PdfDocumentTheme,
+  PdfDocumentThemeOverrides,
+  resolveDocumentTheme,
+} from './pdf-document.theme';
+import { PdfDocumentInput } from './pdf-document.types';
+
+/**
+ * Gera o documento PDF padrão do sistema: letterhead com logo, cards, tabelas,
+ * gráficos, barra de destaque no topo de toda página e paginação "X / N".
+ *
+ * Quem chama entrega blocos de dados ({@link PdfDocumentInput}); o HTML e o
+ * Chromium são responsabilidade daqui.
+ */
+@Injectable()
+export class PdfDocumentService {
+  constructor(
+    @Inject(forwardRef(() => PdfService))
+    private readonly pdf: PdfService,
+    @Inject(forwardRef(() => SettingService))
+    private readonly settingService: SettingService,
+    @Inject(forwardRef(() => BrandAssetService))
+    private readonly brandAsset: BrandAssetService,
+  ) {}
+
+  loadTheme(overrides?: PdfDocumentThemeOverrides): Promise<PdfDocumentTheme> {
+    return resolveDocumentTheme(this.settingService, this.brandAsset, overrides);
+  }
+
+  /** HTML puro, sem Chromium — serve aos testes e a quem quiser inspecionar. */
+  async buildHtml(input: PdfDocumentInput, theme?: PdfDocumentTheme): Promise<string> {
+    return renderDocumentHtml(input, theme ?? (await this.loadTheme()));
+  }
+
+  async render(
+    input: PdfDocumentInput,
+    options: { theme?: PdfDocumentTheme; label?: string; timeoutMs?: number } = {},
+  ): Promise<Buffer> {
+    const theme = options.theme ?? (await this.loadTheme());
+    const html = renderDocumentHtml(input, theme);
+
+    const generatedAt = input.generatedAt ?? new Date();
+    const footerLeft = [
+      input.footerLeft ?? 'Documento Confidencial',
+      `Gerado em ${new Intl.DateTimeFormat(input.locale ?? 'pt-BR').format(generatedAt)}`,
+      theme.companyName,
+    ]
+      .filter(Boolean)
+      .join(' · ');
+
+    return this.pdf.generatePdfFromHtml(html, {
+      format: 'A4',
+      landscape: input.landscape ?? false,
+      printBackground: true,
+      margin: PDF_DOCUMENT_MARGIN,
+      displayHeaderFooter: true,
+      headerTemplate: buildAccentHeaderTemplate(theme),
+      footerTemplate: buildFooterTemplate(theme, footerLeft),
+      // O logo já vem embutido como data URI e não há fonte web: esperar por
+      // rede ociosa só adicionaria o timeout do `networkidle` ao render.
+      waitUntil: 'load',
+      timeoutMs: options.timeoutMs ?? 60_000,
+      label: options.label,
+    });
+  }
+}

package/src/pdf/document/pdf-document.theme.ts

@@ -0,0 +1,146 @@
+import { BrandAssetService } from '../../setting/brand-asset.service';
+import { SettingService } from '../../setting/setting.service';
+
+/**
+ * Tokens do documento padrão. São as mesmas settings que a proposta comercial
+ * do CRM lê, para que os dois PDFs saiam com a mesma identidade sem um copiar
+ * as cores do outro na mão.
+ */
+export interface PdfDocumentTheme {
+  primary: string;
+  /** Fundo suave dos cards e do cabeçalho da tabela. */
+  mutedBg: string;
+  /** Texto secundário: rótulos, legendas, rodapé. */
+  mutedFg: string;
+  /** Texto principal. */
+  ink: string;
+  /** Bordas. */
+  line: string;
+  companyName: string;
+  /** Data URI ou URL absoluta do logo do sistema. */
+  logoUrl: string;
+  fontFamily: string;
+  /** Cores categóricas dos gráficos, com a primária na frente. */
+  chartPalette: string[];
+}
+
+const FALLBACK = {
+  primary: '#ff760c',
+  mutedBg: '#f4f4f5',
+  mutedFg: '#71717a',
+  ink: '#18181b',
+  line: '#e4e4e7',
+  companyName: 'HedHog',
+};
+
+/**
+ * Nenhuma fonte web: o container da API só tem `ttf-freefont`, e um `<link>`
+ * para o Google Fonts com `waitUntil: 'networkidle'` vira espera até o timeout
+ * quando o pod não tem saída para a internet.
+ */
+export const PDF_DOCUMENT_FONT = 'Arial, Helvetica, sans-serif';
+
+/** Paleta print-safe: sem amarelo puro nem cinza claro, que somem no papel. */
+const CATEGORICAL = [
+  '#2563eb',
+  '#16a34a',
+  '#9333ea',
+  '#dc2626',
+  '#0891b2',
+  '#b45309',
+  '#4f46e5',
+  '#475569',
+];
+
+const text = (value: unknown): string | null => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+export interface PdfDocumentThemeOverrides {
+  companyName?: string;
+  primary?: string;
+}
+
+/**
+ * Lê as settings de marca. Qualquer falha cai nos valores de fábrica — um
+ * relatório sem cor certa ainda é um relatório; um relatório que não sai não é.
+ */
+export async function resolveDocumentTheme(
+  settingService: SettingService,
+  brandAsset: BrandAssetService,
+  overrides: PdfDocumentThemeOverrides = {},
+): Promise<PdfDocumentTheme> {
+  let values: Record<string, any> = {};
+
+  try {
+    values = await settingService.getSettingValues([
+      'theme-primary-light',
+      'theme-muted-light',
+      'theme-muted-foreground-light',
+      'theme-secondary-foreground-light',
+      'system-name',
+      'image-url',
+      'icon-url',
+    ]);
+  } catch {
+    values = {};
+  }
+
+  const primary = overrides.primary ?? text(values['theme-primary-light']) ?? FALLBACK.primary;
+
+  return {
+    primary,
+    mutedBg: text(values['theme-muted-light']) ?? FALLBACK.mutedBg,
+    mutedFg: text(values['theme-muted-foreground-light']) ?? FALLBACK.mutedFg,
+    ink: text(values['theme-secondary-foreground-light']) ?? FALLBACK.ink,
+    line: FALLBACK.line,
+    companyName: overrides.companyName ?? text(values['system-name']) ?? FALLBACK.companyName,
+    logoUrl: await resolveSystemLogo(brandAsset, values, primary),
+    fontFamily: PDF_DOCUMENT_FONT,
+    chartPalette: [primary, ...CATEGORICAL],
+  };
+}
+
+/**
+ * O Chromium renderiza sem sessão e, dentro do cluster, pode não ter rota para
+ * o host público — por isso a imagem é baixada e embutida como data URI, com a
+ * URL absoluta como segundo recurso e um wordmark inline como último.
+ */
+async function resolveSystemLogo(
+  brandAsset: BrandAssetService,
+  values: Record<string, any>,
+  primary: string,
+): Promise<string> {
+  const configured = text(values['image-url']) ?? text(values['icon-url']);
+
+  if (configured) {
+    try {
+      const absolute = await brandAsset.resolveAssetUrl(configured);
+      if (absolute) {
+        const dataUri = await brandAsset.fetchAsDataUri(absolute);
+        if (dataUri) return dataUri;
+        return absolute;
+      }
+    } catch {
+      // Cai no wordmark abaixo.
+    }
+  }
+
+  return inlineWordmark(primary);
+}
+
+export function inlineWordmark(primary: string): string {
+  const svg = encodeURIComponent(
+    [
+      '<svg xmlns="http://www.w3.org/2000/svg" width="240" height="72" viewBox="0 0 240 72">',
+      '<rect width="240" height="72" rx="18" fill="#0f172a"/>',
+      `<circle cx="38" cy="36" r="18" fill="${primary}"/>`,
+      '<text x="72" y="43" fill="#ffffff" font-size="26" font-family="Arial, sans-serif" font-weight="700">HedHog</text>',
+      '</svg>',
+    ].join(''),
+  );
+
+  return `data:image/svg+xml;charset=UTF-8,${svg}`;
+}

package/src/pdf/document/pdf-document.types.ts

@@ -0,0 +1,97 @@
+/**
+ * Modelo de um documento PDF padrão: o chamador descreve **dados**, nunca HTML.
+ *
+ * É o que sustenta a regra de escape do renderer — se um serviço pudesse passar
+ * markup, o nome de um aluno com `<` viraria tag dentro de um Chromium headless.
+ * A única exceção é o SVG dos gráficos, que carrega o tipo {@link SafeSvg} e só
+ * pode ser produzido pelos desenhistas do próprio kit.
+ */
+
+/** SVG montado pelos helpers de gráfico do kit — a única string injetada sem escape. */
+export type SafeSvg = string & { readonly __safeSvg: unique symbol };
+
+/**
+ * Marca um SVG como seguro. Só os desenhistas de `./charts` devem chamar isto:
+ * quem passar conteúdo de usuário aqui reabre a porta que o modelo de blocos fecha.
+ */
+export const asSafeSvg = (svg: string): SafeSvg => svg as SafeSvg;
+
+export interface PdfDocumentMeta {
+  label: string;
+  value: string;
+}
+
+export interface PdfDocumentCard {
+  label: string;
+  value: string;
+  /** Linha pequena abaixo do valor, para a unidade ou a ressalva. */
+  hint?: string;
+}
+
+export interface PdfDocumentTableColumn {
+  header: string;
+  align?: 'left' | 'center' | 'right';
+  /**
+   * Largura CSS (ex.: '18%'). Sem ela o Chromium reparte pelo conteúdo e a
+   * tabela muda de forma a cada página.
+   */
+  width?: string;
+}
+
+export interface PdfDocumentTableCell {
+  text: string;
+  /** Segunda linha menor: o e-mail sob o nome, o "Em risco" sob o status. */
+  sub?: string;
+  tone?: 'default' | 'muted' | 'bold' | 'accent' | 'warn';
+}
+
+export type PdfDocumentRow = Array<string | number | null | undefined | PdfDocumentTableCell>;
+
+export type PdfDocumentBlock =
+  | { kind: 'section'; title: string; hint?: string }
+  | {
+      kind: 'cards';
+      items: PdfDocumentCard[];
+      /** Padrão: 4. */
+      columns?: 2 | 3 | 4 | 5;
+      /** 'metric' destaca o valor (indicador); 'filter' é o carimbo do recorte. */
+      variant?: 'metric' | 'filter';
+    }
+  | {
+      kind: 'table';
+      columns: PdfDocumentTableColumn[];
+      rows: PdfDocumentRow[];
+      /** Coluna "#" à esquerda, 1..N contínua entre páginas. */
+      numbered?: boolean;
+      numberHeader?: string;
+      zebra?: boolean;
+      /** Fonte menor, para tabela com muitas colunas. */
+      compact?: boolean;
+      emptyText?: string;
+      /** Aviso de corte quando a origem truncou as linhas. */
+      truncatedNote?: string;
+    }
+  | { kind: 'chart'; title?: string; svg: SafeSvg; caption?: string }
+  | { kind: 'chartGrid'; items: Array<{ title?: string; svg: SafeSvg; caption?: string }> }
+  | { kind: 'note'; text: string; tone?: 'muted' | 'accent' }
+  | { kind: 'legend'; lines: string[] }
+  | { kind: 'pageBreak' };
+
+export interface PdfDocumentInput {
+  /** O `h1` do letterhead. */
+  title: string;
+  /** Sobretítulo laranja, em caixa alta (ex.: "Relatório de Alunos"). */
+  eyebrow?: string;
+  /** Linha cinza abaixo do título — normalmente o nome da empresa. */
+  subtitle?: string;
+  /** Bloco alinhado à direita do letterhead. */
+  meta?: PdfDocumentMeta[];
+  blocks: PdfDocumentBlock[];
+  /** Data URI do logo; sem ele o kit usa o logo do sistema. */
+  logoDataUri?: string | null;
+  generatedAt?: Date;
+  locale?: string;
+  landscape?: boolean;
+  /** Padrão: 'Documento Confidencial'. */
+  footerLeft?: string;
+}

package/src/pdf/pdf.module.ts

@@ -2,6 +2,7 @@ import { forwardRef, Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
 
 import { SettingModule } from '../setting/setting.module';
+import { PdfDocumentService } from './document/pdf-document.service';
 import { PdfController } from './pdf.controller';
 import { PdfService } from './pdf.service';
 
@@ -10,8 +11,8 @@ import { PdfService } from './pdf.service';
     ConfigModule,
     forwardRef(() => SettingModule),
   ],
-  providers: [PdfService],
-  exports: [PdfService],
+  providers: [PdfService, PdfDocumentService],
+  exports: [PdfService, PdfDocumentService],
   controllers: [PdfController],
 })
 export class PdfModule {}

package/src/pdf/pdf.service.spec.ts

@@ -0,0 +1,131 @@
+import { ServiceUnavailableException } from '@nestjs/common';
+import { afterEach, describe, expect, it, jest } from '@jest/globals';
+
+import { PdfService, buildPdfPageOptions } from './pdf.service';
+
+/** O serviço só toca em SettingService/BrandAssetService fora do caminho de render. */
+const makeService = (env: Record<string, string> = {}): PdfService =>
+  new PdfService({} as any, {} as any, {
+    get: (key: string) => env[key],
+  } as any);
+
+describe('buildPdfPageOptions', () => {
+  // O contrato que protege ceia, certificado e material de aula: quem não passa
+  // nenhuma das opções novas tem que receber o mesmo objeto de antes delas
+  // existirem — a simples presença de `displayHeaderFooter` muda o resultado.
+  it('não acrescenta chave nenhuma quando só as opções antigas vêm', () => {
+    expect(buildPdfPageOptions({})).toEqual({
+      format: 'A4',
+      printBackground: true,
+      landscape: false,
+      margin: { top: '0', right: '0', bottom: '0', left: '0' },
+    });
+
+    expect(Object.keys(buildPdfPageOptions({ format: 'A4' })).sort()).toEqual([
+      'format',
+      'landscape',
+      'margin',
+      'printBackground',
+    ]);
+  });
+
+  it('troca format/landscape por width/height quando os dois vêm', () => {
+    const options = buildPdfPageOptions({ width: '1600px', height: '1131px' });
+
+    expect(options).toEqual({
+      width: '1600px',
+      height: '1131px',
+      printBackground: true,
+      margin: { top: '0', right: '0', bottom: '0', left: '0' },
+    });
+  });
+
+  // Com um template só, o Chromium volta a injetar o dele (URL e data) no outro.
+  it('preenche os dois templates quando o cabeçalho/rodapé é ligado', () => {
+    const options = buildPdfPageOptions({
+      displayHeaderFooter: true,
+      headerTemplate: '<div class="bar"></div>',
+    });
+
+    expect(options.displayHeaderFooter).toBe(true);
+    expect(options.headerTemplate).toBe('<div class="bar"></div>');
+    expect(options.footerTemplate).toBe('<span></span>');
+  });
+
+  it('ignora os templates enquanto displayHeaderFooter não for ligado', () => {
+    const options = buildPdfPageOptions({ footerTemplate: '<span></span>' });
+
+    expect(options).not.toHaveProperty('displayHeaderFooter');
+    expect(options).not.toHaveProperty('footerTemplate');
+  });
+
+  it('só repassa scale e pageRanges quando vêm', () => {
+    expect(buildPdfPageOptions({ scale: 0.9, pageRanges: '1-2' })).toMatchObject({
+      scale: 0.9,
+      pageRanges: '1-2',
+    });
+    expect(buildPdfPageOptions({})).not.toHaveProperty('scale');
+  });
+});
+
+describe('fila de renderização', () => {
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('segura o render acima do teto até uma vaga ser devolvida', async () => {
+    const service = makeService({ PDF_MAX_CONCURRENCY: '1' });
+    const releaseFirst = await (service as any).acquireRenderSlot('primeiro');
+
+    let liberado = false;
+    const second = (service as any)
+      .acquireRenderSlot('segundo')
+      .then((release: () => void) => {
+        liberado = true;
+        return release;
+      });
+
+    await new Promise((resolve) => process.nextTick(resolve));
+    expect(liberado).toBe(false);
+
+    releaseFirst();
+    const releaseSecond = await second;
+    expect(liberado).toBe(true);
+    releaseSecond();
+  });
+
+  it('responde 503 quando a espera na fila estoura', async () => {
+    jest.useFakeTimers();
+    const service = makeService({ PDF_MAX_CONCURRENCY: '1', PDF_QUEUE_WAIT_MS: '50' });
+    const release = await (service as any).acquireRenderSlot('primeiro');
+
+    const queued = (service as any).acquireRenderSlot('segundo');
+    const rejeicao = expect(queued).rejects.toBeInstanceOf(ServiceUnavailableException);
+
+    jest.advanceTimersByTime(50);
+    await rejeicao;
+
+    release();
+  });
+
+  // Liberar duas vezes (ex.: `finally` somado a um caminho de erro) não pode
+  // inflar a capacidade e deixar dois Chromium subirem juntos.
+  it('ignora a segunda liberação do mesmo render', async () => {
+    const service = makeService({ PDF_MAX_CONCURRENCY: '1' });
+    const release = await (service as any).acquireRenderSlot('primeiro');
+    release();
+    release();
+
+    const releaseSecond = await (service as any).acquireRenderSlot('segundo');
+
+    let terceiroEntrou = false;
+    void (service as any).acquireRenderSlot('terceiro').then(() => {
+      terceiroEntrou = true;
+    });
+
+    await new Promise((resolve) => process.nextTick(resolve));
+    expect(terceiroEntrou).toBe(false);
+
+    releaseSecond();
+  });
+});