tempest-react-sdk 0.28.1 → 0.29.0

package/bin/lib/css/extract.mjs

@@ -0,0 +1,406 @@
+// `tempest fix --extract-css` — move a declaration block that repeats across CSS
+// Modules into the project's global stylesheet, and rewrite the JSX that pointed
+// at the local copies.
+//
+// Opt-in, and it stays opt-in. The other passes of `fix` remove things that are
+// provably dead; this one makes a **design** decision — that N screens should now
+// share one class, and therefore change together. That is a call about coupling,
+// so it happens only when somebody asks for it by name.
+//
+// Everything here is refusal-first. A group is extracted only when every one of
+// these holds, and each refusal is reported with its reason rather than skipped
+// in silence:
+//
+//   - every occurrence is a lone class selector (`.row`), outside any at-rule;
+//   - no other rule in that module mentions the class (a `:hover`, a descendant
+//     selector or a `@media` override would stay behind and lose its subject);
+//   - the module keeps at least one other rule, so its import does not become
+//     dead and take the remaining styles down with it;
+//   - the class is only ever read as `styles.row` / `styles["row"]`, never
+//     through a computed key or by handing the whole object around;
+//   - the target global sheet exists AND some source file imports it, because
+//     appending to a stylesheet nobody loads is a silent no-op;
+//   - the new global name collides with nothing already in that sheet.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+import { discoverAlias } from "../alias/discover.mjs";
+import { loadTypeScript } from "../alias/typescript.mjs";
+import { collectSources, indexClassUses, resolveSpecifier } from "./references.mjs";
+import { parseCss } from "./parse.mjs";
+import { declSignature } from "./semantic.mjs";
+
+/** A repeated block is only worth extracting from this many declarations up. */
+const MIN_DECLS = 3;
+
+/** Stylesheets treated as "the project's global sheet", in order of preference. */
+const TARGET_CANDIDATES = [
+    "src/styles/globals.css",
+    "src/styles/global.css",
+    "src/globals.css",
+    "src/global.css",
+    "src/index.css",
+    "src/app.css",
+    "app/globals.css",
+    "styles/globals.css",
+    "index.css",
+];
+
+/** `.row` → `row`, or `null` when the selector is anything more than one class. */
+export function loneClass(prelude) {
+    const match = /^\.([A-Za-z_][A-Za-z0-9_-]*)$/.exec(prelude.trim());
+    return match ? match[1] : null;
+}
+
+/** `cardHeader` → `card-header`. */
+export function kebab(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/[_\s]+/g, "-")
+        .toLowerCase();
+}
+
+/** Class names a stylesheet already defines, at any depth. */
+export function classNamesIn(parsed) {
+    const names = new Set();
+    for (const block of parsed.blocks) {
+        for (const match of block.prelude.matchAll(/\.([A-Za-z_][A-Za-z0-9_-]*)/g)) {
+            names.add(match[1]);
+        }
+    }
+    return names;
+}
+
+/**
+ * Pick the global stylesheet to append to, and prove somebody imports it.
+ *
+ * @param {object} params
+ * @param {string} params.root
+ * @param {string} [params.explicit] - Path from `--css-target`.
+ * @param {{ prefix: string, baseDir: string } | null} params.alias
+ * @returns {{ path: string, file: string } | { error: string }}
+ */
+export function findGlobalSheet({ root, explicit, alias }) {
+    const candidates = explicit ? [explicit] : TARGET_CANDIDATES;
+    const found = candidates.map((rel) => join(root, rel)).find(existsSync);
+    if (!found) {
+        return {
+            error: explicit
+                ? `--css-target "${explicit}" não existe`
+                : `nenhuma folha global encontrada (procurei ${TARGET_CANDIDATES.join(", ")}) — passe --css-target <arquivo>`,
+        };
+    }
+    if (found.endsWith(".module.css")) {
+        return {
+            error: `${relative(root, found)} é um CSS Module — a folha alvo tem que ser global`,
+        };
+    }
+
+    const imported = collectSources({ root }).some((file) => {
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        } catch {
+            return false;
+        }
+        if (!text.includes(".css")) return false;
+        for (const match of text.matchAll(/["']([^"']+\.css)["']/g)) {
+            const target = resolveSpecifier({ specifier: match[1], fromFile: file, alias });
+            if (target === found) return true;
+        }
+        return false;
+    });
+    if (!imported) {
+        return {
+            error: `${relative(root, found)} não é importada por nenhum arquivo do projeto — o que fosse movido pra lá não carregaria`,
+        };
+    }
+    return { path: found, file: relative(root, found) };
+}
+
+/** Group the analysed sheets by identical declaration block. */
+function groupBySignature(sheets) {
+    const groups = new Map();
+    for (const sheet of sheets) {
+        if (!sheet.isModule) continue;
+        for (const block of sheet.parsed.blocks) {
+            if (block.kind !== "rule" || block.decls.length < MIN_DECLS) continue;
+            const signature = declSignature(block);
+            const group = groups.get(signature) ?? { signature, entries: [] };
+            group.entries.push({ sheet, block });
+            groups.set(signature, group);
+        }
+    }
+    return [...groups.values()];
+}
+
+/**
+ * Why this occurrence cannot be extracted, or `null` when it can.
+ *
+ * @returns {string | null}
+ */
+function occurrenceRefusal({ sheet, block, className, uses, opaqueModules }) {
+    if (block.context.length > 0) {
+        return `está dentro de \`${block.context.join(" › ")}\` — mover pra fora mudaria quando a regra vale`;
+    }
+    if (!className) return `\`${block.prelude}\` não é uma classe simples`;
+
+    const mentions = sheet.parsed.blocks.filter(
+        (other) =>
+            other !== block && new RegExp(`\\.${className}(?![A-Za-z0-9_-])`).test(other.prelude),
+    );
+    if (mentions.length > 0) {
+        return `outra regra na mesma folha usa \`.${className}\` (linha ${mentions[0].line}) e ficaria sem sujeito`;
+    }
+
+    const remaining = sheet.parsed.blocks.filter(
+        (other) => other !== block && other.kind === "rule",
+    );
+    if (remaining.length === 0) {
+        return "é a única regra do módulo — o import viraria código morto e levaria a folha inteira";
+    }
+
+    const opaque = opaqueModules.get(sheet.path);
+    if (opaque) {
+        return `o módulo é usado de forma não estática em ${opaque.file}:${opaque.line} — ${opaque.reason}`;
+    }
+
+    if (!uses || uses.length === 0) {
+        return `nenhum \`styles.${className}\` no código — a classe já é código morto, e mover não conserta isso`;
+    }
+    return null;
+}
+
+/**
+ * Build the extraction plan.
+ *
+ * @param {object} params
+ * @param {ReturnType<import("./analyze.mjs").analyzeCss>} params.analysis
+ * @param {string} params.root
+ * @param {string} [params.target] - Path from `--css-target`.
+ * @param {string} [params.prefix] - Prefix for the new global class names.
+ * @returns {{
+ *   status: "ok" | "no-typescript" | "no-target",
+ *   message?: string,
+ *   target?: { path: string, file: string },
+ *   groups: Array<object>,
+ *   refusals: Array<{ file: string, line: number, reason: string }>,
+ * }}
+ */
+export function planExtraction({ analysis, root, target, prefix = "u-" }) {
+    const ts = loadTypeScript(root);
+    if (!ts) {
+        return {
+            status: "no-typescript",
+            message:
+                "typescript não instalado — a reescrita do TSX precisa do compilador do projeto",
+            groups: [],
+            refusals: [],
+        };
+    }
+    const alias = discoverAlias({ root, ts });
+    const sheet = findGlobalSheet({ root, explicit: target, alias });
+    if (sheet.error) {
+        return { status: "no-target", message: sheet.error, groups: [], refusals: [] };
+    }
+
+    const modulePaths = analysis.sheets.filter((s) => s.isModule).map((s) => s.path);
+    const { byModule, opaqueModules } = indexClassUses({ root, ts, modulePaths, alias });
+
+    const targetText = readFileSync(sheet.path, "utf8");
+    const taken = classNamesIn(parseCss(targetText));
+    const groups = [];
+    const refusals = [];
+
+    for (const group of groupBySignature(analysis.sheets)) {
+        if (group.entries.length < 2) continue;
+
+        const eligible = [];
+        for (const entry of group.entries) {
+            const className = loneClass(entry.block.prelude);
+            const uses = className ? byModule.get(entry.sheet.path)?.get(className) : null;
+            const refusal = occurrenceRefusal({ ...entry, className, uses, opaqueModules });
+            if (refusal) {
+                refusals.push({ file: entry.sheet.file, line: entry.block.line, reason: refusal });
+                continue;
+            }
+            eligible.push({ ...entry, className, uses });
+        }
+
+        const files = new Set(eligible.map((e) => e.sheet.file));
+        if (eligible.length < 2 || files.size < 2) continue;
+
+        const name = `${prefix}${kebab(commonName(eligible))}`;
+        if (taken.has(name)) {
+            refusals.push({
+                file: sheet.file,
+                line: 1,
+                reason: `\`.${name}\` já existe na folha global — renomeie a classe local ou use --css-prefix`,
+            });
+            continue;
+        }
+        taken.add(name);
+
+        groups.push({
+            name,
+            decls: eligible[0].block.decls.map((d) => ({ prop: d.prop, value: d.value })),
+            occurrences: eligible.map((e) => ({
+                path: e.sheet.path,
+                file: e.sheet.file,
+                line: e.block.line,
+                className: e.className,
+                start: e.block.start,
+                end: e.block.end,
+                sites: e.uses.map((u) => ({
+                    path: u.file,
+                    file: relative(root, u.file),
+                    line: u.line,
+                    start: u.start,
+                    end: u.end,
+                })),
+            })),
+        });
+    }
+
+    return { status: "ok", target: sheet, groups, refusals };
+}
+
+/**
+ * The name for the extracted class: the local name the codebase already uses
+ * most, by modules first and call sites second.
+ *
+ * A tie is the normal case — the copies live in different modules precisely
+ * because nobody agreed on a name — so the order of the occurrences breaks it,
+ * which keeps the result deterministic across runs. The chosen name is printed
+ * before anything is written; `--css-prefix` is there for when it needs a
+ * namespace rather than a different word.
+ */
+function commonName(eligible) {
+    const counts = new Map();
+    for (const entry of eligible) {
+        const current = counts.get(entry.className) ?? { modules: 0, sites: 0 };
+        counts.set(entry.className, {
+            modules: current.modules + 1,
+            sites: current.sites + entry.uses.length,
+        });
+    }
+    return [...counts.entries()].sort(
+        (a, b) => b[1].modules - a[1].modules || b[1].sites - a[1].sites,
+    )[0][0];
+}
+
+/** Render the extracted rule for the global sheet. */
+export function renderRule({ name, decls, occurrences }) {
+    const body = decls.map((d) => `    ${d.prop}: ${d.value};`).join("\n");
+    return [
+        `/* extraído por \`tempest fix --extract-css\` de ${occurrences.length} CSS Modules */`,
+        `.${name} {`,
+        body,
+        "}",
+        "",
+    ].join("\n");
+}
+
+/**
+ * Grow a removal range over the leading indentation and the trailing newline.
+ * Same rule as the dedupe pass, so a removed rule leaves no blank indented line.
+ */
+function expandRange(text, start, end) {
+    let from = start;
+    while (from > 0 && (text[from - 1] === " " || text[from - 1] === "\t")) from -= 1;
+    if (from > 0 && text[from - 1] !== "\n") from = start;
+    let to = end;
+    while (to < text.length && (text[to] === " " || text[to] === "\t")) to += 1;
+    if (text[to] === "\r") to += 1;
+    if (text[to] === "\n") to += 1;
+    return { start: from, end: to };
+}
+
+/** Apply text edits back-to-front. */
+function splice(text, edits) {
+    let out = text;
+    for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+        out = out.slice(0, edit.start) + (edit.text ?? "") + out.slice(edit.end);
+    }
+    return out;
+}
+
+/**
+ * Apply an extraction plan to disk.
+ *
+ * @param {object} params
+ * @param {ReturnType<typeof planExtraction>} params.plan
+ * @param {boolean} [params.dryRun]
+ * @returns {{
+ *   moved: number,
+ *   rules: number,
+ *   files: Array<{ file: string, changes: string[] }>,
+ *   errors: Array<{ file: string, message: string }>,
+ * }}
+ */
+export function applyExtraction({ plan, dryRun = false }) {
+    const result = { moved: 0, rules: 0, files: [], errors: [] };
+    if (plan.status !== "ok" || plan.groups.length === 0) return result;
+
+    const edits = new Map();
+    const changes = new Map();
+    const record = (file, message) => {
+        changes.set(file, [...(changes.get(file) ?? []), message]);
+    };
+    const push = (path, edit) => {
+        edits.set(path, [...(edits.get(path) ?? []), edit]);
+    };
+
+    let appended = "";
+    for (const group of plan.groups) {
+        appended += `\n${renderRule(group)}`;
+        result.rules += 1;
+        for (const occurrence of group.occurrences) {
+            let text;
+            try {
+                text = readFileSync(occurrence.path, "utf8");
+            } catch (err) {
+                result.errors.push({
+                    file: occurrence.file,
+                    message: String(err?.message ?? err),
+                });
+                continue;
+            }
+            push(occurrence.path, expandRange(text, occurrence.start, occurrence.end));
+            record(
+                occurrence.file,
+                `removida \`.${occurrence.className}\` (linha ${occurrence.line}) → \`.${group.name}\` em ${plan.target.file}`,
+            );
+            result.moved += 1;
+            for (const site of occurrence.sites) {
+                push(site.path, { start: site.start, end: site.end, text: `"${group.name}"` });
+                record(
+                    site.file,
+                    `\`styles.${occurrence.className}\` → \`"${group.name}"\` (linha ${site.line})`,
+                );
+            }
+        }
+    }
+
+    if (!dryRun) {
+        for (const [path, fileEdits] of edits) {
+            let text;
+            try {
+                text = readFileSync(path, "utf8");
+                writeFileSync(path, splice(text, fileEdits));
+            } catch (err) {
+                result.errors.push({ file: path, message: String(err?.message ?? err) });
+            }
+        }
+        try {
+            const current = readFileSync(plan.target.path, "utf8");
+            writeFileSync(plan.target.path, `${current.replace(/\s*$/, "\n")}${appended}`);
+        } catch (err) {
+            result.errors.push({ file: plan.target.file, message: String(err?.message ?? err) });
+        }
+    }
+    record(plan.target.file, `+${result.rules} classe(s) global(is)`);
+
+    result.files = [...changes.entries()].map(([file, list]) => ({ file, changes: list }));
+    return result;
+}

