@codefast/cli 0.3.13-canary.0 → 0.3.13-canary.2

package/dist/lib/arrange/domain/constants.js

@@ -0,0 +1,180 @@
+/** Analyze report: long literal threshold (token count). */
+export const LONG_STRING_TOKEN_THRESHOLD = 18;
+/**
+ * Minimum token count for a string to be considered a candidate for grouping
+ * in the apply/preview pipeline. Intentionally much lower than
+ * {@link LONG_STRING_TOKEN_THRESHOLD} (analyze only).
+ */
+export const APPLY_MIN_TOKENS = 2;
+/**
+ * Minimum tokens a group must have to stand alone before singleton-merging.
+ * Set to 2 so single-token groups are not collapsed into unrelated buckets by the merger.
+ */
+export const MIN_GROUP_TOKENS = 2;
+/** Dynamic max groups clamp: base bound. */
+export const MAX_GROUPS_BASE = 4;
+/** Dynamic max groups clamp: upper cap. */
+export const MAX_GROUPS_CAP = 24;
+/**
+ * Extra slots so a few state / aria groups do not force `capGroups` to merge
+ * unrelated buckets (e.g. `bg-border` + `outline-hidden`).
+ */
+export const MAX_GROUPS_HEADROOM = 2;
+/** Maximum findings printed per category in the analyze report. */
+export const MAX_REPORT_LINES = 40;
+/** Maximum recursion depth when traversing `tv()` object literals. */
+export const MAX_OBJECT_DEPTH = 12;
+/** Maximum depth when peeling conditional / parens / arrays inside `cn(...)` args. */
+export const MAX_CLASS_EXPR_DEPTH = 12;
+/**
+ * Maximum variant-stripping passes in {@link stripVariants}.
+ * Real-world Tailwind stacks rarely exceed 4–5 segments (e.g. `@md/sidebar:group-hover:dark:focus-visible:`);
+ * 12 is a conservative safety cap that prevents runaway loops on malformed input.
+ */
+export const MAX_STRIP_VARIANT_PASSES = 12;
+/**
+ * Passed when optional `knownBindings` is missing — size 0 disables matching
+ * for `cn` / `tv` identifier resolution.
+ */
+export const EMPTY_CN_TV_BINDINGS = new Set();
+/**
+ * Bucket sort order — **render pipeline** (lower → earlier in output).
+ * Existence → Position → Layout → Sizing → Spacing → Shape → Background → Shadow
+ * → Typography → Composite → Motion → Starting → Behavior → State (variants) → Selector variants.
+ */
+export const BUCKET_ORDER = {
+    existence: 0,
+    position: 1,
+    layout: 2,
+    sizing: 3,
+    spacing: 4,
+    shape: 5,
+    background: 6,
+    shadow: 7,
+    typography: 8,
+    composite: 9,
+    motion: 10,
+    starting: 11,
+    behavior: 12,
+    state: 13,
+    selector: 14,
+    other: 15,
+    arbitrary: 16,
+};
+/**
+ * Compatible bucket **pairs** — two adjacent tokens whose buckets appear in the same
+ * `Set` may stay in one `cn()` string chunk. Compatibility is **not transitive**: there is
+ * no `{position, sizing}` pair, so `fixed inset-0` and `overflow-auto` become **separate**
+ * literals unless **layout** tokens sit between them in sorted order; then
+ * `position↔layout` and `layout↔sizing` each justify one hop and the whole “box in flow”
+ * (place + tracks + scrollport) stays in one chunk — co-located because they jointly define
+ * stacking and scroll behavior for the same surface.
+ */
+export const COMPATIBLE_BUCKET_SETS = [
+    // existence + position: named container / group / peer context edited next to inset & z-index.
+    new Set(["existence", "position"]),
+    // existence + layout: `group/cmd` + `flex …` are one template row (context + grid/flex).
+    new Set(["existence", "layout"]),
+    // position + layout: `fixed inset-0` + `grid` describe the same stacking + track shell.
+    new Set(["position", "layout"]),
+    // layout + sizing: `grid` + `overflow-auto` / min size are one scrollport / track concern.
+    new Set(["layout", "sizing"]),
+    // shape + shadow: radius/border + shadow/outline overlay are one “chrome” literal in UIs.
+    new Set(["shape", "shadow"]),
+    // background + shadow: fill + depth (card surface) without splitting noise across args.
+    new Set(["background", "shadow"]),
+    // background + typography: destructive buttons etc. (`bg-*` + `text-*` on the same control).
+    new Set(["background", "typography"]),
+    // layout + typography: title rows (`flex` + `text-sm`) in one literal when adjacent in sort order.
+    new Set(["layout", "typography"]),
+    // sizing + typography: chart shell (`aspect-video` + `text-xs`) before selector-variant chunks.
+    new Set(["sizing", "typography"]),
+    // motion + behavior: `transition-*` with `pointer-events-*` / `select-*` on the same surface.
+    new Set(["motion", "behavior"]),
+    // motion + starting: `transition` beside `starting:*` for coordinated enter/exit motion.
+    new Set(["motion", "starting"]),
+    // composite + motion: transforms then transitions (`-translate-*` + `transition-*` + `ease-*`).
+    new Set(["composite", "motion"]),
+    // sizing + composite: width/position utilities with transforms in one interaction block.
+    new Set(["sizing", "composite"]),
+    // sizing + spacing: width utilities with padding on the same slot (`w-auto` + `px-3`).
+    new Set(["sizing", "spacing"]),
+];
+/**
+ * Responsive / variant prefix — Tailwind v4 aware.
+ *
+ * v3: sm: md: … — v4: @sm:, @min-[600px]:, @[480px]:, named @md/sidebar:,
+ * viewport md/sidebar:, min-[100px]: / max-[100px]:, …
+ */
+export const RESPONSIVE_PREFIX = /^(?:@(?:min|max)-\[[^\]]+\]:|@\[[^\]]+\]:|@(?:[a-z0-9]+(?:-[a-z0-9]+)*)(?:\/[a-z][a-z0-9-]*)?:|(?:max-|min-)?(?:sm|md|lg|xl|2xl|3xl)(?:\/[a-z][a-z0-9-]*)?:|(?:max-|min-)\[[^\]]+\]:)/;
+/** State variant stems — hoisted to module scope (not recreated per call). */
+export const STATE_PREFIXES = new Set([
+    "hover",
+    "focus",
+    "focus-within",
+    "focus-visible",
+    "active",
+    "visited",
+    "link",
+    "any-link",
+    "disabled",
+    "enabled",
+    "checked",
+    "indeterminate",
+    "required",
+    "optional",
+    "valid",
+    "invalid",
+    "in-range",
+    "out-of-range",
+    "read-only",
+    "read-write",
+    "placeholder-shown",
+    "default",
+    "autofill",
+    "open",
+    "closed",
+    "first",
+    "last",
+    "only",
+    "odd",
+    "even",
+    "first-of-type",
+    "last-of-type",
+    "only-of-type",
+    "first-child",
+    "last-child",
+    "only-child",
+    "empty",
+    "target",
+    "group",
+    "peer",
+    "aria",
+    "data",
+    "dark",
+    "light",
+    "supports",
+    "motion-reduce",
+    "motion-safe",
+    "print",
+    "screen",
+    "ltr",
+    "rtl",
+    "not",
+    "has",
+    "in",
+    "nth",
+    "file",
+    "selection",
+    "marker",
+    "placeholder",
+    "before",
+    "after",
+    "first-line",
+    "first-letter",
+    "backdrop",
+    "details-content",
+    "popover-open",
+]);
+/** Default directory for arrange analyze/preview/apply when no target is passed. */
+export const DEFAULT_ARRANGE_TARGET = "packages/ui/src/components";

