synthesisui 0.16.399 → 0.16.401

package/dist/absorb-plan.js

@@ -1,5 +1,6 @@
 import { deltaE, JND } from "./doctor/color-distance.js";
 import { familySays, nearestToken, normalizeValue, } from "./doctor/tokens.js";
+import { proposeFromTheirScale, tooCloseToPropose } from "./proposed-name.js";
 /** Onde cada tipo de valor mora na fundação. `color` é o único com dois segmentos. */
 const HOME = {
     color: "color",
@@ -180,7 +181,26 @@ export function absorbPlan(d, theirs, have, cap = 40) {
         const value = normalizeValue(r.literal, theirs.rootPx);
         const theirName = nameOf(r.kind, theirs.byValue.get(value)) ??
             nameOf(r.kind, theirs.compiledAway.get(value)?.map((c) => c.name));
-        const path = pathFor(r.kind, theirName);
+        /**
+         * A LISTA NÃO CHEGA EM BRANCO - e é o que faz o vocabulário dele CRESCER.
+         *
+         * Especificado em 07/09 por entrevista (`steps/02-jornada-projeto-novo.md`): a plataforma
+         * PROPÕE, ele aprova ou edita, e nada entra sem o aval dele. Sem proposta, cada valor novo custa
+         * um batismo manual - e num repositório com 553 valores distintos ninguém batiza 553 vezes. O
+         * vocabulário para de crescer e o próximo componente nasce com outro literal, que é o oposto do
+         * que a plataforma existe para fazer.
+         *
+         * A ORDEM É A DE SEMPRE: o nome que ele JÁ deu vence. Só onde ninguém nomeia é que a derivação
+         * entra - e ela devolve `null` na dúvida (ver `proposed-name.ts`).
+         */
+        /**
+         * UMA FONTE POR ENQUANTO - a escala dele. A segunda está especificada e NÃO entrou, e o motivo
+         * está medido: ver `proposed-name.ts`, no fim.
+         */
+        const proposal = theirName || tooCloseToPropose(r.literal, theirs)
+            ? null
+            : proposeFromTheirScale(r.literal, theirs);
+        const path = pathFor(r.kind, theirName) || proposal?.path || "";
         /** "≈ perto de um token seu" só interessa a quem não tem um EXATO - com o nome na mão, a dica
          *  vira ruído, e no arquivo de proposta ela vira uma segunda opção que não é opção. */
         const near = theirName ? undefined : nearestOwn(theirs, r.literal, r.kind);
@@ -194,6 +214,8 @@ export function absorbPlan(d, theirs, have, cap = 40) {
             count: r.count,
             path,
             ...(theirName ? { theirName: clean(theirName) } : {}),
+            /** A PROCEDÊNCIA VIAJA COM A PROPOSTA - ele julga pela origem, nunca pela palavra. */
+            ...(proposal ? { proposed: proposal.because } : {}),
             ...(near ? { near } : {}),
         });
     }
@@ -213,7 +235,17 @@ export const needingName = (plan) => plan.entries.filter((e) => !e.path);
  * nada.
  */
 export function describeAbsorb(plan) {
-    const ready = plan.entries.filter((e) => e.path);
+    /**
+     * O QUE ELE JÁ NOMEIA E O QUE A PLATAFORMA PROPÔS SÃO DUAS LISTAS - e juntá-las é dizer que ele
+     * nomeou o que ele não nomeou.
+     *
+     * A primeira versão da proposta caiu direto em `ready`, e a linha de cima passou a dizer
+     * *"1 of 1 values already have a name in YOUR vocabulary"* sobre um nome que a PLATAFORMA acabou
+     * de derivar. É a mesma família de defeito que o dia inteiro de 07/09 consertou: uma frase que
+     * afirma sobre o repositório dele algo que veio da nossa dedução.
+     */
+    const ready = plan.entries.filter((e) => e.path && !e.proposed);
+    const proposed = plan.entries.filter((e) => e.proposed);
     const pending = needingName(plan);
     const lines = [];
     /**
@@ -245,6 +277,15 @@ export function describeAbsorb(plan) {
         lines.push(`  ${e.value.padEnd(24)} ${e.path.padEnd(28)} ${e.files} file${e.files === 1 ? "" : "s"}${e.theirName ? ` · your ${e.theirName}` : ""}`);
     if (ready.length > 8)
         lines.push(`  (${ready.length - 8} more)`);
+    if (proposed.length > 0) {
+        if (ready.length > 0)
+            lines.push("");
+        lines.push(`${proposed.length} ${proposed.length === 1 ? "value has" : "values have"} a name PROPOSED from your own scale - approve, edit, or leave ${proposed.length === 1 ? "it" : "them"} hard-coded:`);
+        for (const e of proposed.slice(0, 8))
+            lines.push(`  ${e.value.padEnd(24)} ${e.path.padEnd(28)} ${e.proposed}`);
+        if (proposed.length > 8)
+            lines.push(`  (${proposed.length - 8} more)`);
+    }
     if (pending.length > 0) {
         const close = pending.filter((e) => e.near);
         if (ready.length > 0)
@@ -262,7 +303,12 @@ export function describeAbsorb(plan) {
             ? `${pending.length} nobody names yet. Naming is a design decision, so those wait for a word from you:`
             : `${pending.length} ${everyOneRepeats ? "repeated values" : "values written by hand"}, and none of them has a name yet. Naming is a design decision, so each waits for a word from you:`);
         for (const e of pending.slice(0, 8))
-            lines.push(`  ${e.value.padEnd(24)} ${`<${e.kind}, ${e.files} file${e.files === 1 ? "" : "s"}>`.padEnd(28)} ${e.near ? `≈ your ${e.near.name} (${e.near.away})` : 'path: ""'}`);
+            lines.push(`  ${e.value.padEnd(24)} ${`<${e.kind}, ${e.files} file${e.files === 1 ? "" : "s"}>`.padEnd(28)} ${e.near
+                ? `≈ your ${e.near.name} (${e.near.away})`
+                : /** A proposta chega COM a procedência: ele julga pela origem, não pela palavra. */
+                    e.proposed
+                        ? `${e.path}  ·  ${e.proposed}`
+                        : 'path: ""'}`);
         if (pending.length > 8)
             lines.push(`  (${pending.length - 8} more)`);
         /**

package/dist/commands/component.js

@@ -12,7 +12,7 @@ import { installedThemeCss, whatOnlyTheSheetResolves, } from "../sheet-needed.js
 import { flavourResolver } from "../styles-flavour.js";
 import { inTheirTongue, projectTongue, sumSpoken, } from "../their-tongue.js";
 import { readCensus, unreadComment, unreadForComponent, } from "../unread-for-component.js";
-import { recordWritten } from "../written.js";
+import { editedSinceWritten, readWritten, recordWritten } from "../written.js";
 /**
  * Writes the shared `cn.ts` next to the components, built from THIS project's
  * installed theme.
@@ -233,6 +233,36 @@ export async function component(slug, name, opts) {
          * a mesma pergunta - qual nome este comando vai ocupar - e duas respostas para ela é o defeito.
          */
         const local = localName(res.name, opts.as);
+        /**
+         * A EDIÇÃO DELE NO QUE NÓS ESCREVEMOS - a mesma promessa do `upgrade`, no comando que a violava.
+         *
+         * O QUE ACONTECIA, caminhado em 07/09 com o binário publicado: gerei `btn2`, escrevi uma linha
+         * à mão no topo do arquivo, rodei `component codelevel button --as btn2` de novo - e a linha
+         * sumiu. Sem aviso, sem `--force`, sem uma frase.
+         *
+         * O GUARD QUE EXISTE ACIMA RESPONDE OUTRA PERGUNTA: *"você já tem este componente no seu
+         * repositório?"*, sobre o arquivo de ORIGEM (`recipe.api.file`), de onde o sistema foi
+         * importado. Ele nada sabe sobre o que NÓS escrevemos depois.
+         *
+         * E a informação existia o tempo todo: `recordWritten` grava o fingerprint de cada arquivo a
+         * cada escrita, e o `upgrade` a lê para dizer `kept YOUR file(s)`. Este comando gravava e nunca
+         * lia - a promessa valia num caminho e não no outro, e o outro é o mais percorrido: alguém traz
+         * o componente, ajusta, e roda de novo para pegar uma correção.
+         *
+         * A saída oferecida é a mesma que o `upgrade` oferece, e é a que ele já tem na mão: `--force`.
+         */
+        const slugDir = join(root, "_synthesisui", "ds", slug);
+        const editedHere = await editedSinceWritten((await readWritten(slugDir))[local], join(root, config.componentsDir, local));
+        if (editedHere && editedHere.length > 0 && !opts.force) {
+            console.log(section("You edited this one"));
+            console.log(body(`${editedHere.join(", ")} in ${config.componentsDir}/${local} changed after we wrote ${editedHere.length === 1 ? "it" : "them"} - kept YOUR file(s).`));
+            console.log("");
+            console.log(body("To take the new version anyway:"));
+            console.log(snippet([
+                `npx synthesisui component ${slug} ${res.name}${opts.as ? ` --as ${opts.as}` : ""} --force`,
+            ]));
+            return;
+        }
         const localPascal = local
             .split(/[^a-zA-Z0-9]+/)
             .filter(Boolean)

package/dist/doctor/signals.js

@@ -360,6 +360,26 @@ export function describeSignals(s) {
     else if (t.prefersColorScheme > 0) {
         out.push(`no dark utilities, but ${t.prefersColorScheme} \`prefers-color-scheme\` rule${t.prefersColorScheme === 1 ? "" : "s"} - the second scheme lives in CSS rather than in class names.`);
     }
