synthesisui 0.16.499 → 0.16.500

package/dist/claude-md.js

@@ -1,4 +1,5 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { loadRoleRules, rolesContract } from "./role-rules.js";
 import { dirname, join } from "node:path";
 import { hasHook } from "./agent-wiring.js";
 import { declaredReference } from "./group-role.js";
@@ -468,6 +469,12 @@ written now** - read the code before you edit it, never a remembered signature.`
      * livres passa pelo `landing` antes de qualquer linha - ele lista as seções do catálogo e devolve o prompt da pilha, com
      * as decisões tomadas. Sem servidor também: o `landing` fala com o registro direto.
      */
+    /** Os papéis e as quebras que a página dele já decidiu - ver `role-rules.ts` (18/10). Só existe com `rules.json`. */
+    const roleRules = await loadRoleRules(projectRoot).catch(() => null);
+    const rolesLine = roleRules
+        ? rolesContract(roleRules)
+        : /** Sem rules.json ainda: o agente oferece a leitura (jornada "a leitura no agente", E03, 18/10). */
+            "\n\n**Once the first screen exists, offer to read it.** When the person asks you to read their page - or right after you build the first screen - 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 landingLine = '\n\n**A landing asked in free words:** run `npx synthesisui@latest landing <slug> "<their words>"` first, and follow it.';
     const preferencesLine = recall.available
         ? `
@@ -497,7 +504,7 @@ is \`remember_preference\`.`
             ? `**These are true without asking anyone:** use the project's OWN custom properties, exactly as
 this system declares them. No raw colours, spacings or radii that a token already covers, and never a
 new token invented in silence - say so instead, because a new token is a decision for a person. There
-is no component index for an adopted system: the tokens ARE the contract.${theirsLine}
+is no component index for an adopted system: the tokens ARE the contract.${theirsLine}${rolesLine}
 
 **What the vocabulary IS is not written here.** Fetch only the piece the task requires:
 \`system_doctrine\` for the rules and the voice, \`find_token\` for a value you are about to write.${memoryLine}${preferencesLine}${selfCheck}`
@@ -529,7 +536,7 @@ If nothing covers it, say which indexed entry you considered and why it did not
 project's OWN custom properties, exactly as the guide lists them. Do not write raw colours,
 spacings or radii that a token already covers, and do not invent a new token silently - say so
 instead, because a new token is a decision for a person to make. There is no component