package/dist/lib/arrange/domain/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Structured errors for the arrange CLI library (throw from lib; handle exit in commands).
+ */
+export declare const ArrangeErrorCode: {
+    readonly TARGET_NOT_FOUND: "TARGET_NOT_FOUND";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly INTERNAL: "INTERNAL";
+};
+export type ArrangeErrorCode = (typeof ArrangeErrorCode)[keyof typeof ArrangeErrorCode];
+export declare class ArrangeError extends Error {
+    readonly code: ArrangeErrorCode;
+    constructor(code: ArrangeErrorCode, message: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/arrange/domain/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/lib/arrange/domain/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,gBAAgB;aAC3B,gBAAgB,EAAE,kBAAkB;aACpC,aAAa,EAAE,eAAe;aAC9B,QAAQ,EAAE,UAAU;CACZ,CAAC;AAGX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAExF,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAEhC,YAAY,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAI1E;CACF"}

package/dist/lib/arrange/domain/errors.js

@@ -0,0 +1,16 @@
+/**
+ * Structured errors for the arrange CLI library (throw from lib; handle exit in commands).
+ */
+export const ArrangeErrorCode = {
+    TARGET_NOT_FOUND: "TARGET_NOT_FOUND",
+    INVALID_INPUT: "INVALID_INPUT",
+    INTERNAL: "INTERNAL",
+};
+export class ArrangeError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "ArrangeError";
+        this.code = code;
+    }
+}

package/dist/lib/arrange/domain/grouping.d.ts

@@ -0,0 +1,41 @@
+/**
+ * True when `staticLiteralTexts` carries the **same partition** of Tailwind tokens as
+ * `suggestedGroups` from {@link suggestCnGroups}, ignoring order of arguments and
+ * order of tokens within each chunk.
+ */
+export declare function areCnTailwindPartitionsEquivalent(staticLiteralTexts: string[], suggestedGroups: string[]): boolean;
+/**
+ * Merge singleton groups (< MIN_GROUP_TOKENS tokens) into their nearest
+ * neighbour. Prefers merging toward a bucket-compatible neighbor.
+ *
+ * Loop termination: each iteration either splices one element (shrinking the
+ * array, guaranteeing progress) or finds no singleton that can merge and exits
+ * via `changed = false`. Two mutually-incompatible singletons both hit
+ * `continue` and `changed` stays false, so the loop exits without spinning.
+ */
+export declare function mergeSingletons(groups: string[]): string[];
+/**
+ * Merge adjacent groups until total count ≤ maxGroups.
+ * Only merges pairs allowed by {@link bucketsMergeCompatible} — never glues incompatible
+ * buckets (which previously defaulted to penalty 0 and merged layout+state when over cap).
+ *
+ * Complexity: O(n²) in the number of groups — each merge pass scans all remaining adjacent
+ * pairs. In practice `n` is bounded by {@link MAX_GROUPS_CAP} (24) and typical class strings
+ * are well below that, so this is not a concern for the current usage pattern. If this ever
+ * runs in a high-throughput batch mode, consider a priority-queue approach.
+ */
+export declare function capGroups(groups: string[], maxGroups: number): string[];
+/**
+ * If a chunk is **only** bare `ease-*` timing (Motion), buffer it and prepend to the **first**
+ * **later** chunk that is predominantly `state` **and** contains some `animate-*` utility —
+ * skipping intermediate `state` chunks (`sm:…`, `group-data-[…]:…`, etc.) that sit between
+ * `ease-ui` and `data-open:animate-*`. If no such chunk exists, the ease chunk is left as-is.
+ */
+export declare function mergeEaseTimingIntoFollowingAnimatedState(groups: string[]): string[];
+export declare function suggestCnGroups(classString: string): string[];
+/**
+ * One label per suggested group: a single bucket name, or `mixed:a+b` when that chunk
+ * spans multiple Tailwind buckets (matches `codefast arrange group` stdout).
+ */
+export declare function summarizeGroupBucketLabels(groups: string[]): string[];
+//# sourceMappingURL=grouping.d.ts.map

package/dist/lib/arrange/domain/grouping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grouping.d.ts","sourceRoot":"","sources":["../../../../src/lib/arrange/domain/grouping.ts"],"names":[],"mappings":"AA2BA;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,kBAAkB,EAAE,MAAM,EAAE,EAC5B,eAAe,EAAE,MAAM,EAAE,GACxB,OAAO,CAqBT;AA+BD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CA6C1D;AAaD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAuCvE;AAED;;;;;GAKG;AACH,wBAAgB,yCAAyC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAgCpF;AAaD,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CA4F7D;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAKrE"}

package/dist/lib/arrange/domain/grouping.js

