synthesisui 0.16.274 → 0.16.276

package/dist/anatomy-read.js

@@ -211,8 +211,17 @@ function measuredAt(node, sketch) {
     if (measured?.behaviourProps &&
         Object.keys(measured.behaviourProps).length > 0)
         out.behaviourProps = measured.behaviourProps;
-    if (measured?.passes && Object.keys(measured.passes).length > 0)
+    if (measured?.passes && Object.keys(measured.passes).length > 0) {
         out.passes = measured.passes;
+        /**
+         * A FORMA VIAJA COM O VALOR, SEMPRE - inclusive vazia.
+         *
+         * Um `passes` sem `passesExpr` obriga quem emite a adivinhar entre aspas e chaves, e as duas
+         * adivinhações produzem código errado no arquivo dele. A lista vazia responde "nenhuma é
+         * expressão"; a AUSÊNCIA responde "este censo é velho", e são coisas diferentes.
+         */
+        out.passesExpr = measured.passesExpr ?? [];
+    }
     if (measured?.repeats)
         out.repeats = measured.repeats;
     /**

package/dist/attr-shape.js

@@ -0,0 +1,150 @@
+/**
+ * O QUE UM ATRIBUTO É, pela FORMA da chave e pela ORIGEM da tag - nunca por uma lista de nomes.
+ *
+ * O QUÊ. `passes` carrega tudo que um elemento recebe, e "tudo" são quatro coisas com destinos
+ * opostos: a acessibilidade que ele escreveu (`role`, `aria-valuenow`), o atributo específico do
+ * elemento (`type`, `viewBox`), o handler (`onMouseMove`) e a prop de OUTRO componente
+ * (`variant="premium"`). Emitir as quatro igual entrega código que não compila; calar as quatro
+ * entrega uma `<div>` muda.
+ *
+ * POR QUÊ IMPORTA. Um agente que reconstrói o componente a partir da receita escreve o que a receita
+ * disser. Medido nos dois clientes: `role` em 9 raízes de um e em 4 do outro, `aria-*` em 46 e 23
+ * chaves. Sem esta classificação a barra de progresso dele chega sem `role="progressbar"` e sem
+ * `aria-valuenow` - a lei 10 proíbe acessibilidade SUPOSTA, e calar a que ele ESCREVEU é o inverso.
+ *
+ * COMO. Duas perguntas, e nenhuma delas é "como se chama?":
+ *
+ *     tem prefixo (`aria-`, `data-`, `xlink:`)   -> global, válido em QUALQUER elemento
+ *     a tag é minúscula                          -> é elemento HTML/SVG: tudo nele é atributo
+ *     a tag é Capitalizada                       -> é componente: tudo nele é prop dele
+ *
+ * A lista `GLOBAL_ATTRS` é o único literal, e ela é um fato da especificação do HTML - esses
+ * atributos valem em todo elemento -, não um palpite sobre o código de ninguém. Medida em duas
+ * populações: cobre 100% dos casos de acessibilidade de raiz das duas.
+ *
+ * GÊMEO BYTE-IDÊNTICO de `packages/cli/src/attr-shape.ts`, provado por spec. O CLI é publicado
+ * standalone e não pode importar os contratos.
+ */
+/**
+ * OS ATRIBUTOS QUE VALEM EM QUALQUER ELEMENTO, pela especificação do HTML.
+ *
+ * Não é vocabulário do cliente e não é heurística: `role` e `tabindex` são globais, e um
+ * `aria-*` qualquer também. Por isso eles podem ser escritos no elemento que a gente emite mesmo
+ * quando a tag emitida difere da que ele escreveu - o que `element` não pode.
+ */
+const GLOBAL_ATTRS = new Set([
+    "role",
+    "title",
+    "id",
+    "lang",
+    "dir",
+    "tabIndex",
+    "tabindex",
+    "hidden",
+    "slot",
+    "translate",
+    "inert",
+    "popover",
+    "autoFocus",
+    "autofocus",
+    "spellCheck",
+    "spellcheck",
+    "contentEditable",
+    "contenteditable",
+    "draggable",
+    "accessKey",
+    "accesskey",
+]);
+/**
+ * A CLASSE DE UMA CHAVE, dada a tag que a carrega.
+ *
+ * `tag` ausente significa que a origem não é conhecida, e aí a resposta conservadora é
+ * `composition`: guardar não quebra nada, emitir pode.
+ */
+export function attrKind(key, tag) {
+    if (/^on[A-Z]/.test(key))
+        return "handler";
+    /**
+     * O PREFIXO É A PROVA. `aria-`, `data-` e `xlink:` são espaços de nome do próprio HTML, então uma
+     * chave com um deles é atributo em qualquer elemento - e é exatamente a chave que o coletor
+     * destruía até 22/08, quando `\w` engolia o hífen e `aria-hidden` virava `hidden`.
+     */
+    if (/^(aria|data)-/.test(key) || key.includes(":"))
+        return "global";
+    if (GLOBAL_ATTRS.has(key))
+        return "global";
+    const spelled = String(tag ?? "").trim();
+    if (!spelled)
+        return "composition";
+    /**
+     * A ORIGEM DECIDE, NÃO O NOME - a lei 13, um nível abaixo. Uma tag minúscula é um elemento do
+     * HTML ou do SVG: tudo que ela recebe é atributo, por construção. Uma tag Capitalizada é um
+     * componente, e `variant` nela é a API dele, não marcação.
+     */
+    return /^[a-z]/.test(spelled) ? "element" : "composition";
+}
+/** O texto JSX de um atributo, com a forma que a leitura mediu - ver `passesExpr`. */
+export function attrText(key, value, isExpression) {
+    return isExpression ? ` ${key}={${value}}` : ` ${key}="${value}"`;
+}
+/**
+ * OS ATRIBUTOS QUE PODEM SER ESCRITOS, e os que ficam guardados - numa decisão só.
+ *
+ * A função recebe o NÓ inteiro de propósito. A versão que recebia `passes` e `passesExpr` soltos
+ * podia ser chamada pela metade, e um `passes` sem a forma faz quem emite adivinhar entre aspas e
+ * chaves: as duas adivinhações produzem JSX que não compila. Fechar a porta é mais barato que
+ * vigiá-la (CLAUDE.md §6).
+ *
+ * `sameTag` diz se o elemento que a gente EMITE é o mesmo que ele escreveu. Só aí um atributo
+ * específico de elemento pode viajar: `viewBox` num `<span>` nosso é marcação inválida no arquivo
+ * dele.
+ *
+ * `requires` é o conjunto de props que a receita ALVO marca como obrigatória. Uma prop de
+ * composição obrigatória entra agora, porque sem ela o código não roda; o resto fica guardado na
+ * receita e só aparece quando alguém perguntar quais opções aquele componente tem (dono, 22/08).
+ *
+ * `expressions: "hold"` para quem GERA CÓDIGO, e não é preciosismo. `aria-valuenow={filled}` é
+ * verdadeiro no arquivo dele, onde `filled` existe; escrito dentro de um componente que a gente
+ * gera, `filled` não existe em lugar nenhum e o build DELE quebra. Um snippet é para uma pessoa
+ * adaptar e pode citar o nome dela; um arquivo gerado é para compilar.
+ */
+export function emittableAttrs(node, opts) {
+    /**
+     * FORMA DESCONHECIDA SEGURA TUDO - e este é o caso do censo tirado antes de 22/08.
+     *
+     * `passesExpr` ausente não quer dizer "nenhuma é expressão": quer dizer que o leitor daquele dia
+     * não sabia responder. Tratar como literal escreveria `title="metric.label"` no arquivo dele onde
+     * ele escreveu `title={metric.label}` - uma string no lugar de uma variável, que é leitura errada
+     * virando código errado, exatamente o defeito que esta família de consertos existe para não
+     * cometer.
+     *
+     * A omissão, ao contrário, é reparável: um `sync` traz a forma e o atributo aparece.
+     */
+    if (node.passes && Object.keys(node.passes).length > 0 && !node.passesExpr)
+        return { write: "", held: Object.keys(node.passes) };
+    const expr = new Set(node.passesExpr ?? []);
+    const write = [];
+    const held = [];
+    for (const [key, value] of Object.entries(node.passes ?? {})) {
+        const kind = attrKind(key, null);
+        /**
+         * A CLASSE SEM TAG SÓ SEPARA GLOBAL E HANDLER. Para as outras duas a pergunta é o que a gente
+         * emite, e quem sabe isso é quem chama - por isso `sameTag` e `requires` chegam de fora.
+         */
+        if (kind === "handler")
+            continue;
+        const isExpression = expr.has(key);
+        if (isExpression && opts?.expressions === "hold") {
+            held.push(key);
+            continue;
+        }
+        const allowed = kind === "global" ||
+            Boolean(opts?.sameTag) ||
+            Boolean(opts?.requires?.has(key));
+        if (allowed)
+            write.push(attrText(key, value, isExpression));
+        else
+            held.push(key);
+    }
+    return { write: write.join(""), held };
+}

package/dist/commands/import.js

@@ -3084,13 +3084,45 @@ function rootPackage(tag, sketch) {
  * Off the FIRST sketch node, which is the returned element - the same lookup `rootPackage`
  * makes one line up, guarded the same way.
  */
-function rootBehaviour(tag, sketch) {
-    const first = sketch[0];
-    if (!tag || !first || first.tag !== tag)
+export function rootBehaviour(tag, sketch) {
+    /**
+     * PELO NÓ QUE O COMPONENTE RETORNA, e não pelo primeiro do arquivo.
+     *
+     * `sketch[0]` é uma suposição que a segunda população desmente: um arquivo declara com frequência
+     * um closure ANTES do render que o usa, e é exatamente por isso que `SketchNode.root` existe.
+     * Medido: em 62 dos 323 componentes do dashboard os dois divergem, e em 4 deles o `rootProps`
+     * já se perdia hoje por causa disso. No primeiro cliente o número é 0 - uma população só nunca
+     * teria mostrado.
+     */
+    const root = sketch.find((n) => n.root) ?? sketch[0];
+    if (!tag || !root || root.tag !== tag)
         return {};
-    return first.behaviourProps && Object.keys(first.behaviourProps).length > 0
-        ? { rootProps: first.behaviourProps }
+    const props = root.behaviourProps && Object.keys(root.behaviourProps).length > 0
+        ? { rootProps: root.behaviourProps }
+        : {};
+    /**
+     * E O QUE ELE ESCREVE NA RAIZ - `role`, `aria-*`, `type`. Este é o campo que faltava.
+     *
+     * `passes` só sobrevive num nó da árvore, e a raiz de um componente é CONSUMIDA: ela É o
+     * componente, então não existe nó onde o fato dela caiba. Medido: 26 dos 59 componentes do
+     * primeiro cliente e 113 dos 323 do segundo têm `passes` numa raiz sem slot, e um agente
+     * reconstruindo o `Progress` a partir da receita escrevia uma `<div>` muda - sem
+     * `role="progressbar"`, sem `aria-valuenow`. A lei 10 proíbe acessibilidade SUPOSTA; isto era o
+     * inverso, que é pior: ele escreveu, o censo colheu, e a receita calou.
+     *
+     * SEPARADO DE `rootProps` de propósito. `rootProps` significa *prop cujo valor é uma condição*, e
+     * `component-behaviour.ts` extrai nomes de estado dos valores dele. Jogar `role="progressbar"`
+     * ali faria "progressbar" virar um nome de estado que o componente segura.
+     */
+    const given = root.passes && Object.keys(root.passes).length > 0
+        ? {
+            rootPasses: root.passes,
+            ...(root.passesExpr && root.passesExpr.length > 0
+                ? { rootPassesExpr: root.passesExpr }
+                : {}),
+        }
         : {};
+    return { ...props, ...given };
 }
 export async function resolveReadParts(census, root, 
 /** `true` numa re-medição: o resumo desta etapa fica para o `sync --full` - ver `say`. */

package/dist/component-codegen.js

@@ -1,3 +1,4 @@
+import { emittableAttrs } from "./attr-shape.js";
 import { PHRASING_FORMS, } from "./types.js";
 export const DEFAULT_CONVENTION = {
     prefix: "ds-",
@@ -71,7 +72,27 @@ function elementFor(name, recipe) {
             ? { tag: "button", attrs: ' type="button"' }
             : undefined);
     const tag = hit?.tag ?? "div";
-    const attrs = hit?.attrs ?? "";
+    /**
+     * O QUE ELE ESCREVEU NA RAIZ VENCE O QUE A GENTE SUPÕE - a lei 10, aplicada onde ela nasceu.
+     *
+     * A tabela acima inventa `role="switch"` a partir do NOME da receita. Isso é uma suposição
+     * razoável e continua sendo uma suposição; `role="progressbar"` medido no `<div>` que ELE escreveu
+     * é um fato. Quando os dois falam da mesma chave, o fato ganha - e até 22/08 o fato nem chegava
+     * aqui: 26 dos 59 componentes de um cliente e 113 dos 323 do outro tinham a raiz com atributo e a
+     * receita muda.
+     *
+     * SÓ LITERAL. `aria-valuenow={filled}` é verdade no arquivo dele, onde `filled` existe; escrito
+     * dentro de um componente que a gente GERA, `filled` não existe e o build dele quebra. Ver
+     * `expressions: "hold"` em `attr-shape.ts`.
+     */
+    const theirs = emittableAttrs({
+        passes: recipe.preview?.rootPasses,
+        passesExpr: recipe.preview?.rootPassesExpr,
+    }, {
+        sameTag: tag === recipe.preview?.rootTag,
+        expressions: "hold",
+    }).write;
+    const attrs = mergeAttrs(hit?.attrs ?? "", theirs);
     const isVoid = tag === "input" || tag === "hr";
     /**
      * A VOID ELEMENT CANNOT HOST THE PARTS WE TELL PEOPLE TO PUT INSIDE IT.
@@ -338,6 +359,24 @@ function asElement(tag, attrs, voidEl) {
         offersAs: true,
     };
 }
+/**
+ * DUAS LISTAS DE ATRIBUTOS NUMA, e a DELE ganha a chave repetida.
+ *
+ * Sem isto o elemento sairia com `role="switch" role="progressbar"` - JSX que não compila e, se
+ * compilasse, resolveria pelo último. A chave é extraída do texto porque é assim que as duas metades
+ * já viajam; nada aqui inventa atributo.
+ */
+function mergeAttrs(ours, theirs) {
+    const taken = new Set([...theirs.matchAll(/\s([A-Za-z][\w:-]*)=/g)].map((m) => m[1]));
+    const kept = [...ours.matchAll(/\s[A-Za-z][\w:-]*=(?:"[^"]*"|\{[^}]*\})/g)]
+        .map((m) => m[0])
+        .filter((piece) => {
+        const key = /\s([A-Za-z][\w:-]*)=/.exec(piece)?.[1] ?? "";
+        return !taken.has(key);
+    })
+        .join("");
+    return `${kept}${theirs}`;
+}
 function dataAttrLines(axes) {
     return axes
         .map((a) => a.boolean
@@ -891,8 +930,20 @@ function treeParts(nodes, out = []) {
 function emitTree(nodes, comp, indent) {
     const lines = [];
     for (const node of nodes) {
+        /**
+         * O QUE ELE ESCREVEU NESTE NÓ - `role`, `aria-*`, `data-*`, e a prop que o alvo EXIGE.
+         *
+         * Só literal: uma expressão nomeia uma variável do arquivo DELE que não existe dentro do
+         * componente que a gente gera, e o build dele quebra. `sameTag` é falso porque a tag emitida sai
+         * do formulário do nó (`FORM_TAG`), que é escolha nossa - então atravessa o que o HTML define
+         * como global, que é justamente onde a acessibilidade mora.
+         */
+        const attrs = emittableAttrs(node, {
+            requires: new Set(node.passesRequired ?? []),
+            expressions: "hold",
+        }).write;
         if (node.as === "component") {
-            lines.push(`${indent}{/* your <${pascal(node.ref ?? "")} /> goes here - it has a recipe of its own, so it is not inlined */}`);
+            lines.push(`${indent}{/* your <${pascal(node.ref ?? "")}${attrs} /> goes here - it has a recipe of its own, so it is not inlined */}`);
             continue;
         }
         if (node.as === "external") {
@@ -918,17 +969,17 @@ function emitTree(nodes, comp, indent) {
         }
         const partComp = `${comp}${pascal(node.part)}`;
         if (ARRANGES.has(node.as) && node.children && node.children.length > 0) {
-            lines.push(`${indent}<${partComp}>`);
+            lines.push(`${indent}<${partComp}${attrs}>`);
             lines.push(emitTree(node.children, comp, `${indent}  `));
             lines.push(`${indent}</${partComp}>`);
             continue;
         }
         const { voidEl } = FORM_TAG[node.as] ?? {};
         if (voidEl) {
-            lines.push(`${indent}<${partComp} />`);
+            lines.push(`${indent}<${partComp}${attrs} />`);
             continue;
         }
-        lines.push(`${indent}<${partComp}>${node.text ?? `{/* ${node.part} */}`}</${partComp}>`);
+        lines.push(`${indent}<${partComp}${attrs}>${node.text ?? `{/* ${node.part} */}`}</${partComp}>`);
     }
     return lines.filter(Boolean).join("\n");
 }

package/dist/doctor/sketch.js

@@ -362,8 +362,9 @@ export function passedProps(body,
 /** O que `behaviourProps` já levou, para cada fato viver num lugar só. */
 taken) {
     const out = {};
+    const expression = [];
     const SKIP = /^(className|class|key|ref|style|children)$/;
-    for (const m of body.matchAll(/(\w+)=(?:"([^"]{0,80})"|'([^']{0,80})'|\{([^{}]{1,80})\})/g)) {
+    for (const m of body.matchAll(PROP_ATTR)) {
         const prop = m[1];
         if (SKIP.test(prop) || taken?.[prop] || out[prop])
             continue;
@@ -377,9 +378,27 @@ taken) {
         if (!value || /=>|\bfunction\b/.test(value) || value.startsWith("{"))
             continue;
         out[prop] = value;
+        expression.push(prop);
     }
-    return Object.keys(out).length > 0 ? out : null;
+    return Object.keys(out).length > 0 ? { props: out, expression } : null;
 }
+/**
+ * UM NOME DE PROP INCLUI O HÍFEN, e ele era o pedaço que a acessibilidade dele inteira carregava.
+ *
+ * O padrão anterior era `(\w+)=`, e `\w` não casa `-`. Num `aria-hidden="true"` o motor tentava
+ * `aria`, batia no hífen, voltava, desistia, e recomeçava em `label`/`hidden` - então o censo
+ * gravava a chave SEM o prefixo. Medido no fonte dos dois clientes: 83 `aria-*` + 4 `data-*` no
+ * `packages/ui` do primeiro, 174 + 623 no dashboard do segundo.
+ *
+ * O custo não era só de perda. `aria-hidden` gravado como `hidden` e emitido de volta escreve o
+ * atributo HTML `hidden`, que APAGA o elemento da tela: a leitura errada viraria código errado no
+ * arquivo dele. Por isso o conserto mora na COLETA e não na emissão - depois daqui a informação já
+ * não existe, e nenhum `reinterpret` a recupera.
+ *
+ * `[\w:-]` cobre as três grafias que o JSX aceita num nome de atributo: `data-x`, `aria-x` e
+ * `xlink:href`. A âncora `[A-Za-z]` na primeira posição impede que um hífen solto vire nome.
+ */
+const PROP_ATTR = /\b([A-Za-z][\w:-]*)=(?:"([^"]{0,80})"|'([^']{0,80})'|\{([^{}]{1,80})\})/g;
 /**
  * A expressão que um `map` percorre, quando este elemento está dentro de um - ver `repeats`.
  *
@@ -542,8 +561,21 @@ export function sketchOf(source, name) {
          * para a receita de uma TELA carregar a fiação, e não só a casca.
          */
         const given = passedProps(event.body, conditional);
-        if (given)
-            node.passes = given;
+        if (given) {
+            node.passes = given.props;
+            /**
+             * A FORMA VIAJA SEMPRE QUE O VALOR VIAJA, inclusive VAZIA - e a lista vazia é o ponto.
+             *
+             * Se `passesExpr` só aparecesse quando há expressão, "ausente" significaria duas coisas ao
+             * mesmo tempo: *nenhuma delas é expressão* e *este censo é velho e não sabe responder*. Quem
+             * emite não tem como distinguir, e as duas exigem comportamentos OPOSTOS - escrever tudo como
+             * literal, ou não escrever nada.
+             *
+             * Com o array sempre presente, ausência quer dizer uma coisa só: censo tirado antes de
+             * 0.16.275. Ver `emittableAttrs`, que segura o atributo nesse caso em vez de adivinhar.
+             */
+            node.passesExpr = given.expression;
+        }
         const list = repeatOf(source, event.at);
         if (list)
             node.repeats = list;

package/dist/doctor/transcribe.js

@@ -2014,11 +2014,60 @@ function bodyBrace(source, declAt) {
      * function to alias to either: the body IS the argument.
      */
     const head = source.slice(declAt, declAt + 400);
-    const wrapper = /=\s*(?:React\.)?(?:forwardRef|memo|styled\([^)]*\))\s*(?:<[^>(]*>)?\s*\(/.exec(head);
+    /**
+     * O GENÉRICO PODE SER ANINHADO, e `<[^>(]*>` proibia isso.
+     *
+     * `forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(` tem um `>` dentro do argumento de
+     * tipo, então o padrão parava no primeiro e o wrapper inteiro deixava de casar - o componente caía
+     * na varredura simples, que conta parêntese do `forwardRef` como se fosse do corpo. `ModalBody` e
+     * `ModalFooter` do cliente ficavam sem raiz por isso.
+     *
+     * `[^(]*` deixa o `>` passar e para no parêntese, que é o delimitador de verdade aqui.
+     */
+    const wrapper = /=\s*(?:React\.)?(?:forwardRef|memo|styled\([^)]*\))\s*(?:<[^(]*>)?\s*\(/.exec(head);
     if (wrapper) {
-        const arrow = /(?:=>|function\s*[A-Za-z0-9_]*\s*\([^)]*\))\s*\{/.exec(source.slice(declAt + wrapper.index));
+        const from = declAt + wrapper.index;
+        const rest = source.slice(from);
+        /**
+         * A LISTA DE PARÂMETROS PODE TER UM PARÊNTESE DENTRO, e o padrão anterior não podia saber disso.
+         *
+         * Ele exigia `\([^)]*\)`, que para no PRIMEIRO `)`. O `NoiseOverlay` do cliente escreve
+         * `color = "rgba(0,0,0,0.025)"` como default de prop, então a varredura terminava dentro da
+         * lista, não achava a chave do corpo, e o componente inteiro ficava sem raiz: sem `rootTag`, sem
+         * nó marcado `root`, sem `rootClasses` e sem `rootArrange`.
+         *
+         * Medido nas duas populações: 7 de 59 componentes de um cliente (12%) e 13 de 320 do outro
+         * ficavam assim. É a forma de perda que o mapa cataloga - uma enumeração mais estreita que a
+         * própria entrada -, e o conserto é contar parêntese em vez de proibi-lo.
+         */
+        const named = /function\s*[A-Za-z0-9_$]*\s*\(/.exec(rest);
+        const arrow = /=>\s*\{/.exec(rest);
+        /**
+         * O QUE VIER PRIMEIRO, como a alternância anterior já decidia. Procurar `function` no arquivo
+         * inteiro casaria a PRÓXIMA função declarada quando o wrapper carrega um arrow - `forwardRef((
+         * props, ref) => { … })` -, e o corpo lido seria o de outro componente.
+         */
+        const namedFirst = named != null && (arrow == null || named.index < arrow.index);
+        if (namedFirst && named) {
+            const open = named.index + named[0].length - 1;
+            let depth = 0;
+            for (let j = open; j < rest.length; j++) {
+                const ch = rest[j];
+                if (ch === "(")
+                    depth += 1;
+                else if (ch === ")") {
+                    depth -= 1;
+                    if (depth === 0) {
+                        const body = /^\s*\{/.exec(rest.slice(j + 1));
+                        if (body)
+                            return from + j + body[0].length;
+                        break;
+                    }
+                }
+            }
+        }
         if (arrow) {
-            const at = declAt + wrapper.index + arrow.index + arrow[0].length - 1;
+            const at = from + arrow.index + arrow[0].length - 1;
             if (source[at] === "{")
                 return at;
         }
@@ -2088,7 +2137,26 @@ function ownReturn(source, declAt) {
             continue;
         }
         if (ch === '"' || ch === "'" || ch === "`") {
-            quote = ch;
+            /**
+             * UM APÓSTROFO DENTRO DE UMA PALAVRA NÃO ABRE STRING - `Don't`, `we'll`, `it's`.
+             *
+             * Em texto JSX o apóstrofo é uma letra como outra qualquer, e tratá-lo como delimitador abria
+             * uma "string" que só fechava no próximo apóstrofo do arquivo. Tudo depois disso ficava fora
+             * de sincronia: a contagem de chaves perdia o passo e o `return` da raiz nunca era visto no
+             * nível certo.
+             *
+             * Medido no dashboard do segundo cliente: 6 componentes ficavam sem raiz nenhuma por causa
+             * disto - `CurateTemplate`, `CustomCardList`, `TunePreferences` e mais três -, e com a regra
+             * nova nenhuma das 376 respostas que já estavam certas nas duas populações muda.
+             *
+             * A regra é estreita de propósito: só o apóstrofo com letra dos dois lados. `'a'` continua
+             * string, e `it's` continua texto.
+             */
+            const dentroDePalavra = ch === "'" &&
+                /[A-Za-z]/.test(source[j - 1] ?? "") &&
+                /[A-Za-z]/.test(source[j + 1] ?? "");
+            if (!dentroDePalavra)
+                quote = ch;
             continue;
         }
         if (ch === "{")

package/dist/install-marks.js

@@ -128,7 +128,7 @@
  * é sempre o bump deste PR - nunca o número que o `package.json` já carrega, porque alguém pode
  * publicar no meio.
  */
-export const MATERIALISER_SINCE = "0.16.270";
+export const MATERIALISER_SINCE = "0.16.276";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/populations.spec-input.js

@@ -0,0 +1,53 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * ONDE ESTÃO AS POPULAÇÕES MEDIDAS - e por que elas não moram mais na máquina de ninguém.
+ *
+ * O QUÊ. 23 specs medem contra o censo de dois repositórios reais. Até 22/08 cada um apontava para
+ * `~/projects/frontend-hub` ou `~/personal/codelevel-monorepo` na home do dono.
+ *
+ * POR QUÊ ISSO ERA UM DEFEITO. Não porque quebrava - 35 dos 36 pulavam educadamente quando o
+ * arquivo sumia. Porque ficava VERDE. Medido em 22/08: três artefatos do `signalui` já não estavam
+ * no disco e 12 testes pulavam em silêncio havia sabe-se lá quanto tempo. Uma suíte que fica verde
+ * quando parou de medir é pior que uma vermelha, e essa é a única classe de defeito que esta
+ * esteira não pode aceitar num instrumento.
+ *
+ * E O SEGUNDO CUSTO, que é o do produto: sem a segunda população, toda régua nova passa a ser
+ * medida num repositório só. Três réguas escritas em 22/08 estariam erradas por isso.
+ *
+ * COMO. `fixtures/populations/`, versionado, compacto. `npm run populations:refresh` atualiza a
+ * partir dos repositórios vivos quando eles existem - e o que mudou aparece no `git diff`, que é
+ * onde uma mudança de insumo pode ser revisada em vez de sentida.
+ *
+ * GÊMEO de `apps/web/src/lib/ds/populations.ts`: o CLI é publicado standalone e não importa de lá. As
+ * duas cópias resolvem o mesmo diretório por caminho relativo, então elas não podem divergir de
+ * conteúdo - só de posição.
+ */
+/** A raiz do monorepo, a partir deste arquivo: `packages/cli/src` → 3 níveis acima. */
+const ROOT = join(import.meta.dirname, "..", "..", "..");
+const POPULATIONS = join(ROOT, "fixtures", "populations");
+/**
+ * 323 componentes, escopo `apps/web-dashboard`. A população que derruba régua feita em cima da
+ * outra: ela não declara um `--animate-*` sequer, escreve o relógio literal na receita, e tem 62
+ * componentes cujo primeiro nó do sketch não é a raiz.
+ */
+export const FRONTEND_HUB_CENSUS = join(POPULATIONS, "frontend-hub.census.json");
+/**
+ * 59 componentes, escopo `packages/ui`. O caso de teste vivo do dia a dia - é dele que saem os
+ * números do `triage` e é nele que a jornada é conferida na tela.
+ */
+export const CODELEVEL_CENSUS = join(POPULATIONS, "codelevel-ui.census.json");
+/**
+ * OS REPOSITÓRIOS VIVOS - e estes NÃO estão congelados, de propósito.
+ *
+ * Um punhado de specs não mede o censo: eles varrem os `.tsx` de ORIGEM para exercitar o COLETOR -
+ * `sketchOf`, `rootTag`, o leitor de `cn()`. Congelar 69 arquivos de código de cliente dentro deste
+ * repositório é uma decisão diferente de congelar uma medição, e ela não foi tomada.
+ *
+ * Então estes caminhos continuam dependendo da máquina, e é aqui que isso está DITO. Todo spec que
+ * os usa tem que guardar com `existsSync` - sem o guard, a ausência derruba a suíte em vez de pular.
+ *
+ * Medido em 22/08: 5 specs no `apps/web` e no `packages/cli` estão nesta situação.
+ */
+export const CODELEVEL_REPO = join(homedir(), "personal", "codelevel-monorepo");
+export const FRONTEND_HUB_REPO = join(homedir(), "projects", "frontend-hub");

package/package.json

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