@meistrari/minuta-editor 1.1.0 → 1.2.1

package/README.md

@@ -2,7 +2,8 @@
 
 O editor de minuta do **defesa.ai** sem framework: a folha A4 paginada de
 verdade, edição rica, cabeçalho/rodapé, placeholders de variável e export
-DOCX com as mesmas quebras de página do preview. Monta em qualquer app —
+DOCX que reflui no Word como na folha (só a quebra manual do template é
+forçada; título leva keep-with-next). Monta em qualquer app —
 React, Vue, Svelte, vanilla — com uma chamada:
 
 ```ts
@@ -37,6 +38,8 @@ const editor = createMinutaEditor(el, {
     onReady: tiptap => {},
     onChange: () => {},
     onEditChrome: part => {},               // clique no cabeçalho/rodapé
+    onVariableClick: ({ variableId, parentBlockId, text, kind }) => {}, // kind: 'text' | 'image' | 'missingImage'
+    onBlockClick: blockId => {},            // read-only (ou com blockClickWhileEditing)
 })
 
 editor.getHTML()          // → string
@@ -46,6 +49,15 @@ editor.setEditable(bool)
 editor.setChrome({ header, footer, headerScope, footerScope, showPageNumber })
 editor.setHeader({ logoUrl, position })
 editor.setVariables(catalogo)
+editor.setBlockClickWhileEditing(bool)
+
+// variáveis do case marcadas no documento (<span|img data-variable-id>, aviso de imagem faltando)
+editor.scrollToVariable(id)              // → boolean (rola e dá um flash)
+editor.setVariableValue(id, texto)       // → nº de ocorrências (o aviso de "faltando" vira chip)
+editor.setVariableImage(id, src)         // → nº de ocorrências (o aviso de imagem vira <img>)
+editor.variablesInDocument()             // → string[]
+editor.refreshVaultImages(vaultUrl => Promise<string>) // renova o src das imagens inseridas (data-vault-src)
+
 editor.schedulePaginate() // repagina (após mudar algo que afeta altura por fora)
 editor.totalPages()
 editor.destroy()

package/dist/chunks/docxExport.mjs

@@ -1,5 +1,5 @@
-import { f as footnoteHtmlToRuns, p as pocLoneCellIndex } from '../shared/minuta-editor.b2512170.mjs';
-import { BorderStyle, TextRun, ExternalHyperlink, Paragraph, Document, Header, Packer, AlignmentType, PageBreak, LineRuleType, Table, TableRow, TableCell, WidthType, TableLayoutType, Footer, FootnoteReferenceRun, VerticalAlign, ImageRun, HorizontalPositionRelativeFrom, VerticalPositionRelativeFrom, TextWrappingType, FrameAnchorType, PageNumber, HeadingLevel } from 'docx';
+import { f as footnoteHtmlToRuns, p as pocLoneCellIndex, a as pocLooksLikeTitle } from '../shared/minuta-editor.d9d0c0ce.mjs';
+import { BorderStyle, TextRun, ExternalHyperlink, Paragraph, Document, Header, Packer, AlignmentType, LineRuleType, Table, TableRow, TableCell, WidthType, TableLayoutType, Footer, FootnoteReferenceRun, VerticalAlign, ImageRun, HorizontalPositionRelativeFrom, VerticalPositionRelativeFrom, TextWrappingType, FrameAnchorType, PageNumber, HeadingLevel } from 'docx';
 import '@tiptap/pm/state';
 import '@tiptap/pm/view';
 
@@ -117,7 +117,7 @@ function measureEl(el) {
     // Piso = 1.0em: protege o caso patológico (0.7em) SEM inflar entrelinha
     // justa (1.0em, comum em citações) — com 1.15em o export ficava mais
     // alto que o preview mediu, o conteúdo derramava no Word e a quebra
-    // explícita seguinte abria página quase vazia (TLF ¶36/¶52).
+    // explícita seguinte abria página quase vazia.
     lineExactTw: lineHpx && Number.isFinite(lineHpx) ? Math.round(Math.max(lineHpx, fontPx) * PX_TO_TWIP) : null,
     afterTw: Math.round((Number.parseFloat(cs.marginBottom) || 0) * PX_TO_TWIP),
     beforeTw: Math.round((Number.parseFloat(cs.marginTop) || 0) * PX_TO_TWIP),
@@ -257,7 +257,7 @@ function domInlineToRuns(root, fallback = {}) {
     runs.push(new TextRun({
       text,
       // sem rFonts o run cai no default Arial do Document — a fonte
-      // REAL do preview (ex.: Calibri do TLF) tem que viajar no run
+      // REAL do preview (ex.: Calibri) tem que viajar no run
       font: primaryFont(cs) ?? fallback.font,
       size: Math.round((Number.parseFloat(cs.fontSize) || 16) / PX_PER_PT * 2),
       color: cssColorToHex(cs.color) ?? fallback.color,
@@ -328,6 +328,7 @@ function textBlockToParagraph(node, pos, ctx, opts = {}) {
     spacing.before = Math.max(0, spacing.before - ctx.lastAfterTw);
   ctx.lastAfterTw = spacing.after ?? 0;
   const runs = inlineToRuns(node, base, ctx);
+  const keepNext = Boolean(opts.heading || m && pocLooksLikeTitle(m.el)) || void 0;
   const paragraph = new Paragraph({
     children: runs,
     // sem alinhamento explícito, corpo de peça vai justificado (o Word
@@ -336,7 +337,8 @@ function textBlockToParagraph(node, pos, ctx, opts = {}) {
     spacing,
     indent: total ? { left: total } : void 0,
     heading: opts.heading ? headingLevelFor(opts.heading) : void 0,
-    pageBreakBefore: breakBefore
+    pageBreakBefore: breakBefore,
+    keepNext
   });
   ctx.meta.set(paragraph, { spacer: runs.length === 0 && !opts.heading, breakBefore });
   return paragraph;
@@ -703,7 +705,7 @@ function collectImageIslands(node, pos) {
   }
   return out.length ? out : null;
 }
-async function inlineImagesParagraph(islands, innerPx, ctx) {
+async function inlineImagesParagraphs(islands, innerPx, ctx) {
   const GAP_PX = 8;
   const items = [];
   for (const { node, pos } of islands) {
@@ -711,27 +713,41 @@ async function inlineImagesParagraph(islands, innerPx, ctx) {
     const src = await srcToDataUrl(img.getAttribute("src") || "");
     if (!src)
       continue;
-    const live = domAt(ctx, pos)?.querySelector("img");
+    const islandEl = domAt(ctx, pos);
+    const live = islandEl?.querySelector("img");
     const styleW = Number.parseFloat(getProp(img.getAttribute("style"), "width") ?? "");
     const widthPx = live?.offsetWidth || 0 || (Number.isFinite(styleW) && styleW > 0 ? styleW : 0) || Math.min(innerPx, 200);
-    items.push({ src, widthPx });
+    const zoom = islandEl ? zoomFactor(islandEl) : 1;
+    const top = islandEl ? islandEl.getBoundingClientRect().top / zoom : Number.NaN;
+    items.push({ src, widthPx, top });
   }
   if (!items.length)
-    return null;
-  const total = items.reduce((a, b) => a + b.widthPx, 0) + GAP_PX * (items.length - 1);
-  const scale = innerPx > 0 && total > innerPx ? (innerPx - GAP_PX * (items.length - 1)) / (total - GAP_PX * (items.length - 1)) : 1;
-  const runs = [];
-  for (let i = 0; i < items.length; i++) {
-    const run = await dataUrlToImageRun(items[i].src, Math.max(1, Math.round(items[i].widthPx * scale)));
-    if (!run)
-      continue;
+    return [];
+  const lines = [];
+  for (const item of items) {
+    const line = lines[lines.length - 1];
+    if (line && (Number.isNaN(item.top) || Number.isNaN(line[0].top) || Math.abs(item.top - line[0].top) <= 8))
+      line.push(item);
+    else
+      lines.push([item]);
+  }
+  const paragraphs = [];
+  for (const line of lines) {
+    const total = line.reduce((a, b) => a + b.widthPx, 0) + GAP_PX * (line.length - 1);
+    const scale = innerPx > 0 && total > innerPx ? (innerPx - GAP_PX * (line.length - 1)) / (total - GAP_PX * (line.length - 1)) : 1;
+    const runs = [];
+    for (const item of line) {
+      const run = await dataUrlToImageRun(item.src, Math.max(1, Math.round(item.widthPx * scale)));
+      if (!run)
+        continue;
+      if (runs.length)
+        runs.push(new TextRun({ text: "  " }));
+      runs.push(run);
+    }
     if (runs.length)
-      runs.push(new TextRun({ text: "  " }));
-    runs.push(run);
+      paragraphs.push(new Paragraph({ children: runs, alignment: AlignmentType.CENTER, spacing: { after: 0, before: 0 } }));
   }
-  if (!runs.length)
-    return null;
-  return new Paragraph({ children: runs, alignment: AlignmentType.CENTER, spacing: { after: 0, before: 0 } });
+  return paragraphs;
 }
 async function tableToDocx(node, pos, contentWidthPx, ctx) {
   const tableDomRaw = domAt(ctx, pos);
@@ -785,9 +801,7 @@ async function tableToDocx(node, pos, contentWidthPx, ctx) {
             endPos += next.nodeSize;
             end++;
           }
-          const para = await inlineImagesParagraph(islands, cellInnerPx, cellCtx);
-          if (para)
-            cellContent.push(para);
+          cellContent.push(...await inlineImagesParagraphs(islands, cellInnerPx, cellCtx));
           childPos = endPos;
           k = end - 1;
           continue;
@@ -937,9 +951,8 @@ async function nodeToDocx(node, pos, contentWidthPx, ctx) {
     }
     case "paragraph": {
       if (node.textContent.trim() === "PAGEBREAK") {
-        if (ctx.breakSet.size)
-          return [];
-        return [new Paragraph({ children: [new PageBreak()] })];
+        ctx.pending.breakBefore = true;
+        return [];
       }
       return [textBlockToParagraph(node, pos, ctx)];
     }
@@ -1303,11 +1316,13 @@ async function pocExportDocx(editor, margins, chrome, options = {}) {
   const doc = editor.state.doc;
   const ctx = {
     view: editor.view,
-    // quebras `soft` (dentro de um parágrafo) não viram pageBreakBefore:
-    // partir o parágrafo em dois no Word entregaria ao advogado um arquivo
-    // que não reflui ao editar. Ali o Word quebra sozinho, no mesmo lugar
-    // ou a uma linha de distância.
-    breakSet: new Set((options.breaks ?? []).filter((b) => !b.soft).map((b) => b.pos)),
+    // só a quebra pedida pelo template vira pageBreakBefore. As demais
+    // (entre blocos ou entre linhas de um parágrafo) ficam por conta do
+    // Word: ele parte parágrafo, lista e tabela sozinho e empurra imagem
+    // só quando ela de fato não cabe na página DELE. Forçar a quebra do
+    // preview deixava o arquivo com o pé da página vazio sempre que o
+    // Word cabia mais (ou menos) texto que o browser.
+    breakSet: new Set((options.breaks ?? []).filter((b) => b.manual).map((b) => b.pos)),
     pending: { breakBefore: false },
     lastAfterTw: 0,
     meta: /* @__PURE__ */ new WeakMap(),

package/dist/docx.d.mts

@@ -1,4 +1,4 @@
-export { a as PocDocxChrome, b as PocDocxExportOptions, u as pocExportDocx } from './shared/minuta-editor.e223a421.mjs';
+export { a as PocDocxChrome, b as PocDocxExportOptions, w as pocExportDocx } from './shared/minuta-editor.9e65d163.mjs';
 import '@tiptap/core';
 import '@tiptap/pm/model';
 import '@tiptap/pm/view';

package/dist/docx.d.ts

@@ -1,4 +1,4 @@
-export { a as PocDocxChrome, b as PocDocxExportOptions, u as pocExportDocx } from './shared/minuta-editor.e223a421.js';
+export { a as PocDocxChrome, b as PocDocxExportOptions, w as pocExportDocx } from './shared/minuta-editor.9e65d163.js';
 import '@tiptap/core';
 import '@tiptap/pm/model';
 import '@tiptap/pm/view';

package/dist/docx.mjs

@@ -1,5 +1,5 @@
 export { pocExportDocx } from './chunks/docxExport.mjs';
-import './shared/minuta-editor.b2512170.mjs';
+import './shared/minuta-editor.d9d0c0ce.mjs';
 import '@tiptap/pm/state';
 import '@tiptap/pm/view';
 import 'docx';

package/dist/index.d.mts

@@ -19,8 +19,8 @@
 /// <reference types="@tiptap/extension-bubble-menu" />
 import { Node, Editor, Mark, Extension } from '@tiptap/core';
 import { EditorView } from '@tiptap/pm/view';
-import { P as PocPageConfig } from './shared/minuta-editor.e223a421.mjs';
-export { e as PAGINATE_META, a as PocDocxChrome, b as PocDocxExportOptions, q as PocLoneRow, d as PocPageBreak, c as PocPageNote, t as PocPaginationPlugin, s as breaksEqual, h as buildPocFooterEl, g as buildPocHeaderEl, j as buildPocNotesEl, k as computePocBreaks, r as computePocLoneRows, i as isPocChromeCanvas, l as isPocFlexRow, f as pocChromeFlowHeight, o as pocLoneCellIndex, m as pocNodeHasVisibleContent, n as pocNodePaintsBox, p as pocPageKey } from './shared/minuta-editor.e223a421.mjs';
+import { P as PocPageConfig } from './shared/minuta-editor.9e65d163.mjs';
+export { e as PAGINATE_META, a as PocDocxChrome, b as PocDocxExportOptions, s as PocLoneRow, d as PocPageBreak, c as PocPageNote, v as PocPaginationPlugin, u as breaksEqual, h as buildPocFooterEl, g as buildPocHeaderEl, j as buildPocNotesEl, l as computePocBreaks, t as computePocLoneRows, i as isPocChromeCanvas, n as isPocFlexRow, f as pocChromeFlowHeight, m as pocDescendsInto, r as pocLoneCellIndex, k as pocLooksLikeTitle, o as pocNodeHasVisibleContent, q as pocNodePaintsBox, p as pocPageKey } from './shared/minuta-editor.9e65d163.mjs';
 import '@tiptap/pm/model';
 import '@tiptap/pm/state';
 
@@ -92,6 +92,19 @@ declare function resolveTemplateVariables(html: string | null | undefined, value
 declare const POC_ASSET_SWAP = "pocAssetSwap";
 declare const PocDocument: Node<any, any>;
 declare const PocMinutaBlock: Node<any, any>;
+/**
+ * Clique numa variável do case — a ponte documento → formulário. Disparado no
+ * DOM do editor (com bubbling), não em `window`: dois editores na página não
+ * se cruzam, e o host escuta no próprio elemento. `kind` diz o que foi
+ * clicado: chip de texto, `<img data-variable-id>` ou aviso de imagem faltando.
+ */
+type VariableClickKind = 'text' | 'image' | 'missingImage';
+declare function dispatchVariableClick(editor: Editor, detail: {
+    variableId: string | null;
+    parentBlockId: string | null;
+    text: string;
+    kind: VariableClickKind;
+}): void;
 declare const PocHtmlIsland: Node<any, any>;
 /**
  * Aviso de imagem faltando — a caixa tracejada que o render emite quando a
@@ -113,7 +126,12 @@ declare const PocHtmlIsland: Node<any, any>;
  */
 declare const PocMissingImage: Node<any, any>;
 declare const PocVariableChip: Node<any, any>;
-/** `<span data-variable-id>` com o texto trocado — o que `setVariableValue` grava no chip */
+/**
+ * `<span data-variable-id>` com o texto trocado — o que `setVariableValue` grava
+ * no chip. O aviso de variável sem valor (`data-invalid-variable`, vermelho)
+ * é o mesmo nó: ao receber um valor ele vira chip comum — perde a marca de
+ * inválido e o estilo do aviso, mantém id, bloco e índice.
+ */
 declare function variableChipHtml(currentHtml: string, text: string): string;
 /**
  * Placeholder de variável do TEMPLATE — o `#NOME_VARIAVEL` de antigamente, só