-manifest for an adopted system - the tokens ARE the contract.${theirsLine}${landingLine}${selfCheck}`
+manifest for an adopted system - the tokens ARE the contract.${theirsLine}${rolesLine}${landingLine}${selfCheck}`
             : `**When creating or editing components, read the system's GUIDE.md and follow it:** use the
 vocabulary it lists - every name in it is a name THIS project already declares, written exactly as
 you would write it. Do not use raw values outside the system's scale, and never a name from a

package/dist/commands/hook.js

@@ -1,6 +1,7 @@
 import { readFile, stat, writeFile } from "node:fs/promises";
 import { ourSpellingLines } from "../our-spelling.js";
-import { join, relative, resolve } from "node:path";
+import { existsSync } 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 { emptyTally, exportedNames, internalSpecifiers, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
@@ -8,6 +9,7 @@ import { checkContracts } from "../doctor/contract-check.js";
 import { componentOf } from "../doctor/component-of.js";
 import { appendEvent, ledgerPath } from "../doctor/ledger.js";
 import { describeOffScale, diagnose, nameToWrite, scanSource } from "../doctor/scan.js";
+import { checkRoles, loadRoleRules, onlyOnce } from "../role-rules.js";
 import { declarados, falaDaPrateleira, naPrateleira } from "../doctor/shelf.js";
 import { governs, ungovernedIn } from "../governed.js";
 import { readMode } from "../mode.js";
@@ -313,6 +315,9 @@ async function report(root, filePath, mode) {
     const offScale = describeOffScale(d.files);
     /** A nossa grafia no arquivo dele - ver `our-spelling.ts`. Entra nas mesmas portas que os `phantoms`. */
     const ours = d.tokenUses;
+    /** Os papéis e as quebras que a página dele já decidiu - ver `role-rules.ts` (18/10). */
+    const roleRules = await loadRoleRules(root).catch(() => null);
+    const roles = roleRules ? await onlyOnce(root, rel, checkRoles(rel, src, roleRules)) : [];
     // Every check leaves one line in the ledger - INCLUDING the clean ones,
     // because a fix is itself a write, so the clean re-check of a file that was
     // just flagged is the evidence the agent read the report and acted. Without
@@ -327,6 +332,7 @@ async function report(root, filePath, mode) {
         phantoms: phantoms.length,
         unnamed: unnamed.length,
         offScale: d.files.reduce((n, f) => n + (f.offScale?.length ?? 0), 0),
+        ...(roleRules ? { roles: roles.length } : {}),
         ...(component ? { component } : {}),
     });
     /** O bloqueio de CONSUMIR é a única saída que recusa, e ele acompanha o relatório seja qual for. */
@@ -338,6 +344,7 @@ async function report(root, filePath, mode) {
         phantoms.length === 0 &&
         offScale.length === 0 &&
         unnamed.length === 0 &&
+        roles.length === 0 &&
         ours === 0) {
         const hello = await greet(root, rel);
         return hello ? say(hello) : null;
@@ -376,6 +383,7 @@ async function report(root, filePath, mode) {
         named.length === 0 &&
         phantoms.length === 0 &&
         offScale.length === 0 &&
+        roles.length === 0 &&
         ours === 0)
         return say(broke.join("\n"));
     const sample = unnamed
@@ -387,6 +395,7 @@ async function report(root, filePath, mode) {
         named.length === 0 &&
         phantoms.length === 0 &&
         offScale.length === 0 &&
+        roles.length === 0 &&
         ours === 0)
         return say([
             `${rel} - ${unnamed.length} value${unnamed.length === 1 ? "" : "s"} here ${unnamed.length === 1 ? "has" : "have"} no name in this system, and nothing to replace ${unnamed.length === 1 ? "it" : "them"} with: ${sample}${unnamed.length > 3 ? `, +${unnamed.length - 3} more` : ""}.`,
@@ -413,6 +422,9 @@ async function report(root, filePath, mode) {
         ...(broke.length > 0 ? [...broke, ""] : []),
         `${rel} - checked against ${table.name ?? table.slug}.`,
     ];
+    if (roles.length > 0) {
+        lines.push("", "Headings that leave the role this project already decided (read from its own pages):", ...roles, "", "Fix these now, while you have the file open - one role, one class.");
+    }
     if (named.length > 0) {
         lines.push("", "Values written by hand that this system already has a name for:", ...named
             .slice(0, 20)
@@ -459,8 +471,28 @@ const namedInPayload = (input) => {
         input.tool_name === "MultiEdit";
     return writes ? (input.tool_input?.file_path ?? null) : null;
 };
+/**
+ * A RAIZ É O PROJETO, NÃO A PASTA ONDE A SESSÃO PAROU - jornada "a leitura no agente", E01 (18/10).
+ *
+ * O Claude Code roda o gancho na pasta em que o terminal do agente está. Na rodada dos relógios, o agente terminou os
+ * turnos 3 e 7 com `cd .impeccable/review`; o fim do turno rodou ali, não achou `_synthesisui/` e passou calado - a
+ * página de cada relógio, o trabalho inteiro do turno 3, nunca foi conferida. A ordem: a pasta que o Claude Code
+ * declara (`CLAUDE_PROJECT_DIR`), quando ela é um projeto nosso; senão, a pasta mais próxima, subindo, que tenha
+ * `_synthesisui/`; senão, onde estamos (o comportamento de antes).
+ */
+export function projectRootFrom(cwd, env = process.env) {
+    const declared = env.CLAUDE_PROJECT_DIR;
+    if (declared && existsSync(join(declared, "_synthesisui")))
+        return resolve(declared);
+    for (let dir = resolve(cwd);; dir = dirname(dir)) {
+        if (existsSync(join(dir, "_synthesisui")))
+            return dir;
+        if (dirname(dir) === dir)
+            return resolve(cwd);
+    }
+}
 export async function hook(opts) {
-    const root = resolve(opts.dir ?? process.cwd());
+    const root = resolve(opts.dir ?? projectRootFrom(process.cwd()));
     let raw = "";
     for await (const chunk of process.stdin)
         raw += chunk;

package/dist/commands/read.js

@@ -0,0 +1,317 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, 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 { decodePng } from "../reading/png.js";
+import { pxOf } from "../role-rules.js";
+import { agentsToMaintain } from "../agents-chosen.js";
+import { syncClaudeMd } from "../claude-md.js";
+import { projectRootFrom } from "./hook.js";
+/**
+ * `synthesisui read` - O QUE A SUA PÁGINA JÁ DECIDIU (jornada "a leitura no agente", E02, 18/10).
+ *
+ * A fase 1 do mapa aprovado: depois da primeira tela que a camada de estética criou, a pessoa pede ao agente para ler a
+ * página, e recebe o sistema que ela já decidiu - os papéis de título com a classe e o lugar no código, as escalas, as
+ * quebras que a fazem ser dela, a deriva e o contraste que falha. Lê a página RENDERIZADA no dev server (o que o visitante
+ * vê) e liga cada achado ao componente pelo React, não pela forma de estilo.
+ *
+ * O NAVEGADOR É SOB DEMANDA (D9 do mapa): o CLI continua sem dependência nenhuma. No primeiro `read` ele DIZ o que vai
+ * baixar e baixa o leitor (playwright-core) numa pasta própria; usa o Chromium que já estiver na máquina, e só baixa um
+ * quando não há nenhum.
+ *
+ * Grava `_synthesisui/reading.json` - a proposta. O `rules.json` nasce da confirmação da pessoa (E03), nunca daqui.
+ */
+const READER_VERSION = "1.58.2";
+const READER_DIR = join(homedir(), ".synthesisui", "reader");
+const VIEWPORTS = [
+    ["desktop", 1440, 900],
+    ["celular", 390, 844],
+];
+function loadReader(say) {
+    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)) {
+        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) {
+    for (const o of [{}, { channel: "chrome" }, { channel: "msedge" }]) {
+        try {
+            return await pw.chromium.launch(o);
+        }
+        catch {
+            /* o próximo */
+        }
+    }
+    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();
+}
+/**
+ * O DEV SERVER DESTE PROJETO, E NÃO O PRIMEIRO QUE RESPONDER - a porta que o script `dev` do próprio projeto declara
+ * (`-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) {
+    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})/);
+        return m ? Number(m[1] ?? m[2]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function findServer(url, root) {
+    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) });
+            if (r.status < 500)
+                return u;
+        }
+        catch {
+            /* o próximo */
+        }
+    }
+    return null;
+}
+/** 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) ?? [];
+    if (toks.length === 0)
+        return null;
+    const best = toks.sort((a, b) => (pxOf(b) ?? 0) - (pxOf(a) ?? 0))[0];
+    return best.replace(/^(?:[a-z0-9]+:)+/, "");
+}
+function sources(root) {
+    const out = [];
+    const walk = (d) => {
+        for (const n of readdirSync(d)) {
+            if (n === "node_modules" || n.startsWith(".") || n === "_synthesisui")
+                continue;
+            const p = join(d, n);
+            const s = statSync(p);
+            if (s.isDirectory())
+                walk(p);
+            else if (/\.(tsx|jsx)$/.test(n))
+                out.push(p);
+        }
+    };
+    const src = existsSync(join(root, "src")) ? join(root, "src") : root;
+    walk(src);
+    return out;
+}
+/** Onde o texto mora no código: o componente (React) -> o arquivo que o declara -> a linha da classe; senão, pela classe. */
+function homeOf(root, files, t) {
+    const cls = sizeClassOf(t.cls);
+    const lineOf = (f) => {
+        if (!cls)
+            return null;
+        const i = readFileSync(f, "utf8").split("\n").findIndex((l) => l.includes(cls));
+        return i >= 0 ? i + 1 : null;
+    };
+    if (t.comp) {
+        const decl = new RegExp(`(function|const|class)\\s+${t.comp}\\b`);
+        const f = files.find((x) => decl.test(readFileSync(x, "utf8")));
+        if (f)
+            return { file: relative(root, f), line: lineOf(f), cls, via: "component", component: t.comp };
+    }
+    if (cls) {
+        const f = files.find((x) => readFileSync(x, "utf8").includes(cls));
+        if (f)
+            return { file: relative(root, f), line: lineOf(f), cls, via: "class", component: t.comp };
+    }
+    return null;
+}
+/**
+ * NO MÁXIMO OITO PERGUNTAS, UMA DECISÃO CADA - por quebra e por papel com deriva, nunca por elemento (seção 6 do estudo:
+ * "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 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")
+        return "big number";
+    if (role === "decoração")
+        return "decoration";
+    if (role === "bloco")
+        return "block";
+    return nameOf(role);
+}
+function questionsFor(breaks, drift) {
+    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}).`,
+        options: ["Yes, it is part of my design", "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: [] };
+        g.pxs.push(d.px);
+        groups.set(`${d.role}|${d.surface}`, g);
+    }
+    for (const g of groups.values())
+        qs.push({
+            id: `drift:${g.role}:${g.surface}`,
+            text: `Are these the same ${plainRole(g.role)}? Most places use ${g.rulePx}px; here ${g.pxs.join("px, ")}px.`,
+            options: [`Yes, use ${g.rulePx}px everywhere`, "No, they are different roles"],
+        });
+    return qs.slice(0, 8);
+}
+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) => {
+    const el = role.split(" ")[0];
+    return contextOf(role) === "card" ? "card title" : contextOf(role) === "prose" ? `heading inside running text (${el})` : (NAME[el] ?? role);
+};
+const at = (h) => (h ? `${h.file}${h.line ? `:${h.line}` : ""}` : "");
+/**
+ * \`read --confirm\` - AS RESPOSTAS DELA VIRAM O SISTEMA (E03). Lê \`reading.json\` e as respostas (um JSON \`{ "<id da
+ * pergunta>": 0 | 1 }\`, o índice da opção; sem arquivo, a primeira opção de todas) e grava \`_synthesisui/ds/<slug>/rules.json\`
+ * no formato que a checagem lê (\`role-rules.ts\`); depois regenera o contrato. Um "não" numa quebra a tira do sistema; um
+ * "são papéis diferentes" vira papel próprio, com a classe que ele usa.
+ */
+export async function confirm(opts) {
+    const say = (s) => process.stdout.write(`${s}\n`);
+    const root = opts.dir ?? projectRootFrom(process.cwd());
+    const rp = join(root, "_synthesisui", "reading.json");
+    if (!existsSync(rp)) {
+        say("No reading yet - run `synthesisui read` first.");
+        process.exitCode = 1;
+        return;
+    }
+    const R = JSON.parse(readFileSync(rp, "utf8"));
+    const answers = opts.answers ? JSON.parse(readFileSync(opts.answers, "utf8")) : {};
+    const pick = (id) => answers[id] ?? 0;
+    const dsDir = join(root, "_synthesisui", "ds");
+    const slug = existsSync(dsDir) ? readdirSync(dsDir).find((d) => statSync(join(dsDir, d)).isDirectory()) : undefined;
+    if (!slug) {
+        say("This project has no adopted system yet - run `synthesisui adopt --write` first.");
+        process.exitCode = 1;
+        return;
+    }
+    const roles = R.roles
+        .filter((r) => r.home?.cls)
+        .map((r) => ({
+        id: `${r.role.split(" ")[0]}-${contextOf(r.role)}-${r.surface}`, name: nameOf(r.role), element: r.role.split(" ")[0],
+        context: contextOf(r.role), surface: r.surface, class: r.home?.cls, px: r.px, home: at(r.home), places: r.places,
+    }));
+    for (const d of R.drift) {
+        if (pick(`drift:${d.role}:${d.surface}`) !== 1 || !d.home?.cls)
+            continue;
+        roles.push({ id: `${d.role.split(" ")[0]}-${contextOf(d.role)}-${d.surface}-${d.px}`, name: `${nameOf(d.role)} (${d.px}px)`, element: d.role.split(" ")[0],
+            context: contextOf(d.role), surface: d.surface, class: d.home.cls, px: d.px, home: at(d.home), places: 1 });
+    }
+    const breaks = R.breaks
+        .filter((b) => pick(`break:${b.rule}:${b.role}:${b.px}`) === 0 && b.home)
+        .map((b) => ({ id: `${b.rule}-${b.px}`, rule: b.name, what: b.what, element: b.role, class: b.home?.cls ?? null, px: b.px,
+        /* 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 };
+    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.`);
+    say(contract ? "The contract your agent reads now lists them - every heading is checked against its role at the end of each turn." : "Run `synthesisui connect` so your agent reads and checks it.");
+}
+export async function read(opts) {
+    const say = (s) => process.stdout.write(`${s}\n`);
+    const root = opts.dir ?? projectRootFrom(process.cwd());
+    const started = Date.now();
+    const base = await findServer(opts.url, root);
+    if (!base) {
+        say("No dev server answered (tried :3000, :3001, :5173, :4321). Start it - `npm run dev` - and run `synthesisui read` again, or pass `--url`.");
+        process.exitCode = 1;
+        return;
+    }
+    const routes = opts.routes?.length ? opts.routes : ["/"];
+    const pw = loadReader(say);
+    const browser = await launch(pw, say);
+    const seen = [];
+    const pages = new Map();
+    try {
+        for (const rota of routes) {
+            for (const [disp, w, h] of VIEWPORTS) {
+                const ctx = await browser.newContext({ viewport: { width: w, height: h }, reducedMotion: "reduce" });
+                const page = await ctx.newPage();
+                await page.goto(new URL(rota, base).href, { waitUntil: "networkidle", timeout: 90_000 });
+                await page.waitForTimeout(800);
+                const textos = (await page.evaluate(PAGE_SCRIPT));
+                for (const t of textos)
+                    seen.push({ ...t, rota, disp });
+                pages.set(`${rota}|${disp}`, { page, ctx });
+            }
+        }
+        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;
+        const files = sources(root);
+        const home = (t) => homeOf(root, files, t);
+        const out = {
+            read: new Date().toISOString(),
+            url: base,
+            routes,
+            seconds: Math.round((Date.now() - started) / 1000),
+            sectionTitlePx: reading.tituloSecao,
+            typeSteps: reading.passos,
+            roles: reading.papeis.map((r) => ({ role: r.papel, surface: r.superficie, px: r.px, places: r.lugares, seen: r.onde, home: home(r.sample) })),
+            breaks: reading.quebras.map((q) => ({ rule: q.regra, name: q.nome, role: q.papel, px: q.px, what: q.medida, times: q.vezes, seen: q.onde, home: home(q.sample) })),
+            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,
+            questions: [],
+        };
+        out.questions = questionsFor(out.breaks, out.drift);
+        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}` : ""}` : "?");
+        say(`\nWhat your page already decided (${routes.join(", ")}, read in ${out.seconds}s):\n`);
+        say(`  Type steps that repeat: ${out.typeSteps.join(" · ")} px`);
+        say("  Roles:");
+        for (const r of out.roles)
+            say(`    ${r.role} (${r.surface}): ${r.px}px, ${r.home?.cls ?? "?"} - ${at(r.home)}`);
+        if (out.breaks.length)
+            say("  Breaks (each one rule, broken on purpose - confirm or not):");
+        for (const q of out.breaks)
+            say(`    ${q.name}: ${q.role}, ${q.what} - ${at(q.home)}`);
+        if (out.drift.length)
+            say("  Drift (the same role at another size):");
+        for (const d of out.drift)
+            say(`    ${d.role} at ${d.px}px instead of ${d.rulePx}px - ${at(d.home)}`);
+        if (out.lowContrast.length)
+            say("  Hard to read (checked against the pixels):");
+        for (const c of out.lowContrast)
+            say(`    ${c.ratio}:1 (needs ${c.target}:1) ${c.text} on ${c.background} - ${at(c.home)}`);
+        if (out.questions.length)
+            say(`\n  ${out.questions.length} question${out.questions.length === 1 ? "" : "s"} for the person in _synthesisui/reading.json - then \`synthesisui read --confirm <answers.json>\` (no file = yes to all).`);
+        say(`\n  Written to _synthesisui/reading.json. Nothing in your code changed.`);
+    }
+    finally {
+        for (const { ctx } of pages.values())
+            await ctx.close().catch(() => { });
+        await browser.close().catch(() => { });
+    }
+}

package/dist/index.js

@@ -6,6 +6,7 @@ import "./copy/connect.pt-BR.js";
 import { absorb } from "./commands/absorb.js";
 import { add } from "./commands/add.js";
 import { adopt } from "./commands/adopt.js";
+import { confirm, read } from "./commands/read.js";
 import { advise } from "./commands/advise.js";
 import { align } from "./commands/align.js";
 import { autopilot } from "./commands/autopilot.js";
@@ -70,6 +71,10 @@ Usage - governance (deterministic, FREE):
                                            their variant axes and options, their parts and shape, and
                                            where one is built from another - then the values you repeat,
                                            with file and line. No account, no network, nothing written
+  synthesisui read [--url <dev server>] [--routes /,/x]
+  synthesisui read --confirm [answers.json]  the person's answers become the roles and breaks the check keeps
+                                           read the page you already built and say the system it decided:
+                                           roles, breaks, drift and contrast, with file and line
   synthesisui adopt [--write]              turn the design system you ALREADY have into a contract
   synthesisui import [--scope <p>] [--usage <p>]  read what you already have and make it a system
                                            your agent follows - without touching your CSS
@@ -309,6 +314,19 @@ async function main() {
                 registry,
             });
             break;
+        case "read":
+            // What the page already decided - read from the running dev server; writes only _synthesisui/reading.json.
+            // `--confirm [answers.json]` turns the person's answers into rules.json and the contract.
+            if (flags.confirm !== undefined) {
+                await confirm({ dir, answers: typeof flags.confirm === "string" ? flags.confirm : undefined });
+                break;
+            }
+            await read({
+                dir,
+                url: typeof flags.url === "string" ? flags.url : undefined,
+                routes: typeof flags.routes === "string" ? flags.routes.split(",").map((r) => r.trim()).filter(Boolean) : undefined,
+            });
+            break;
         case "adopt":
             // Dry by default: `--write` is the only way anything lands on disk.
             await adopt({

package/dist/install-marks.js

@@ -344,7 +344,13 @@
  * `[font-size:var(--text-sm)]` em vez de `[font-size:0.875rem]`. Um componente escrito antes traz os tamanhos à mão. No
  * mesmo PR, o `init` declara a largura da página (`--container-page`) e a seção a escreve pelo nome, não como `1440px`.
  */
-export const MATERIALISER_SINCE = "0.16.499";
+/**
+ * 0.16.499 -> 0.16.500 em 18/10, e o passo 1 dá **SIM** (jornada "a leitura no agente"): o bloco do `CLAUDE.md` de um
+ * sistema adotado ganha os papéis de título e as quebras que a pessoa confirmou (`_synthesisui/ds/<slug>/rules.json`) e,
+ * sem eles, a linha que ensina o agente a oferecer a leitura (`synthesisui read`) e a confirmar (`read --confirm`). Uma
+ * pasta escrita antes não fala de papéis nem da leitura.
+ */
+export const MATERIALISER_SINCE = "0.16.500";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *
@@ -562,7 +568,13 @@ export const COUNTED_DIFFERENTLY = "this run counts a value as named only when Y
  * de texto escrito à mão (`font-size`, `[font-size:X]`, `text-[X]`), e a família de fonte no colchete do Tailwind deixa de
  * engolir o resto da linha. Um hook anterior diz "limpo" sobre um `[font-size:0.875rem]` com `--text-sm` declarado.
  */
-export const CHECKER_SINCE = "0.16.499";
+/**
+ * 0.16.499 -> 0.16.500 em 18/10, e o passo 1 dá **SIM** (jornada "a leitura no agente"): o hook confere os papéis e as
+ * quebras do `rules.json` (o título fora do papel, a quebra fora do lugar em qualquer elemento, o papel novo dito uma
+ * vez) e acha a raiz pelo projeto - não pela pasta onde o terminal do agente parou, que deixava turnos inteiros sem
+ * conferência. Um hook pinado antes não confere papel nenhum.
+ */
+export const CHECKER_SINCE = "0.16.500";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *

package/dist/reading/classify.js

@@ -0,0 +1,181 @@
+/**
+ * O QUE A PÁGINA JÁ DECIDIU - a classificação da leitura, pura (jornada "a leitura no agente", E02, 18/10).
+ *
+ * Porta, regra por regra, a régua do conjunto (`synthesisui-tests/regua/conjunto/analisar.py`), que provou em 7 lugares -
+ * impeccable, Claude livre, SynthesisUI livre, dois sites públicos - que a mesma conta separa, sem ajuste por projeto:
+ *
+ *     REGRA    o que se repete: os passos de tipo (3+ lugares), o papel de cada título
+ *     QUEBRA   uma regra nomeada quebrada num papel só, de propósito - o vocabulário das peças de Rule breakers:
+ *              Q1 passa da escala dos títulos · Q2 sai do eixo (inclinado) · Q3 motivo grande fora dos títulos
+ *     DERIVA   o mesmo papel com tamanhos diferentes na mesma faixa
+ *
+ * Determinístico: os mesmos textos medidos dão a mesma classificação. E TUDO É CANDIDATO - a pessoa confirma (E03). Este
+ * módulo não lê a página nem o disco: recebe o que o navegador mediu e devolve a proposta.
+ */
+const VIZ = 0.05;
+const FAIXA = 1.4;
+const pagina = (rota) => (rota === "/" ? "landing" : rota);
+const superficie = (rota) => (/^\/(dashboard|admin|team)\b/.test(rota) ? "painel" : "site");
+const r1 = (v) => Math.round(v * 10) / 10;
+/** O papel de um texto: o título que ele é (ou está dentro), de cartão ou do texto corrido; decoração; número; texto. */
+export function roleOf(t) {
+    const h = /^h[1-3]$/.test(t.tag) ? t.tag : t.papel && /^h[1-3]$/.test(t.papel) ? t.papel : null;
+    if (h)
+        return h + (h !== "h1" && t.cartao ? " de cartão" : h !== "h1" && t.corrido ? " do texto corrido" : "");
+    if (t.decorativo)
+        return "decoração";
+    if (/^[\d.,%$“”"#]+$/.test(t.texto))
+        return "número";
+    return "texto";
+}
+function lum(c) {
+    const f = (v) => (v / 255 <= 0.03928 ? v / 255 / 12.92 : ((v / 255 + 0.055) / 1.055) ** 2.4);
+    return 0.2126 * f(c.r) + 0.7152 * f(c.g) + 0.0722 * f(c.b);
+}
+export const mix = (t, b) => ({ r: t.r * t.a + b.r * (1 - t.a), g: t.g * t.a + b.g * (1 - t.a), b: t.b * t.a + b.b * (1 - t.a), a: 1 });
+export function ratio(c, f) {
+    const [a, b] = [lum(mix(c, f)), lum(f)].sort((x, y) => y - x);
+    return (a + 0.05) / (b + 0.05);
+}
+export const hex = (c) => `#${[c.r, c.g, c.b].map((v) => Math.round(v).toString(16).padStart(2, "0")).join("")}`;
+export function classify(seen) {
+    const all = seen.map((t) => ({ ...t, px: r1(t.tam), pp: roleOf(t), sup: superficie(t.rota), pg: pagina(t.rota) }));
+    const desk = all.filter((t) => t.disp === "desktop");
+    const lugar = (xs) => new Set(xs.map((x) => `${x.pg}|${x.secao}`)).size;
+    const label = (x) => `${x.pg}: ${x.texto.slice(0, 44)}`;
+    const uniq = (xs) => [...new Set(xs)].sort();
+    // A ESCALA: tamanhos a menos de 5% um do outro são o mesmo passo; passo = usado em 3+ lugares
+    const tams = [...new Set(desk.map((t) => t.px))].sort((a, b) => a - b);
+    const grupos = [];
+    for (const v of tams) {
+        const g = grupos[grupos.length - 1];
+        if (g && v <= g[0] * (1 + VIZ))
+            g.push(v);
+        else
+            grupos.push([v]);
+    }
+    const passos = [];
+    for (const g of grupos) {
+        const xs = desk.filter((t) => g.includes(t.px));
+        if (lugar(xs) < 3)
+            continue;
+        const anc = [...g].sort((a, b) => lugar(xs.filter((t) => t.px === b)) - lugar(xs.filter((t) => t.px === a)) || xs.filter((t) => t.px === b).length - xs.filter((t) => t.px === a).length)[0];
+        passos.push(anc);
+    }
+    // OS PAPÉIS E A DERIVA: por papel e superfície; dentro de uma faixa (vizinhos até 1,4x), o tamanho com mais lugares manda
+    const por = new Map();
+    for (const t of desk)
+        if (t.pp.startsWith("h"))
+            por.set(`${t.sup}|${t.pp}`, [...(por.get(`${t.sup}|${t.pp}`) ?? []), t]);
+    const best = (vals, xs) => [...vals].sort((a, b) => lugar(xs.filter((x) => x.px === b)) - lugar(xs.filter((x) => x.px === a)) || b - a)[0];
+    const papeis = [];
+    const deriva = [];
+    for (const xs of por.values()) {
+        const { sup, pp } = xs[0];
+        const principal = best([...new Set(xs.map((x) => x.px))], xs);
+        const ps = xs.filter((x) => x.px === principal);
+        papeis.push({ papel: pp, superficie: sup, px: principal, lugares: lugar(ps), onde: uniq(ps.map(label)).slice(0, 3), sample: ps[0] });
+        const vs = [...new Set(xs.map((x) => x.px))].sort((a, b) => a - b);
+        const faixas = [];
+        for (const v of vs) {
+            const f = faixas[faixas.length - 1];
+            if (f && v <= f[f.length - 1] * FAIXA)
+                f.push(v);
+            else
+                faixas.push([v]);
+        }
+        for (const fx of faixas) {
+            if (fx.length < 2)
+                continue;
+            const grupo = xs.filter((x) => fx.includes(x.px));
+            const regra = best(fx, grupo);
+            const rs = grupo.filter((x) => x.px === regra);
+            for (const v of fx) {
+                if (v === regra)
+                    continue;
+                const ys = grupo.filter((x) => x.px === v);
+                deriva.push({ papel: pp, superficie: sup, px: v, regraPx: regra, onde: uniq(ys.map(label)), sample: ys[0], ruleSample: rs[0] });
+            }
+        }
+    }
+    // O TÍTULO DE SEÇÃO = a maior faixa de h2 do site com 2+ textos (os próprios <h2>, não os <span> dentro deles)
+    const h2own = desk.filter((x) => x.sup === "site" && x.pp === "h2" && x.tag === "h2");
+    const h2 = h2own.length ? h2own : desk.filter((x) => x.sup === "site" && x.pp === "h2");
+    const near = (a, b) => Math.abs(a - b) <= Math.max(a, b) * VIZ;
+    const cands = [...new Set(h2.map((x) => x.px))].sort((a, b) => b - a);
+    const tituloSecao = cands.find((v) => new Set(h2.filter((x) => near(x.px, v)).map((x) => x.texto)).size >= 2) ?? passos[passos.length - 1] ?? 0;
+    // AS QUEBRAS
+    const derivados = new Set(deriva.map((d) => `${d.superficie}|${d.papel}|${d.px}`));
+    const quebras = new Map();
+    for (const t of desk) {
+        if (t.sup !== "site")
+            continue;
+        let q = null;
+        if (t.px > tituloSecao * 1.04 && !derivados.has(`${t.sup}|${t.pp}|${t.px}`))
+            q = { regra: "Q1", nome: "above the heading scale", papel: t.pp, px: t.px, medida: `${t.px}px against the ${tituloSecao}px section title` };
+        else if ((t.pp === "número" || t.pp === "decoração") && t.px >= 40)
+            q = { regra: "Q3", nome: "big motif outside the headings", papel: t.pp, px: t.px, medida: `${t.px}px, ${t.decorativo ? "hidden from screen readers" : "read as content"}` };
+        if (!q || quebras.has(`${q.regra}|${q.papel}|${q.px}`))
+            continue;
+        const xs = desk.filter((x) => x.sup === "site" && x.pp === t.pp && x.px === t.px);
+        quebras.set(`${q.regra}|${q.papel}|${q.px}`, { ...q, vezes: xs.length, onde: uniq(xs.map(label)).slice(0, 5), sample: t });
+    }
+    const giros = new Map();
+    for (const t of desk)
+        if (t.giro)
+            giros.set(`${t.pg}|${t.giro}`, [...(giros.get(`${t.pg}|${t.giro}`) ?? []), t]);
+    for (const xs of giros.values()) {
+        const alvo = xs.find((x) => x.pp === "h1") ?? xs[0];
+        const k = `Q2|bloco|${alvo.px}`;
+        if (!quebras.has(k))
+            quebras.set(k, { regra: "Q2", nome: "off the axis (tilted)", papel: "bloco", px: alvo.px, medida: `${alvo.giro}° - the whole block, ${xs.length} texts inside`, vezes: 1, onde: uniq(xs.map(label)).slice(0, 4), sample: alvo });
+    }
+    // O CONTRASTE - candidatos pelo fundo do DOM; quem chama confere cada um pelos pixels (`pixelRatio`)
+    const falhas = new Map();
+    let sobreImagem = 0;
+    for (const t of all) {
+        if (t.decorativo || !t.cor)
+            continue;
+        if (t.sobreImagem) {
+            sobreImagem++;
+            continue;
+        }
+        const r = ratio(t.cor, t.fundo);
+        const alvo = t.tam >= 24 || (t.tam >= 18.66 && t.peso >= 700) ? 3 : 4.5;
+        if (r >= alvo)
+            continue;
+        const k = `${hex(mix(t.cor, t.fundo))}|${hex(t.fundo)}|${Math.round(t.tam)}`;
+        const f = falhas.get(k) ?? { razao: Math.round(r * 100) / 100, alvo, texto: hex(mix(t.cor, t.fundo)), fundo: hex(t.fundo), px: t.tam, onde: [], sample: t };
+        f.onde = uniq([...f.onde, label(t)]).slice(0, 5);
+        falhas.set(k, f);
+    }
+    return { passos, tituloSecao, papeis, deriva, quebras: [...quebras.values()], contraste: [...falhas.values()].sort((a, b) => a.razao - b.razao), sobreImagem };
+}
+/**
+ * A TINTA DE VERDADE, PELOS PIXELS - na régua, a conta pelo fundo do DOM acusou 1,0:1 num "$" visível (o fundo vinha de
+ * outra camada), e o linear.app teve 7 textos que nem estavam pintados. Recebe os pixels RGBA da caixa do texto: o fundo é
+ * a cor mais presente; a tinta, entre as que ocupam 3%+ da caixa, a que mais contrasta com ele. Sem tinta (< 1,2:1) é
+ * texto não pintado ali, nunca uma falha.
+ */
+export function pixelRatio(rgba) {
+    const n = Math.floor(rgba.length / 4);
+    if (n < 4)
+        return null;
+    const buckets = new Map();
+    for (let i = 0; i < n; i++) {
+        const r = rgba[i * 4], g = rgba[i * 4 + 1], b = rgba[i * 4 + 2];
+        const k = ((r >> 4) << 8) | ((g >> 4) << 4) | (b >> 4);
+        const e = buckets.get(k) ?? { c: 0, r: 0, g: 0, b: 0 };
+        e.c++;
+        e.r += r;
+        e.g += g;
+        e.b += b;
+        buckets.set(k, e);
+    }
+    const cores = [...buckets.values()].sort((a, b) => b.c - a.c).map((e) => ({ c: e.c, cor: { r: e.r / e.c, g: e.g / e.c, b: e.b / e.c, a: 1 } }));
+    const fundo = cores[0].cor;
+    const tintas = cores.slice(1).filter((x) => x.c / n >= 0.03);
+    if (tintas.length === 0)
+        return cores.length > 1 ? ratio(cores[1].cor, fundo) : 1;
+    return Math.max(...tintas.map((x) => ratio(x.cor, fundo)));
+}

package/dist/reading/page-script.js

@@ -0,0 +1,64 @@
+/**
+ * O QUE RODA DENTRO DA PÁGINA - a medida de cada texto como o visitante o vê (jornada "a leitura no agente", E02, 18/10).
+ *
+ * O mesmo leitor da régua do conjunto (`synthesisui-tests/regua/conjunto/ler.mjs`), reduzido ao que a classificação usa:
+ * tamanho, família, peso, cor, o fundo real atrás do texto (subindo pelos ancestrais e misturando transparência), se está
+ * sobre imagem, inclinação, ênfase, cartão (estrutura repetida 3+), texto corrido, o COMPONENTE (pela fibra do React, no
+ * `next dev` - a ligação ao código que independe da forma de estilo) e a classe. É uma string porque roda no navegador,
+ * não no Node: `page.evaluate(PAGE_SCRIPT)`.
+ */
+export const PAGE_SCRIPT = String.raw `(() => {
+  const parse = (s) => { const m = s.match(/rgba?\(([^)]+)\)/); if (!m) return null; const v = m[1].split(/[ ,/]+/).filter(Boolean).map(Number); return { r: v[0], g: v[1], b: v[2], a: v.length > 3 ? v[3] : 1 }; };
+  const mix = (top, bot) => ({ r: top.r * top.a + bot.r * (1 - top.a), g: top.g * top.a + bot.g * (1 - top.a), b: top.b * top.a + bot.b * (1 - top.a), a: 1 });
+  const fundo = (el) => {
+    const camadas = []; let img = false;
+    for (let e = el; e; e = e.parentElement) {
+      const cs = getComputedStyle(e);
+      if (cs.backgroundImage && cs.backgroundImage !== "none") img = img || /url\(|gradient/.test(cs.backgroundImage);
+      const bg = parse(cs.backgroundColor); if (bg && bg.a > 0) { camadas.push(bg); if (bg.a >= 1) break; }
+      if (e.parentElement && [...e.parentElement.children].some((s) => s !== e && /^(VIDEO|IMG)$/.test(s.tagName) && getComputedStyle(s).position === "absolute")) img = true;
+    }
+    let cor = { r: 255, g: 255, b: 255, a: 1 };
+    for (let i = camadas.length - 1; i >= 0; i--) cor = mix(camadas[i], cor);
+    return { cor, img };
+  };
+  const secao = (el) => { for (let e = el; e; e = e.parentElement) { if (/^(SECTION|HEADER|FOOTER|NAV|MAIN|ASIDE|ARTICLE|DIALOG)$/.test(e.tagName) || e.id) return e.tagName.toLowerCase() + (e.id ? "#" + e.id : ""); } return "body"; };
+  const textos = [];
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+  const vistos = new Set();
+  while (walker.nextNode()) {
+    const t = walker.currentNode; const el = t.parentElement; if (!el || vistos.has(el)) continue;
+    const txt = t.textContent.trim(); if (!txt) continue;
+    const cs = getComputedStyle(el);
+    if (cs.visibility === "hidden" || cs.display === "none" || Number(cs.opacity) === 0) continue;
+    const r = el.getBoundingClientRect(); if (r.width < 1 || r.height < 1) continue;
+    vistos.add(el);
+    let giro = 0; for (let e = el; e && e !== document.body; e = e.parentElement) { const tf = getComputedStyle(e).transform; if (tf && tf !== "none") { const m = tf.match(/matrix\(([^)]+)\)/); if (m) { const [a, bb] = m[1].split(",").map(Number); const ang = Math.round(Math.atan2(bb, a) * 1800 / Math.PI) / 10; if (ang) { giro = ang; break; } } } }
+    const tit = el.closest("h1,h2,h3"); const enfase = !!(tit && tit !== el && getComputedStyle(tit).color !== cs.color);
+    let cartao = false;
+    for (let e = el, i = 0; e && e.parentElement && i < 6 && !cartao; e = e.parentElement, i++) {
+      const irmaos = [...e.parentElement.children].filter((x) => x.tagName === e.tagName && (x.getAttribute("class") || "") === (e.getAttribute("class") || ""));
+      if (irmaos.length >= 3 && e !== el) cartao = true;
+    }
+    const corrido = !!(tit || el).closest("article") || (((tit || el).parentElement && (tit || el).parentElement.querySelectorAll(":scope > p").length) || 0) >= 3;
+    let comp = null;
+    const fk = Object.keys(el).find((k) => k.startsWith("__reactFiber$"));
+    for (let f = fk ? el[fk] : null, i = 0; f && i < 40 && !comp; f = f.return, i++) {
+      const st = f._debugStack && String(f._debugStack.stack || "");
+      if (st) for (const ln of st.split("\n").slice(1)) { const mm = ln.match(/at ([A-Z][A-Za-z0-9_]*) \(/); if (mm && !/^(Object|Array|Error|Promise)$/.test(mm[1])) { comp = mm[1]; break; } }
+    }
+    let op = 1; for (let e = el; e; e = e.parentElement) op *= Number(getComputedStyle(e).opacity);
+    const cor = parse(cs.color); if (cor) cor.a *= op;
+    const f = fundo(el);
+    textos.push({
+      texto: txt.slice(0, 60), tag: el.tagName.toLowerCase(),
+      papel: (el.closest("h1,h2,h3,h4,h5,h6,button,a,label,th,figcaption,blockquote,input") || { tagName: "" }).tagName.toLowerCase() || null,
+      tam: parseFloat(cs.fontSize), familia: cs.fontFamily.split(",")[0].replace(/["']/g, "").trim(), peso: Number(cs.fontWeight),
+      cor, fundo: f.cor, sobreImagem: f.img, decorativo: !!el.closest("[aria-hidden=true]"),
+      cartao, corrido, giro, enfase, comp,
+      cls: [el, ...(tit && tit !== el ? [tit] : []), el.parentElement].filter(Boolean).map((x) => x.getAttribute("class") || "").join(" | ").slice(0, 600),
+      secao: secao(el), x: r.left + scrollX, y: r.top + scrollY, w: r.width, h: r.height,
+    });
+  }
+  return textos;
+})()`;

package/dist/reading/png.js

@@ -0,0 +1,66 @@
+import { inflateSync } from "node:zlib";
+/**
+ * O PNG DE UMA CAIXA DE TEXTO, EM PIXELS - sem dependência (o CLI não tem nenhuma, e não é a conferência do contraste que vai
+ * inaugurar a primeira). Lê o que o navegador devolve num `screenshot`: 8 bits, RGB ou RGBA, sem entrelaçamento. Qualquer
+ * outra forma devolve `null`, e quem chama trata como "não conferido" - nunca como falha.
+ */
+export function decodePng(buf) {
+    if (buf.length < 8 || buf.readUInt32BE(0) !== 0x89504e47)
+        return null;
+    let off = 8, w = 0, h = 0, type = 0, depth = 0, interlace = 0;
+    const idat = [];
+    while (off + 8 <= buf.length) {
+        const len = buf.readUInt32BE(off);
+        const kind = buf.toString("ascii", off + 4, off + 8);
+        const data = buf.subarray(off + 8, off + 8 + len);
+        if (kind === "IHDR") {
+            w = data.readUInt32BE(0);
+            h = data.readUInt32BE(4);
+            depth = data[8];
+            type = data[9];
+            interlace = data[12];
+        }
+        else if (kind === "IDAT")
+            idat.push(data);
+        else if (kind === "IEND")
+            break;
+        off += 12 + len;
+    }
+    if (depth !== 8 || interlace !== 0 || (type !== 2 && type !== 6) || !w || !h)
+        return null;
+    const bpp = type === 6 ? 4 : 3;
+    const raw = inflateSync(Buffer.concat(idat));
+    const stride = w * bpp;
+    const out = new Uint8Array(w * h * 4);
+    const prev = new Uint8Array(stride);
+    const cur = new Uint8Array(stride);
+    for (let y = 0; y < h; y++) {
+        const filter = raw[y * (stride + 1)];
+        for (let x = 0; x < stride; x++) {
+            const v = raw[y * (stride + 1) + 1 + x];
+            const a = x >= bpp ? cur[x - bpp] : 0;
+            const b = prev[x];
+            const c = x >= bpp ? prev[x - bpp] : 0;
+            let p = 0;
+            if (filter === 1)
+                p = a;
+            else if (filter === 2)
+                p = b;
+            else if (filter === 3)
+                p = (a + b) >> 1;
+            else if (filter === 4) {
+                const pa = Math.abs(b - c), pb = Math.abs(a - c), pc = Math.abs(a + b - 2 * c);
+                p = pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+            }
+            cur[x] = (v + p) & 255;
+        }
+        for (let x = 0; x < w; x++) {
+            out[(y * w + x) * 4] = cur[x * bpp];
+            out[(y * w + x) * 4 + 1] = cur[x * bpp + 1];
+            out[(y * w + x) * 4 + 2] = cur[x * bpp + 2];
+            out[(y * w + x) * 4 + 3] = bpp === 4 ? cur[x * bpp + 3] : 255;
+        }
+        prev.set(cur);
+    }
+    return out;
+}

package/dist/role-rules.js

@@ -0,0 +1,168 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+export async function loadRoleRules(root) {
+    const ds = join(root, "_synthesisui", "ds");
+    const slugs = await readdir(ds).catch(() => []);
+    for (const slug of slugs) {
+        const raw = await readFile(join(ds, slug, "rules.json"), "utf8").catch(() => null);
+        if (!raw)
+            continue;
+        try {
+            const r = JSON.parse(raw);
+            if (Array.isArray(r.roles))
+                return { ...r, breaks: r.breaks ?? [] };
+        }
+        catch {
+            /* um rules.json quebrado não derruba a checagem: ela só não fala de papéis */
+        }
+    }
+    return null;
+}
+const NAMED = { xs: 12, sm: 14, base: 16, lg: 18, xl: 20, "2xl": 24, "3xl": 30, "4xl": 36, "5xl": 48, "6xl": 60, "7xl": 72, "8xl": 96, "9xl": 128 };
+/** Só classe de TAMANHO: `text-[#1b1406]` é cor e não entra (achado na leitura do synthesisui.com, 18/10). */
+const SIZE = /(?:^|\s)((?:[a-z0-9]+:)?text-(?:\[(?:clamp\([^\]\s]+\)|[\d.]+(?:rem|px|em))\]|xs|sm|base|lg|[2-9]?xl))(?=\s|$)/g;
+/** O tamanho final (desktop) de uma classe: o teto do `clamp`, o valor do colchete, ou a escala do Tailwind. */
+export function pxOf(cls) {
+    const bare = cls.replace(/^(?:[a-z0-9]+:)+/, "");
+    const named = bare.match(/^text-(xs|sm|base|lg|[2-9]?xl)$/);
+    if (named)
+        return NAMED[named[1]] ?? null;
+    const inner = bare.match(/^text-\[(.+)\]$/)?.[1];
+    if (!inner)
+        return null;
+    const last = inner.startsWith("clamp(") ? inner.slice(6, -1).split(",").pop()?.trim() : inner;
+    const m = last?.match(/^([\d.]+)(rem|px)$/);
+    if (!m)
+        return null;
+    return m[2] === "rem" ? Number(m[1]) * 16 : Number(m[1]);
+}
+/** O maior tamanho entre as classes de um elemento - o que vale no desktop (a régua mede em 1440). */
+function sizeClass(attrs) {
+    const cls = attrs.match(/className=\{?\s*["'`]([^"'`]*)["'`]/)?.[1] ?? attrs.match(/className=\{cn\(([^)]*)\)/)?.[1] ?? "";
+    const found = [...` ${cls} `.matchAll(SIZE)].map((m) => m[1]);
+    if (found.length === 0)
+        return null;
+    return found.sort((a, b) => (pxOf(b) ?? 0) - (pxOf(a) ?? 0))[0] ?? null;
+}
+/** Dentro de um `.map(` ainda aberto = o título se repete = é de cartão. A mesma pergunta que a régua faz ao DOM. */
+function insideMap(src, at) {
+    const before = src.slice(0, at);
+    const open = before.lastIndexOf(".map(");
+    if (open < 0)
+        return false;
+    let depth = 0;
+    for (const ch of before.slice(open + 4))
+        depth += ch === "(" ? 1 : ch === ")" ? -1 : 0;
+    return depth > 0;
+}
+const near = (a, b) => Math.abs(a - b) / Math.max(a, b) < 0.03;
+export function checkRoles(rel, src, rules) {
+    if (rules.enforce === false || !/\.(tsx|jsx)$/.test(rel))
+        return [];
+    const component = basename(rel, extname(rel));
+    const known = new Set((rules.knownDrift ?? []).filter((d) => d.at.startsWith(rel)).map((d) => d.class));
+    const section = rules.roles.find((r) => r.element === "h2" && r.context === "section");
+    const out = [];
+    for (const m of src.matchAll(/<(h1|h2|h3)\b([^>]*)>/g)) {
+        const el = m[1];
+        const cls = sizeClass(m[2]);
+        if (!cls)
+            continue;
+        const line = src.slice(0, m.index).split("\n").length;
+        const context = insideMap(src, m.index ?? 0) ? "card" : "section";
+        const bare = cls.replace(/^(?:[a-z0-9]+:)+/, "");
+        const mine = rules.roles.filter((r) => r.element === el);
+        if (mine.some((r) => r.class === bare))
+            continue;
+        if (rules.breaks.some((b) => b.class === bare && b.allowedIn === component))
+            continue;
+        if (known.has(bare))
+            continue;
+        const px = pxOf(bare);
+        const role = mine.find((r) => r.context === context) ?? mine[0];
+        const brk = rules.breaks.find((b) => b.class === bare);
+        if (brk) {
+            out.push(`  line ${line}  <${el}> ${bare} is the break "${brk.rule}", which the person chose for ${brk.allowedIn} only (${brk.home}).${role ? ` Here, use the ${role.name}: ${role.class} (${role.home}).` : ""}`);
+            continue;
+        }
+        if (role && px && near(px, role.px)) {
+            out.push(`  line ${line}  <${el}> ${bare} renders like the ${role.name} but is written differently - use ${role.class} (${role.home}), so the two stay one rule.`);
+            continue;
+        }
+        if (section && px && px > section.px * 1.04 && el !== "h1") {
+            out.push(`  line ${line}  <${el}> ${bare} (~${Math.round(px)}px) goes above this project's section titles (${Math.round(section.px)}px). Only the breaks the person chose go there. Use the ${role?.name ?? "section title"} (${role?.class ?? section.class}), or ask whether this is a new break.`);
+            continue;
+        }
+        if (!role || !px)
+            continue;
+        /**
+         * PERTO DO PAPEL É DERIVA; LONGE DELE É PROVAVELMENTE UM PAPEL NOVO - e papel novo é decisão da pessoa. Medido na
+         * primeira versão, contra o corte: o título DENTRO do artigo (36px) ouviu "use o título de seção (86px)", e seguir
+         * isso estragaria a página. A mesma faixa da régua (1,4x) separa os dois casos.
+         */
+        if (px >= role.px / 1.4 && px <= role.px * 1.4)
+            out.push(`  line ${line}  <${el}> ${bare} (~${Math.round(px)}px) - the ${role.name} role in this project is ${role.class} (${Math.round(role.px)}px, ${role.home}). Use it, so the role stays one size.`);
+        else
+            out.push(`  line ${line}  <${el}> ${bare} (~${Math.round(px)}px) is a heading size this project has no role for yet (its ${role.name} is ${Math.round(role.px)}px). If it is a new role - a heading inside an article, a card - keep it and name the role to the person in one line; if it is a ${role.name}, use ${role.class}.`);
+    }
+    /**
+     * A QUEBRA FORA DO LUGAR, EM QUALQUER ELEMENTO - medido na linha B (18/10): sem checagem, a página do cachorro copiou os
+     * números grandes da landing. Os títulos já estão acima; aqui, todo elemento que não é título e usa a classe de uma
+     * quebra fora do componente dela. A cópia com OUTRO tamanho (41,6 no lugar de 57,6) não aparece no código - é a régua
+     * da página renderizada que vê ("o mesmo motivo"), no fecho do turno.
+     */
+    for (const b of rules.breaks) {
+        if (!b.class || b.allowedIn === component)
+            continue;
+        for (const m of src.matchAll(/<([a-z][a-z0-9]*)\b([^>]*)>/g)) {
+            if (/^h[1-3]$/.test(m[1]))
+                continue;
+            const cls = m[2].match(/className=\{?\s*["'`]([^"'`]*)["'`]/)?.[1] ?? "";
+            if (!` ${cls} `.includes(` ${b.class} `))
+                continue;
+            const line = src.slice(0, m.index).split("\n").length;
+            out.push(`  line ${line}  <${m[1]}> ${b.class} is the break "${b.rule}" the person chose for ${b.allowedIn} (${b.home}). Reuse that component here instead of copying the motif, or ask whether this page gets its own.`);
+        }
+    }
+    return out;
+}
+/** O bloco do contrato: os papéis e as quebras, para o agente saber ANTES de escrever (a prevenção). */
+export function rolesContract(rules) {
+    const roles = rules.roles
+        .map((r) => `- ${r.name} (\`<${r.element}>\`${r.context === "card" ? " in a repeated card" : ""}): \`${r.class}\` - ${r.home}`)
+        .join("\n");
+    const breaks = rules.breaks
+        .filter((b) => b.class)
+        .map((b) => `- ${b.rule}: \`${b.class}\` - only in ${b.allowedIn} (${b.home})`)
+        .join("\n");
+    return `\n\n**The type roles this project already decided** (read from its own pages). A new heading takes the class of its role - never a new size for an existing role:\n${roles}${breaks ? `\n\n**The breaks the person chose** - they stay where they live, and nowhere else:\n${breaks}` : ""}`;
+}
+/**
+ * O PAPEL NOVO É DITO UMA VEZ - medido na linha A (18/10): o aviso "a heading size this project has no role for yet" voltou
+ * em TODO fim de turno nos mesmos arquivos do blog, e cada repetição custou leitura e resposta do agente (a rodada saiu
+ * ~US$ 1 mais cara por turno que o corte). Papel novo é decisão da pessoa; depois de dito, repetir é ruído. A deriva (o
+ * título perto do papel e escrito diferente) continua sendo dita sempre - ela é conserto, não decisão.
+ */
+const SAID = (root) => join(root, "_synthesisui", ".roles-said.json");
+export async function onlyOnce(root, rel, lines) {
+    const said = new Set(JSON.parse((await readFile(SAID(root), "utf8").catch(() => "[]")) || "[]"));
+    const out = [];
+    let changed = false;
+    for (const l of lines) {
+        if (!l.includes("has no role for yet")) {
+            out.push(l);
+            continue;
+        }
+        const key = `${rel}|${l.match(/> (\S+)/)?.[1] ?? l}`;
+        if (said.has(key))
+            continue;
+        said.add(key);
+        changed = true;
+        out.push(l);
+    }
+    if (changed) {
+        await mkdir(join(root, "_synthesisui"), { recursive: true }).catch(() => undefined);
+        await writeFile(SAID(root), JSON.stringify([...said], null, 1)).catch(() => undefined);
+    }
+    return out;
+}

package/package.json

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