synthesisui 0.16.502 → 0.16.504

package/dist/claude-md.js

@@ -10,7 +10,7 @@ import { readResponsiveForm, responsiveLine } from "./responsive-form.js";
  * A LEITURA - o caminho do sistema desde a fase 1 (18/10). Escrita uma vez e usada nos dois contratos: o de quem já tem
  * sistema sem `rules.json` e o de quem chegou pela porta e ainda não tem sistema nenhum (fase 2).
  */
-const READ_THE_PAGE = "**Once the first screen is done, offer to read it - once.** If their next message does not take the offer up, do not offer it again; they can still ask. When the person asks you to read their page - or right after the creation of the first screen ends (with impeccable, once it has written `DESIGN.md`; never while it still asks for another round) - run `npx synthesisui read` with the dev server up, tell them in a few lines the system it found, then ask the questions in `_synthesisui/reading.json` ONE AT A TIME with your question tool (the first option is the default). Save their answers as `{ \"<question id>\": <option index> }` and run `npx synthesisui read --confirm <that file>`: their answers become the roles and breaks this project keeps.";
+const READ_THE_PAGE = "**Once the first screen is done, offer to read it - once.** If their next message does not take the offer up, do not offer it again; they can still ask. When the person asks you to read their page - or right after the creation of the first screen ends (with impeccable, once it has written `DESIGN.md`; never while it still asks for another round) - run `npx synthesisui read` with the dev server up, tell them in a few lines the system it found, then ask ALL the questions in `_synthesisui/reading.json` TOGETHER, in one call of your question tool (up to 4 per call; more go in a second call), in plain words and quoting the text on the page each one is about (the first option is the default). Save their answers as `{ \"<question id>\": <option index> }` and run `npx synthesisui read --confirm <that file>`: their answers become the roles and breaks this project keeps.";
 /** A frase do revisor depois da criação - ver o comentário em `renderRegion`, junto dos papéis. */
 const REVIEWER_AFTER_CREATION = "\n\n**How a change closes here.** The visual world is decided - the roles and breaks above. From here on SynthesisUI's check closes a change (`check_file`, and the end-of-turn check). Impeccable's reviewer is for creating: spawn `impeccable-finish-reviewer` or run `impeccable detect` only when the person asks for a new visual direction or a large new surface with its own look - never as the routine close of a change, and never its degraded self-review in its place.";
 const START = "<!-- synthesisui:start -->";

package/dist/commands/hook.js

@@ -4,6 +4,7 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { readAutoSync, startSync } from "../auto-sync.js";
 import { changedSince } from "../changed-files.js";
+import { rereadScreens } from "../reading/reread.js";
 import { emptyTally, exportedNames, internalSpecifiers, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
 import { checkContracts } from "../doctor/contract-check.js";
 import { componentOf } from "../doctor/component-of.js";
@@ -767,6 +768,10 @@ async function endOfTurn(root, input) {
     const grown = await takeGrowthNote(root).catch(() => null);
     if (grown)
         said.push(grown);
+    /** A tela relida - E01 da fase 3 (20/10): o contraste e o tamanho que só a página renderizada mostra. */
+    const screens = changed.length > 0 ? await rereadScreens(root, changed, input.transcript_path).catch(() => null) : null;
+    if (screens)
+        said.push(screens);
     const offer = await offerTheReading(root, changed, input.transcript_path, clock).catch(() => null);
     await moveTurnClock(root);
     out(said.length === 0 && !offer

package/dist/commands/read.js

@@ -1,14 +1,15 @@
 import { execFileSync } from "node:child_process";
 import { desligarCaptura, ligarCaptura } from "../transcript.js";
 import { adopt } from "./adopt.js";
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { join, relative } from "node:path";
 import { classify, pixelRatio } from "../reading/classify.js";
 import { PAGE_SCRIPT } from "../reading/page-script.js";
+import { headingsOf } from "../reading/reread.js";
 import { decodePng } from "../reading/png.js";
-import { globalClassOf, globalStyles, moduleClassName, pxOf } from "../role-rules.js";
+import { PENDING, globalClassOf, loadRoleRules, globalStyles, moduleClassName, pxOf, readPending } from "../role-rules.js";
 import { agentsToMaintain } from "../agents-chosen.js";
 import { syncClaudeMd } from "../claude-md.js";
 import { projectRootFrom } from "./hook.js";
@@ -28,23 +29,26 @@ import { projectRootFrom } from "./hook.js";
  */
 const READER_VERSION = "1.58.2";
 const READER_DIR = join(homedir(), ".synthesisui", "reader");
-const VIEWPORTS = [
+export const VIEWPORTS = [
     ["desktop", 1440, 900],
     ["celular", 390, 844],
 ];
-function loadReader(say) {
+/** `download: false` é o fim do turno: ele nunca baixa nada sozinho - sem o leitor na máquina, não relê (E01, fase 3). */
+export function loadReader(say, download = true) {
     const override = process.env.SYNTHESISUI_PLAYWRIGHT;
     if (override)
         return createRequire(join(override, "package.json"))(override);
     const mod = join(READER_DIR, "node_modules", "playwright-core");
     if (!existsSync(mod)) {
+        if (!download)
+            return null;
         say(`First read on this machine: downloading the page reader (playwright-core ${READER_VERSION}, about 3 MB) into ${READER_DIR}. It is used only by \`read\`.`);
         mkdirSync(READER_DIR, { recursive: true });
         execFileSync("npm", ["install", "--prefix", READER_DIR, "--no-save", "--no-audit", "--no-fund", `playwright-core@${READER_VERSION}`], { stdio: "ignore" });
     }
     return createRequire(join(READER_DIR, "package.json"))("playwright-core");
 }
-async function launch(pw, say) {
+export async function launch(pw, say, download = true) {
     for (const o of [{}, { channel: "chrome" }, { channel: "msedge" }]) {
         try {
             return await pw.chromium.launch(o);
@@ -53,6 +57,8 @@ async function launch(pw, say) {
             /* o próximo */
         }
     }
+    if (!download)
+        return null;
     say("No Chromium found on this machine: downloading one for the reader (about 150 MB, once).");
     execFileSync(process.execPath, [join(READER_DIR, "node_modules", "playwright-core", "cli.js"), "install", "chromium"], { stdio: "ignore" });
     return pw.chromium.launch();
@@ -62,7 +68,7 @@ async function launch(pw, say) {
  * (`-p 3389`, `--port 3389`, `PORT=3389`) vem antes das portas de sempre. Sem isto, numa máquina com outro projeto na
  * 3000, a leitura descreveria a página de outra pessoa.
  */
-function declaredPort(root) {
+export function declaredPort(root) {
     try {
         const dev = (JSON.parse(readFileSync(join(root, "package.json"), "utf8")).scripts?.dev ?? "");
         const m = dev.match(/(?:-p|--port)[ =](\d{2,5})|PORT=(\d{2,5})/);
@@ -72,12 +78,12 @@ function declaredPort(root) {
         return null;
     }
 }
-async function findServer(url, root) {
+export async function findServer(url, root, waitMs = 4000) {
     const port = declaredPort(root);
     const cands = url ? [url] : [...(port ? [`http://localhost:${port}`] : []), "http://localhost:3000", "http://localhost:3001", "http://localhost:5173", "http://localhost:4321"];
     for (const u of cands) {
         try {
-            const r = await fetch(u, { signal: AbortSignal.timeout(4000) });
+            const r = await fetch(u, { signal: AbortSignal.timeout(waitMs) });
             if (r.status < 500)
                 return u;
         }
@@ -87,6 +93,26 @@ async function findServer(url, root) {
     }
     return null;
 }
+/**
+ * CADA CONTRASTE BAIXO CONFERIDO PELOS PIXELS: sem tinta é texto não pintado; acima do alvo, o DOM errou o fundo. A mesma
+ * conferência na leitura e no fim do turno (E01 da fase 3) - duas cópias divergiriam no primeiro conserto.
+ */
+export async function confirmByPixels(found, pageOf) {
+    const confirmed = [];
+    for (const f of found) {
+        const page = pageOf(f.sample);
+        let px = null;
+        if (page && f.sample.w >= 2 && f.sample.h >= 2) {
+            const png = await page.screenshot({ fullPage: true, clip: { x: Math.max(0, f.sample.x), y: Math.max(0, f.sample.y), width: f.sample.w, height: f.sample.h } }).catch(() => null);
+            const rgba = png ? decodePng(png) : null;
+            px = rgba ? pixelRatio(rgba) : null;
+        }
+        if (px !== null && (px < 1.2 || px >= f.alvo))
+            continue;
+        confirmed.push({ ...f, pixels: px });
+    }
+    return confirmed;
+}
 /** O maior tamanho entre as classes de um texto (o do desktop), sem o prefixo de tela - a mesma escolha da checagem. */
 function sizeClassOf(cls) {
     const toks = cls.match(/(?:[a-z0-9]+:)?text-(?:\[(?:clamp\([^\]\s]+\)|[\d.]+(?:rem|px|em))\]|xs|sm|base|lg|[2-9]?xl)(?=\s|$|\|)/g) ?? [];
@@ -95,7 +121,7 @@ function sizeClassOf(cls) {
     const best = toks.sort((a, b) => (pxOf(b) ?? 0) - (pxOf(a) ?? 0))[0];
     return best.replace(/^(?:[a-z0-9]+:)+/, "");
 }
-function sources(root) {
+export function sources(root) {
     const out = [];
     const walk = (d) => {
         for (const n of readdirSync(d)) {
@@ -135,7 +161,7 @@ function moduleOf(cls, files) {
     return null;
 }
 let stylesOf = null;
-function homeOf(root, files, t) {
+export function homeOf(root, files, t) {
     const sized = sizeClassOf(t.cls);
     /* a classe global (o juízo dele, 19/10): `className="section-title"` com o tamanho no globals.css - a do elemento
        primeiro, depois a do pai (o `<h3>` sem classe dentro de `.route`, medido em `.route h3`) */
@@ -174,6 +200,17 @@ function homeOf(root, files, t) {
  * "5-8 perguntas por projeto, não 300"). As quebras vêm primeiro: dizer sim à própria assinatura é o caminho feliz. A
  * primeira opção é sempre a padrão, e é o que vale quando a pessoa não responde.
  */
+/**
+ * O TEXTO QUE A PESSOA VÊ NA PÁGINA - o juízo dele (19/10): "O título de capa passa bem acima da escala (180px contra
+ * 70px)" pede que ela ache sozinha qual título é. Com o texto ("TRILHO 07") ela reconhece na hora. `seen` vem como
+ * "rota: texto"; até 40 caracteres.
+ */
+function quoted(seen) {
+    const t = seen?.[0]?.replace(/^[^:]*:\s*/, "").trim();
+    if (!t)
+        return "this";
+    return `"${t.length > 40 ? `${t.slice(0, 39)}…` : t}"`;
+}
 /** O nome que a pessoa entende - nunca o rótulo interno da classificação ("h3 de cartão", "número"). */
 function plainRole(role) {
     if (role === "número")
@@ -184,12 +221,18 @@ function plainRole(role) {
         return "block";
     return nameOf(role);
 }
-function questionsFor(breaks, drift) {
+export function questionsFor(breaks, drift, newRoles = []) {
     const qs = breaks.map((b) => ({
         id: `break:${b.rule}:${b.role}:${b.px}`,
-        text: `Is this on purpose? The ${plainRole(b.role)} ${b.rule === "Q2" ? "is tilted off the grid" : b.rule === "Q3" ? "is a big motif, outside the headings" : "goes above the heading scale"} (${b.what}).`,
+        text: `Is ${quoted(b.seen)} on purpose? The ${plainRole(b.role)} ${b.rule === "Q2" ? "is tilted off the grid" : b.rule === "Q3" ? "is a big motif, outside the headings" : "goes above the heading scale"} (${b.what}).`,
         options: ["Yes, it is part of my design", "No, make it follow the scale"],
     }));
+    for (const n of newRoles)
+        qs.push({
+            id: newRoleId(n),
+            text: `Is ${quoted([n.text])} a new kind of heading? It is ${n.px}px, and no heading role here has that size${n.closest ? ` (the closest is the ${n.closest.name}, ${n.closest.px}px)` : ""}.`,
+            options: ["Yes, it is a new kind of heading", n.closest ? `No, it is the ${n.closest.name} (${n.closest.px}px)` : "No, make it follow the scale"],
+        });
     const groups = new Map();
     for (const d of drift) {
         const g = groups.get(`${d.role}|${d.surface}`) ?? { role: d.role, surface: d.surface, rulePx: d.rulePx, pxs: [] };
@@ -204,6 +247,26 @@ function questionsFor(breaks, drift) {
         });
     return qs.slice(0, 8);
 }
+const newRoleId = (n) => `newrole:${n.element}:${n.class}:${n.file}`;
+function newRolesOnPage(pending, seen, home, 
+/** os papéis do sistema que ela JÁ confirmou - a pergunta é contra eles, nunca contra o que esta leitura acabou de
+ *  inferir (medido em 20/10: a leitura fez do próprio título novo um papel, e a pergunta saiu "o mais perto é ele mesmo") */
+roles) {
+    const out = [];
+    for (const p of pending) {
+        const t = seen.find((s) => s.disp === "desktop" && s.papel === p.element && s.tag === p.element && (() => {
+            const h = home(s);
+            return h?.file === p.file && h?.cls === p.class;
+        })());
+        if (!t)
+            continue;
+        const context = t.cartao ? "card" : t.corrido ? "prose" : "section";
+        const same = roles.filter((r) => r.element === p.element && r.class !== p.class);
+        const c = [...same].sort((a, b) => Math.abs(a.px - t.tam) - Math.abs(b.px - t.tam))[0];
+        out.push({ ...p, px: Math.round(t.tam * 10) / 10, text: t.texto, context, closest: c ? { id: c.id, name: c.name, px: c.px } : null });
+    }
+    return out;
+}
 const contextOf = (role) => (role.includes("cartão") ? "card" : role.includes("texto corrido") ? "prose" : "section");
 const NAME = { h1: "cover title", h2: "section title", h3: "subheading" };
 const nameOf = (role) => {
@@ -266,7 +329,27 @@ export async function confirm(opts) {
         /* o ARQUIVO onde a quebra mora, como a checagem compara (role-rules.ts) - não o componente do React, que pode
            ser um de vários no mesmo arquivo (o DogCard mora em Entries.tsx) */
         allowedIn: (b.home?.file.split("/").pop()?.replace(/\.[jt]sx?$/, "") ?? ""), home: at(b.home) }));
-    const rules = { version: 1, enforce: true, source: `synthesisui read, ${R.read}`, confirmed: opts.answers ? "the person's answers" : "yes to every question (no answers file)", roles, breaks };
+    /* o papel novo (E02 da fase 3): "sim" vira papel com a classe e o tamanho dele; "não" grava qual papel ele é, e a checagem
+       passa a cobrar esse papel naquele arquivo (`decided` em role-rules.ts) */
+    const decided = [];
+    for (const n of (R.newRoles ?? [])) {
+        if (pick(newRoleId(n)) === 1 && n.closest) {
+            decided.push({ class: n.class, at: n.file, role: n.closest.id });
+            /* a classificação pode ter feito dele um papel sozinha (o título do texto corrido): o "não" dela vale mais */
+            for (let i = roles.length - 1; i >= 0; i--)
+                if (roles[i].class === n.class && roles[i].id !== n.closest.id)
+                    roles.splice(i, 1);
+            continue;
+        }
+        if (pick(newRoleId(n)) !== 0 || roles.some((r) => r.class === n.class))
+            continue;
+        const shape = `${n.element}${n.context === "card" ? " de cartão" : n.context === "prose" ? " do texto corrido" : ""}`;
+        roles.push({ id: `${n.element}-${n.context}-site-${n.px}`, name: `${nameOf(shape)} (${n.px}px)`, element: n.element,
+            context: n.context, surface: "site", class: n.class, px: n.px, home: `${n.file}:${n.line}`, places: 1 });
+    }
+    const rules = { version: 1, enforce: true, source: `synthesisui read, ${R.read}`, confirmed: opts.answers ? "the person's answers" : "yes to every question (no answers file)", roles, breaks, ...(decided.length ? { decided } : {}) };
+    /* a leitura viu a página: o que ela perguntou está respondido, e o que não estava mais nela saiu junto */
+    rmSync(PENDING(root), { force: true });
     writeFileSync(join(dsDir, slug, "rules.json"), `${JSON.stringify(rules, null, 2)}\n`);
     const contract = await syncClaudeMd(root, await agentsToMaintain(root));
     say(`Your system: ${roles.length} roles and ${breaks.length} breaks, written to _synthesisui/ds/${slug}/rules.json.`);
@@ -288,7 +371,7 @@ export async function read(opts) {
     }
     const routes = opts.routes?.length ? opts.routes : ["/"];
     const pw = loadReader(say);
-    const browser = await launch(pw, say);
+    const browser = (await launch(pw, say));
     const seen = [];
     const pages = new Map();
     try {
@@ -305,21 +388,7 @@ export async function read(opts) {
             }
         }
         const reading = classify(seen);
-        // cada contraste baixo conferido pelos pixels: sem tinta é texto não pintado; acima do alvo, o DOM errou o fundo
-        const confirmed = [];
-        for (const f of reading.contraste) {
-            const p = pages.get(`${f.sample.rota}|${f.sample.disp}`);
-            let px = null;
-            if (p && f.sample.w >= 2 && f.sample.h >= 2) {
-                const png = await p.page.screenshot({ fullPage: true, clip: { x: Math.max(0, f.sample.x), y: Math.max(0, f.sample.y), width: f.sample.w, height: f.sample.h } }).catch(() => null);
-                const rgba = png ? decodePng(png) : null;
-                px = rgba ? pixelRatio(rgba) : null;
-            }
-            if (px !== null && (px < 1.2 || px >= f.alvo))
-                continue;
-            confirmed.push({ ...f, pixels: px });
-        }
-        reading.contraste = confirmed;
+        reading.contraste = await confirmByPixels(reading.contraste, (t) => pages.get(`${t.rota}|${t.disp}`)?.page);
         const files = sources(root);
         const home = (t) => homeOf(root, files, t);
         const out = {
@@ -334,9 +403,14 @@ export async function read(opts) {
             drift: reading.deriva.map((d) => ({ role: d.papel, surface: d.superficie, px: d.px, rulePx: d.regraPx, seen: d.onde, home: home(d.sample), ruleHome: home(d.ruleSample) })),
             lowContrast: reading.contraste.map((c) => ({ ratio: c.razao, target: c.alvo, text: c.texto, background: c.fundo, px: c.px, seen: c.onde, home: home(c.sample) })),
             overImages: reading.sobreImagem,
+            /** Cada título como estava quando a pessoa confirmou - a base do fecho do turno (E01 da fase 3): ele acusa o que
+             *  o turno MUDOU, nunca o que a página já era. */
+            headings: headingsOf(seen),
+            newRoles: [],
             questions: [],
         };
-        out.questions = questionsFor(out.breaks, out.drift);
+        out.newRoles = newRolesOnPage(await readPending(root), seen, home, (await loadRoleRules(root).catch(() => null))?.roles ?? []);
+        out.questions = questionsFor(out.breaks, out.drift, out.newRoles);
         mkdirSync(join(root, "_synthesisui"), { recursive: true });
         writeFileSync(join(root, "_synthesisui", "reading.json"), `${JSON.stringify(out, null, 2)}\n`);
         const at = (x) => (x ? `${x.file}${x.line ? `:${x.line}` : ""}` : "?");

package/dist/install-marks.js

@@ -585,7 +585,14 @@ export const COUNTED_DIFFERENTLY = "this run counts a value as named only when Y
  * oferece. E a checagem por papel lê CSS Modules (`className={styles.h2}`, o tamanho no `.module.css`): um hook anterior
  * não confere papel nenhum numa página escrita assim.
  */
-export const CHECKER_SINCE = "0.16.501";
+/**
+ * 0.16.501 -> 0.16.504 em 20/10, e o passo 1 dá **SIM** (jornada "o fecho do turno", E01): com o sistema confirmado e o dev
+ * server do projeto de pé, o fim do turno relê as telas mexidas e devolve ao agente o texto ilegível (o fundo real) e o
+ * título que renderiza fora do papel - o que a checagem por arquivo não vê. Um hook pinado antes não relê tela nenhuma.
+ * E (E02, no mesmo PR) guarda o tamanho de título sem papel para a próxima leitura perguntar, e cobra o papel que a pessoa
+ * escolheu no "não" (`decided` no rules.json): um hook pinado antes diz "papel novo" uma vez e nunca cobra.
+ */
+export const CHECKER_SINCE = "0.16.504";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *

package/dist/reading/reread.js

@@ -0,0 +1,364 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, extname, join, relative, sep } from "node:path";
+import { confirmByPixels, declaredPort, findServer, homeOf, launch, loadReader, sources } from "../commands/read.js";
+import { loadRoleRules } from "../role-rules.js";
+import { classify } from "./classify.js";
+import { PAGE_SCRIPT } from "./page-script.js";
+/**
+ * A TELA RELIDA NO FIM DO TURNO - E01 da jornada "o fecho do turno" (fase 3 do mapa, 20/10).
+ *
+ * A checagem por arquivo (`role-rules.ts`) confere o que está ESCRITO: a classe de cada título, a quebra fora do lugar. O
+ * que só a página renderizada responde ficava sem ninguém olhar depois da confirmação:
+ *
+ *     CONTRASTE   a cor atrás do texto vem de um ancestral, às vezes de outro componente ("Only my pins", 3,17:1, 18/10).
+ *                 Nenhuma conta sobre o arquivo vê o par
+ *     TAMANHO     o tamanho que o título GANHA na tela - o papel cuja regra mudou no globals.css, o seletor de ancestral,
+ *                 a cascata. O arquivo do título não mudou e diz a mesma classe; a tela diz outro tamanho
+ *
+ * SÓ AS TELAS MEXIDAS, SÓ COM O SISTEMA CONFIRMADO, E NUNCA SOBE NADA. Sem `rules.json` não há papel com que comparar (a
+ * porta é da fase 2). Sem dev server de pé, não relê e diz isso uma vez por sessão - subir servidor dentro do fim do turno
+ * deixaria processo para trás e custaria 10-30 s (decidido em 20/10, as quatro perspectivas, na abertura da jornada). Sem
+ * o leitor na máquina, também não baixa: quem baixa é o `read`, que diz o que vai baixar.
+ *
+ * Desktop só (1440): os papéis do `rules.json` foram gravados na medida do desktop - comparar o celular com eles acusaria
+ * todo título responsivo.
+ */
+/** Uma tela: o mesmo filtro do fim do turno (`SCREEN` em `hook.ts`). */
+const SCREEN = /\.(tsx|jsx|vue|svelte|astro|html|css|scss)$/;
+const PAGE_FILE = /(?:^|\/)(?:src\/)?app\/(.*?)\/?page\.(?:tsx|jsx|ts|js|mdx)$|(?:^|\/)(?:src\/)?pages\/(.*?)\.(?:tsx|jsx)$/;
+/** Quatro rotas no máximo: um turno que mexe no layout não vira a leitura do site inteiro. */
+const AT_MOST_ROUTES = 4;
+/**
+ * O teto do fecho inteiro: estourou, o turno passa e DIZ que a tela não foi relida - um fecho que prende a sessão é pior
+ * que nenhum, e um que some calado é pior ainda. Medido em 20/10, na Naiker: a primeira resposta do `next dev` depois de
+ * uma mudança no globals.css levou 46 s (frio); as seguintes, 0,03 s.
+ */
+const BUDGET_MS = 30_000;
+const near = (a, b) => Math.abs(a - b) / Math.max(a, b) < 0.03;
+const BASELINE = (root) => join(root, "_synthesisui", ".reread-baseline.json");
+/** Os caminhos dos links da página, do mesmo site - é deles que sai o endereço de uma rota dinâmica. */
+const LINKS = `[...document.querySelectorAll("a[href]")].map((a) => new URL(a.href, location.href)).filter((u) => u.origin === location.origin).map((u) => u.pathname)`;
+const SAID = (root) => join(root, "_synthesisui", ".reread-said.json");
+const NO_SERVER = (root) => join(root, "_synthesisui", ".reread-no-server");
+export const TOO_SLOW = "The screens this turn touched were not re-read: the dev server did not answer within 30 s (it is probably still compiling). The file check above still ran.";
+export const NOT_REREAD = "The screens this turn touched were not re-read: this project's dev server is not up (the port in its `dev` script, or the one `synthesisui read` used). The file check above still ran. Tell the person in one line that contrast and the real size of each heading are checked only while `npm run dev` is running.";
+/**
+ * O SERVIDOR DESTE PROJETO, E SÓ ELE - medido em 20/10, na prova do servidor parado: o `read` tenta as portas de sempre
+ * (:3000, :3001, :5173, :4321) e, com a Naiker parada, o fecho achou o PAINEL do hub na :4321 e acusou seis contrastes
+ * da página de outro projeto. Na leitura a pessoa vê a URL e pode corrigir; no fim do turno ninguém vê. Então só duas
+ * portas valem: a que o script `dev` do projeto declara, e a que a leitura confirmada usou (`reading.json`).
+ */
+async function ownServer(root) {
+    const port = declaredPort(root);
+    const read = JSON.parse((await readFile(join(root, "_synthesisui", "reading.json"), "utf8").catch(() => "{}")) || "{}");
+    for (const u of [...(port ? [`http://localhost:${port}`] : []), ...(read.url ? [read.url] : [])]) {
+        const found = await findServer(u, root, 1500);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/**
+ * A ROTA DE UM ARQUIVO DE PÁGINA DO NEXT (app ou pages), com o segmento dinâmico como está (`/dogs/[slug]`); `null` para
+ * API ou o que não é página. A página de cada cachorro é exatamente onde a deriva nasce
+ * (18/10: o h2 do cachorro a 79,2px) - pular rota dinâmica deixaria a releitura cega no caso que motivou a fase. O
+ * endereço concreto sai dos links das páginas já abertas (ver `measure`).
+ */
+export function patternOf(rel) {
+    const m = rel.split(sep).join("/").match(PAGE_FILE);
+    if (!m)
+        return null;
+    const raw = m[1] ?? m[2] ?? "";
+    if (m[2] !== undefined && (/^(_app|_document|_error|api)(\/|$)/.test(raw)))
+        return null;
+    const parts = raw.split("/").filter((p) => p && !/^\(.*\)$/.test(p) && !p.startsWith("@") && p !== "index");
+    return `/${parts.join("/")}`;
+}
+function walk(dir, out = []) {
+    let names = [];
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const n of names) {
+        if (n === "node_modules" || n.startsWith(".") || n === "_synthesisui" || n === "public")
+            continue;
+        const p = join(dir, n);
+        try {
+            if (statSync(p).isDirectory())
+                walk(p, out);
+            else
+                out.push(p);
+        }
+        catch {
+            /* o próximo */
+        }
+    }
+    return out;
+}
+/**
+ * AS TELAS QUE O TURNO MEXEU. A página mexida é a rota dela. Um componente mexido é toda página que o importa (até dois
+ * saltos de import, pelo nome do arquivo). Folha de estilo, layout ou componente que nenhuma página importa diretamente:
+ * todas as rotas estáticas, até o teto - a raiz primeiro.
+ */
+export function routesFor(root, changed) {
+    const screens = changed.filter((c) => SCREEN.test(c.rel));
+    if (screens.length === 0)
+        return [];
+    const files = walk(existsSync(join(root, "src")) ? join(root, "src") : root).concat(existsSync(join(root, "src")) && existsSync(join(root, "app")) ? walk(join(root, "app")) : []);
+    const pages = files.map((f) => ({ f, route: patternOf(relative(root, f)) })).filter((p) => p.route !== null);
+    const all = [...new Set(pages.map((p) => p.route))];
+    const out = new Set();
+    let everywhere = false;
+    const code = files.filter((f) => /\.(tsx|jsx|ts|js)$/.test(f));
+    const textOf = new Map();
+    const read = (f) => {
+        if (!textOf.has(f))
+            textOf.set(f, (() => { try {
+                return readFileSync(f, "utf8");
+            }
+            catch {
+                return "";
+            } })());
+        return textOf.get(f);
+    };
+    const importers = (stem) => code.filter((f) => new RegExp(`from\\s+["'][^"']*\\/${stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?:\\.[jt]sx?)?["']`).test(read(f)));
+    for (const c of screens) {
+        const own = patternOf(c.rel);
+        if (own) {
+            out.add(own);
+            continue;
+        }
+        const stem = basename(c.rel, extname(c.rel));
+        if (/\.(css|scss)$/.test(c.rel) || /^(layout|template)$/.test(stem)) {
+            everywhere = true;
+            continue;
+        }
+        const first = importers(stem);
+        const reach = new Set(first);
+        for (const f of first)
+            for (const g of importers(basename(f, extname(f))))
+                reach.add(g);
+        const hit = pages.filter((p) => reach.has(p.f)).map((p) => p.route);
+        if (hit.length === 0)
+            everywhere = true;
+        for (const r of hit)
+            out.add(r);
+    }
+    if (everywhere)
+        for (const r of all)
+            out.add(r);
+    const rank = (r) => (r === "/" ? 0 : r.includes("[") ? 2 : 1);
+    return [...out].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b)).slice(0, AT_MOST_ROUTES);
+}
+export function headingsOf(seen) {
+    const out = new Map();
+    for (const t of seen) {
+        const el = t.papel;
+        if (el !== "h1" && el !== "h2" && el !== "h3")
+            continue;
+        if (t.disp !== "desktop" || t.tag !== el || t.decorativo || t.giro !== 0 || !(t.tam > 0))
+            continue;
+        const k = `${t.rota}|${el}|${t.texto}`;
+        if (!out.has(k))
+            out.set(k, { rota: t.rota, el, text: t.texto, px: round(t.tam) });
+    }
+    return [...out.values()];
+}
+/**
+ * O TÍTULO NA TELA CONTRA O PAPEL - E O QUE O TURNO MUDOU, NUNCA O QUE A PÁGINA JÁ ERA. Medido na primeira rodada, na
+ * Naiker sem mudança nenhuma (20/10): cinco acusações sobre a página que a pessoa tinha acabado de confirmar - os quatro
+ * `<h3>` de 20px que a leitura não fez papel, e a quebra de 144px que mora num subcomponente da Landing. Um fecho que
+ * acusa a página confirmada ensina o agente a ignorá-lo.
+ *
+ * Então vale a BASE: o tamanho de cada título quando a pessoa confirmou (`headings` no `reading.json`). Título que está
+ * nela no mesmo tamanho passa. Título novo, ou que mudou de tamanho, é comparado com a mesma faixa da checagem por arquivo:
+ *
+ *     perto de um papel (até 1,4x) e fora dele   deriva - volta ao agente com o papel
+ *     no tamanho de uma quebra, fora do lugar     a quebra copiada
+ *     acima do título de seção, sem ser quebra    passou da escala
+ *     longe de todo papel                         provável papel novo - é decisão da pessoa (E02), não deriva
+ */
+export function offRole(seen, rules, baseline, fileOf) {
+    const out = [];
+    const before = new Map((baseline ?? []).map((h) => [`${h.rota}|${h.el}|${h.text}`, h.px]));
+    const section = rules.roles.find((r) => r.element === "h2" && r.context === "section");
+    const sample = new Map();
+    for (const t of seen)
+        if (t.disp === "desktop")
+            sample.set(`${t.rota}|${t.papel}|${t.texto}`, t);
+    for (const h of headingsOf(seen)) {
+        const t = sample.get(`${h.rota}|${h.el}|${h.text}`);
+        const was = before.get(`${h.rota}|${h.el}|${h.text}`);
+        if (was !== undefined && near(was, h.px))
+            continue;
+        const mine = rules.roles.filter((r) => r.element === h.el);
+        if (mine.length === 0 || mine.some((r) => near(h.px, r.px)))
+            continue;
+        const role = mine.find((r) => r.context === (t.cartao ? "card" : t.corrido ? "prose" : "section")) ?? mine[0];
+        const said = `"${h.text.length > 40 ? `${h.text.slice(0, 39)}…` : h.text}"`;
+        const brk = rules.breaks.find((b) => b.element === h.el && near(h.px, b.px));
+        if (brk) {
+            const home = brk.home.split(":")[0];
+            if (t.comp === brk.allowedIn || (home && fileOf(t) === home))
+                continue;
+            out.push({ t, el: h.el, text: `<${h.el}> ${said} renders at ${h.px}px - the size of the break "${brk.rule}", which the person chose for ${brk.allowedIn} only (${brk.home}). Here, the ${role.name} is ${round(role.px)}px (${role.class}, ${role.home}).` });
+            continue;
+        }
+        if (section && h.el !== "h1" && h.px > section.px * 1.04) {
+            out.push({ t, el: h.el, text: `<${h.el}> ${said} renders at ${h.px}px, above this project's section titles (${round(section.px)}px). Only the breaks the person chose go there - use the ${role.name} (${role.class}), or ask whether this is a new break.` });
+            continue;
+        }
+        if (h.px >= role.px / 1.4 && h.px <= role.px * 1.4)
+            out.push({ t, el: h.el, text: `<${h.el}> ${said} renders at ${h.px}px${was !== undefined ? ` (it was ${was}px when the person confirmed)` : ""}, and this project's ${role.name} is ${round(role.px)}px (${role.class}, ${role.home}).` });
+    }
+    return out;
+}
+const round = (n) => Math.round(n * 10) / 10;
+/**
+ * A BASE: os títulos que o `read` gravou na confirmação. Leitura antiga, sem eles (confirmada antes da fase 3): a primeira
+ * releitura de cada rota vira a base, calada - perde-se um turno de checagem de tamanho naquela rota, e não se acusa a
+ * página inteira que a pessoa já tinha.
+ */
+async function baselineOf(root, seen) {
+    const fromRead = JSON.parse((await readFile(join(root, "_synthesisui", "reading.json"), "utf8").catch(() => "{}")) || "{}");
+    const kept = JSON.parse((await readFile(BASELINE(root), "utf8").catch(() => "[]")) || "[]");
+    /* com a base da confirmação, uma rota fora dela é página NOVA - e página nova é onde a deriva nasce (a página do
+       cachorro, 18/10): ela é conferida inteira, nunca vira base calada */
+    if (fromRead.headings)
+        return fromRead.headings;
+    const base = kept;
+    const known = new Set(base.map((h) => h.rota));
+    const fresh = headingsOf(seen).filter((h) => !known.has(h.rota));
+    if (fresh.length > 0) {
+        await mkdir(join(root, "_synthesisui"), { recursive: true }).catch(() => undefined);
+        await writeFile(BASELINE(root), JSON.stringify([...kept, ...fresh], null, 1)).catch(() => undefined);
+    }
+    return [...base, ...fresh];
+}
+async function onlyNew(root, keys) {
+    const said = new Set(JSON.parse((await readFile(SAID(root), "utf8").catch(() => "[]")) || "[]"));
+    const fresh = new Set(keys.filter((k) => !said.has(k)));
+    if (fresh.size > 0) {
+        for (const k of fresh)
+            said.add(k);
+        await mkdir(join(root, "_synthesisui"), { recursive: true }).catch(() => undefined);
+        await writeFile(SAID(root), JSON.stringify([...said], null, 1)).catch(() => undefined);
+    }
+    return fresh;
+}
+/** A linha do "não relida" vale uma vez por sessão: a sessão é o registro da conversa que o Claude Code passa. */
+async function noServerOnce(root, session) {
+    const key = session ?? "no-session";
+    if ((await readFile(NO_SERVER(root), "utf8").catch(() => "")).trim() === key)
+        return null;
+    await mkdir(join(root, "_synthesisui"), { recursive: true }).catch(() => undefined);
+    await writeFile(NO_SERVER(root), `${key}\n`).catch(() => undefined);
+    return NOT_REREAD;
+}
+export async function rereadScreens(root, changed, session) {
+    if (!changed.some((c) => SCREEN.test(c.rel)))
+        return null;
+    const rules = await loadRoleRules(root).catch(() => null);
+    if (!rules || rules.enforce === false)
+        return null;
+    const routes = routesFor(root, changed);
+    if (routes.length === 0)
+        return null;
+    const base = await ownServer(root);
+    if (!base)
+        return noServerOnce(root, session);
+    const pw = loadReader(() => { }, false);
+    if (!pw)
+        return null;
+    let timer;
+    const budget = new Promise((ok) => {
+        timer = setTimeout(() => ok(TOO_SLOW), BUDGET_MS);
+    });
+    const held = { browser: null };
+    try {
+        return await Promise.race([measure(root, rules, routes, base, pw, held), budget]);
+    }
+    finally {
+        clearTimeout(timer);
+        /* estourado o teto, o navegador fecha aqui - senão o processo do gancho fica de pé esperando a página, e o turno junto */
+        await held.browser?.close().catch(() => { });
+    }
+}
+async function measure(root, rules, routes, base, pw, held) {
+    const browser = await launch(pw, () => { }, false);
+    if (!browser)
+        return null;
+    held.browser = browser;
+    const pages = new Map();
+    try {
+        const seen = [];
+        const ctx = await browser.newContext({ viewport: { width: 1440, height: 900 }, reducedMotion: "reduce" });
+        const links = [];
+        const open = async (path) => {
+            const page = await ctx.newPage();
+            const ok = await page.goto(new URL(path, base).href, { waitUntil: "networkidle", timeout: 25_000 }).then(() => true, () => false);
+            if (ok)
+                links.push(...(await page.evaluate(LINKS).catch(() => [])));
+            return ok ? page : null;
+        };
+        for (const route of routes) {
+            let rota = route;
+            if (route.includes("[")) {
+                if (links.length === 0)
+                    await open("/");
+                const re = new RegExp(`^${route.replace(/\[\.\.\.[^\]]+\]/g, ".+").replace(/\[[^\]]+\]/g, "[^/]+")}$`);
+                const hit = links.find((l) => re.test(l));
+                if (!hit)
+                    continue;
+                rota = hit;
+            }
+            const page = await open(rota);
+            if (!page)
+                continue;
+            await page.waitForTimeout(500);
+            const textos = (await page.evaluate(PAGE_SCRIPT));
+            for (const t of textos)
+                seen.push({ ...t, rota, disp: "desktop" });
+            pages.set(rota, page);
+        }
+        if (seen.length === 0)
+            return null;
+        const low = await confirmByPixels(classify(seen).contraste, (t) => pages.get(t.rota));
+        const files = sources(root);
+        const fileOf = (t) => homeOf(root, files, t)?.file ?? null;
+        const baseline = await baselineOf(root, seen);
+        const off = offRole(seen, rules, baseline, fileOf);
+        const at = (t) => {
+            const h = homeOf(root, files, t);
+            return h ? `${h.file}${h.line ? `:${h.line}` : ""}` : `${t.rota}${t.comp ? `, ${t.comp}` : ""}`;
+        };
+        const lowLines = low.map((c) => ({
+            key: `contrast|${c.sample.rota}|${c.sample.texto}|${c.razao}`,
+            text: `  "${c.sample.texto}" - ${c.razao}:1, needs ${c.alvo}:1 (${c.texto} on ${c.fundo}) - ${at(c.sample)}`,
+        }));
+        const offLines = off.map((o) => ({ key: `size|${o.t.rota}|${o.el}|${o.t.texto}|${round(o.t.tam)}`, text: `  ${o.text} - ${at(o.t)}` }));
+        const fresh = await onlyNew(root, [...lowLines, ...offLines].map((l) => l.key));
+        const lows = lowLines.filter((l) => fresh.has(l.key)).map((l) => l.text);
+        const offs = offLines.filter((l) => fresh.has(l.key)).map((l) => l.text);
+        if (lows.length === 0 && offs.length === 0)
+            return null;
+        return [
+            `Re-read the screens this turn touched (${[...pages.keys()].join(", ")}) on ${base}, as the visitor sees them:`,
+            ...(lows.length ? ["Hard to read (the real background, checked against the pixels):", ...lows] : []),
+            ...(offs.length ? ["Headings that render off this project's roles:", ...offs] : []),
+            ...(lows.length ? ["Raise the contrast of each one where the text sits - the color, the opacity, or the background behind it."] : []),
+            ...(offs.length
+                ? ["Bring each heading back to its role. If the heading already uses the role's class, the change was to the role itself (its rule in the stylesheet): that changes the system the person confirmed - put it back, or ask them in one line."]
+                : []),
+        ].join("\n");
+    }
+    finally {
+        for (const p of pages.values())
+            await p.close?.().catch(() => { });
+        await browser.close().catch(() => { });
+    }
+}

package/dist/role-rules.js

@@ -205,6 +205,12 @@ export function checkRoles(rel, src, rules, root) {
         if (known.has(bare))
             continue;
         const px = mod ? pxOfModule(mod.path, mod.local) : glob ? glob.px : pxOf(bare);
+        const told = rules.decided?.find((d) => d.class === bare && d.at === rel);
+        const toldRole = told ? rules.roles.find((r) => r.id === told.role) : undefined;
+        if (toldRole) {
+            out.push(`  line ${line}  <${el}> ${bare} - the person said this heading is the ${toldRole.name}. Use ${toldRole.class} (${toldRole.home}).`);
+            continue;
+        }
         const role = mine.find((r) => r.context === context) ?? mine[0];
         const brk = rules.breaks.find((b) => b.class === bare);
         if (brk) {
@@ -296,6 +302,31 @@ export async function onlyOnce(root, rel, lines) {
     if (changed) {
         await mkdir(join(root, "_synthesisui"), { recursive: true }).catch(() => undefined);
         await writeFile(SAID(root), JSON.stringify([...said], null, 1)).catch(() => undefined);
+        await rememberNewRoles(root, rel, out.filter((l) => l.includes("has no role for yet"))).catch(() => undefined);
     }
     return out;
 }
+export const PENDING = (root) => join(root, "_synthesisui", "roles-pending.json");
+export async function readPending(root) {
+    try {
+        const p = JSON.parse(await readFile(PENDING(root), "utf8"));
+        return Array.isArray(p) ? p : [];
+    }
+    catch {
+        return [];
+    }
+}
+async function rememberNewRoles(root, rel, lines) {
+    if (lines.length === 0)
+        return;
+    const pending = await readPending(root);
+    for (const l of lines) {
+        const m = l.match(/line (\d+)\s+<(h[1-3])> (.+?) \(~(\d+)px\)/);
+        if (!m)
+            continue;
+        const entry = { element: m[2], class: m[3], px: Number(m[4]), file: rel, line: Number(m[1]) };
+        if (!pending.some((p) => p.class === entry.class && p.file === entry.file && p.element === entry.element))
+            pending.push(entry);
+    }
+    await writeFile(PENDING(root), `${JSON.stringify(pending, null, 1)}\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.502",
+  "version": "0.16.504",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {