synthesisui 0.16.499 → 0.16.501

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,237 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, 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;
+}
+/**
+ * A CLASSE DE UM CSS MODULE - achado na rodada real da porta (18/10, `regua/rodadas/porta-2`): o impeccable escreveu a
+ * landing com `className={styles.h2}` (117 usos, 4 `.module.css`), a leitura achou 5 papéis e o `--confirm` gravou ZERO,
+ * porque a identidade de um papel era só a classe de tamanho do Tailwind. Uma de três criações medidas foi assim.
+ *
+ * A identidade passa a ser o ARQUIVO e o nome local - `page.module.css .h2` -, que é o que a pessoa acha no código e o
+ * que o hash do build não muda. O apelido do import (`styles`, `s`) não entra: dois arquivos podem chamar o mesmo módulo
+ * de jeitos diferentes.
+ */
+export function moduleClassName(file, local) {
+    return `${file} .${local}`;
+}
+/** Os imports de CSS Module de um arquivo: apelido -> o caminho como foi escrito. */
+function moduleImports(src) {
+    const out = new Map();
+    for (const m of src.matchAll(/import\s+(\w+)\s+from\s+["']([^"']+\.module\.s?css)["']/g))
+        out.set(m[1], m[2]);
+    return out;
+}
+/** As classes de módulo dentro de um `className={...}`, na ordem em que aparecem. */
+function moduleClasses(attrs, imports) {
+    const expr = attrs.match(/className=\{([^}]*(?:\}[^}]*)?)\}/)?.[1] ?? "";
+    const out = [];
+    for (const m of expr.matchAll(/\b(\w+)(?:\.([A-Za-z_][\w-]*)|\[["']([\w-]+)["']\])/g)) {
+        const path = imports.get(m[1]);
+        const local = (m[2] ?? m[3]);
+        if (path && local)
+            out.push({ name: moduleClassName(basename(path), local), path, local });
+    }
+    return out;
+}
+/** O `font-size` de uma classe dentro do `.module.css` - o maior de um `clamp()` (o desktop), `rem` a 16px. */
+export function modulePx(css, local) {
+    let best = null;
+    const esc = local.replace(/[-]/g, "\\-");
+    for (const m of css.matchAll(new RegExp(`([^{}]*\\.${esc}(?![\\w-])[^{}]*)\\{([^}]*)\\}`, "g"))) {
+        const v = m[2].match(/font-size\s*:\s*([^;]+)/)?.[1]?.trim();
+        if (!v)
+            continue;
+        const parts = v.startsWith("clamp(") ? v.slice(6, -1).split(",") : [v];
+        for (const p of parts) {
+            const n = p.trim().match(/^([\d.]+)(px|rem)$/);
+            if (!n)
+                continue;
+            const px = Number(n[1]) * (n[2] === "rem" ? 16 : 1);
+            if (best === null || px > best)
+                best = px;
+        }
+    }
+    return best;
+}
+/** 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, root) {
+    if (rules.enforce === false || !/\.(tsx|jsx)$/.test(rel))
+        return [];
+    const imports = moduleImports(src);
+    const cssOf = new Map();
+    const pxOfModule = (path, local) => {
+        if (!root)
+            return null;
+        const file = join(root, dirname(rel), path);
+        if (!cssOf.has(file))
+            cssOf.set(file, existsSync(file) ? readFileSync(file, "utf8") : "");
+        return modulePx(cssOf.get(file), local);
+    };
+    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 mod = sizeClass(m[2]) ? null : (moduleClasses(m[2], imports)[0] ?? null);
+        const cls = sizeClass(m[2]) ?? mod?.name ?? null;
+        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 = mod ? pxOfModule(mod.path, mod.local) : 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.
+     */
+    /* duas quebras podem morar na mesma classe (a capa da porta-2: "Batch" e "Nº 01" em `.batch span`) - uma linha basta */
+    const said = new Set();
+    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] ?? "";
+            const mods = moduleClasses(m[2], imports).map((c) => c.name);
+            if (!` ${cls} `.includes(` ${b.class} `) && !mods.includes(b.class))
+                continue;
+            const line = src.slice(0, m.index).split("\n").length;
+            if (said.has(`${line} ${b.class}`))
+                continue;
+            said.add(`${line} ${b.class}`);
+            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.501",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {