synthesisui 0.16.329 → 0.16.330

package/dist/commands/import.js

@@ -18,6 +18,7 @@ import { classifyAside, crosswalk, floorSize, isLibrary, observedRules, useLiveC
 import { keyframeOffsets, moduleImports, partialCandidates, readGlobalClasses, readModuleCss, readModuleUsage, sheetImports, transcribeModule, } from "../doctor/css-modules.js";
 import { dataContract } from "../doctor/data-contract.js";
 import { inherit, readDeclaredForms, } from "../doctor/declared-forms.js";
+import { defaultSchemeOf, } from "../doctor/default-scheme.js";
 import { reconcile, scanDefinitions, } from "../doctor/definitions-scan.js";
 import { accountExportsInto, emptyExportAccount, exportInvariantHolds, } from "../doctor/export-census.js";
 import { fragmentsOfSource, fragmentsOfStylesheet, judgeFragments, } from "../doctor/fragments.js";
@@ -2101,6 +2102,24 @@ export async function takeCensus(root, opts) {
      * `workspaces` declaram, que é onde recharts/chakra/mui realmente moram.
      */
     finishSignals(signals, importTally, versions);
+    /**
+     * QUAL FACE O PROJETO ABRE - observação estrutural, aqui porque os sinais de tema já
+     * fecharam. Ver `default-scheme.ts` para a escada de evidência e para por que ela nunca
+     * usa luminância. `census.scheme`, decidido bem depois em `runImport`, é outra coisa: a
+     * decisão RESOLVIDA daquela execução, e ela nunca reescreve o que foi observado.
+     */
+    const polarity = defaultSchemeOf({
+        sheets: globalSheets.map((g) => ({ file: g.file, css: g.body })),
+        signals: signals.theme,
+    });
+    const declaredSchemes = {
+        base: Object.fromEntries(schemes.base),
+        light: Object.fromEntries(schemes.light),
+        dark: Object.fromEntries(schemes.dark),
+        defaultScheme: polarity.scheme,
+        defaultSchemeSource: polarity.source,
+        ...(polarity.evidence ? { defaultSchemeEvidence: polarity.evidence } : {}),
+    };
     // Every name their CSS defines, from the same harvest the token table came
     // from - so a reference is judged against what actually exists, not against
     // the subset we managed to read as a ramp.
@@ -2343,9 +2362,10 @@ export async function takeCensus(root, opts) {
         classStyle,
         ...(Object.keys(looks).length > 0 ? { looks } : {}),
         ...(naming.components > 0 ? { naming } : {}),
-        ...(schemes.alt.size > 0
-            ? { declaredAlt: Object.fromEntries(schemes.alt) }
+        ...(schemes.dark.size > 0
+            ? { declaredAlt: Object.fromEntries(schemes.dark) }
             : {}),
+        declaredSchemes,
         observed: distinctValues(d),
         ...(components.length > 0 ? { components } : {}),
         ...(defined.length > 0 ? { defined } : {}),
@@ -3351,6 +3371,41 @@ async function askScheme(suggested) {
  * light greys, and its dashboard is near-black - so the count agrees with the
  * screen. It is only a default; the person confirms it either way.
  */
+/**
+ * A FACE QUE O PROJETO ABRE, quando a estrutura dele respondeu - senão `null`.
+ *
+ * Só vale para medição NOVA: um censo sem `declaredSchemes` foi medido por uma versão que
+ * não fazia esta pergunta, e responder por ele seria inventar. Ver a nota de compatibilidade
+ * em `Census.declaredSchemes`.
+ */
+export function observedPolarity(census) {
+    const fact = census.declaredSchemes;
+    if (!fact || fact.defaultScheme === "unknown")
+        return null;
+    return fact.defaultScheme;
+}
+/**
+ * QUANDO A ESTEIRA TEM DE FICAR CALADA sobre qual face abre.
+ *
+ * Medição nova, polaridade `unknown`, e nenhum lado declarado explicitamente: aqui a base
+ * é de verdade indeterminada, e a escada de neutros só sabe responder por LUMINÂNCIA - a
+ * evidência que este contrato recusa. Sem TTY, `askScheme` devolve esse palpite calado, e
+ * era assim que "a base é clara" voltava pela porta dos fundos.
+ *
+ * Com pelo menos um override explícito, as duas faces são conhecíveis mesmo sem saber qual
+ * abre, então este portão não fecha - o que fica pendente é só o padrão.
+ *
+ * Censo LEGADO nunca cai aqui: ele não tem o fato, e o comportamento dele é preservado
+ * inteiro. Decisão do dono (28/08, saída A).
+ */
+export function mustNotGuessPolarity(census) {
+    const fact = census.declaredSchemes;
+    if (!fact)
+        return false;
+    if (fact.defaultScheme !== "unknown")
+        return false;
+    return (Object.keys(fact.light).length === 0 && Object.keys(fact.dark).length === 0);
+}
 export function defaultScheme(declared) {
     let dark = 0;
     let light = 0;
@@ -4088,15 +4143,23 @@ export async function runImport(opts) {
         // contradict it.
         (read?.has?.length === 1
             ? read.has[0]
-            : reach.light && reach.dark
-                ? await askScheme(defaultScheme(census.declared))
-                : reach.dark
-                    ? "dark"
-                    : reach.light
-                        ? "light"
-                        : undefined);
+            : (observedPolarity(census) ??
+                (mustNotGuessPolarity(census)
+                    ? undefined
+                    : reach.light && reach.dark
+                        ? await askScheme(defaultScheme(census.declared))
+                        : reach.dark
+                            ? "dark"
+                            : reach.light
+                                ? "light"
+                                : undefined)));
     if (scheme)
         census.scheme = scheme;
+    if (!scheme && mustNotGuessPolarity(census)) {
+        console.log("");
+        console.log(body("Your stylesheet does not say which face this project opens in, and nothing here declares a light or a dark scheme on its own. Nothing was guessed: the measurement is complete and the default stays yours to pick."));
+        console.log(body(`Name it with ${paint.strong("--scheme dark")} or ${paint.strong("--scheme light")}, or answer the question this command asks at a terminal.`));
+    }
     // The file on disk has to say what we sent, or the next person to read it is
     // reading a different import than the one that happened.
     await writeFile(out, `${JSON.stringify(census, null, 2)}\n`, "utf8");

package/dist/doctor/default-scheme.js

@@ -0,0 +1,143 @@
+/**
+ * QUAL FACE O PROJETO ABRE - lida da estrutura dele, ou não afirmada.
+ *
+ * O QUE ISTO RESOLVE PARA O CLIENTE: um sistema que abre no escuro parava de ser escuro
+ * ao chegar aqui, porque a esteira tratava "a base da cascata" como se fosse "a face
+ * clara". Ninguém nunca declarou isso; era uma suposição embutida em dois leitores.
+ *
+ * ESTE FATO É SÓ OBSERVAÇÃO. `census.scheme` é a decisão RESOLVIDA daquela execução -
+ * `--scheme`, a resposta de quem estava no terminal, a leitura do agente. Uma decisão
+ * nunca reescreve o que foi observado: se ele digitou `--scheme=dark` num projeto sem
+ * sinal nenhum, o fato continua `unknown` e a execução continua `dark`. Misturar os dois
+ * apagaria a única informação capaz de dizer "este projeto não nos conta qual face abre".
+ *
+ * A EVIDÊNCIA É ESTRUTURAL, e por decisão do dono (28/08) nunca:
+ * luminância das cores, nome de token, nome de repositório, presença isolada de `.dark`
+ * ou `.light`, convenção de um framework específico.
+ *
+ * Sem sinal, `unknown`. Um palpite aqui vale menos que a pergunta que a esteira já sabe
+ * fazer.
+ */
+import { scopedBlocks } from "./scheme-scope.js";
+/** `color-scheme: dark` - e as formas que não respondem nada. */
+const COLOR_SCHEME = /^color-scheme$/i;
+function schemeWord(value) {
+    const words = value.toLowerCase().trim().split(/\s+/).filter(Boolean);
+    // `light dark`, `normal`, `only light` declaram capacidade ou neutralidade, não
+    // polaridade. Só uma palavra sozinha é uma afirmação.
+    if (words.length !== 1)
+        return null;
+    return words[0] === "dark" || words[0] === "light" ? words[0] : null;
+}
+/**
+ * O sinal mais forte, e o único que vive dentro da própria folha: um `color-scheme`
+ * numa raiz SEM escopo de esquema.
+ *
+ * A restrição do escopo é o que faz a regra valer em qualquer projeto. Medido em 28/08:
+ * o `frontend-hub` declara `[data-theme='dark'] { color-scheme: light }` dentro de um
+ * `.module.scss` de componente - contraditório e local. Ele é excluído duas vezes, por
+ * ter escopo de esquema e por não ser de documento, então um componente nunca decide a
+ * polaridade do projeto.
+ *
+ * E `html[data-theme="light"] { color-scheme: light }` é CORROBORAÇÃO do override, não
+ * voto para o padrão: o bloco já diz de qual face ele é.
+ */
+function fromColorScheme(sheets) {
+    const votes = [];
+    for (const sheet of sheets) {
+        for (const block of scopedBlocks(sheet.css)) {
+            if (block.scope !== "base")
+                continue;
+            for (const d of block.declarations) {
+                if (!COLOR_SCHEME.test(d.name))
+                    continue;
+                const word = schemeWord(d.value);
+                if (!word)
+                    continue;
+                votes.push({
+                    scheme: word,
+                    file: sheet.file,
+                    selector: block.stack[block.stack.length - 1] ?? "",
+                });
+            }
+        }
+    }
+    if (votes.length === 0)
+        return null;
+    const distinct = new Set(votes.map((v) => v.scheme));
+    if (distinct.size > 1)
+        return { scheme: "unknown", source: "conflicting" };
+    return {
+        scheme: votes[0].scheme,
+        source: "root-color-scheme",
+        evidence: { file: votes[0].file, selector: votes[0].selector },
+    };
+}
+/**
+ * A polaridade padrão do projeto, ou `unknown`.
+ *
+ * A ESCADA, e a primeira que responde vence:
+ *
+ *   1  `color-scheme` numa raiz sem escopo de esquema  - está na folha dele
+ *   2  `defaultTheme="dark"` no provider               - o próprio provider diz
+ *   3  `<html data-theme="dark">` num layout raiz      - o portador, verbatim
+ *   4  nada disso                                       unknown
+ *
+ * `color-scheme` vem primeiro porque é a declaração do PADRÃO WEB para exatamente esta
+ * pergunta, e porque ela mora na folha que o escopo medido já carrega - os sinais 2 e 3
+ * vêm de um app que um `--scope packages/ui` pode não estar lendo. Medido no
+ * FlowSanctuary: os três campos de tema vêm `null`, e só o sinal 1 responde.
+ *
+ * `nota`: `scopedBlocks` é chamado de novo aqui em vez de receber os blocos prontos. É
+ * uma varredura de string sobre folhas que já estão em memória, e o custo de passá-la
+ * adiante seria acoplar esta pergunta ao laço do import.
+ */
+export function defaultSchemeOf(input) {
+    /**
+     * A PORTA FECHADA EM VEZ DE VIGIADA: nenhuma saída daqui pode dizer ao mesmo tempo "não
+     * sei" e "achei na folha dele". Uma edição futura que produzisse esse par cairia no
+     * estado honesto em vez de viajar até a plataforma como um fato que não se sustenta.
+     */
+    const fact = pickDefaultScheme(input);
+    return schemeFactIsCoherent({
+        defaultScheme: fact.scheme,
+        defaultSchemeSource: fact.source,
+    })
+        ? fact
+        : { scheme: "unknown", source: "absent" };
+}
+function pickDefaultScheme(input) {
+    const declared = fromColorScheme(input.sheets);
+    if (declared)
+        return declared;
+    const provider = input.signals?.defaultTheme?.trim().toLowerCase();
+    if (provider === "dark" || provider === "light") {
+        return { scheme: provider, source: "theme-default" };
+    }
+    /**
+     * O `<html>` carrega o tema escrito à mão. Casado contra o atributo que o PRÓPRIO
+     * projeto usa: um `class="dark"` e um `data-theme="dark"` são o mesmo fato em
+     * projetos diferentes, e cravar um dos dois seria escolher por convenção.
+     */
+    const attribute = input.signals?.attribute?.trim();
+    for (const carried of input.signals?.htmlCarries ?? []) {
+        const key = attribute && attribute !== "class" ? attribute : "class";
+        const m = new RegExp(`${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*=\\s*["'\`{]*([^"'\`}]*)`, "i").exec(carried);
+        const word = m?.[1] && schemeWord(m[1].split(/\s+/).pop() ?? "");
+        if (word)
+            return { scheme: word, source: "html-carrier" };
+    }
+    return { scheme: "unknown", source: "absent" };
+}
+/**
+ * A INVARIANTE DO CONTRATO, escrita uma vez e usada pelos dois lados.
+ *
+ * `unknown` se e somente se a fonte é `conflicting` ou `absent`. Sem isto, um `unknown`
+ * com fonte `root-color-scheme` seria representável - e ele diria ao mesmo tempo "não sei"
+ * e "achei na folha dele".
+ */
+export function schemeFactIsCoherent(fact) {
+    const undetermined = fact.defaultSchemeSource === "conflicting" ||
+        fact.defaultSchemeSource === "absent";
+    return (fact.defaultScheme === "unknown") === undetermined;
+}

package/dist/doctor/scheme-blocks.js

@@ -1,77 +1,54 @@
 /**
- * TOKENS BY SCHEME - which declarations belong to the base scheme and which to
- * the dark one.
+ * TOKENS POR ESQUEMA - de qual face é cada declaração que o projeto escreveu.
  *
- * The harvest used to flatten every stylesheet into one `name → value` map with
- * the first declaration winning, which silently discards the second half of
- * every themed project. A shadcn codebase declares its whole vocabulary twice -
- * `:root` and `.dark` - so half of it was being thrown away before anything
- * could read it.
+ * A colheita achatava toda folha num único mapa `nome → valor` com a primeira declaração
+ * vencendo, o que descarta em silêncio a segunda metade de todo projeto com tema: um
+ * codebase shadcn declara o vocabulário inteiro duas vezes - `:root` e `.dark` - e metade
+ * era jogada fora antes de qualquer um ler.
  *
- * Honest scope note (measured 30/07 on the project this was written for): its
- * own dark block holds exactly two tokens, because its dark mode lives in a
- * Tailwind `dark:` variant applied in components rather than in token values.
- * This reader finds what a project declares; it cannot find what a project
- * expresses in class names.
+ * O QUE MUDOU EM 28/08, e é a razão de existirem três baldes em vez de dois: `base` e
+ * `alt` misturavam duas perguntas. `:root` responde ONDE na cascata; `.dark` responde DE
+ * QUAL ESQUEMA. Tratar a primeira como se fosse a segunda embute "a base é a face clara",
+ * que nenhum projeto declara - e um projeto que abre no escuro recebia a face clara
+ * pintada com os valores do escuro. Medido no FlowSanctuary: 17 declarações claras, 0
+ * chegando, `canvas` e `foreground` no mesmo hex.
  *
- * Deliberately a scanner, not a CSS parser. It tracks brace depth and the
- * selector that opened each level, which is all that is needed to answer "which
- * scope is this declaration in" - and it survives the nesting Tailwind v4
- * produces (`@layer base { :root { … } }`) without a dependency.
- */
-/** A scope that means "this is the dark theme". Covers the spellings that
- *  actually appear: shadcn's `.dark`, the data-attribute forms, and the
- *  `:where(...)` wrapper Tailwind v4 emits for a custom variant.
+ * Agora `base` é posição, `light` e `dark` são esquema, e qual face abre por padrão é
+ * outro fato inteiro - ver `default-scheme.ts`.
  *
- *  The closing `]` is load-bearing and a spec caught it missing:
- *  `[data-theme="darkroom"]` was being read as the dark theme. */
-const DARK_SCOPE = /(^|[\s,(])(\.dark\b|\.theme-dark\b|\[data-(?:theme|scheme|mode)\s*[~^|*$]?=\s*["']?dark["']?\s*\])/i;
-/** A scope that carries a document's own tokens, as opposed to a component's. */
-const ROOT_SCOPE = /(^|[\s,(])(:root\b|html\b|body\b)/i;
-const DECL = /(--[a-z0-9-]+)\s*:\s*([^;]+)/gi;
+ * Nota de escopo honesta (medida em 30/07 no projeto para o qual isto foi escrito): o
+ * bloco escuro dele tem exatamente dois tokens, porque o modo escuro dele vive numa
+ * variante `dark:` do Tailwind aplicada nos componentes, não em valor de token. Este
+ * leitor acha o que um projeto DECLARA; não acha o que ele expressa em nome de classe.
+ */
+import { scopedBlocks } from "./scheme-scope.js";
+/**
+ * A máquina do Tailwind v4, que não é vocabulário de ninguém - ela é emitida em `@theme`
+ * junto com o que a pessoa escreveu.
+ */
+const MACHINERY = /^--tw-/;
 export function parseSchemeBlocks(css) {
     const base = new Map();
-    const alt = new Map();
-    const clean = css.replace(/\/\*[\s\S]*?\*\//g, "");
-    // The selector (or at-rule) that opened each open brace, innermost last.
-    const stack = [];
-    let prelude = "";
-    for (let i = 0; i < clean.length; i++) {
-        const ch = clean[i];
-        if (ch === "{") {
-            stack.push(prelude.trim());
-            prelude = "";
-            continue;
-        }
-        if (ch === "}") {
-            stack.pop();
-            prelude = "";
+    const light = new Map();
+    const dark = new Map();
+    const into = { base, light, dark };
+    for (const block of scopedBlocks(css)) {
+        if (block.scope === "other")
             continue;
-        }
-        if (ch === ";") {
-            // A declaration ends here: everything since the last delimiter is it.
-            const text = prelude;
-            prelude = "";
-            if (stack.length === 0)
-                continue;
-            const dark = stack.some((s) => DARK_SCOPE.test(s));
-            const rooted = stack.some((s) => ROOT_SCOPE.test(s) || /^@theme\b/i.test(s));
-            if (!dark && !rooted)
+        const bucket = into[block.scope];
+        for (const d of block.declarations) {
+            // Só vocabulário: `scopedBlocks` também colhe propriedade padrão, porque a
+            // detecção de polaridade precisa do `color-scheme` com a MESMA classificação
+            // de escopo. Aqui só interessa o que o projeto NOMEIA.
+            if (!d.name.startsWith("--") || MACHINERY.test(d.name))
                 continue;
-            DECL.lastIndex = 0;
-            const m = DECL.exec(text);
-            if (!m)
-                continue;
-            const name = m[1].toLowerCase();
-            const value = m[2].trim();
-            const into = dark ? alt : base;
-            // First declaration wins, the same rule the flat harvest used - a later
-            // sheet overriding an earlier one is a cascade question this cannot see.
-            if (!into.has(name))
-                into.set(name, value);
-            continue;
+            // A primeira declaração vence, a mesma regra que a colheita achatada usava - uma
+            // folha posterior sobrescrevendo uma anterior é uma questão de cascata que este
+            // scanner não vê. Vale DENTRO de um balde; entre baldes quem resolve é a
+            // plataforma, e ali o override vence a base.
+            if (!bucket.has(d.name))
+                bucket.set(d.name, d.value);
         }
-        prelude += ch;
     }
-    return { base, alt };
+    return { base, light, dark };
 }

package/dist/doctor/scheme-scope.js

@@ -0,0 +1,272 @@
+/**
+ * ONDE UMA DECLARAÇÃO VIVE - e o cliente para de receber a face errada do próprio sistema.
+ *
+ * O QUE ELE VIVIA: um projeto que abre no escuro e declara o claro à mão em
+ * `[data-theme="light"]` recebia a face clara pintada com os valores do escuro - fundo e
+ * texto no mesmo hex, contraste 1,00:1. Medido no FlowSanctuary em 28/08: 17 declarações
+ * claras, 0 chegando.
+ *
+ * A CAUSA ERAM DUAS COISAS MISTURADAS num só juízo. `:root` responde "onde na cascata",
+ * `.dark` responde "de qual esquema" - e os dois leitores de token tratavam a primeira
+ * pergunta como se respondesse a segunda. Daí "base significa claro", que nenhum projeto
+ * jamais declarou.
+ *
+ * Aqui elas se separam. Este módulo responde SÓ a pergunta do escopo, e responde a mesma
+ * coisa para os dois leitores - `parseRootTokens` e `parseSchemeBlocks` tinham regex
+ * próprias e DISCORDAVAM: `html.dark` era escuro para um e raiz para o outro.
+ *
+ * A polaridade padrão do projeto - qual face abre - é outro fato, e mora em
+ * `defaultSchemeOf`. Um seletor não sabe qual face é a padrão; só sabe de qual face ele é.
+ */
+/**
+ * O MARCADOR DE ESQUEMA, nas grafias que aparecem de verdade.
+ *
+ * O `]` de fechamento carrega peso e um spec já pegou ele faltando: sem ele,
+ * `[data-theme="darkroom"]` era lido como o tema escuro.
+ *
+ * Sem fronteira à esquerda de propósito - `html.dark` é escuro, e exigir espaço antes do
+ * ponto fazia essa forma (a que o Tailwind com `darkMode: "class"` produz) cair no
+ * repouso. A fronteira que importa é a da DIREITA, e ela está no `\b` / no `]`.
+ */
+const SCHEME_MARK = /(\.dark\b|\.light\b|\.theme-dark\b|\.theme-light\b|\[data-(?:theme|scheme|mode)\s*[~^|*$]?=\s*["']?(?:dark|light)["']?\s*\])/gi;
+const DARK_MARK = /(\.dark\b|\.theme-dark\b|\[data-(?:theme|scheme|mode)\s*[~^|*$]?=\s*["']?dark["']?\s*\])/i;
+const LIGHT_MARK = /(\.light\b|\.theme-light\b|\[data-(?:theme|scheme|mode)\s*[~^|*$]?=\s*["']?light["']?\s*\])/i;
+/** As raízes do documento - os lugares onde alguém escreve o vocabulário do projeto. */
+const ROOT_MARK = /(^|[\s>+~,])(:root|html|:host|body)\b/gi;
+/** `@theme` do Tailwind v4 é raiz por definição: é onde a paleta inteira é declarada. */
+const AT_THEME = /^@theme\b/i;
+/**
+ * A OUTRA GRAFIA DE "ESTA DECLARAÇÃO É DAQUELE ESQUEMA" - a que o CSS oferece nativamente.
+ *
+ * `@media (prefers-color-scheme: dark) { :root { … } }` diz exatamente o mesmo que
+ * `.dark { … }`, e sem esta linha ela cairia em `base` - o mesmo defeito de sempre com
+ * outra sintaxe. Zero ocorrências nas quatro populações medidas em 28/08; entra porque
+ * ignorá-la APAGARIA declarações que hoje chegam, não para cobrir um caso hipotético.
+ */
+const PREFERS = /prefers-color-scheme\s*:\s*(dark|light)/i;
+/**
+ * AT-RULES QUE SÓ EMBRULHAM - elas não são seletor de ninguém.
+ *
+ * `@layer base { :root { … } }` é a forma que o Tailwind v4 emite, e tratá-la como um
+ * nível da pilha fazia o `:root` de dentro virar `other`. `@media (min-width: …)` idem.
+ */
+const TRANSPARENT_AT = /^@(layer|supports|container|scope|media)\b/i;
+/**
+ * O seletor fala do DOCUMENTO INTEIRO, ou de um pedaço dele?
+ *
+ * A régua: tire os marcadores de esquema e as raízes. Se sobrou seletor, sobrou
+ * componente - e uma declaração de componente não é foundation.
+ *
+ * `html.dark .holo-card` vira `html .holo-card` vira ` .holo-card` - sobrou, então é
+ * local. `:root[data-theme="light"]` vira `:root` vira vazio - documento.
+ *
+ * Medido nas quatro populações em 28/08: a régua tira 2 declarações de 1128, e as 2 são
+ * o defeito (`--holo-inner-bg`, uma variável da `@utility holo-card` do codelevel).
+ */
+function isDocumentScoped(selector) {
+    if (AT_THEME.test(selector.trim()))
+        return true;
+    // `:where(…)` e `:is(…)` são pura AGRUPAÇÃO - o que importa é o que está dentro.
+    // Sem desembrulhar, `:where([data-theme=dark], [data-theme=dark] *)` do repositório
+    // real virava local, e com ele os dois tokens que o comentário de `tokens.ts` cita
+    // por nome (`--loader-color`, `--color-track`).
+    const flat = selector.replace(/:(?:where|is)\s*\(/gi, "").replace(/\)/g, "");
+    return flat.split(",").every((one) => {
+        SCHEME_MARK.lastIndex = 0;
+        const scoped = SCHEME_MARK.test(one);
+        ROOT_MARK.lastIndex = 0;
+        const rooted = ROOT_MARK.test(one);
+        let bare = one.replace(SCHEME_MARK, "").replace(ROOT_MARK, "$1");
+        // `[data-theme=dark] *` é a mesma declaração alcançando tudo que herda dela - a
+        // forma que o Tailwind v4 emite. O `*` só some quando o pedaço JÁ é de esquema ou
+        // de raiz; `*, ::before, ::after` sozinho continua sendo o `--tw-*` do v3, que
+        // nunca foi vocabulário de ninguém.
+        if (scoped || rooted)
+            bare = bare.replace(/\*/g, "");
+        return bare.replace(/[\s>+~]/g, "").trim() === "";
+    });
+}
+/**
+ * De qual face é esta pilha de seletores - do mais externo ao mais interno.
+ *
+ * PILHA e não seletor solto porque o aninhamento decide: `@layer base { html { … } }` e
+ * `[data-theme="light"] { .x { … } }` só se respondem olhando os dois níveis.
+ *
+ * A ORDEM DA DECISÃO É LEI: esquema explícito vence posição. Um bloco que diz `light`
+ * é claro mesmo escrito em cima de `:root`, e é justamente essa inversão que fazia 14
+ * declarações claras da nossa própria folha entrarem como base.
+ *
+ * Claro E escuro na mesma pilha é contradição aninhada, e contradição não se adivinha:
+ * sai `other`.
+ */
+export function schemeScopeOf(stack) {
+    const all = stack.map((s) => s.trim()).filter((s) => s !== "");
+    if (all.length === 0)
+        return "other";
+    /** O que o `@media (prefers-color-scheme: …)` da pilha diz, quando ela tem um. */
+    const prefers = all
+        .filter((s) => TRANSPARENT_AT.test(s))
+        .map((s) => PREFERS.exec(s)?.[1]?.toLowerCase())
+        .find((s) => s != null);
+    /** Os embrulhos saem: eles não selecionam nada, então não classificam nada. */
+    const real = all.filter((s) => !TRANSPARENT_AT.test(s));
+    if (real.length === 0)
+        return "other";
+    const dark = prefers === "dark" || real.some((s) => DARK_MARK.test(s));
+    const light = prefers === "light" || real.some((s) => LIGHT_MARK.test(s));
+    if (dark && light)
+        return "other";
+    // Toda parte da pilha precisa ser de documento. Um `html { }` que contém `.card { }`
+    // fala do card, e o nível interno é quem denuncia isso.
+    if (!real.every((s) => isDocumentScoped(s)))
+        return "other";
+    if (dark)
+        return "dark";
+    if (light)
+        return "light";
+    // Sem marcador de esquema, só é base quem é raiz de verdade. `isDocumentScoped` já
+    // aprovou a pilha inteira, então basta ter uma raiz nomeada em algum nível - o
+    // `@layer base { :root { … } }` que o Tailwind v4 emite passa por aqui.
+    const rooted = real.some((s) => {
+        if (AT_THEME.test(s.trim()))
+            return true;
+        ROOT_MARK.lastIndex = 0;
+        return ROOT_MARK.test(s);
+    });
+    return rooted ? "base" : "other";
+}
+/**
+ * A VARREDURA ÚNICA - os dois leitores de token passam por aqui.
+ *
+ * Deliberadamente um scanner, não um parser de CSS. O que ele precisa responder é uma
+ * pergunta só - "de qual escopo é esta declaração" -, e para isso bastam a profundidade
+ * de chave e o seletor que abriu cada nível. É o que o faz sobreviver ao aninhamento que
+ * o Tailwind v4 produz sem uma dependência (o CLI é publicado standalone e tem zero deps).
+ *
+ * Existe porque `parseRootTokens` e `parseSchemeBlocks` tinham cada um a sua varredura e a
+ * sua regex de escopo, e DISCORDAVAM: `html.dark` era raiz para um e nada para o outro.
+ * Duas respostas para a mesma pergunta é como a face errada chega na tela do cliente.
+ *
+ * MAS UM SCANNER DE CHAVE INGÊNUO LÊ CONTEÚDO COMO SE FOSSE ESTRUTURA, e isso não é
+ * hipótese: medido em 29/08 contra a versão de 28/08, 7 de 12 formas de CSS VÁLIDO
+ * quebravam. `content: "}"` fechava o bloco e a declaração seguinte sumia; `--x: "a;b"`
+ * chegava truncado em `"a`; um `url("data:image/svg+xml;base64,…")` perdia o payload
+ * inteiro; e a remoção de comentário feita por regex sobre o arquivo inteiro comia o
+ * miolo de qualquer string que contivesse `/*`.
+ *
+ * A PROPRIEDADE, e ela vale para qualquer folha: delimitador que pertence ao CONTEÚDO
+ * léxico de um valor não pode mexer na pilha estrutural. Por isso o laço abaixo tem
+ * estado - código, aspas simples, aspas duplas, escape, comentário e profundidade de
+ * parênteses -, e `{`, `}`, `;` e `:` só são estruturais no primeiro deles.
+ */
+export function scopedBlocks(css) {
+    const out = [];
+    const stack = [];
+    /** Índice em `out` do bloco de cada nível aberto, para as declarações irem no lugar. */
+    const at = [];
+    /** O texto desde o último delimitador - vira seletor num `{` e declaração num `;`/`}`. */
+    let prelude = "";
+    /** Onde, dentro de `prelude`, está o `:` que separa nome de valor. -1 = nenhum ainda. */
+    let colon = -1;
+    /** `null` fora de string; a aspa que abriu, dentro dela. */
+    let quote = null;
+    let inComment = false;
+    /**
+     * `url(data:image/svg+xml;base64,…)` sem aspas é CSS válido, e ali o `;` é payload.
+     * Contar parênteses cobre isso e todo `calc()`/`clamp()` de uma vez, sem citar função.
+     */
+    let parens = 0;
+    const flush = (closing) => {
+        const text = prelude;
+        const nameEnd = colon;
+        prelude = "";
+        colon = -1;
+        const here = at[at.length - 1];
+        if (here != null && nameEnd >= 0) {
+            const name = text.slice(0, nameEnd).trim().toLowerCase();
+            const value = text.slice(nameEnd + 1).trim();
+            if (name && value && NAME.test(name)) {
+                out[here].declarations.push({ name, value });
+            }
+        }
+        if (closing) {
+            stack.pop();
+            at.pop();
+        }
+    };
+    for (let i = 0; i < css.length; i++) {
+        const ch = css[i];
+        if (inComment) {
+            if (ch === "*" && css[i + 1] === "/") {
+                inComment = false;
+                i += 1;
+            }
+            continue;
+        }
+        if (quote) {
+            // Uma barra invertida consome o próximo caractere, seja ele qual for - inclusive
+            // outra barra e a própria aspa de fechamento.
+            if (ch === "\\") {
+                prelude += ch + (css[i + 1] ?? "");
+                i += 1;
+                continue;
+            }
+            if (ch === quote)
+                quote = null;
+            prelude += ch;
+            continue;
+        }
+        // `/*` só ABRE comentário fora de string - senão `"/* isto não é comentário */"`
+        // perderia o próprio conteúdo.
+        if (ch === "/" && css[i + 1] === "*") {
+            inComment = true;
+            i += 1;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            prelude += ch;
+            continue;
+        }
+        if (ch === "(")
+            parens += 1;
+        else if (ch === ")")
+            parens = Math.max(0, parens - 1);
+        if (parens === 0) {
+            if (ch === "{") {
+                stack.push(prelude.trim());
+                prelude = "";
+                colon = -1;
+                at.push(out.length);
+                out.push({
+                    scope: schemeScopeOf(stack),
+                    stack: [...stack],
+                    declarations: [],
+                });
+                continue;
+            }
+            if (ch === "}" || ch === ";") {
+                // A ÚLTIMA DECLARAÇÃO NÃO PRECISA DE `;`, e `:root { --x: red }` é CSS válido -
+                // por isso o `}` também fecha uma declaração antes de fechar o bloco.
+                flush(ch === "}");
+                continue;
+            }
+            // O PRIMEIRO `:` do prelúdio separa nome de valor. Só o primeiro: um
+            // `background: url(a:b)` já está protegido pelos parênteses, e `a:hover { }`
+            // nunca chega ao `flush` porque termina em `{`.
+            if (ch === ":" && colon < 0)
+                colon = prelude.length;
+        }
+        prelude += ch;
+    }
+    return out;
+}
+/**
+ * Um nome de propriedade, custom ou padrão. `--my_var` é legal, então `_` entra.
+ *
+ * Propriedade padrão também passa: `color-scheme: dark` numa raiz é a evidência
+ * estrutural de qual face o projeto abre, e ela precisa da MESMA classificação de escopo
+ * que os tokens - ver `default-scheme.ts`. Quem só quer vocabulário filtra por `--` no
+ * consumo.
+ */
+const NAME = /^(--[a-z0-9_-]+|-{0,2}[a-z][a-z0-9-]*)$/i;

package/dist/doctor/tokens.js

@@ -11,17 +11,8 @@
  * Pure and dependency-free on purpose: every function here takes text and
  * returns data, so the whole diagnosis is testable without a filesystem.
  */
-/**
- * Where the vocabulary being measured against came from.
- *
- * `"installed"` is a system we wrote. `"yours"` is the project's OWN custom
- * properties, harvested from its stylesheets - the case that matters most,
- * because the people who feel this problem hardest already have a design
- * system and had no reason to adopt ours before seeing a number.
- */
-/** `"adopted"` is theirs too, but described by `adopt` and therefore NAMED -
- *  it must not be offered a system to install, having just adopted one. */
 import { DEFAULT_ROOT_PX } from "./root-size.js";
+import { parseSchemeBlocks } from "./scheme-blocks.js";
 export const EMPTY_TABLE = {
     source: null,
     name: null,
@@ -307,94 +298,19 @@ export function parseDeclaredNames(css) {
  * (declared on `*, ::before, ::after`) and Radix's `--radix-*` (set on the
  * component) without naming a single vendor.
  *
- * The flat brace regex is deliberate and handles one level of nesting for
- * free: against `@media x { :root { ... } }` the outer selector fails to match
- * because its body contains a brace, so the scan moves on and finds the inner
- * block on its own.
+ * A CLASSIFICAÇÃO É COMPARTILHADA desde 28/08 - ver `scheme-scope.ts`. Este leitor tinha
+ * regex própria de raiz e discordava do leitor de esquemas: `html.dark .holo-card` era
+ * raiz aqui e nada lá, então uma variável LOCAL de um componente do codelevel
+ * (`--holo-inner-bg`, declarada dentro de `@utility holo-card`) subia para cá como token
+ * global do sistema - e subia com o valor do tema ESCURO na face que a plataforma lê como
+ * padrão. Duas respostas para a mesma pergunta é como a face errada chega na tela.
+ *
+ * Aqui ficam só as declarações de escopo `base`: raiz de documento, sem escopo de esquema.
+ * O que um projeto declara explicitamente como claro ou escuro viaja em
+ * `Census.declaredSchemes`, com a face nomeada em vez de achatada.
  */
 export function parseRootTokens(css) {
-    const out = new Map();
-    const isRoot = (sel) => /^@theme\b/i.test(sel) || /(^|[\s,>+~])(:root|html|:host)\b/i.test(sel);
-    // Every `<selector> {` in the file. Nested ones show up too and are filtered
-    // by isRoot, so an @keyframes inside @theme is skipped rather than mined.
-    const opens = /([^{}]*)\{/g;
-    let m = opens.exec(css);
-    while (m !== null) {
-        // The capture runs back to the previous brace, so it carries imports and
-        // comments with it. The SELECTOR is only what follows the last `;` or
-        // comment - and `@theme` is anchored to the start, so without this it
-        // matched only when the block happened to be the first thing in the file.
-        // Every fixture had it first. This repo's own globals.css does not, and
-        // reported 0 of its 48 tokens (27/07).
-        const sel = (m[1]
-            .replace(/\/\*[\s\S]*?\*\//g, "")
-            .split(";")
-            .pop() ?? "").trim();
-        if (!isRoot(sel)) {
-            m = opens.exec(css);
-            continue;
-        }
-        // Walk to the MATCHING close, counting depth. The flat regex this replaces
-        // required a body with no braces at all, so it silently skipped any
-        // `@theme` containing `@keyframes` - which is the documented Tailwind v4
-        // layout. Measured against this repo's own globals.css: 48 tokens present,
-        // 2 found, and the 2 came from unrelated test fixtures (27/07).
-        const start = m.index + m[0].length;
-        let depth = 1;
-        let i = start;
-        while (i < css.length && depth > 0) {
-            const c = css[i];
-            if (c === "{")
-                depth++;
-            else if (c === "}")
-                depth--;
-            i++;
-        }
-        // Only declarations that are DIRECT children count. A custom property
-        // inside a keyframe step is animation state, not a design token.
-        let flat = "";
-        let d = 0;
-        for (let j = start; j < i - 1; j++) {
-            const c = css[j];
-            if (c === "{")
-                d++;
-            else if (c === "}")
-                d--;
-            else if (d === 0)
-                flat += c;
-        }
-        for (const t of flat.matchAll(/(--[a-z0-9_-]+)\s*:\s*([^;}]+)/gi)) {
-            const name = t[1].toLowerCase();
-            // Belt and braces: v4 emits some `--tw-*` bookkeeping into @theme, and
-            // it is machinery, not somebody's design vocabulary.
-            if (name.startsWith("--tw-"))
-                continue;
-            const value = t[2].trim();
-            if (!value)
-                continue;
-            /**
-             * O ALIAS FICA, E É RESOLVIDO DEPOIS - antes ele era descartado aqui, e era justamente o
-             * token mais cheio de significado que sumia.
-             *
-             * `--loader-color: var(--color-ocean-500)` não é ruído: é um PAPEL, a frase que diz "esta
-             * função é esta cor". Descartá-lo deixava só as primitivas - a paleta sem o vocabulário.
-             *
-             * A assimetria que isso produzia, medida no repo do dono em 11/08: `declaredAlt` sai de
-             * `parseSchemeBlocks`, que não tem este filtro, então o valor ESCURO de `--loader-color` e
-             * `--color-track` viajava e o CLARO não. Dois tokens presentes só no dark, e o
-             * `CircularProgress.tsx:100` lendo `var(--color-track, …)` sem que ninguém soubesse o que
-             * `--color-track` é.
-             *
-             * Resolver é o mesmo que o caminho `installed` já faz com `resolveAliases`: a máquina existia
-             * e só não era usada aqui.
-             */
-            if (!out.has(name))
-                out.set(name, value);
-        }
-        opens.lastIndex = i;
-        m = opens.exec(css);
-    }
-    return out;
+    return parseSchemeBlocks(css).base;
 }
 export function buildTable(input) {
     const source = input.source ?? "installed";

package/dist/install-marks.js

@@ -367,7 +367,7 @@ export const CHECKER_SINCE = "0.16.308";
  * nunca era alcançado. Medido: 1134 componentes, 77 mudaram, e a receita que o cliente recebe muda
  * com eles. Uma medição anterior não produz o conserto, então a marca sobe.
  */
-export const READER_SINCE = "0.16.329";
+export const READER_SINCE = "0.16.330";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/dist/merge-census.js

@@ -89,6 +89,23 @@ export function mergeCensus(list) {
     ];
     const declared = { ...asRecord(first.declared) };
     const declaredAlt = { ...asRecord(first.declaredAlt) };
+    /**
+     * OS TRÊS BALDES DE ESQUEMA, escopo a escopo - ver `Census.declaredSchemes`.
+     *
+     * Mesmo desempate de `declared`: o primeiro escopo vence e a perda entra em `conflicts`,
+     * porque dois pacotes que declaram o mesmo nome é um achado, não um detalhe.
+     *
+     * A POLARIDADE NÃO SE SOMA. Dois escopos que observam faces padrão diferentes não têm
+     * média: viram `conflicting`, que é a verdade. Um escopo que não observou nada não vota -
+     * senão o silêncio de um pacote apagaria a evidência do outro.
+     */
+    const firstSchemes = first.declaredSchemes;
+    const schemeBuckets = {
+        base: { ...asRecord(firstSchemes?.base) },
+        light: { ...asRecord(firstSchemes?.light) },
+        dark: { ...asRecord(firstSchemes?.dark) },
+    };
+    const polarities = firstSchemes ? [firstSchemes] : [];
     const keyframes = { ...(first.keyframes ?? {}) };
     const looks = { ...(first.looks ?? {}) };
     let observed = first.observed.map((v) => ({ ...v }));
@@ -111,6 +128,13 @@ export function mergeCensus(list) {
         const firstName = nameOf(first, 0);
         mergeDeclared(declared, asRecord(c.declared), firstName, scopeName, conflicts);
         mergeDeclared(declaredAlt, asRecord(c.declaredAlt), firstName, scopeName, conflicts);
+        const theirSchemes = c.declaredSchemes;
+        if (theirSchemes) {
+            polarities.push(theirSchemes);
+            for (const face of ["base", "light", "dark"]) {
+                mergeDeclared(schemeBuckets[face], asRecord(theirSchemes[face]), firstName, scopeName, conflicts);
+            }
+        }
         /**
          * O COMPONENTE QUE OS DOIS DEFINEM fica com a receita do primeiro escopo, e
          * o descarte entra em `collisions` - a mesma lista que `name-claim.ts`
@@ -197,6 +221,23 @@ export function mergeCensus(list) {
     };
     if (Object.keys(declaredAlt).length > 0)
         out.declaredAlt = declaredAlt;
+    if (polarities.length > 0) {
+        const observed = polarities.filter((p) => p.defaultScheme !== "unknown");
+        const distinct = new Set(observed.map((p) => p.defaultScheme));
+        const winner = distinct.size === 1 ? observed[0] : null;
+        out.declaredSchemes = {
+            ...schemeBuckets,
+            defaultScheme: winner ? winner.defaultScheme : "unknown",
+            defaultSchemeSource: winner
+                ? winner.defaultSchemeSource
+                : distinct.size > 1
+                    ? "conflicting"
+                    : "absent",
+            ...(winner?.defaultSchemeEvidence
+                ? { defaultSchemeEvidence: winner.defaultSchemeEvidence }
+                : {}),
+        };
+    }
     if (Object.keys(keyframes).length > 0)
         out.keyframes = keyframes;
     if (Object.keys(looks).length > 0)

package/package.json

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