@@ -0,0 +1,307 @@
+import { BUCKET_ORDER, MAX_GROUPS_BASE, MAX_GROUPS_CAP, MAX_GROUPS_HEADROOM, MIN_GROUP_TOKENS, } from "#lib/arrange/domain/constants";
+import { bucketsCompatible, bucketsMergeCompatible, classifyToken, compositeSecondaryOrder, selectorKey, stateKey, stripVariants, tokenizeClassString, } from "#lib/arrange/domain/tokenizer";
+function isVariantKeyedBucket(bucket) {
+    return bucket === "selector" || bucket === "state" || bucket === "starting";
+}
+function variantGroupKey(bucket, classToken) {
+    return bucket === "selector" ? selectorKey(classToken) : stateKey(classToken);
+}
+/**
+ * True when `staticLiteralTexts` carries the **same partition** of Tailwind tokens as
+ * `suggestedGroups` from {@link suggestCnGroups}, ignoring order of arguments and
+ * order of tokens within each chunk.
+ */
+export function areCnTailwindPartitionsEquivalent(staticLiteralTexts, suggestedGroups) {
+    const partitionSignatures = (chunks) => chunks
+        .map((chunk) => {
+        const classTokens = tokenizeClassString(chunk);
+        return classTokens.length === 0 ? "" : [...classTokens].sort().join(" ");
+    })
+        .filter((s) => s.length > 0)
+        .sort((a, b) => a.localeCompare(b));
+    const staticPartitionSigs = partitionSignatures(staticLiteralTexts);
+    const suggestedPartitionSigs = partitionSignatures(suggestedGroups);
+    if (staticPartitionSigs.length !== suggestedPartitionSigs.length) {
+        return false;
+    }
+    for (let i = 0; i < staticPartitionSigs.length; i++) {
+        if (staticPartitionSigs[i] !== suggestedPartitionSigs[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Dominant bucket of a whitespace-delimited class group (for merge heuristics). */
+function dominantBucketOfGroup(groupStr) {
+    const counts = new Map();
+    for (const classToken of tokenizeClassString(groupStr)) {
+        const tokenBucket = classifyToken(classToken);
+        counts.set(tokenBucket, (counts.get(tokenBucket) ?? 0) + 1);
+    }
+    let best = "other";
+    let bestN = 0;
+    for (const [bucket, count] of counts) {
+        if (count > bestN) {
+            best = bucket;
+            bestN = count;
+            continue;
+        }
+        // Deterministic tie-break: prefer earlier render-pipeline bucket.
+        if (count === bestN && BUCKET_ORDER[bucket] < BUCKET_ORDER[best]) {
+            best = bucket;
+        }
+    }
+    return best;
+}
+/** Dynamic cap: more tokens → allow more groups, within [BASE, CAP]. */
+function dynamicMaxGroups(tokenCount) {
+    const byTokens = Math.ceil(tokenCount / 2) + MAX_GROUPS_HEADROOM;
+    return Math.max(MAX_GROUPS_BASE, Math.min(MAX_GROUPS_CAP, byTokens));
+}
+/**
+ * Merge singleton groups (< MIN_GROUP_TOKENS tokens) into their nearest
+ * neighbour. Prefers merging toward a bucket-compatible neighbor.
+ *
+ * Loop termination: each iteration either splices one element (shrinking the
+ * array, guaranteeing progress) or finds no singleton that can merge and exits
+ * via `changed = false`. Two mutually-incompatible singletons both hit
+ * `continue` and `changed` stays false, so the loop exits without spinning.
+ */
+export function mergeSingletons(groups) {
+    if (groups.length <= 1) {
+        return groups;
+    }
+    const result = [...groups];
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (let i = 0; i < result.length; i++) {
+            if (tokenizeClassString(result[i]).length < MIN_GROUP_TOKENS) {
+                if (result.length === 1) {
+                    break;
+                }
+                const myBucket = dominantBucketOfGroup(result[i]);
+                const prevCompat = i > 0 && bucketsMergeCompatible(myBucket, dominantBucketOfGroup(result[i - 1]));
+                const nextCompat = i < result.length - 1 &&
+                    bucketsMergeCompatible(myBucket, dominantBucketOfGroup(result[i + 1]));
+                let mergeDir;
+                if (nextCompat && !prevCompat) {
+                    mergeDir = "forward";
+                }
+                else if (prevCompat && !nextCompat) {
+                    mergeDir = "backward";
+                }
+                else if (prevCompat && nextCompat) {
+                    mergeDir = i < result.length - 1 ? "forward" : "backward";
+                }
+                else {
+                    continue;
+                }
+                if (mergeDir === "forward") {
+                    result[i + 1] = result[i] + " " + result[i + 1];
+                }
+                else {
+                    result[i - 1] = result[i - 1] + " " + result[i];
+                }
+                result.splice(i, 1);
+                changed = true;
+                break;
+            }
+        }
+    }
+    return result;
+}
+/** Tie-break when two merge candidates are both {@link bucketsMergeCompatible} (same bucket or COMPATIBLE_BUCKET_SETS). */
+function capMergePenalty(leftBucket, rightBucket) {
+    if (leftBucket === rightBucket) {
+        return 0;
+    }
+    if (bucketsCompatible(leftBucket, rightBucket)) {
+        return 0;
+    }
+    return 500;
+}
+/**
+ * Merge adjacent groups until total count ≤ maxGroups.
+ * Only merges pairs allowed by {@link bucketsMergeCompatible} — never glues incompatible
+ * buckets (which previously defaulted to penalty 0 and merged layout+state when over cap).
+ *
+ * Complexity: O(n²) in the number of groups — each merge pass scans all remaining adjacent
+ * pairs. In practice `n` is bounded by {@link MAX_GROUPS_CAP} (24) and typical class strings
+ * are well below that, so this is not a concern for the current usage pattern. If this ever
+ * runs in a high-throughput batch mode, consider a priority-queue approach.
+ */
+export function capGroups(groups, maxGroups) {
+    const result = [...groups];
+    const lengths = result.map((groupStr) => tokenizeClassString(groupStr).length);
+    while (result.length > maxGroups) {
+        const mergePairCandidates = [];
+        for (let i = 0; i < result.length - 1; i++) {
+            const dominantLeft = dominantBucketOfGroup(result[i]);
+            const dominantRight = dominantBucketOfGroup(result[i + 1]);
+            if (!bucketsMergeCompatible(dominantLeft, dominantRight)) {
+                continue;
+            }
+            mergePairCandidates.push({
+                i,
+                size: lengths[i] + lengths[i + 1],
+                penalty: capMergePenalty(dominantLeft, dominantRight),
+            });
+        }
+        if (mergePairCandidates.length === 0) {
+            break;
+        }
+        let best = mergePairCandidates[0];
+        for (const candidate of mergePairCandidates) {
+            if (candidate.penalty < best.penalty ||
+                (candidate.penalty === best.penalty && candidate.size < best.size)) {
+                best = candidate;
+            }
+        }
+        const bestIdx = best.i;
+        result[bestIdx] = result[bestIdx] + " " + result[bestIdx + 1];
+        lengths[bestIdx] = lengths[bestIdx] + lengths[bestIdx + 1];
+        result.splice(bestIdx + 1, 1);
+        lengths.splice(bestIdx + 1, 1);
+    }
+    return result;
+}
+/**
+ * If a chunk is **only** bare `ease-*` timing (Motion), buffer it and prepend to the **first**
+ * **later** chunk that is predominantly `state` **and** contains some `animate-*` utility —
+ * skipping intermediate `state` chunks (`sm:…`, `group-data-[…]:…`, etc.) that sit between
+ * `ease-ui` and `data-open:animate-*`. If no such chunk exists, the ease chunk is left as-is.
+ */
+export function mergeEaseTimingIntoFollowingAnimatedState(groups) {
+    const result = [...groups];
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (let i = 0; i < result.length; i++) {
+            if (!chunkIsOnlyEaseTimingMotion(result[i])) {
+                continue;
+            }
+            const easeStr = result[i];
+            let target = -1;
+            for (let j = i + 1; j < result.length; j++) {
+                if (dominantBucketOfGroup(result[j]) !== "state") {
+                    continue;
+                }
+                const classTokens = tokenizeClassString(result[j]);
+                if (!classTokens.some((classToken) => /^animate/.test(stripVariants(classToken)))) {
+                    continue;
+                }
+                target = j;
+                break;
+            }
+            if (target === -1) {
+                continue;
+            }
+            result[target] = `${easeStr} ${result[target]}`.trim();
+            result.splice(i, 1);
+            changed = true;
+            break;
+        }
+    }
+    return result;
+}
+function chunkIsOnlyEaseTimingMotion(groupStr) {
+    const classTokens = tokenizeClassString(groupStr);
+    if (classTokens.length === 0) {
+        return false;
+    }
+    return classTokens.every((classToken) => classifyToken(classToken) === "motion" && /^ease-/.test(stripVariants(classToken)));
+}
+export function suggestCnGroups(classString) {
+    const tokens = tokenizeClassString(classString);
+    if (tokens.length === 0) {
+        return [];
+    }
+    const classified = tokens.map((classToken, index) => ({
+        classToken,
+        bucket: classifyToken(classToken),
+        index,
+    }));
+    classified.sort((left, right) => {
+        const bucketOrderDiff = BUCKET_ORDER[left.bucket] - BUCKET_ORDER[right.bucket];
+        if (bucketOrderDiff !== 0) {
+            return bucketOrderDiff;
+        }
+        if (left.bucket === "composite" && right.bucket === "composite") {
+            const compositeOrderDiff = compositeSecondaryOrder(stripVariants(left.classToken)) -
+                compositeSecondaryOrder(stripVariants(right.classToken));
+            if (compositeOrderDiff !== 0) {
+                return compositeOrderDiff;
+            }
+        }
+        return left.index - right.index;
+    });
+    const rawGroups = [];
+    /** Bucket of the last token already placed in the current run (pairwise compat with `COMPATIBLE_BUCKET_SETS`). */
+    let lastBucketInRun = null;
+    let currentStateKey = null;
+    let currentTokens = [];
+    const flush = () => {
+        if (currentTokens.length > 0) {
+            rawGroups.push(currentTokens.join(" "));
+            currentTokens = [];
+        }
+        lastBucketInRun = null;
+        currentStateKey = null;
+    };
+    for (const { classToken, bucket: tokenBucket } of classified) {
+        if (lastBucketInRun === null) {
+            lastBucketInRun = tokenBucket;
+            currentStateKey = isVariantKeyedBucket(tokenBucket)
+                ? variantGroupKey(tokenBucket, classToken)
+                : null;
+            currentTokens.push(classToken);
+            continue;
+        }
+        if (isVariantKeyedBucket(tokenBucket)) {
+            const key = variantGroupKey(tokenBucket, classToken);
+            if (currentStateKey !== null && key !== currentStateKey) {
+                flush();
+                lastBucketInRun = tokenBucket;
+                currentStateKey = key;
+                currentTokens.push(classToken);
+                continue;
+            }
+        }
+        if (!bucketsCompatible(tokenBucket, lastBucketInRun)) {
+            flush();
+            lastBucketInRun = tokenBucket;
+            currentStateKey = isVariantKeyedBucket(tokenBucket)
+                ? variantGroupKey(tokenBucket, classToken)
+                : null;
+            currentTokens.push(classToken);
+            continue;
+        }
+        if (isVariantKeyedBucket(tokenBucket)) {
+            currentStateKey = variantGroupKey(tokenBucket, classToken);
+        }
+        else if (currentStateKey !== null) {
+            // Defensive reset: keeps state-key logic explicit if bucket rules evolve.
+            currentStateKey = null;
+        }
+        lastBucketInRun = tokenBucket;
+        currentTokens.push(classToken);
+    }
+    flush();
+    const merged = mergeSingletons(rawGroups);
+    const withEaseMerged = mergeEaseTimingIntoFollowingAnimatedState(merged);
+    // Never cap-merge below the semantic chunk count from the tokenizer (fixes layout+state glued
+    // when `preferred` compat list was empty and unrelated pairs used penalty 0).
+    const maxAllowed = Math.max(dynamicMaxGroups(tokens.length), withEaseMerged.length);
+    return capGroups(withEaseMerged, maxAllowed);
+}
+/**
+ * One label per suggested group: a single bucket name, or `mixed:a+b` when that chunk
+ * spans multiple Tailwind buckets (matches `codefast arrange group` stdout).
+ */
+export function summarizeGroupBucketLabels(groups) {
+    return groups.map((g) => {
+        const uniq = new Set(tokenizeClassString(g).map(classifyToken));
+        return uniq.size === 1 ? [...uniq][0] : `mixed:${[...uniq].sort().join("+")}`;
+    });
+}

package/dist/lib/arrange/domain/imports.d.ts

@@ -0,0 +1,7 @@
+import { type DomainSourceFile } from "#lib/arrange/domain/ast/ast-node.model";
+/**
+ * Resolve the module specifier used when injecting a `cn` import into a file.
+ */
+export declare function cnModuleSpecifierForFile(filePath: string, override?: string): string;
+export declare function ensureCnImport(sourceFile: DomainSourceFile, cnImportOverride?: string): string;
+//# sourceMappingURL=imports.d.ts.map

package/dist/lib/arrange/domain/imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imports.d.ts","sourceRoot":"","sources":["../../../../src/lib/arrange/domain/imports.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EAItB,MAAM,wCAAwC,CAAC;AAsBhD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAMpF;AAeD,wBAAgB,cAAc,CAAC,UAAU,EAAE,gBAAgB,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CA2C9F"}

package/dist/lib/arrange/domain/imports.js

@@ -0,0 +1,80 @@
+import { isDomainImportDeclaration, isDomainNamedImports, isDomainStringLiteral, } from "#lib/arrange/domain/ast/ast-node.model";
+function sourceFileImportsCn(sourceFile) {
+    for (const statement of sourceFile.statements) {
+        if (!isDomainImportDeclaration(statement) || !statement.importClause) {
+            continue;
+        }
+        const clause = statement.importClause;
+        if (clause.name?.text === "cn") {
+            return true;
+        }
+        if (clause.namedBindings && isDomainNamedImports(clause.namedBindings)) {
+            for (const importedBinding of clause.namedBindings.elements) {
+                if (importedBinding.name.text === "cn") {
+                    return true;
+                }
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Resolve the module specifier used when injecting a `cn` import into a file.
+ */
+export function cnModuleSpecifierForFile(filePath, override) {
+    void filePath;
+    if (override) {
+        return override;
+    }
+    return "@codefast/tailwind-variants";
+}
+function findImportDeclarationFromModule(sourceFile, moduleSpecifier) {
+    for (const statement of sourceFile.statements) {
+        if (!isDomainImportDeclaration(statement)) {
+            continue;
+        }
+        const spec = statement.moduleSpecifier;
+        if (isDomainStringLiteral(spec) && spec.text === moduleSpecifier) {
+            return statement;
+        }
+    }
+    return undefined;
+}
+export function ensureCnImport(sourceFile, cnImportOverride) {
+    const sourceText = sourceFile.text;
+    if (sourceFileImportsCn(sourceFile)) {
+        return sourceText;
+    }
+    const moduleSpecifier = cnModuleSpecifierForFile(sourceFile.fileName, cnImportOverride);
+    const decl = findImportDeclarationFromModule(sourceFile, moduleSpecifier);
+    if (decl?.importClause &&
+        !decl.importClause.isTypeOnly &&
+        decl.importClause.namedBindings &&
+        isDomainNamedImports(decl.importClause.namedBindings)) {
+        const elements = decl.importClause.namedBindings.elements;
+        if (elements.length > 0) {
+            const pos = elements[0].pos;
+            return `${sourceText.slice(0, pos)}cn, ${sourceText.slice(pos)}`;
+        }
+    }
+    const importLine = `import { cn } from "${moduleSpecifier}";`;
+    let firstImport = -1;
+    for (const statement of sourceFile.statements) {
+        if (isDomainImportDeclaration(statement)) {
+            firstImport = statement.pos;
+            break;
+        }
+    }
+    const useClient = /^["']use client["'];?\s*\r?\n/.exec(sourceText);
+    let insertAt;
+    if (useClient) {
+        insertAt = useClient[0].length;
+    }
+    else if (firstImport !== -1) {
+        insertAt = firstImport;
+    }
+    else {
+        insertAt = 0;
+    }
+    return `${sourceText.slice(0, insertAt)}${importLine}\n${sourceText.slice(insertAt)}`;
+}

package/dist/lib/arrange/domain/source-text-formatters.d.ts

@@ -0,0 +1,16 @@
+export declare function escapeTsStringLiteralContent(group: string): string;
+/**
+ * Multiline fragment for use *inside* an existing `cn(...)` — replaces one
+ * string argument with several, without producing `cn(cn(...))`.
+ */
+export declare function formatCnArguments(groups: string[], options?: {
+    indent?: string;
+    commaAfterLastGroup?: boolean;
+    trailingClassName?: boolean;
+}): string;
+export declare function formatCnCall(groups: string[], options?: {
+    trailingClassName?: boolean;
+}): string;
+export declare function formatArray(groups: string[]): string;
+export declare function formatJsxCnAttributeValue(groups: string[], source: string, valueNodeStart: number): string;
+//# sourceMappingURL=source-text-formatters.d.ts.map