@@ -198,12 +216,14 @@ interface MinutaChromeText {
     footerScope?: 'all' | 'first';
     showPageNumber?: boolean;
 }
-/** uma variável do case dentro do documento (`<span data-variable-id>`) */
+/** uma variável do case dentro do documento (`<span data-variable-id>`, `<img data-variable-id>` ou aviso de imagem faltando) */
 interface MinutaVariableRef {
     variableId: string;
     parentBlockId: string | null;
-    /** texto atual do trecho */
+    /** texto atual do trecho (vazio para imagens) */
     text: string;
+    /** o que foi clicado: chip de texto, imagem marcada, ou o aviso de imagem faltando */
+    kind: 'text' | 'image' | 'missingImage';
 }
 interface MinutaEditorOptions {
     /** documento inicial (HTML) */
@@ -252,8 +272,10 @@ interface MinutaEditorOptions {
     /** clique no cabeçalho/rodapé da folha (além do CustomEvent `poc:edit-chrome`) */
     onEditChrome?: (part: 'header' | 'footer') => void;
     /**
-     * Clique numa variável renderizada (`<span data-variable-id>` do documento).
-     * É a ponte documento → formulário: o host recebe o id e foca o campo.
+     * Clique numa variável renderizada: chip de texto (`<span data-variable-id>`),
+     * imagem marcada (`<img data-variable-id>`) ou aviso de imagem faltando —
+     * `kind` diz qual. É a ponte documento → formulário: o host recebe o id e
+     * foca o campo.
      */
     onVariableClick?: (variable: MinutaVariableRef) => void;
     onError?: (message: string) => void;
@@ -291,7 +313,9 @@ interface MinutaEditor {
      * Troca o texto de TODAS as ocorrências da variável no documento — inclusive
      * numa edição livre, porque a marca é um nó e sobrevive à lapidação. É o que
      * deixa um formulário de variáveis continuar valendo depois que o advogado
-     * editou o texto em volta. Devolve quantas ocorrências mudaram.
+     * editou o texto em volta. O aviso de variável sem valor
+     * (`data-invalid-variable`) também é uma ocorrência: ao receber valor vira
+     * chip comum. Devolve quantas ocorrências mudaram.
      */
     setVariableValue: (variableId: string, value: string) => number;
     /**
@@ -302,6 +326,13 @@ interface MinutaEditor {
     setVariableImage: (variableId: string, src: string) => number;
     /** ids marcados no documento, na ordem, sem repetição: chips de texto, imagens e imagens faltando */
     variablesInDocument: () => string[];
+    /**
+     * Renova o `src` das imagens inseridas no editor (as que têm `data-vault-src`):
+     * o presignado do upload expira, então quem reabre uma edição salva passa
+     * um resolvedor `vault://` → URL nova (no defesa.ai, `POST /data/vault/download-url`).
+     * Devolve quantos nós mudaram. Não entra no undo nem dispara `onChange`.
+     */
+    refreshVaultImages: (resolveUrl: (vaultUrl: string) => Promise<string>) => Promise<number>;
     /** repagina (o host chama após mudar algo que afeta altura fora do editor) */
     schedulePaginate: () => void;
     /** reconstrói cabeçalhos/rodapés com o chrome atual, sem repaginar */
@@ -401,6 +432,24 @@ declare function shouldMoveBreakToHeading(params: {
     capacity: number;
 }): boolean;
 
+interface RefreshVaultImagesOptions {
+    /**
+     * Metadados extras da transação (ex.: a marca de "programática" do embed
+     * Nuxt, para o rastro de anotações não contar a troca como texto novo).
+     */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Re-resolve todas as imagens `vault://` do documento: as inseridas pela
+ * toolbar entram com `src` presignado (funciona agora) e `data-vault-src`
+ * durável; como o presignado expira, quem reabre uma edição salva chama isto
+ * no load. `resolveUrl` recebe a `vault://` e devolve a URL nova (no defesa.ai,
+ * `POST /data/vault/download-url`). Devolve quantos nós mudaram.
+ *
+ * Fora do histórico de undo: renovar um link não é uma edição do advogado.
+ */
+declare function refreshVaultImages(editor: Editor, resolveUrl: (vaultUrl: string) => Promise<string>, options?: RefreshVaultImagesOptions): Promise<number>;
+
 /**
  * Sanitização do HTML rico de cabeçalho/rodapé (chrome) — conteúdo criado em
  * contenteditable e PERSISTIDO (template.headers, case_edition.chrome). Sem
@@ -423,5 +472,5 @@ declare function escapeVaultAttr(value: string): string;
 declare function decodeVaultAttr(value: string): string;
 declare function vaultImageHtml(src: string, vaultUrl: string): string;
 
-export { A4_HEIGHT_PX, A4_WIDTH_PX, DEFAULT_MARGINS, DOC_FONTS, ICON_PATHS, POC_ASSET_SWAP, PocDocument, PocFootnoteRef, PocHtmlIsland, PocInlineStyle, PocMinutaBlock, PocMissingImage, PocPageConfig, PocStylePassthrough, PocStyledDiv, PocTemplateVariable, PocUnderline, PocVariableChip, buildPocExtensions, createMinutaEditor, decodeVaultAttr, escapeHtml, escapeVaultAttr, extractTemplateVariables, footnoteHtmlToRuns, footnoteSizePt, iconSvg, renumberPocFootnotes, resolveTemplateVariables, sanitizeFootnoteHtml, sanitizeRichHtml, shouldMoveBreakToHeading, variableChipHtml, vaultImageHtml };
-export type { FootnoteRun, MinutaChromeText, MinutaEditor, MinutaEditorOptions, MinutaHeader, MinutaMargins, MinutaVariableCatalog, MinutaVariableDef, MinutaVariableRef, PocKeepWithNextItem };
+export { A4_HEIGHT_PX, A4_WIDTH_PX, DEFAULT_MARGINS, DOC_FONTS, ICON_PATHS, POC_ASSET_SWAP, PocDocument, PocFootnoteRef, PocHtmlIsland, PocInlineStyle, PocMinutaBlock, PocMissingImage, PocPageConfig, PocStylePassthrough, PocStyledDiv, PocTemplateVariable, PocUnderline, PocVariableChip, buildPocExtensions, createMinutaEditor, decodeVaultAttr, dispatchVariableClick, escapeHtml, escapeVaultAttr, extractTemplateVariables, footnoteHtmlToRuns, footnoteSizePt, iconSvg, refreshVaultImages, renumberPocFootnotes, resolveTemplateVariables, sanitizeFootnoteHtml, sanitizeRichHtml, shouldMoveBreakToHeading, variableChipHtml, vaultImageHtml };
+export type { FootnoteRun, MinutaChromeText, MinutaEditor, MinutaEditorOptions, MinutaHeader, MinutaMargins, MinutaVariableCatalog, MinutaVariableDef, MinutaVariableRef, PocKeepWithNextItem, RefreshVaultImagesOptions, VariableClickKind };

package/dist/index.d.ts

@@ -19,8 +19,8 @@
 /// <reference types="@tiptap/extension-bubble-menu" />
 import { Node, Editor, Mark, Extension } from '@tiptap/core';
 import { EditorView } from '@tiptap/pm/view';
-import { P as PocPageConfig } from './shared/minuta-editor.e223a421.js';
-export { e as PAGINATE_META, a as PocDocxChrome, b as PocDocxExportOptions, q as PocLoneRow, d as PocPageBreak, c as PocPageNote, t as PocPaginationPlugin, s as breaksEqual, h as buildPocFooterEl, g as buildPocHeaderEl, j as buildPocNotesEl, k as computePocBreaks, r as computePocLoneRows, i as isPocChromeCanvas, l as isPocFlexRow, f as pocChromeFlowHeight, o as pocLoneCellIndex, m as pocNodeHasVisibleContent, n as pocNodePaintsBox, p as pocPageKey } from './shared/minuta-editor.e223a421.js';
+import { P as PocPageConfig } from './shared/minuta-editor.9e65d163.js';
+export { e as PAGINATE_META, a as PocDocxChrome, b as PocDocxExportOptions, s as PocLoneRow, d as PocPageBreak, c as PocPageNote, v as PocPaginationPlugin, u as breaksEqual, h as buildPocFooterEl, g as buildPocHeaderEl, j as buildPocNotesEl, l as computePocBreaks, t as computePocLoneRows, i as isPocChromeCanvas, n as isPocFlexRow, f as pocChromeFlowHeight, m as pocDescendsInto, r as pocLoneCellIndex, k as pocLooksLikeTitle, o as pocNodeHasVisibleContent, q as pocNodePaintsBox, p as pocPageKey } from './shared/minuta-editor.9e65d163.js';
 import '@tiptap/pm/model';
 import '@tiptap/pm/state';
 
@@ -92,6 +92,19 @@ declare function resolveTemplateVariables(html: string | null | undefined, value
 declare const POC_ASSET_SWAP = "pocAssetSwap";
 declare const PocDocument: Node<any, any>;
 declare const PocMinutaBlock: Node<any, any>;
+/**
+ * Clique numa variável do case — a ponte documento → formulário. Disparado no
+ * DOM do editor (com bubbling), não em `window`: dois editores na página não
+ * se cruzam, e o host escuta no próprio elemento. `kind` diz o que foi
+ * clicado: chip de texto, `<img data-variable-id>` ou aviso de imagem faltando.
+ */
+type VariableClickKind = 'text' | 'image' | 'missingImage';
+declare function dispatchVariableClick(editor: Editor, detail: {
+    variableId: string | null;
+    parentBlockId: string | null;
+    text: string;
+    kind: VariableClickKind;
+}): void;
 declare const PocHtmlIsland: Node<any, any>;
 /**
  * Aviso de imagem faltando — a caixa tracejada que o render emite quando a
@@ -113,7 +126,12 @@ declare const PocHtmlIsland: Node<any, any>;
  */
 declare const PocMissingImage: Node<any, any>;
 declare const PocVariableChip: Node<any, any>;
-/** `<span data-variable-id>` com o texto trocado — o que `setVariableValue` grava no chip */
+/**
+ * `<span data-variable-id>` com o texto trocado — o que `setVariableValue` grava
+ * no chip. O aviso de variável sem valor (`data-invalid-variable`, vermelho)
+ * é o mesmo nó: ao receber um valor ele vira chip comum — perde a marca de
+ * inválido e o estilo do aviso, mantém id, bloco e índice.
+ */
 declare function variableChipHtml(currentHtml: string, text: string): string;
 /**
  * Placeholder de variável do TEMPLATE — o `#NOME_VARIAVEL` de antigamente, só
@@ -198,12 +216,14 @@ interface MinutaChromeText {
     footerScope?: 'all' | 'first';
     showPageNumber?: boolean;
 }
-/** uma variável do case dentro do documento (`<span data-variable-id>`) */
+/** uma variável do case dentro do documento (`<span data-variable-id>`, `<img data-variable-id>` ou aviso de imagem faltando) */
 interface MinutaVariableRef {
     variableId: string;
     parentBlockId: string | null;
-    /** texto atual do trecho */
+    /** texto atual do trecho (vazio para imagens) */
     text: string;
+    /** o que foi clicado: chip de texto, imagem marcada, ou o aviso de imagem faltando */
+    kind: 'text' | 'image' | 'missingImage';
 }
 interface MinutaEditorOptions {
     /** documento inicial (HTML) */
@@ -252,8 +272,10 @@ interface MinutaEditorOptions {
     /** clique no cabeçalho/rodapé da folha (além do CustomEvent `poc:edit-chrome`) */
     onEditChrome?: (part: 'header' | 'footer') => void;
     /**
-     * Clique numa variável renderizada (`<span data-variable-id>` do documento).
-     * É a ponte documento → formulário: o host recebe o id e foca o campo.
+     * Clique numa variável renderizada: chip de texto (`<span data-variable-id>`),
+     * imagem marcada (`<img data-variable-id>`) ou aviso de imagem faltando —
+     * `kind` diz qual. É a ponte documento → formulário: o host recebe o id e
+     * foca o campo.
      */
     onVariableClick?: (variable: MinutaVariableRef) => void;
     onError?: (message: string) => void;
@@ -291,7 +313,9 @@ interface MinutaEditor {
      * Troca o texto de TODAS as ocorrências da variável no documento — inclusive
      * numa edição livre, porque a marca é um nó e sobrevive à lapidação. É o que
      * deixa um formulário de variáveis continuar valendo depois que o advogado
-     * editou o texto em volta. Devolve quantas ocorrências mudaram.
+     * editou o texto em volta. O aviso de variável sem valor
+     * (`data-invalid-variable`) também é uma ocorrência: ao receber valor vira
+     * chip comum. Devolve quantas ocorrências mudaram.
      */
     setVariableValue: (variableId: string, value: string) => number;
     /**
@@ -302,6 +326,13 @@ interface MinutaEditor {
     setVariableImage: (variableId: string, src: string) => number;
     /** ids marcados no documento, na ordem, sem repetição: chips de texto, imagens e imagens faltando */
     variablesInDocument: () => string[];
+    /**
+     * Renova o `src` das imagens inseridas no editor (as que têm `data-vault-src`):
+     * o presignado do upload expira, então quem reabre uma edição salva passa
+     * um resolvedor `vault://` → URL nova (no defesa.ai, `POST /data/vault/download-url`).
+     * Devolve quantos nós mudaram. Não entra no undo nem dispara `onChange`.
+     */
+    refreshVaultImages: (resolveUrl: (vaultUrl: string) => Promise<string>) => Promise<number>;
     /** repagina (o host chama após mudar algo que afeta altura fora do editor) */
     schedulePaginate: () => void;
     /** reconstrói cabeçalhos/rodapés com o chrome atual, sem repaginar */
@@ -401,6 +432,24 @@ declare function shouldMoveBreakToHeading(params: {
     capacity: number;
 }): boolean;
 
+interface RefreshVaultImagesOptions {
+    /**
+     * Metadados extras da transação (ex.: a marca de "programática" do embed
+     * Nuxt, para o rastro de anotações não contar a troca como texto novo).
+     */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Re-resolve todas as imagens `vault://` do documento: as inseridas pela
+ * toolbar entram com `src` presignado (funciona agora) e `data-vault-src`
+ * durável; como o presignado expira, quem reabre uma edição salva chama isto
+ * no load. `resolveUrl` recebe a `vault://` e devolve a URL nova (no defesa.ai,
+ * `POST /data/vault/download-url`). Devolve quantos nós mudaram.
+ *
+ * Fora do histórico de undo: renovar um link não é uma edição do advogado.
+ */
+declare function refreshVaultImages(editor: Editor, resolveUrl: (vaultUrl: string) => Promise<string>, options?: RefreshVaultImagesOptions): Promise<number>;
+
 /**
  * Sanitização do HTML rico de cabeçalho/rodapé (chrome) — conteúdo criado em
  * contenteditable e PERSISTIDO (template.headers, case_edition.chrome). Sem
@@ -423,5 +472,5 @@ declare function escapeVaultAttr(value: string): string;
 declare function decodeVaultAttr(value: string): string;
 declare function vaultImageHtml(src: string, vaultUrl: string): string;
 
-export { A4_HEIGHT_PX, A4_WIDTH_PX, DEFAULT_MARGINS, DOC_FONTS, ICON_PATHS, POC_ASSET_SWAP, PocDocument, PocFootnoteRef, PocHtmlIsland, PocInlineStyle, PocMinutaBlock, PocMissingImage, PocPageConfig, PocStylePassthrough, PocStyledDiv, PocTemplateVariable, PocUnderline, PocVariableChip, buildPocExtensions, createMinutaEditor, decodeVaultAttr, escapeHtml, escapeVaultAttr, extractTemplateVariables, footnoteHtmlToRuns, footnoteSizePt, iconSvg, renumberPocFootnotes, resolveTemplateVariables, sanitizeFootnoteHtml, sanitizeRichHtml, shouldMoveBreakToHeading, variableChipHtml, vaultImageHtml };
-export type { FootnoteRun, MinutaChromeText, MinutaEditor, MinutaEditorOptions, MinutaHeader, MinutaMargins, MinutaVariableCatalog, MinutaVariableDef, MinutaVariableRef, PocKeepWithNextItem };
+export { A4_HEIGHT_PX, A4_WIDTH_PX, DEFAULT_MARGINS, DOC_FONTS, ICON_PATHS, POC_ASSET_SWAP, PocDocument, PocFootnoteRef, PocHtmlIsland, PocInlineStyle, PocMinutaBlock, PocMissingImage, PocPageConfig, PocStylePassthrough, PocStyledDiv, PocTemplateVariable, PocUnderline, PocVariableChip, buildPocExtensions, createMinutaEditor, decodeVaultAttr, dispatchVariableClick, escapeHtml, escapeVaultAttr, extractTemplateVariables, footnoteHtmlToRuns, footnoteSizePt, iconSvg, refreshVaultImages, renumberPocFootnotes, resolveTemplateVariables, sanitizeFootnoteHtml, sanitizeRichHtml, shouldMoveBreakToHeading, variableChipHtml, vaultImageHtml };
+export type { FootnoteRun, MinutaChromeText, MinutaEditor, MinutaEditorOptions, MinutaHeader, MinutaMargins, MinutaVariableCatalog, MinutaVariableDef, MinutaVariableRef, PocKeepWithNextItem, RefreshVaultImagesOptions, VariableClickKind };