+    else if (t.library) {
+        /**
+         * NENHUM SINAL DE SEGUNDO ESQUEMA, MAS UM ALTERNADOR INSTALADO - e as duas frases se negavam.
+         *
+         * MEDIDO EM 07/09 no `~/projects/web-subscribe`, caminhando o ATO 3: o relatório imprimia, em
+         * linhas CONSECUTIVAS, *"one scheme, and adding a second is a decision rather than a
+         * discovery"* e *"switched by next-themes"*. Quem lê recebe as duas ao mesmo tempo: não existe
+         * segundo esquema, e existe uma biblioteca que alterna entre esquemas.
+         *
+         * AS DUAS METADES ESTÃO CERTAS separadamente, e é isso que torna a contradição fácil de
+         * escrever: uma conta utilitários `dark:` e regras `prefers-color-scheme` no CSS; a outra lê o
+         * `package.json` e o provider. O que faltava era uma olhar para a outra.
+         *
+         * E O FATO COMBINADO É MAIS ÚTIL QUE QUALQUER UMA DAS DUAS: o alternador está instalado e não
+         * há nada para ele alternar. Isso é uma pendência do projeto dele - e é acionável, ao contrário
+         * de "adicionar um segundo esquema é uma decisão", que ele já tomou quando instalou a
+         * biblioteca.
+         */
+        out.push(`no dark utilities and no \`prefers-color-scheme\` - so the second scheme has nothing to paint yet, even though ${t.library} is installed to switch between them.`);
+    }
     else {
         out.push("no dark utilities and no `prefers-color-scheme` - one scheme, and adding a second is a decision rather than a discovery.");
     }

package/dist/proposed-name.js