package/bin/lib/css/extract.test.mjs

@@ -0,0 +1,304 @@
+import { createRequire } from "node:module";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { analyzeCss } from "./analyze.mjs";
+import { applyExtraction, classNamesIn, kebab, loneClass, planExtraction } from "./extract.mjs";
+import { parseCss } from "./parse.mjs";
+
+const SELF_DIR = resolve(dirname(new URL(import.meta.url).pathname), "..", "..");
+const TYPESCRIPT_DIR = dirname(createRequire(import.meta.url).resolve("typescript/package.json"));
+
+let root;
+
+/** Write a file inside the fixture project, creating its directory. */
+function write(rel, text) {
+    const full = join(root, rel);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, text);
+    return full;
+}
+
+const ROW = `.row {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+.title {
+    font-weight: 600;
+}
+`;
+
+/**
+ * A minimal project the codemod can act on: a tsconfig with the `@/*` alias, a
+ * global stylesheet that the entry imports, and the project's own TypeScript
+ * (symlinked, because the CLI resolves the compiler from the project on purpose).
+ */
+function project() {
+    write("package.json", JSON.stringify({ name: "fixture" }));
+    write(
+        "tsconfig.json",
+        JSON.stringify({ compilerOptions: { baseUrl: ".", paths: { "@/*": ["./src/*"] } } }),
+    );
+    write("src/index.css", ":root {\n    --brand: #0d6efd;\n}\n");
+    write("src/main.tsx", 'import "./index.css";\n');
+    mkdirSync(join(root, "node_modules"), { recursive: true });
+    symlinkSync(TYPESCRIPT_DIR, join(root, "node_modules", "typescript"), "dir");
+}
+
+/** Two modules declaring the same block, each used from its own component. */
+function twoCopies() {
+    write("src/components/Card.module.css", ROW);
+    write(
+        "src/components/Card.tsx",
+        'import styles from "./Card.module.css";\n\nexport const Card = () => (\n  <div className={styles.row}>\n    <b className={styles.title}>x</b>\n  </div>\n);\n',
+    );
+    write("src/components/List.module.css", ROW.replace(".row", ".line"));
+    write(
+        "src/components/List.tsx",
+        'import styles from "@/components/List.module.css";\n\nexport const List = () => (\n  <li className={styles.line}>\n    <b className={styles.title}>x</b>\n  </li>\n);\n',
+    );
+}
+
+const plan = (options = {}) =>
+    planExtraction({
+        analysis: analyzeCss({ root, targets: ["."], selfDir: SELF_DIR }),
+        root,
+        ...options,
+    });
+
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "tempest-extract-"));
+});
+
+afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+});
+
+describe("helpers", () => {
+    it("recognizes a lone class selector and rejects anything else", () => {
+        expect(loneClass(".row")).toBe("row");
+        expect(loneClass("  .card-header ")).toBe("card-header");
+        expect(loneClass(".row:hover")).toBeNull();
+        expect(loneClass(".a .b")).toBeNull();
+        expect(loneClass(".a.b")).toBeNull();
+        expect(loneClass("div")).toBeNull();
+    });
+
+    it("kebab-cases a camelCase class name", () => {
+        expect(kebab("cardHeader")).toBe("card-header");
+        expect(kebab("row")).toBe("row");
+        expect(kebab("grid_2")).toBe("grid-2");
+    });
+
+    it("collects every class a sheet defines", () => {
+        const parsed = parseCss(".a .b { color: red; }\n.c:hover { color: blue; }\n");
+        expect(classNamesIn(parsed)).toEqual(new Set(["a", "b", "c"]));
+    });
+});
+
+describe("planExtraction — the happy path", () => {
+    beforeEach(() => {
+        project();
+        twoCopies();
+    });
+
+    it("plans one global class from two modules, with every call site", () => {
+        const result = plan();
+        expect(result.status).toBe("ok");
+        expect(result.target.file).toBe(join("src", "index.css"));
+        expect(result.groups).toHaveLength(1);
+
+        const [group] = result.groups;
+        expect(group.name).toBe("u-row");
+        expect(group.decls.map((d) => d.prop)).toEqual(["display", "align-items", "gap"]);
+        expect(group.occurrences.map((o) => o.className).sort()).toEqual(["line", "row"]);
+        expect(group.occurrences.flatMap((o) => o.sites)).toHaveLength(2);
+    });
+
+    it("honors --css-prefix", () => {
+        expect(plan({ prefix: "shared-" }).groups[0].name).toBe("shared-row");
+    });
+
+    it("honors an explicit --css-target", () => {
+        write("src/styles/app.css", "");
+        write("src/main.tsx", 'import "./styles/app.css";\n');
+        expect(plan({ target: "src/styles/app.css" }).target.file).toBe(
+            join("src", "styles", "app.css"),
+        );
+    });
+});
+
+describe("applyExtraction", () => {
+    beforeEach(() => {
+        project();
+        twoCopies();
+    });
+
+    it("moves the rule, deletes the local copies and rewrites the JSX", () => {
+        const result = applyExtraction({ plan: plan() });
+        expect(result.moved).toBe(2);
+        expect(result.rules).toBe(1);
+
+        const global = readFileSync(join(root, "src/index.css"), "utf8");
+        expect(global).toContain(".u-row {");
+        expect(global).toContain("align-items: center;");
+        expect(global).toContain("extraído por");
+
+        const card = readFileSync(join(root, "src/components/Card.module.css"), "utf8");
+        expect(card).not.toContain(".row");
+        expect(card).toContain(".title");
+
+        // `className={styles.row}` loses the braces; the other class is untouched.
+        const tsx = readFileSync(join(root, "src/components/Card.tsx"), "utf8");
+        expect(tsx).toContain('<div className="u-row">');
+        expect(tsx).toContain("{styles.title}");
+    });
+
+    it("writes nothing on a dry run", () => {
+        const before = readFileSync(join(root, "src/components/Card.tsx"), "utf8");
+        const result = applyExtraction({ plan: plan(), dryRun: true });
+        expect(result.moved).toBe(2);
+        expect(readFileSync(join(root, "src/components/Card.tsx"), "utf8")).toBe(before);
+        expect(readFileSync(join(root, "src/index.css"), "utf8")).not.toContain(".u-row");
+    });
+
+    it("leaves nothing to do on a second run", () => {
+        applyExtraction({ plan: plan() });
+        expect(plan().groups).toEqual([]);
+    });
+
+    it("rewrites a class read through a string index", () => {
+        write(
+            "src/components/List.tsx",
+            'import styles from "./List.module.css";\n\nexport const List = () => <li className={styles["line"]} />;\n',
+        );
+        applyExtraction({ plan: plan() });
+        expect(readFileSync(join(root, "src/components/List.tsx"), "utf8")).toContain(
+            'className="u-row"',
+        );
+    });
+
+    it("keeps the surrounding call when the class is one argument of many", () => {
+        write(
+            "src/components/List.tsx",
+            'import { cn } from "tempest-react-sdk";\nimport styles from "./List.module.css";\n\nexport const List = ({ on }: { on: boolean }) => (\n  <li className={cn(styles.line, on && styles.title)} />\n);\n',
+        );
+        applyExtraction({ plan: plan() });
+        expect(readFileSync(join(root, "src/components/List.tsx"), "utf8")).toContain(
+            'cn("u-row", on && styles.title)',
+        );
+    });
+});
+
+describe("planExtraction — refusals", () => {
+    beforeEach(project);
+
+    /** The reason attached to the first refusal, for a fixture built by the caller. */
+    const refusal = () => plan().refusals[0]?.reason ?? "";
+
+    it("refuses a class another rule in the same module mentions", () => {
+        twoCopies();
+        write("src/components/Card.module.css", `${ROW}.row:hover {\n    opacity: 0.8;\n}\n`);
+        expect(refusal()).toContain("ficaria sem sujeito");
+        expect(plan().groups).toEqual([]);
+    });
+
+    it("refuses a rule inside an at-rule", () => {
+        twoCopies();
+        write(
+            "src/components/Card.module.css",
+            `.title {\n    font-weight: 600;\n}\n@media (min-width: 600px) {\n    .row {\n        display: flex;\n        align-items: center;\n        gap: 8px;\n    }\n}\n`,
+        );
+        expect(refusal()).toContain("mudaria quando a regra vale");
+    });
+
+    it("refuses when the module would be left empty", () => {
+        twoCopies();
+        write(
+            "src/components/Card.module.css",
+            ".row {\n    display: flex;\n    align-items: center;\n    gap: 8px;\n}\n",
+        );
+        expect(refusal()).toContain("única regra do módulo");
+    });
+
+    it("refuses a module used through a computed key", () => {
+        twoCopies();
+        write(
+            "src/components/Card.tsx",
+            'import styles from "./Card.module.css";\n\nexport const Card = ({ k }: { k: string }) => (\n  <div className={styles[k]}>\n    <b className={styles.row} />\n  </div>\n);\n',
+        );
+        expect(refusal()).toContain("não estática");
+    });
+
+    it("refuses a module whose styles object is passed around whole", () => {
+        twoCopies();
+        write(
+            "src/components/Card.tsx",
+            'import styles from "./Card.module.css";\n\nexport const Card = () => (\n  <div className={styles.row} data-keys={Object.keys(styles).length} />\n);\n',
+        );
+        expect(refusal()).toContain("usado inteiro");
+    });
+
+    it("refuses a class no source file reads", () => {
+        twoCopies();
+        write(
+            "src/components/Card.tsx",
+            'import styles from "./Card.module.css";\n\nexport const Card = () => <div className={styles.title} />;\n',
+        );
+        expect(refusal()).toContain("código morto");
+    });
+
+    it("needs the block in two different files", () => {
+        write(
+            "src/components/Card.module.css",
+            `${ROW}.other {\n    display: flex;\n    align-items: center;\n    gap: 8px;\n}\n`,
+        );
+        write(
+            "src/components/Card.tsx",
+            'import styles from "./Card.module.css";\n\nexport const Card = () => (\n  <div className={styles.row}>\n    <b className={styles.other} />\n    <i className={styles.title} />\n  </div>\n);\n',
+        );
+        expect(plan().groups).toEqual([]);
+    });
+
+    it("refuses when the new name is already taken in the global sheet", () => {
+        twoCopies();
+        write("src/index.css", ".u-row {\n    display: block;\n}\n");
+        const result = plan();
+        expect(result.groups).toEqual([]);
+        expect(result.refusals[0].reason).toContain("já existe na folha global");
+    });
+
+    it("reports a missing global stylesheet instead of creating one", () => {
+        twoCopies();
+        rmSync(join(root, "src/index.css"));
+        const result = plan();
+        expect(result.status).toBe("no-target");
+        expect(result.message).toContain("nenhuma folha global");
+    });
+
+    it("refuses a global stylesheet nobody imports", () => {
+        twoCopies();
+        write("src/main.tsx", "export const main = 1;\n");
+        const result = plan();
+        expect(result.status).toBe("no-target");
+        expect(result.message).toContain("não é importada");
+    });
+
+    it("refuses a CSS Module as the target", () => {
+        twoCopies();
+        write("src/theme.module.css", ".x { color: red; }\n");
+        const result = plan({ target: "src/theme.module.css" });
+        expect(result.status).toBe("no-target");
+        expect(result.message).toContain("é um CSS Module");
+    });
+
+    it("reports a missing TypeScript instead of guessing at the call sites", () => {
+        twoCopies();
+        rmSync(join(root, "node_modules", "typescript"), { recursive: true, force: true });
+        const result = plan();
+        expect(result.status).toBe("no-typescript");
+    });
+});

