@zaip-ai/cli 6.3.0 → 7.6.0

package/templates/.agents/design/design-system-maker/frontend/catalog/filters.js

@@ -0,0 +1,132 @@
+import { cardPalette } from "../shared/model.js";
+import { previewModel } from "../shared/visual-model.js";
+
+export const colorOptions = [
+  ["red", "Vermelho", "#ef4444"],
+  ["orange", "Laranja", "#f97316"],
+  ["yellow", "Amarelo", "#facc15"],
+  ["green", "Verde", "#22c55e"],
+  ["cyan", "Ciano", "#22d3ee"],
+  ["blue", "Azul", "#3b82f6"],
+  ["purple", "Roxo", "#8b5cf6"],
+  ["pink", "Rosa", "#ec4899"],
+  ["brown", "Marrom", "#92400e"],
+  ["black", "Preto", "#111111"],
+  ["gray", "Cinza", "#9ca3af"],
+  ["white", "Branco", "#ffffff"],
+];
+
+// Coarse hue families for the shared evidence palette, including CSS-only candidates.
+export function colorFamily(value) {
+  if (!/^#(?:[\da-f]{3}|[\da-f]{6}|[\da-f]{8})$/i.test(value ?? "")) return null;
+  let hex = value.slice(1);
+  if (hex.length === 3) hex = [...hex].map((letter) => letter.repeat(2)).join("");
+  if (hex.length === 8 && Number.parseInt(hex.slice(6), 16) < 128) return null;
+  const [r, g, b] = [0, 2, 4].map(
+    (index) => Number.parseInt(hex.slice(index, index + 2), 16) / 255,
+  );
+  const max = Math.max(r, g, b),
+    min = Math.min(r, g, b),
+    delta = max - min;
+  if (max <= 0.16) return "black";
+  if (delta / max <= 0.14) return min >= 0.86 ? "white" : "gray";
+  let hue =
+    delta === 0
+      ? 0
+      : max === r
+        ? ((g - b) / delta) % 6
+        : max === g
+          ? (b - r) / delta + 2
+          : (r - g) / delta + 4;
+  hue = (hue * 60 + 360) % 360;
+  if (hue >= 15 && hue < 50 && max < 0.65) return "brown";
+  if (hue < 15 || hue >= 345) return "red";
+  if (hue < 45) return "orange";
+  if (hue < 70) return "yellow";
+  if (hue < 165) return "green";
+  if (hue < 195) return "cyan";
+  if (hue < 245) return "blue";
+  if (hue < 290) return "purple";
+  return "pink";
+}
+
+export function matchesCatalog(item, query, theme = "", colors = []) {
+  const text = [
+    item.name,
+    item.host,
+    item.url,
+    item.id,
+    item.design_code,
+    item.design_code ? `#${item.design_code}` : null,
+  ]
+    .filter(Boolean)
+    .join(" ")
+    .toLocaleLowerCase("pt-BR");
+  if (!text.includes(query.trim().toLocaleLowerCase("pt-BR"))) return false;
+  if (theme) {
+    const model = previewModel(item);
+    if (!model.available || (model.dark ? "dark" : "light") !== theme) return false;
+  }
+  return (
+    !colors.length ||
+    cardPalette(item, 192).some((token) => colors.includes(colorFamily(token.value)))
+  );
+}
+
+export function mountColorFilter(details, onChange) {
+  const summary = details.querySelector("summary");
+  const options = details.querySelector("fieldset");
+  const inputs = [];
+  const selected = () => inputs.filter((input) => input.checked).map((input) => input.value);
+  const update = () => {
+    const values = selected();
+    summary.textContent =
+      values.length === 1
+        ? colorOptions.find(([id]) => id === values[0])[1]
+        : values.length
+          ? `${values.length} cores`
+          : "Todas as cores";
+    onChange();
+  };
+  for (const [id, name, color] of colorOptions) {
+    const label = document.createElement("label"),
+      input = document.createElement("input"),
+      dot = document.createElement("span");
+    input.type = "checkbox";
+    input.value = id;
+    input.name = "paletteColor";
+    dot.className = "filter-color-dot";
+    dot.style.backgroundColor = color;
+    dot.setAttribute("aria-hidden", "true");
+    label.append(input, dot, name);
+    options.append(label);
+    inputs.push(input);
+    input.addEventListener("change", update);
+  }
+  const clear = () => {
+    for (const input of inputs) input.checked = false;
+    update();
+  };
+  details.querySelector("button").addEventListener("click", clear);
+  const onKey = (event) => {
+    if (event.key === "Escape") {
+      details.open = false;
+      summary.focus();
+    }
+  };
+  const onOutsideClick = (event) => {
+    if (!details.contains(event.target)) details.open = false;
+  };
+  details.addEventListener("keydown", onKey);
+  document.addEventListener("click", onOutsideClick);
+  return {
+    selected,
+    clear,
+    dispose() {
+      for (const input of inputs) input.removeEventListener("change", update);
+      details.querySelector("button").removeEventListener("click", clear);
+      details.removeEventListener("keydown", onKey);
+      document.removeEventListener("click", onOutsideClick);
+    },
+  };
+}

package/templates/.agents/design/design-system-maker/frontend/catalog/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="pt-BR">
+<head><link rel="icon" type="image/png" href="/assets/zaip-icon.png"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Zaip Design System Maker</title><link rel="stylesheet" href="/styles/maker.css"><script type="module" src="/catalog/index.js"></script></head>
+<body class="catalog-v2-page">
+<a class="skip-link" href="#catalogGrid">Pular para a coleção</a>
+<header class="ds-topbar"><h1>Zaip Design System Maker</h1><nav aria-label="Navegação principal"><a class="action primary" href="/generate.html">Criar por URL</a><a class="action" href="/viewer/">Viewer</a><a class="action" href="/viewer/?collection=trash">Lixeira</a><a class="action" href="/advanced/">Avançado</a></nav></header>
+<main class="catalog-v2-main">
+  <div class="catalog-toolbar">
+    <div class="catalog-search-field"><label for="catalogSearch">Buscar designs</label><input type="search" id="catalogSearch" placeholder="Nome, site ou ID" autocomplete="off"></div>
+    <div class="catalog-filter-field"><label for="catalogTheme">Tema</label><select id="catalogTheme"><option value="">Todos os temas</option><option value="light">Light</option><option value="dark">Dark</option></select></div>
+    <div class="catalog-filter-field"><span id="catalogColorLabel" class="filter-label">Cor</span><details id="catalogColors" class="catalog-color-filter"><summary aria-labelledby="catalogColorLabel catalogColorSummary" id="catalogColorSummary">Todas as cores</summary><div class="catalog-color-options"><fieldset><legend>Cores da paleta do card</legend></fieldset><button type="button">Limpar cores</button></div></details></div>
+    <button id="catalogClear" class="catalog-clear" type="button" disabled>Limpar filtros</button>
+    <p id="catalogStatus" role="status" aria-live="polite">Carregando coleção…</p>
+  </div>
+  <div id="catalogGrid" class="catalog-grid" tabindex="-1" aria-busy="true"></div><div class="page-actions"><button id="catalogMore" type="button" hidden>Carregar mais outputs</button><button id="catalogRetry" type="button" hidden>Tentar novamente</button></div><noscript>Ative JavaScript para consultar a coleção local.</noscript>
+</main>
+</body></html>

package/templates/.agents/design/design-system-maker/frontend/catalog/index.js

@@ -0,0 +1,82 @@
+import { CollectionPager } from "../shared/api.js";
+import { empty, extractionCard } from "../shared/components.js";
+import { hydrateVisualModels } from "../shared/model-hydration.js";
+import { matchesCatalog, mountColorFilter } from "./filters.js";
+
+const pager = new CollectionPager();
+const grid = document.querySelector("#catalogGrid");
+const search = document.querySelector("#catalogSearch");
+const status = document.querySelector("#catalogStatus");
+const more = document.querySelector("#catalogMore");
+const retry = document.querySelector("#catalogRetry");
+const theme = document.querySelector("#catalogTheme");
+const clear = document.querySelector("#catalogClear");
+const colors = mountColorFilter(document.querySelector("#catalogColors"), render);
+function render() {
+  const selected = colors.selected();
+  const filtered = pager.items.filter((item) =>
+    matchesCatalog(item, search.value, theme.value, selected),
+  );
+  clear.disabled = !search.value && !theme.value && !selected.length;
+  grid.replaceChildren(...filtered.map(extractionCard));
+  if (!filtered.length)
+    grid.append(
+      empty(
+        pager.total === 0 ? "Sua coleção começa aqui" : "Nenhum output encontrado",
+        pager.total === 0
+          ? "Crie um DESIGN.md por URL para guardar sua primeira referência."
+          : "Altere a busca, limpe os filtros ou carregue mais designs.",
+      ),
+    );
+  const count = document.createElement("span");
+  const number = (value) => {
+    const strong = document.createElement("strong");
+    strong.textContent = String(value);
+    return strong;
+  };
+  count.append(number(filtered.length));
+  if (pager.total != null) count.append(" de ", number(pager.total));
+  count.append(" designs");
+  status.replaceChildren(count);
+  if (pager.total == null || pager.total > pager.items.length) {
+    const hint = document.createElement("small");
+    hint.textContent =
+      pager.total == null ? "Total ainda desconhecido" : "Busca nos designs carregados";
+    status.append(hint);
+  }
+  more.hidden = pager.next === null;
+  more.disabled = pager.busy;
+  retry.hidden = true;
+}
+async function load() {
+  grid.setAttribute("aria-busy", "true");
+  more.disabled = true;
+  retry.hidden = true;
+  status.textContent = "Carregando outputs…";
+  try {
+    await pager.more();
+    await hydrateVisualModels(pager.items);
+    render();
+  } catch (error) {
+    status.textContent = `Não foi possível carregar a coleção: ${error.message}`;
+    retry.hidden = false;
+    more.hidden = true;
+    if (!pager.items.length)
+      grid.replaceChildren(
+        empty("Coleção indisponível", "Tente novamente para consultar os outputs locais."),
+      );
+  } finally {
+    grid.setAttribute("aria-busy", "false");
+    more.disabled = false;
+  }
+}
+search.addEventListener("input", render);
+theme.addEventListener("change", render);
+clear.addEventListener("click", () => {
+  search.value = "";
+  theme.value = "";
+  colors.clear();
+});
+more.addEventListener("click", load);
+retry.addEventListener("click", load);
+await load();

package/templates/.agents/design/design-system-maker/frontend/generate.html

@@ -0,0 +1,74 @@
+<!doctype html>
+<html lang="pt-BR">
+<head><link rel="icon" type="image/png" href="/assets/zaip-icon.png">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Gerar por URL · ZAIP</title>
+<link rel="stylesheet" href="/styles/maker.css">
+<script type="module" src="/generate.js">
+</script>
+</head>
+<body class="page-body">
+<a class="skip-link" href="#generateForm">Pular para o formulário</a>
+<header class="topbar ds-topbar">
+<div>
+<p class="kicker">URL TO DESIGN.MD</p>
+<h1>Gerar por URL</h1>
+</div>
+<nav aria-label="Navegação principal">
+<a class="action" href="/catalog/">Catálogo</a>
+<a class="action" href="/viewer/">Viewer</a>
+</nav>
+</header>
+<main class="generate-main">
+<section class="generate-hero">
+<p class="kicker">NOVO OUTPUT</p>
+<h2>Cole uma URL pública e gere um DESIGN.md</h2>
+<p>Guarde observações, candidatos de tokens e componentes em uma coleção local, com fonte, incertezas e histórico de revisões.</p>
+</section>
+<div class="generate-layout">
+<form id="generateForm" class="panel" novalidate>
+<h3 id="formTitle">Uma referência, um novo output</h3>
+<label for="sourceUrl">URL pública</label>
+<input type="url" id="sourceUrl" name="url" placeholder="https://exemplo.com" required maxlength="4096" aria-describedby="urlHelp formError">
+<p id="urlHelp" class="help">Informe uma URL pública. Endereços sem protocolo receberão https:// antes da validação.</p>
+<label for="outputName">Nome do output <span class="muted">(opcional)</span>
+</label>
+<input id="outputName" name="name" maxlength="128" placeholder="Nome para encontrar no catálogo">
+<p id="revisionInfo" class="meta">Novo output · primeira revisão</p>
+<label class="browser-option" for="browserMode">
+<input id="browserMode" type="checkbox" disabled aria-describedby="browserHelp browserAvailability">
+<span>Abrir navegador local para extrair</span>
+</label>
+<p id="browserHelp" class="help">Abre uma janela própria, sem seus cookies pessoais. Se houver um desafio, conclua-o nessa janela. Espera de até 120 segundos; você pode cancelar.</p>
+<p id="browserAvailability" class="meta" role="status">Verificando disponibilidade do navegador local…</p>
+<p id="formError" class="error" role="alert">
+</p>
+<div class="page-actions">
+<button id="generateSubmit" class="primary" type="submit" disabled>Gerar DESIGN.md</button>
+<button id="sessionRetry" type="button" hidden>Reconectar sessão</button>
+<a class="action" href="/generate.html" id="newOutput" hidden>Criar outro output</a>
+</div>
+<p class="help">Relatório de evidências CSS com fontes, amostragem e histórico. Cobertura da extração não é avaliação de qualidade visual ou acessibilidade.</p>
+</form>
+<section class="job-panel panel" aria-labelledby="jobTitle">
+<p class="kicker">EXTRAÇÃO</p>
+<h3 id="jobTitle">Acompanhe o output</h3>
+<span id="jobSpinner" class="job-spinner" aria-hidden="true" hidden></span>
+<p id="jobStatus" role="status" aria-live="polite">Preparando sessão local…</p>
+<div id="jobDetails"></div>
+<div id="jobResult">
+</div>
+<button id="jobRetry" type="button" hidden>Retomar acompanhamento</button>
+<button id="jobCancel" type="button" hidden>Cancelar extração no navegador</button>
+<h4>Registro da operação</h4>
+<!-- biome-ignore lint/a11y/noNoninteractiveTabindex: scrollable log region needs keyboard access -->
+<section class="code-region" tabindex="0" aria-label="Registro da operação">
+<pre id="jobLog">Nenhuma operação iniciada.</pre>
+</section>
+</section>
+</div>
+<noscript>Ative JavaScript para iniciar a extração.</noscript>
+</main>
+</body>
+</html>

package/templates/.agents/design/design-system-maker/frontend/generate.js

@@ -0,0 +1,226 @@
+import { cancelJob, connect, detail, generate, job, reprocess } from "./shared/api.js";
+import { action } from "./shared/components.js";
+import { jobText, renderJobProgress } from "./shared/job-view.js";
+import { normalizeInputUrl, viewerPath } from "./shared/model.js";
+
+const form = document.querySelector("#generateForm");
+const submit = document.querySelector("#generateSubmit");
+const url = document.querySelector("#sourceUrl");
+const name = document.querySelector("#outputName");
+const errorMessage = document.querySelector("#formError");
+const status = document.querySelector("#jobStatus");
+const result = document.querySelector("#jobResult");
+const log = document.querySelector("#jobLog");
+const progress = document.querySelector("#jobDetails");
+const spinner = document.querySelector("#jobSpinner");
+const sessionRetry = document.querySelector("#sessionRetry");
+const jobRetry = document.querySelector("#jobRetry");
+const browserMode = document.querySelector("#browserMode");
+const browserAvailability = document.querySelector("#browserAvailability");
+const jobCancel = document.querySelector("#jobCancel");
+const params = new URLSearchParams(location.search);
+const id = params.get("id");
+let expectedRevision = null;
+let activeJob = params.get("job");
+let timer = null;
+let controller = null;
+let busy = false;
+let ready = false;
+let browserAvailable = false;
+let browserJobActive = false;
+let cancelRevision = null;
+let cancelling = false;
+function configureBrowser(capabilities) {
+  const browser = capabilities?.browser;
+  browserAvailable = browser?.available === true && browser.method === "local-isolated-cdp";
+  browserAvailability.textContent = browserAvailable
+    ? "Coleta renderizada selecionada: abre uma janela própria para carregar páginas dinâmicas. Desmarque para usar somente HTML/CSS via HTTP."
+    : `Navegador local indisponível: ${browser?.reason ?? "disponibilidade não informada pela sessão"}. A extração HTTP continua disponível.`;
+  if (!browserAvailable) browserMode.checked = false;
+  else browserMode.checked = params.get("mode") !== "http";
+}
+function setBusy(value) {
+  busy = value;
+  submit.disabled = value || !ready;
+  url.disabled = value;
+  name.disabled = value;
+  name.readOnly = Boolean(id);
+  browserMode.disabled = value || !browserAvailable;
+  submit.textContent = browserMode.checked ? "Abrir navegador e extrair" : "Gerar DESIGN.md";
+  form.setAttribute("aria-busy", String(value));
+  spinner.hidden = !value;
+}
+function showError(error) {
+  const prefix =
+    error.status === 409
+      ? "A revisão mudou. Reconecte para carregar a atual. "
+      : error.status === 429
+        ? "Fila cheia. Aguarde uma operação terminar e tente novamente. "
+        : error.status === 403
+          ? "A sessão mudou. Reconecte antes de gerar. "
+          : "";
+  errorMessage.textContent = prefix + error.message;
+  if ([403, 409].includes(error.status)) {
+    ready = false;
+    sessionRetry.hidden = false;
+  }
+}
+async function prepare() {
+  ready = false;
+  setBusy(true);
+  sessionRetry.hidden = true;
+  errorMessage.textContent = "";
+  try {
+    configureBrowser(await connect());
+    if (id) {
+      const value = await detail(id);
+      url.value = value.summary.replay_available ? value.summary.request_url : "";
+      name.value = value.summary.name;
+      expectedRevision = value.revision;
+      document.querySelector("#urlHelp").textContent = value.summary.replay_available
+        ? "URL exata e segura da solicitação original, preservada separadamente da URL final."
+        : (value.summary.replay_unavailable_reason ??
+          "URL exata indisponível: forneça o endereço seguro explicitamente.");
+      document.querySelector("#formTitle").textContent = "Reprocessar referência";
+      document.querySelector("#revisionInfo").textContent =
+        `Output ${id} · revisão atual ${expectedRevision} · próxima revisão ${expectedRevision + 1}`;
+      document.querySelector("#newOutput").hidden = false;
+      if (value.status === "collecting")
+        throw new Error(
+          "Este output ainda está coletando. Acompanhe pelo Viewer antes de reprocessar.",
+        );
+    }
+    ready = true;
+    status.textContent = "Pronto para iniciar uma extração.";
+  } catch (error) {
+    showError(error);
+    sessionRetry.hidden = false;
+    status.textContent = "Preparação indisponível; nenhuma operação iniciada.";
+  } finally {
+    setBusy(false);
+  }
+}
+function renderJob(value) {
+  status.textContent = jobText(value);
+  renderJobProgress(value, progress, log);
+  browserJobActive =
+    (value.mode === "browser" || Boolean(value.browser)) &&
+    ["queued", "running"].includes(value.status);
+  if (Number.isInteger(value.summary?.revision)) cancelRevision = value.summary.revision;
+  jobCancel.hidden = !browserJobActive;
+  jobCancel.disabled = cancelling || !Number.isInteger(cancelRevision);
+  result.replaceChildren(
+    action(
+      "Abrir relatório no Viewer →",
+      viewerPath(value.entry_id, value.result_revision ?? null),
+      true,
+    ),
+  );
+}
+async function poll() {
+  clearTimeout(timer);
+  controller?.abort();
+  controller = new AbortController();
+  const active = controller;
+  jobRetry.hidden = true;
+  try {
+    const value = await job(activeJob, active.signal);
+    if (active !== controller) return;
+    renderJob(value);
+    if (["queued", "running"].includes(value.status)) {
+      timer = setTimeout(poll, 1000);
+      return;
+    }
+    ready = false;
+    setBusy(false);
+    sessionRetry.hidden = false;
+    sessionRetry.textContent = id ? "Preparar nova revisão" : "Preparar outra extração";
+  } catch (error) {
+    if (error.name === "AbortError" || active !== controller) return;
+    spinner.hidden = true;
+    status.textContent = `Acompanhamento interrompido: ${error.message}. A operação pode continuar no servidor.`;
+    jobRetry.hidden = false;
+  }
+}
+form.addEventListener("submit", async (event) => {
+  event.preventDefault();
+  if (busy || !ready) return;
+  setBusy(true);
+  status.textContent = "Enviando referência…";
+  errorMessage.textContent = "";
+  url.removeAttribute("aria-invalid");
+  result.replaceChildren();
+  progress.replaceChildren();
+  jobCancel.hidden = true;
+  cancelRevision = null;
+  log.textContent = "Aguardando confirmação do servidor local.";
+  let requestSent = false;
+  try {
+    const normalized = normalizeInputUrl(url.value);
+    url.value = normalized.url;
+    if (normalized.addedHttps)
+      document.querySelector("#urlHelp").textContent =
+        "Adicionado https:// ao endereço informado; a API validará o destino.";
+    requestSent = true;
+    const mode = browserMode.checked ? "browser" : undefined;
+    const accepted = id
+      ? await reprocess(id, expectedRevision, normalized.url, mode)
+      : await generate({ url: normalized.url, name: name.value.trim(), mode });
+    activeJob = accepted.jobId;
+    if (Number.isInteger(accepted.entry?.revision)) cancelRevision = accepted.entry.revision;
+    status.textContent = "Na fila";
+    if (accepted.job) renderJob(accepted.job);
+    await poll();
+  } catch (error) {
+    showError(error);
+    if (!requestSent) url.setAttribute("aria-invalid", "true");
+    status.textContent =
+      requestSent && !error.status
+        ? "Resposta não recebida. A operação pode ter sido aceita; consulte o catálogo antes de tentar novamente."
+        : "A extração não foi aceita; nenhum progresso foi presumido.";
+    if (requestSent && !error.status) {
+      ready = false;
+      sessionRetry.hidden = false;
+    }
+    setBusy(false);
+    if (!requestSent) url.focus();
+  }
+});
+sessionRetry.addEventListener("click", prepare);
+browserMode.addEventListener("change", () => setBusy(busy));
+jobCancel.addEventListener("click", async () => {
+  if (cancelling || !browserJobActive || !Number.isInteger(cancelRevision)) return;
+  cancelling = true;
+  jobCancel.disabled = true;
+  try {
+    await cancelJob(activeJob, cancelRevision);
+    await poll();
+  } catch (error) {
+    showError(error);
+    status.textContent = `Cancelamento não confirmado: ${error.message}. Retome o acompanhamento para conferir a operação.`;
+    jobRetry.hidden = false;
+  } finally {
+    cancelling = false;
+    jobCancel.disabled = !Number.isInteger(cancelRevision);
+  }
+});
+jobRetry.addEventListener("click", () => {
+  spinner.hidden = false;
+  poll();
+});
+window.addEventListener("pagehide", () => {
+  clearTimeout(timer);
+  controller?.abort();
+});
+if (activeJob) {
+  try {
+    configureBrowser(await connect());
+    setBusy(true);
+    status.textContent = "Retomando acompanhamento…";
+    await poll();
+  } catch (error) {
+    showError(error);
+    setBusy(false);
+    sessionRetry.hidden = false;
+  }
+} else await prepare();

package/templates/.agents/design/design-system-maker/frontend/shared/api.js

@@ -0,0 +1,112 @@
+import { entryPath } from "./model.js";
+
+let session = null;
+export class ApiError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+}
+export async function request(path, options = {}) {
+  if (!path.startsWith("/api/") || path.startsWith("//") || path.includes("\\"))
+    throw new Error("Somente API local é permitida");
+  const response = await fetch(path, { credentials: "same-origin", cache: "no-store", ...options });
+  const body = await response.json();
+  if (!response.ok)
+    throw new ApiError(body.error || `Erro HTTP ${response.status}`, response.status);
+  return body;
+}
+export async function connect() {
+  session = await request("/api/session");
+  return session.capabilities;
+}
+export function detail(id, revision = null, offset = 0, signal) {
+  const path = entryPath(id, "", revision);
+  return request(
+    `${path}${revision == null ? "?" : "&"}history_offset=${offset}&history_limit=20`,
+    { signal },
+  );
+}
+export function job(id, signal) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$/.test(id)) throw new Error("Job inválido");
+  return request(`/api/jobs/${encodeURIComponent(id)}`, { signal });
+}
+export function generate({ url, name, id, expected_revision, mode }) {
+  const input = { url };
+  addMode(input, mode);
+  if (name) input.name = name;
+  if (id) {
+    entryPath(id);
+    input.id = id;
+    input.expected_revision = expected_revision;
+  }
+  return mutate("/api/generate", "POST", input);
+}
+function mutate(path, method, input) {
+  if (!session?.nonce) throw new Error("Reconecte a sessão local antes de gerar");
+  return request(path, {
+    method,
+    headers: { "Content-Type": "application/json", "X-Maker-Nonce": session.nonce },
+    body: JSON.stringify(input),
+  });
+}
+function addMode(input, mode) {
+  if (mode == null) return;
+  if (!["http", "browser"].includes(mode)) throw new Error("Modo de extração inválido");
+  input.mode = mode;
+}
+export function reprocess(id, expected_revision, url, mode) {
+  const input = { expected_revision };
+  if (url) input.url = url;
+  addMode(input, mode);
+  return mutate(`${entryPath(id)}/reprocess`, "POST", input);
+}
+export function cancelJob(id, expected_revision) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,95}$/.test(id)) throw new Error("Job inválido");
+  if (!Number.isInteger(expected_revision) || expected_revision < 1)
+    throw new Error("Revisão do job indisponível; retome o acompanhamento");
+  return mutate(`/api/jobs/${encodeURIComponent(id)}/cancel`, "POST", { expected_revision });
+}
+export function moveToTrash(summary) {
+  return mutate(entryPath(summary.id), "DELETE", {
+    expected_revision: summary.revision,
+    expected_trash_revision: summary.trash_revision,
+  });
+}
+export function restore(summary) {
+  entryPath(summary.id);
+  return mutate(`/api/trash/${encodeURIComponent(summary.id)}/restore`, "POST", {
+    expected_revision: summary.revision,
+    expected_trash_revision: summary.trash_revision,
+  });
+}
+export class CollectionPager {
+  items = [];
+  total = null;
+  next = 0;
+  busy = false;
+  constructor(collection = "extracts") {
+    if (!["extracts", "trash"].includes(collection)) throw new Error("Coleção inválida");
+    this.collection = collection;
+  }
+  async more() {
+    if (this.busy || this.next === null) return;
+    this.busy = true;
+    try {
+      const page = await request(`/api/${this.collection}?offset=${this.next}&limit=100`);
+      if (
+        !Array.isArray(page.extracts) ||
+        !Number.isInteger(page.total) ||
+        (page.next_offset != null && page.next_offset <= this.next)
+      )
+        throw new Error("Paginação inválida recebida da API");
+      const items = new Map(this.items.map((item) => [item.id, item]));
+      for (const item of page.extracts) items.set(item.id, item);
+      this.items = [...items.values()];
+      this.total = page.total;
+      this.next = page.next_offset;
+    } finally {
+      this.busy = false;
+    }
+  }
+}