@@ -0,0 +1,121 @@
+import { chroma, deltaE, lightness } from "./doctor/color-distance.js";
+import { normalizeValue } from "./doctor/tokens.js";
+function stepsOf(theirs) {
+    const out = [];
+    for (const [name, value] of theirs.byName) {
+        const m = /^--(.*[a-z0-9])-(\d{2,4})$/.exec(name.toLowerCase());
+        if (!m)
+            continue;
+        out.push({ family: m[1], step: Number(m[2]), value });
+    }
+    return out;
+}
+/**
+ * O DEGRAU QUE FALTA NA ESCALA DELE.
+ *
+ * A proposta só existe quando o valor cai ENTRE dois degraus vizinhos da MESMA família dele, e o
+ * degrau proposto é o ponto médio entre os dois. A palavra é inteiramente dele; só a posição é
+ * calculada.
+ *
+ * AS TRÊS PORTAS, e cada uma existe para o lado do "propor de menos":
+ *
+ *     mesma família     dois degraus de famílias diferentes não formam escala - `ink-700` e
+ *                       `brand-900` não têm um meio
+ *     entre eles        um valor fora do intervalo não tem degrau intermediário; extrapolar seria
+ *                       inventar a continuação da escala dele
+ *     lugar livre       se o degrau do meio já existe, o valor não é um degrau novo - é outra
+ *                       decisão que por acaso caiu perto, e propor sobrescreveria a dele
+ */
+export function proposeFromTheirScale(literal, theirs) {
+    const l = lightness(normalizeValue(literal, theirs.rootPx));
+    if (l === null)
+        return null;
+    /**
+     * O CROMA ENTRA JUNTO COM A LUMINOSIDADE, e sem ele a derivação INVENTA.
+     *
+     * MEDIDO NA PRIMEIRA VERSÃO DISTO, em 07/09: um verde (`#0d5c2a`) recebeu `color.ink.800`, porque
+     * a luminosidade dele cai entre dois cinzas dele. Um degrau que falta numa escala está perto dos
+     * vizinhos NA COR, não só no claro-escuro - propor o contrário é dizer que o verde dele é um tom
+     * de cinza.
+     *
+     * O INTERVALO É O DOS PRÓPRIOS VIZINHOS, nunca um limiar escolhido: um cinza tem croma perto de
+     * zero e um verde não, então a porta se fecha sozinha. Numa escala de azul os dois vizinhos têm
+     * croma alto e o degrau novo passa. Sem folga, porque o lado seguro do erro é hard-coded.
+     */
+    const c = chroma(normalizeValue(literal, theirs.rootPx));
+    if (c === null)
+        return null;
+    const steps = stepsOf(theirs)
+        .map((s) => {
+        const v = normalizeValue(s.value, theirs.rootPx);
+        return { ...s, l: lightness(v), c: chroma(v) };
+    })
+        .filter((s) => s.l !== null && s.c !== null);
+    if (steps.length < 2)
+        return null;
+    let best = null;
+    for (const a of steps) {
+        for (const b of steps) {
+            if (a.family !== b.family || a.step >= b.step)
+                continue;
+            /** O valor tem de cair ENTRE os dois - extrapolar seria inventar a continuação da escala. */
+            const lo = Math.min(a.l, b.l);
+            const hi = Math.max(a.l, b.l);
+            if (l <= lo || l >= hi)
+                continue;
+            /** E na COR também: fora do croma dos dois vizinhos, não é um degrau desta escala. */
+            const cLo = Math.min(a.c, b.c);
+            const cHi = Math.max(a.c, b.c);
+            if (c < cLo || c > cHi)
+                continue;
+            const mid = Math.round((a.step + b.step) / 2 / 50) * 50;
+            if (mid === a.step || mid === b.step)
+                continue;
+            /** O degrau já existe: então este valor não é um degrau que falta, é outra decisão. */
+            if (steps.some((s) => s.family === a.family && s.step === mid))
+                continue;
+            const gap = b.step - a.step;
+            if (!best || gap < best.gap)
+                best = { family: a.family, step: mid, gap };
+        }
+    }
+    if (!best)
+        return null;
+    return {
+        path: `${best.family.replace(/-/g, ".")}.${best.step}`,
+        because: `between your ${best.family}-${best.step - Math.round(best.gap / 2)} and ${best.family}-${best.step + Math.round(best.gap / 2)}`,
+    };
+}
+/**
+ * PERTO DEMAIS DE UM TOKEN DELE NÃO É UM DEGRAU NOVO - é a mesma decisão escrita duas vezes.
+ *
+ * `nearestOwn` já diz isso na proposta do `absorb` (o `≈` que aparece na lista), e propor um nome
+ * ali empurraria para BATIZAR o que a leitura já diz para NORMALIZAR. As duas linhas se
+ * contradiriam na mesma tela.
+ */
+export function tooCloseToPropose(literal, theirs, jnd = 2) {
+    const v = normalizeValue(literal, theirs.rootPx);
+    for (const value of theirs.byName.values()) {
+        const d = deltaE(v, normalizeValue(value, theirs.rootPx));
+        if (d !== null && d < jnd)
+            return true;
+    }
+    return false;
+}
+/**
+ * A SEGUNDA FONTE - ESPECIFICADA, TENTADA, E NÃO ENTREGUE. O motivo é medido, e ele é o valor deste
+ * comentário.
+ *
+ * A especificação da PARTE 2 (07/09, por entrevista) admite derivar *"da função observada no código
+ * dele - o valor aparece 12× em `background` e 0× em texto, então é proposto como uma superfície"*.
+ *
+ * O QUE A TENTATIVA ENCONTROU, no mesmo dia: `scanSource` reporta UMA ocorrência por literal POR
+ * LINHA. Numa linha com `background: "#7a1f1f"` e `borderColor: "#7a1f1f"`, ele devolve um achado -
+ * e a contagem por propriedade opera sobre uma amostra que não é a contagem real. A proposta então
+ * afirmaria *"todos os seus 2 usos são texto"* sobre um valor que também é borda.
+ *
+ * Uma afirmação falsa sobre o repositório DELE é exatamente o que esta parte existe para impedir, e
+ * é a razão de a fonte 2 não estar aqui. O pré-requisito está nomeado: o scan precisa reportar cada
+ * ocorrência, e não a primeira de cada literal por linha - o que muda a granularidade de tudo que
+ * consome `findings`, e por isso é uma frente própria, não uma linha a mais neste arquivo.
+ */

package/package.json

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