package/bin/lib/css/fix.e2e.test.mjs

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -97,3 +98,93 @@ describe("tempest fix — the CSS pass", () => {
         expect(code).toBe(1);
     });
 });
+
+const TYPESCRIPT_DIR = dirname(createRequire(import.meta.url).resolve("typescript/package.json"));
+
+/**
+ * A fixture with two modules declaring the same block, each read from its own
+ * component, plus the global sheet the entry imports and the project's own
+ * TypeScript — everything `--extract-css` refuses to work without.
+ */
+function extractableProject() {
+    const rule =
+        ".row {\n    display: flex;\n    align-items: center;\n    gap: 8px;\n}\n.title {\n    font-weight: 600;\n}\n";
+    writeFileSync(
+        join(root, "package.json"),
+        JSON.stringify({ name: "fixture", devDependencies: { typescript: "^5" } }),
+    );
+    write(
+        "tsconfig.json",
+        JSON.stringify({ compilerOptions: { baseUrl: ".", paths: { "@/*": ["./src/*"] } } }),
+    );
+    write("src/index.css", ":root {\n    --brand: #0d6efd;\n}\n");
+    write("src/main.tsx", 'import "./index.css";\n');
+    write("src/components/Card.module.css", rule);
+    write(
+        "src/components/Card.tsx",
+        'import styles from "./Card.module.css";\n\nexport const Card = () => (\n  <div className={styles.row}>\n    <b className={styles.title} />\n  </div>\n);\n',
+    );
+    write("src/components/List.module.css", rule.replace(".row", ".line"));
+    write(
+        "src/components/List.tsx",
+        'import styles from "@/components/List.module.css";\n\nexport const List = () => (\n  <li className={styles.line}>\n    <b className={styles.title} />\n  </li>\n);\n',
+    );
+    mkdirSync(join(root, "node_modules"), { recursive: true });
+    symlinkSync(TYPESCRIPT_DIR, join(root, "node_modules", "typescript"), "dir");
+}
+
+describe("tempest fix --extract-css", () => {
+    it("moves the repeated block into the global sheet and rewrites the JSX", () => {
+        extractableProject();
+        const { out } = fix(["--extract-css"]);
+        expect(out).toContain("css extract");
+        expect(out).toContain("movidas 2 regra(s)");
+        expect(readFileSync(join(root, "src/index.css"), "utf8")).toContain(".u-row {");
+        expect(readFileSync(join(root, "src/components/Card.tsx"), "utf8")).toContain(
+            'className="u-row"',
+        );
+        expect(readFileSync(join(root, "src/components/Card.module.css"), "utf8")).not.toContain(
+            ".row",
+        );
+    });
+
+    it("writes nothing under --dry-run", () => {
+        extractableProject();
+        const before = readFileSync(join(root, "src/components/Card.tsx"), "utf8");
+        const { out } = fix(["--extract-css", "--dry-run"]);
+        expect(out).toContain("moveria 2 regra(s)");
+        expect(readFileSync(join(root, "src/components/Card.tsx"), "utf8")).toBe(before);
+    });
+
+    it("honors --css-prefix without treating its value as a path", () => {
+        extractableProject();
+        fix(["--extract-css", "--css-prefix", "shared-"]);
+        expect(readFileSync(join(root, "src/index.css"), "utf8")).toContain(".shared-row {");
+    });
+
+    it("does nothing extra when the flag is absent", () => {
+        extractableProject();
+        const { out } = fix([]);
+        expect(out).not.toContain("css extract");
+        expect(readFileSync(join(root, "src/index.css"), "utf8")).not.toContain(".u-row");
+    });
+
+    it("rejects --css-target without --extract-css", () => {
+        extractableProject();
+        const { out, code } = fix(["--css-target", "src/index.css"]);
+        expect(out).toContain("só valem com --extract-css");
+        expect(code).toBe(1);
+    });
+
+    it("reports the reason instead of extracting what it cannot prove safe", () => {
+        extractableProject();
+        write(
+            "src/components/Card.module.css",
+            ".row {\n    display: flex;\n    align-items: center;\n    gap: 8px;\n}\n.row:hover {\n    opacity: 0.8;\n}\n.title {\n    font-weight: 600;\n}\n",
+        );
+        const { out } = fix(["--extract-css"]);
+        expect(out).toContain("não extraído");
+        expect(out).toContain("nada a extrair");
+        expect(readFileSync(join(root, "src/index.css"), "utf8")).not.toContain(".u-row");
+    });
+});

package/bin/lib/css/index.mjs

@@ -3,6 +3,16 @@ export { analyzeCss, applyCssFixes } from "./analyze.mjs";
 export { collectStylesheets, customPropertiesInSources, looksMinified } from "./collect.mjs";
 export { countBySeverity, finding, SEVERITY, sortFindings } from "./findings.mjs";
 export { fixCss } from "./fix.mjs";
+export {
+    applyExtraction,
+    classNamesIn,
+    findGlobalSheet,
+    kebab,
+    loneClass,
+    planExtraction,
+    renderRule,
+} from "./extract.mjs";
+export { collectSources, findClassUses, indexClassUses, resolveSpecifier } from "./references.mjs";
 export { maskValue, normalizeSelectors, parseCss, stripComments } from "./parse.mjs";
 export { distance, KNOWN_AT_RULES, KNOWN_PROPERTIES, nearest } from "./properties.mjs";
 export { matchUtility, repetitionFindings } from "./repetition.mjs";

package/bin/lib/css/references.mjs

@@ -0,0 +1,238 @@
+// Where a CSS Module class is used in TypeScript.
+//
+// Extraction cannot be a CSS-only edit: deleting `.row` from `Card.module.css`
+// leaves `styles.row` in `Card.tsx` evaluating to `undefined`, which renders an
+// element with `class="undefined"` and no styling — valid code, silent damage. So
+// the codemod only touches a class it can see **every** use of.
+//
+// "Every use" is decided with the project's own TypeScript compiler rather than a
+// regex: `styles.row` inside a comment, a template literal or a string is not a
+// use, and a regex cannot tell. When anything about a module's usage is not
+// statically decidable — `styles[key]`, `Object.keys(styles)`, the object handed
+// to a child as a prop — the whole module is declared opaque and nothing in it is
+// extracted.
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, extname, join, relative, resolve } from "node:path";
+
+const SOURCE_EXTS = new Set([".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"]);
+const SKIP_DIRS = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    ".git",
+    ".vite",
+    ".next",
+    ".turbo",
+    ".cache",
+]);
+
+/** Every source file under `root` the codemod may read. */
+export function collectSources({ root, maxFiles = 4000 }) {
+    const out = [];
+    const walk = (dir) => {
+        if (out.length >= maxFiles) return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (SKIP_DIRS.has(entry.name)) continue;
+            if (entry.name.startsWith(".") && entry.isDirectory()) continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) walk(full);
+            else if (entry.isFile() && SOURCE_EXTS.has(extname(entry.name))) out.push(full);
+        }
+    };
+    walk(root);
+    return out.sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Resolve an import specifier to an absolute path, honoring the project alias.
+ *
+ * @param {object} params
+ * @param {string} params.specifier - Raw module specifier.
+ * @param {string} params.fromFile - File the import is written in.
+ * @param {{ prefix: string, baseDir: string } | null} params.alias
+ * @returns {string | null} Absolute path, or `null` when it is a bare package.
+ */
+export function resolveSpecifier({ specifier, fromFile, alias }) {
+    if (specifier.startsWith("./") || specifier.startsWith("../")) {
+        return resolve(dirname(fromFile), specifier);
+    }
+    if (alias && specifier.startsWith(`${alias.prefix}/`)) {
+        return resolve(alias.baseDir, specifier.slice(alias.prefix.length + 1));
+    }
+    return null;
+}
+
+/**
+ * Find every static use of a CSS Module's classes in one source file.
+ *
+ * @param {object} params
+ * @param {string} params.filePath
+ * @param {string} params.text - File contents.
+ * @param {object} params.ts - The project's `typescript` module.
+ * @param {Set<string>} params.moduleFiles - Absolute paths of the CSS Modules of interest.
+ * @param {{ prefix: string, baseDir: string } | null} params.alias
+ * @returns {{
+ *   uses: Array<{ module: string, className: string, start: number, end: number, line: number }>,
+ *   opaque: Array<{ module: string, reason: string, line: number }>,
+ * }}
+ */
+export function findClassUses({ filePath, text, ts, moduleFiles, alias }) {
+    const uses = [];
+    const opaque = [];
+    const source = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true);
+
+    /** Local identifier → absolute CSS Module path, for the modules we care about. */
+    const bindings = new Map();
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement)) continue;
+        const specifier = statement.moduleSpecifier;
+        if (!ts.isStringLiteral(specifier)) continue;
+        const target = resolveSpecifier({ specifier: specifier.text, fromFile: filePath, alias });
+        if (!target || !moduleFiles.has(target)) continue;
+        const clause = statement.importClause;
+        if (clause?.name) bindings.set(clause.name.text, target);
+        // `import * as styles from "./x.module.css"` behaves the same for our purposes.
+        if (clause?.namedBindings && ts.isNamespaceImport(clause.namedBindings)) {
+            bindings.set(clause.namedBindings.name.text, target);
+        }
+    }
+    if (bindings.size === 0) return { uses, opaque };
+
+    const lineOf = (pos) => source.getLineAndCharacterOfPosition(pos).line + 1;
+
+    /**
+     * Range to replace with the new class string.
+     *
+     * `className={styles.row}` widens to the whole `{…}` container so the result
+     * is `className="u-row"` rather than `className={"u-row"}` — the braces are
+     * only there because the value was an expression, and leaving them behind
+     * would make every rewritten attribute read like generated code.
+     */
+    const replacementRange = (access) => {
+        const parent = access.parent;
+        if (
+            parent &&
+            ts.isJsxExpression(parent) &&
+            parent.expression === access &&
+            parent.parent &&
+            ts.isJsxAttribute(parent.parent)
+        ) {
+            return { start: parent.getStart(source), end: parent.getEnd() };
+        }
+        return { start: access.getStart(source), end: access.getEnd() };
+    };
+
+    /**
+     * Record a use, or mark the module opaque when the reference is not a plain
+     * `styles.name` / `styles["name"]` read.
+     */
+    const visit = (node) => {
+        if (ts.isIdentifier(node) && bindings.has(node.text)) {
+            const module = bindings.get(node.text);
+            const parent = node.parent;
+            const isImportName =
+                parent &&
+                (ts.isImportClause(parent) || ts.isNamespaceImport(parent)) &&
+                parent.name === node;
+            if (isImportName) return;
+
+            if (parent && ts.isPropertyAccessExpression(parent) && parent.expression === node) {
+                uses.push({
+                    module,
+                    className: parent.name.text,
+                    ...replacementRange(parent),
+                    line: lineOf(parent.getStart(source)),
+                });
+                return;
+            }
+            if (
+                parent &&
+                ts.isElementAccessExpression(parent) &&
+                parent.expression === node &&
+                parent.argumentExpression &&
+                ts.isStringLiteralLike(parent.argumentExpression)
+            ) {
+                uses.push({
+                    module,
+                    className: parent.argumentExpression.text,
+                    ...replacementRange(parent),
+                    line: lineOf(parent.getStart(source)),
+                });
+                return;
+            }
+            opaque.push({
+                module,
+                reason:
+                    parent && ts.isElementAccessExpression(parent)
+                        ? "acesso dinâmico (`styles[expr]`)"
+                        : "o objeto de estilos é usado inteiro, não por classe",
+                line: lineOf(node.getStart(source)),
+            });
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+
+    ts.forEachChild(source, visit);
+    return { uses, opaque };
+}
+
+/**
+ * Index every static class use across the project.
+ *
+ * @param {object} params
+ * @param {string} params.root
+ * @param {object} params.ts
+ * @param {Iterable<string>} params.modulePaths - Absolute paths of CSS Modules.
+ * @param {{ prefix: string, baseDir: string } | null} params.alias
+ * @returns {{
+ *   byModule: Map<string, Map<string, Array<{ file: string, start: number, end: number, line: number }>>>,
+ *   opaqueModules: Map<string, { file: string, reason: string, line: number }>,
+ *   texts: Map<string, string>,
+ * }}
+ */
+export function indexClassUses({ root, ts, modulePaths, alias }) {
+    const moduleFiles = new Set(modulePaths);
+    const byModule = new Map();
+    const opaqueModules = new Map();
+    const texts = new Map();
+
+    for (const file of collectSources({ root })) {
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        } catch {
+            continue;
+        }
+        if (!text.includes(".module.css")) continue;
+        const { uses, opaque } = findClassUses({ filePath: file, text, ts, moduleFiles, alias });
+        if (uses.length === 0 && opaque.length === 0) continue;
+        texts.set(file, text);
+        for (const entry of opaque) {
+            if (!opaqueModules.has(entry.module)) {
+                opaqueModules.set(entry.module, {
+                    file: relative(root, file),
+                    reason: entry.reason,
+                    line: entry.line,
+                });
+            }
+        }
+        for (const use of uses) {
+            const classes = byModule.get(use.module) ?? new Map();
+            const sites = classes.get(use.className) ?? [];
+            sites.push({ file, start: use.start, end: use.end, line: use.line });
+            classes.set(use.className, sites);
+            byModule.set(use.module, classes);
+        }
+    }
+
+    return { byModule, opaqueModules, texts };
+}

package/bin/tempest.mjs

@@ -14,7 +14,7 @@ import { fileURLToPath } from "node:url";
 import { aliasImports } from "./lib/alias/index.mjs";
 import { loadTypeScript } from "./lib/alias/typescript.mjs";
 import { readTsconfig } from "./lib/alias/tsconfig.mjs";
-import { analyzeCss, applyCssFixes } from "./lib/css/index.mjs";
+import { analyzeCss, applyCssFixes, applyExtraction, planExtraction } from "./lib/css/index.mjs";
 import { checkLucide } from "./lib/doctor/lucide.mjs";
 import { generateRegistry, loadIconTables } from "./lib/icons/generate.mjs";
 import { generate } from "./lib/openapi/generate.mjs";
@@ -814,7 +814,36 @@ function lint(args) {
 }
 
 /** Flags `fix` owns itself; anything else is rejected rather than forwarded. */
-const FIX_FLAGS = new Set(["--no-alias", "--no-css", "--dry-run"]);
+const FIX_FLAGS = new Set(["--no-alias", "--no-css", "--dry-run", "--extract-css"]);
+
+/** Flags of `fix` that consume the next argument as their value. */
+const FIX_VALUE_FLAGS = new Set(["--css-target", "--css-prefix"]);
+
+/**
+ * Split the `fix` argv into flags, flag values and positional paths.
+ *
+ * `splitArgs` cannot do this: it classifies by leading `-`, so the value of
+ * `--css-target src/index.css` would land in the path list and `fix` would run
+ * against a single stylesheet instead of the project.
+ *
+ * @param {string[]} args
+ * @returns {{ flags: string[], values: Record<string, string>, paths: string[] }}
+ */
+function parseFixArgs(args) {
+    const flags = [];
+    const values = {};
+    const paths = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (FIX_VALUE_FLAGS.has(arg)) {
+            values[arg] = args[i + 1] ?? "";
+            i += 1;
+            continue;
+        }
+        (arg.startsWith("-") ? flags : paths).push(arg);
+    }
+    return { flags, values, paths };
+}
 
 /**
  * Print the alias pass result.
@@ -875,9 +904,12 @@ function severityMark(severity) {
  * @param {object} params
  * @param {string[]} params.targets - Positional paths from the command line.
  * @param {boolean} params.dryRun
+ * @param {boolean} [params.extract] - Run the opt-in cross-file extraction codemod.
+ * @param {string} [params.target] - Global stylesheet to extract into.
+ * @param {string} [params.prefix] - Prefix for the extracted class names.
  * @returns {number} Exit status contribution.
  */
-function cssPass({ targets, dryRun }) {
+function cssPass({ targets, dryRun, extract = false, target, prefix }) {
     console.log(
         `${c.dim}→ css (dedupe declarations · drop dead rules)${dryRun ? " [dry-run]" : ""}${c.reset}`,
     );
@@ -939,20 +971,95 @@ function cssPass({ targets, dryRun }) {
             `  ${c.red}✗ ${analysis.counts.error} CSS syntax error(s)${c.reset} ${c.dim}— those files were not touched; fix them and run again${c.reset}`,
         );
     }
-    return result.errors.length || analysis.counts.error ? 1 : 0;
+
+    const extractStatus = extract
+        ? extractPass({ targets, dryRun, target, prefix, dedupedFiles: result.files.length })
+        : 0;
+
+    return result.errors.length || analysis.counts.error || extractStatus ? 1 : 0;
+}
+
+/**
+ * The opt-in extraction codemod: a block repeated across CSS Modules becomes one
+ * class in the project's global stylesheet, and the `styles.x` that pointed at
+ * the local copies become the new class name.
+ *
+ * The analysis is re-run from disk rather than reused: the dedupe pass that just
+ * finished may have rewritten these same files, and every edit here is a splice at
+ * a recorded offset. Reusing the stale parse would splice at positions that no
+ * longer exist.
+ *
+ * @param {object} params
+ * @param {string[]} params.targets
+ * @param {boolean} params.dryRun
+ * @param {string} [params.target]
+ * @param {string} [params.prefix]
+ * @param {number} params.dedupedFiles - Files the dedupe pass touched, for the re-read note.
+ * @returns {number} Exit status contribution.
+ */
+function extractPass({ targets, dryRun, target, prefix, dedupedFiles }) {
+    console.log(
+        `${c.dim}→ css extract (bloco repetido → classe global)${dryRun ? " [dry-run]" : ""}${c.reset}`,
+    );
+    let plan;
+    try {
+        const fresh = analyzeCss({ root: ROOT, targets, selfDir: SELF_DIR });
+        if (dedupedFiles > 0 && !dryRun) {
+            console.log(`  ${c.dim}re-analisado depois da passada de dedupe${c.reset}`);
+        }
+        plan = planExtraction({ analysis: fresh, root: ROOT, target, prefix });
+    } catch (err) {
+        console.log(
+            `  ${c.red}✗ extraction failed${c.reset} ${c.dim}${err?.message ?? err}${c.reset}`,
+        );
+        return 1;
+    }
+
+    if (plan.status !== "ok") {
+        console.log(`  ${c.yellow}! ${plan.message}${c.reset}`);
+        return 0;
+    }
+    for (const refusal of plan.refusals) {
+        console.log(
+            `  [${c.yellow}!${c.reset}] ${refusal.file}:${refusal.line} ${c.dim}não extraído — ${refusal.reason}${c.reset}`,
+        );
+    }
+    if (plan.groups.length === 0) {
+        console.log(`  ${c.dim}nada a extrair${c.reset}`);
+        return 0;
+    }
+
+    const result = applyExtraction({ plan, dryRun });
+    for (const file of result.files) {
+        console.log(`  ${file.file} ${c.dim}${file.changes.length}${c.reset}`);
+        for (const change of file.changes) console.log(`    ${c.dim}${change}${c.reset}`);
+    }
+    for (const err of result.errors) {
+        console.log(`  ${c.red}✗ ${err.file}${c.reset} ${c.dim}${err.message}${c.reset}`);
+    }
+    const verb = dryRun ? "moveria" : "movidas";
+    console.log(
+        `  ${c.green}✓${c.reset} ${verb} ${result.moved} regra(s) local(is) para ${result.rules} classe(s) em ${plan.target.file}`,
+    );
+    return result.errors.length ? 1 : 0;
 }
 
 function fix(args) {
-    const { flags, paths } = splitArgs(args);
+    const { flags, values, paths } = parseFixArgs(args);
     const unknown = flags.filter((f) => !FIX_FLAGS.has(f));
     if (unknown.length) {
         console.error(
-            `${c.red}✗ Unknown flag for fix: ${unknown.join(", ")}${c.reset} — supported: ${[...FIX_FLAGS].join(", ")}`,
+            `${c.red}✗ Unknown flag for fix: ${unknown.join(", ")}${c.reset} — supported: ${[...FIX_FLAGS, ...FIX_VALUE_FLAGS].join(", ")}`,
         );
         return 1;
     }
     const targets = paths.length ? paths : ["."];
     const dryRun = flags.includes("--dry-run");
+    const extract = flags.includes("--extract-css");
+    if (!extract && (values["--css-target"] || values["--css-prefix"])) {
+        console.error(`${c.red}✗ --css-target/--css-prefix só valem com --extract-css.${c.reset}`);
+        return 1;
+    }
 
     let aliasStatus = 0;
     if (!flags.includes("--no-alias")) {
@@ -962,7 +1069,15 @@ function fix(args) {
         aliasStatus = result.status === "error" ? 1 : 0;
     }
 
-    const cssStatus = flags.includes("--no-css") ? 0 : cssPass({ targets, dryRun });
+    const cssStatus = flags.includes("--no-css")
+        ? 0
+        : cssPass({
+              targets,
+              dryRun,
+              extract,
+              target: values["--css-target"],
+              prefix: values["--css-prefix"],
+          });
 
     if (dryRun) return aliasStatus || cssStatus;
 
@@ -1125,6 +1240,13 @@ ${c.bold}fix options${c.reset}
                     write nothing
   --no-alias        Skip the alias pass
   --no-css          Skip the CSS pass (analysis and dead-code removal)
+  --extract-css     Move a declaration block repeated across CSS Modules into the
+                    project's global stylesheet and rewrite the styles.x reads that
+                    pointed at the local copies (opt-in — it changes what couples
+                    to what). Refuses anything it cannot prove safe, with a reason
+  --css-target <f>  Global stylesheet to extract into (default: the first of
+                    src/styles/globals.css, src/globals.css, src/index.css, …)
+  --css-prefix <p>  Prefix for extracted class names (default: u-)
 
 ${c.bold}Options${c.reset}
   -h, --help        Show this help

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempest-react-sdk",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "description": "SDK público da Tempest com componentes, hooks e integrações para projetos React.",
   "type": "module",
   "license": "MIT",